接口 QueryInterface

aliasField(string $field, string|null $alias = null): array<string, string>

返回一个键 => 值数组，表示一个可以直接传递给 select() 方法的单个别名字段。键将包含别名，值将包含实际字段名。

如果该字段已被别名化，则不会更改它。如果未传递 $alias，则将使用此查询的默认表。

参数

返回

aliasFields(array $fields, string|null $defaultAlias = null): array<string, string>

对提供列表中的每个字段运行 aliasField()，并将结果放在一个数组中返回。

参数

返回

all(): Cake\Datasource\ResultSetInterface<T>

获取此查询的结果。

将通过 setResult() 返回结果集，或者执行此查询并返回准备用于结果流的 ResultSetDecorator 对象。

ResultSetDecorator 是一个可遍历对象，它实现了 Cake\Collection\Collection 中的方法。

返回

andWhere(mixed $conditions, array $types = []): $this

使用 AND 运算符将任何先前定义的条件集连接到提供的列表。{@see \Cake\Database\Query::andWhere()}

参数

返回

applyOptions(array<string, mixed> $options): $this

使用数组填充或添加到当前查询子句中。这对于一次性传递所有查询子句非常有用。选项数组接受

• fields：映射到 select 方法
• conditions：映射到 where 方法
• limit：映射到 limit 方法
• order：映射到 order 方法
• offset：映射到 offset 方法
• group：映射到 group 方法
• having：映射到 having 方法
• contain：映射到用于 eager loading 的 contain 选项
• join：映射到 join 方法
• page：映射到 page 方法

示例

$query->applyOptions([
  'fields' => ['id', 'name'],
  'conditions' => [
    'created >=' => '2013-01-01'
  ],
  'limit' => 10
]);

等效于

 $query
 ->select(['id', 'name'])
 ->where(['created >=' => '2013-01-01'])
 ->limit(10)

参数

返回

count(): int

返回查询的总结果数。

返回

find(string $finder, mixed ...$args): static

对现有的查询对象应用自定义查找。

允许自定义查找方法组合并应用于彼此。

$repository->find('all')->find('recent');

以上是将多个查找方法堆叠到单个查询中的示例。

参数

返回

first(): mixed

返回执行此查询的第一个结果，如果查询之前没有执行过，它将为性能原因将 limit 子句设置为 1。

示例

$singleUser = $query->select(['id', 'username'])->first();

返回

firstOrFail(): Cake\Datasource\EntityInterface|array

从执行查询中获取第一个结果，或者引发异常。{@see \Cake\Database\Query::firstOrFail()}

返回

getRepository(): Cake\Datasource\RepositoryInterface|null

返回此查询将使用的默认存储库对象，即将在 from 子句中出现的存储库。

返回

limit(int|null $limit): $this

设置应从数据库中检索的记录数，接受一个整数或一个计算结果为整数的表达式对象。在某些数据库中，此操作可能不受支持，或者需要转换查询才能限制结果集的大小。

示例

$query->limit(10) // generates LIMIT 10
$query->limit($query->newExpr()->add(['1 + 1'])); // LIMIT (1 + 1)

参数

返回

offset(int|null $offset): $this

设置应从原始结果集中跳过的记录数。这通常用于对大型结果进行分页。接受一个整数或一个计算结果为整数的表达式对象。

在某些数据库中，此操作可能不受支持，或者需要转换查询才能限制结果集的大小。

示例

 $query->offset(10) // generates OFFSET 10
 $query->offset($query->newExpr()->add(['1 + 1'])); // OFFSET (1 + 1)

参数

返回

order(Closure|array|string $fields, bool $overwrite = false): $this

添加一个或多个字段，这些字段将在此查询的 ORDER 子句中使用。字段可以作为字符串数组、表达式对象数组、单个表达式或单个字符串传递。

如果传递的是数组，则键将用作字段本身，而值将表示该字段应该排序的顺序。当多次调用相同字段作为键时，最后一次排序定义将优先于其他定义。

默认情况下，此函数将把任何传递的参数追加到要选择的字段列表中，除非第二个参数设置为 true。

示例

$query->orderBy(['title' => 'DESC', 'author_id' => 'ASC']);

产生

ORDER BY title DESC, author_id ASC

$query
    ->orderBy(['title' => $query->newExpr('DESC NULLS FIRST')])
    ->orderBy('author_id');

将生成

ORDER BY title DESC NULLS FIRST, author_id

$expression = $query->newExpr()->add(['id % 2 = 0']);
$query->orderBy($expression)->orderBy(['title' => 'ASC']);

将变成

ORDER BY (id %2 = 0), title ASC

如果您需要将复杂的表达式设置为排序条件，则应使用orderByAsc()或orderByDesc()。

参数

返回

orderBy(Closure|array|string $fields, bool $overwrite = false): $this

添加一个或多个字段，这些字段将在此查询的 ORDER 子句中使用。字段可以作为字符串数组、表达式对象数组、单个表达式或单个字符串传递。

如果传递的是数组，则键将用作字段本身，而值将表示该字段应该排序的顺序。当多次调用相同字段作为键时，最后一次排序定义将优先于其他定义。

