Интерфейс QueryInterface

aliasField()source public

aliasField( string $field , string|null $alias = null )

Возвращает массив ключ => значение, представляющий одно алиасированное поле, которое можно передать непосредственно методу select(). Ключ будет содержать алиас, а значение — фактическое имя поля.

Если поле уже алиасировано, оно не будет изменено. Если $alias не передан, будет использоваться таблица по умолчанию для этого запроса.

Параметры

строка $field

Поле, которое следует алиасить

строка|null $alias необязательно null

алиас, используемый для префикса поля

Возвращает

строка

aliasFields()source public

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

Выполняет aliasField() для каждого поля в предоставленном списке и возвращает результат в виде одного массива.

Параметры

массив $fields

Поля, которые следует алиасить

строка|null $defaultAlias необязательно null

Алиас по умолчанию

Возвращает

массив строк

all()source public

all( )

Получить результаты для этого запроса.

Вернёт либо набор результатов через setResult(), либо выполнит этот запрос и вернёт объект ResultSetDecorator, готовый для потоковой передачи результатов.

ResultSetDecorator — это итерируемый объект, который реализует методы, найденные в Cake\Collection\Collection.

Возвращает

Cake\Datasource\ResultSetInterface

applyOptions()source public

applyOptions( array $options )

Заполняет или добавляет части текущих условий запроса с помощью массива. Это удобно для передачи всех условий запроса сразу. Массив опций принимает:

• fields: Соответствует методу select
• conditions: Соответствует методу where
• limit: Соответствует методу limit
• order: Соответствует методу order
• offset: Соответствует методу offset
• group: Соответствует методу group
• having: Соответствует методу having
• contain: Соответствует параметрам 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)

Параметры

массив $options

список условий запроса для применения новых частей.

Возвращает

$this

count()source public

count( )

Возвращает общее количество результатов для запроса.

Возвращает

целое число

find()source public

find( string $finder , array $options = [] )

Применить пользовательские методы поиска к существующему объекту запроса.

Позволяет комбинировать пользовательские методы поиска и применять их друг к другу.

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

Вышеприведённый пример показывает, как наращивать несколько методов поиска для одного запроса.

Параметры

строка $finder

Метод поиска, который нужно использовать.

массив $options необязательно []

Параметры для метода поиска.

Возвращает

$this Возвращает изменённый запрос.

first()source public

first( )

Возвращает первый результат выполнения этого запроса. Если запрос ещё не выполнен, он установит условие ограничения до 1 для повышения производительности.

Пример:

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

Возвращает

смешанный тип
Первый результат из ResultSet

limit()source public

limit( integer $num )

Устанавливает количество записей, которые должны быть извлечены из базы данных. Принимает целое число или объект выражения, вычисляемый в целое число. В некоторых базах данных эта операция может быть не поддерживаема или потребует преобразования запроса для ограничения размера набора результатов.

Примеры

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

Параметры

целое число $num

Количество записей, которые должны быть возвращены

Возвращает

$this

offset()source public

offset( integer $num )

Устанавливает количество записей, которые следует пропустить из исходного набора результатов. Это обычно используется для постраничной навигации по большим результатам. Принимает целое число или объект выражения, результатом вычисления которого является целое число.

В некоторых базах данных эта операция может не поддерживаться или потребует преобразования запроса для ограничения размера набора результатов.

Примеры

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

Параметры

integer $num

количество записей, которые нужно пропустить

Возвращает

$this

order()source public

order( array|string $fields , boolean $overwrite = false )

Добавляет одно или несколько полей, которые будут использоваться в предложении ORDER для этого запроса. Поля могут быть переданы в виде массива строк, массива объектов выражений, одного объекта выражения или одной строки.

Если передается массив, ключи будут использоваться в качестве самих полей, а значения будут представлять порядок, в котором эти поля должны быть отсортированы. При вызове этого метода несколько раз с одними и теми же полями в качестве ключей, последнее определение порядка будет преобладать над другими.

По умолчанию эта функция будет добавлять любые переданные аргументы в список полей для выбора, если второй аргумент не установлен в true.

Примеры:

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

Производит:

ORDER BY title DESC, author_id ASC

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

Сгенерирует:

ORDER BY title DESC NULLS FIRST, author_id

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

Превратится в:

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

Если вам нужно задать сложные выражения в качестве условий сортировки, вы должны использовать orderAsc() или orderDesc().

Параметры

array|string $fields

поля, которые нужно добавить в список

boolean $overwrite optional false

нужно ли сбросить порядок с переданным списком полей или нет

Возвращает

$this

page()source public

page( integer $num , integer|null $limit = null )

Устанавливает страницу результатов, которую вы хотите получить.

Этот метод предоставляет более удобный интерфейс для установки limit + offset в наборе записей, которые вы хотите получить в качестве результатов. Если он пуст, limit будет по умолчанию равен существующему ограничению, а если и оно пустое, то будет использоваться 25.

Страницы должны начинаться с 1.

Параметры

integer $num

Номер страницы, которую вы хотите получить.

integer|null $limit optional null

Количество строк на странице. Если null, будет использоваться текущее ограничение.

Возвращает

$this

Исключение

InvalidArgumentException
Если номер страницы < 1.

repository()source public

repository( Cake\Datasource\RepositoryInterface $repository = null )

Возвращает объект репозитория по умолчанию, который будет использоваться этим запросом, то есть репозиторий, который будет отображаться в предложении from.

Параметры

Cake\Datasource\RepositoryInterface $repository optional null

Объект репозитория по умолчанию

Возвращает

Cake\Datasource\RepositoryInterface|Cake\Datasource\QueryInterface
$this

toArray()source public

toArray( )

Возвращает массив результатов после выполнения запроса.

Возвращает

array

where()source public

where( string|array|callable|null $conditions = null , array $types = [] , boolean $overwrite = false )

Добавляет условие или набор условий, которые будут использоваться в предложении 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]])

Обратите внимание, что каждый раз, когда вы вызываете where() с третьим параметром, установленным в false (по умолчанию), он будет присоединять переданные условия к предыдущему сохраненному списку, используя оператор 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-инъекций. Если вы используете строковые условия, убедитесь, что ваши значения правильно заключены в кавычки. Самое безопасное, что вы можете сделать, это никогда не использовать строковые условия.

Параметры

string|array|callable|null $conditions optional null

Условие для фильтрации.

array $types optional []

ассоциативный массив имен типов, используемый для привязки значений к запросу

boolean $overwrite optional false

нужно ли сбросить условия с переданным списком или нет

Возвращает

$this

getRepository( )