默认情况下，此函数将把任何传递的参数追加到要选择的字段列表中，除非第二个参数设置为 true。

示例

$query->orderBy(['title' => 'DESC', 'author_id' => 'ASC']);

产生

ORDER BY title DESC, author_id ASC

$query
    ->orderBy(['title' => $query->newExpr('DESC NULLS FIRST')])
    ->orderBy('author_id');

将生成

ORDER BY title DESC NULLS FIRST, author_id

$expression = $query->newExpr()->add(['id % 2 = 0']);
$query->orderBy($expression)->orderBy(['title' => 'ASC']);

将变成

ORDER BY (id %2 = 0), title ASC

如果您需要将复杂的表达式设置为排序条件，则应使用orderByAsc()或orderByDesc()。

参数

返回

page(int $num, int|null $limit = null): $this

设置要获取的结果页。

此方法提供了一个更易于使用的接口来设置您想要作为结果的记录集中的限制 + 偏移量。如果为空，则限制将默认为现有的限制子句，如果该子句也为空，则将使用 25。

页码必须从 1 开始。

参数

返回

抛出

select(Closure|array|string|float|int $fields, bool $overwrite = false): $this

添加要从数据源中选择的字段。

多次调用此函数会将更多字段追加到要选择的字段列表中。

如果在第二个参数中传递 true，则任何先前的选择都将被第一个参数中传递的列表覆盖。

参数

返回

setRepository(Cake\Datasource\RepositoryInterface $repository): $this

设置此查询将使用的默认 Table 对象并形成 FROM 子句。

参数

返回

toArray(): array

返回执行查询后的结果的数组表示形式。

返回

where(Closure|array|string|null $conditions = null, array<string, string> $types = [], bool $overwrite = false): $this

添加一个条件或一组条件，这些条件将在此查询的 WHERE 子句中使用。条件可以表示为一个键为字段，值为比较运算符的数组，数组的值将用于将字段与该文字进行比较。最后，条件可以表示为单个字符串或字符串数组。

使用数组时，每个条目将使用 AND 运算符与其余条件连接。对该函数的连续调用也将使用 AND 运算符连接指定的新的条件。此外，值可以使用表达式对象来表达，这些对象可以包含其他查询对象。

使用此方法创建的任何条件都可以与任何 SELECT、UPDATE 和 DELETE 类型的查询一起使用。

使用运算符的条件

 $query->where([
     'posted >=' => new DateTime('3 days ago'),
     'title LIKE' => 'Hello W%',
     'author_id' => 1,
 ], ['posted' => 'datetime']);

前面的示例产生

WHERE posted >= 2012-01-27 AND title LIKE 'Hello W%' AND author_id = 1

第二个参数用于指定对每个传递的键期望的类型。有效类型可以使用 Database\Type 类中的映射。

使用连接嵌套条件

 $query->where([
     'author_id !=' => 1,
     'OR' => ['published' => true, 'posted <' => new DateTime('now')],
     'NOT' => ['title' => 'Hello']
 ], ['published' => boolean, 'posted' => 'datetime']

前面的示例产生

WHERE author_id = 1 AND (published = 1 OR posted < '2012-02-01') AND NOT (title = 'Hello')

您可以使用连接嵌套条件，次数不限。有时，您可能希望为同一个键定义 2 个不同的选项，在这种情况下，您可以将每个条件包装在一个新的数组中

$query->where(['OR' => [['published' => false], ['published' => true]])

请记住，每次使用第三个参数设置为 false（默认值）调用 where() 时，它将使用 AND 运算符将传递的条件连接到先前存储的列表中。此外，在对该方法的连续调用中，使用相同的数组键两次不会覆盖先前的值。

使用表达式对象

 $exp = $query->newExpr()->add(['id !=' => 100, 'author_id' != 1])->tieWith('OR');
 $query->where(['published' => true], ['published' => 'boolean'])->where($exp);

前面的示例产生

WHERE (id != 100 OR author_id != 1) AND published = 1

其他查询对象可用作任何字段的条件。

分步添加条件

您可以使用回调来构建复杂的表达式，函数接收第一个参数为一个新的 QueryExpression 对象，第二个参数为这个查询实例。函数必须返回一个表达式对象，该对象将使用 AND 运算符添加到查询的条件列表中。

 $query
 ->where(['title !=' => 'Hello World'])
 ->where(function ($exp, $query) {
     $or = $exp->or(['id' => 1]);
     $and = $exp->and(['id >' => 2, 'id <' => 10]);
 return $or->add($and);
 });

• 前面的示例产生

WHERE title != 'Hello World' AND (id = 1 OR (id > 2 AND id < 10))

字符串条件

 $query->where(['articles.author_id = authors.id', 'modified IS NULL']);

前面的示例产生

WHERE articles.author_id = authors.id AND modified IS NULL

请注意，使用数组表示法或表达式对象时，所有值都会被正确地引用并自动转换为相应的数据库数据类型，从而保护您的应用程序免受 SQL 注入攻击。如果您使用字符串条件，请确保您的值被正确地引用。您可以做到的最安全的事情是永远不要使用字符串条件。

参数

返回