Класс Query

__call()source public

__call( $method , $arguments )

Исключения

BadMethodCallException
если метод вызывается для запроса, не связанного с выборкой

__clone()source public

__clone( )

Клон объекта.

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

Переопределяет

Cake\Database\Query::__clone()

__construct()source public

__construct( Cake\Database\Connection $connection , Cake\ORM\Table $table )

Конструктор

Параметры

Cake\Database\Connection $connection

Объект подключения

Cake\ORM\Table $table

Таблица, на которой начинается этот запрос

Переопределяет

Cake\Database\Query::__construct()

__debugInfo()source public

__debugInfo( )

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

Возвращает

array

Переопределяет

Cake\Database\Query::__debugInfo()

_addAssociationsToTypeMap()source protected

_addAssociationsToTypeMap( Cake\ORM\Table $table , Cake\Database\TypeMap $typeMap , array $associations )

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

Параметры

Cake\ORM\Table $table

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

Cake\Database\TypeMap $typeMap

Карта типов для проверки столбцов. Эта карта типов косвенно изменяется через Cake\ORM\Query::addDefaultTypes()

массив $associations

Вложенное дерево ассоциаций для обхода.

_addDefaultFields()source protected

_addDefaultFields( )

Проверяет, есть ли заданные поля для выбора, в противном случае добавляет все поля для таблицы по умолчанию.

_addDefaultSelectTypes()source protected

_addDefaultSelectTypes( )

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

_decorateResults()source protected

_decorateResults( Traversable $result )

Декорирует итератор результатов с помощью процедур MapReduce и форматировщиков.

Параметры

Итерируемый $result

Оригинальные результаты

Возвращает

Cake\Datasource\ResultSetInterface

_dirty()source protected

_dirty( )

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

Переопределяет

Cake\Database\Query::_dirty()

_execute()source protected

_execute( )

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

Возвращает

Cake\ORM\ResultSet

_performCount()source protected

_performCount( )

Выполняет и возвращает COUNT(*) для запроса.

Возвращает

целое число

_transformQuery()source protected

_transformQuery( )

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

В частности, добавляет предложение FROM, добавляет поля таблицы по умолчанию, если они не указаны, и применяет соединения, необходимые для ленивой загрузки ассоциаций, определённых с помощью contain

Также устанавливает типы по умолчанию для столбцов в предложении SELECT.

См. также

\Cake\Database\Query::execute()

addDefaultTypes()source public

addDefaultTypes( Cake\ORM\Table $table )

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

Этот метод возвращает тот же объект запроса для цепочки вызовов.

Параметры

Cake\ORM\Table $table

Таблица для извлечения типов

Возвращает

$this

all()source public

all( )

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

Возвращает

Cake\Datasource\ResultSetInterface

Выбрасывает

RuntimeException
если этот метод вызывается для запроса, который не является запросом выбора.

Реализация

Cake\Datasource\QueryInterface::all()

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

Реализация

Cake\Datasource\QueryInterface::applyOptions()

autoFields()source public

autoFields( boolean|null $value null )

Получить/установить, нужно ли ORM автоматически добавлять поля.

По умолчанию вызов select() отключит автоматическое добавление полей. Вы можете снова включить автоматическое добавление полей с помощью этого метода.

Устаревшее

3.4.0 Используйте enableAutoFields()/isAutoFieldsEnabled() вместо этого.

Параметры

boolean|null $value необязательный null

Значение для установки или null для чтения текущего значения.

Возвращает

boolean|Cake\ORM\Query
$this Либо текущее значение, либо объект запроса.

cache()source public

cache( $key , $config 'default' )

Возвращает

$this

Выбрасывает

RuntimeException
Когда вы пытаетесь кэшировать запрос, который не является запросом выбора.

cleanCopy()source public

cleanCopy( )

Создаёт копию текущего запроса, запускает beforeFind и сбрасывает некоторые состояния.

Следующее состояние будет очищено:

• autoFields
• limit
• offset
• функции map/reduce
• форматировщики результатов
• order
• содержания

Этот метод создаёт клоны запросов, которые полезны при работе с подзапросами.

Возвращает

Cake\ORM\Query

clearContain()source public

clearContain( )

Очищает содержащие ассоциации из текущего запроса.

Возвращает

$this

contain()source public

contain( array|string|null $associations null , callable|boolean $override false )

Устанавливает список ассоциаций, которые должны быть загружены вместе с этим запросом. Список связанных таблиц, переданный, должен был быть ранее задан как ассоциации с помощью API таблицы.

Пример:

// Bring articles' author information
$query->contain('Author');

// Also bring the category and tags associated to each article
$query->contain(['Category', 'Tag']);

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

Пример:

// Eager load the product info, and for each product load other 2 associations
$query->contain(['Product' => ['Manufacturer', 'Distributor']);

// Which is equivalent to calling
$query->contain(['Products.Manufactures', 'Products.Distributors']);

// For an author query, load his region, state and country
$query->contain('Regions.States.Countries');

Можно контролировать условия и поля, выбранные для каждой из содержащихся ассоциаций:

Пример:

$query->contain(['Tags' => function ($q) {
    return $q->where(['Tags.is_popular' => true]);
}]);

$query->contain(['Products.Manufactures' => function ($q) {
    return $q->select(['name'])->where(['Manufactures.active' => true]);
}]);

Каждая ассоциация может определять специальные параметры при ленивой загрузке, разрешенные параметры, которые можно задать для каждой ассоциации:

• foreignKey: Используется для задания другого поля для сопоставления обеих таблиц, если установлено в false, условия соединения не будут генерироваться автоматически. false может быть использован только для присоединяемых ассоциаций и не может использоваться с ассоциациями hasMany или belongsToMany.
• fields: Массив с полями, которые должны быть извлечены из ассоциации.
• finder: Фи́ндер для использования при загрузке связанных записей. Либо имя финдера в виде строки, либо массив для определения параметров для передачи финдеру.
• queryBuilder: Эквивалентно передаче вызываемого объекта вместо массива параметров.

Пример:

// Set options for the hasMany articles that will be eagerly loaded for an author
$query->contain([
    'Articles' => [
        'fields' => ['title', 'author_id']
    ]
]);

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

// Retrieve translations for the articles, but only those for the `en` and `es` locales
$query->contain([
    'Articles' => [
        'finder' => [
            'translations' => [
                'locales' => ['en', 'es']
            ]
        ]
    ]
]);

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

// Use a query builder to add conditions to the containment
$query->contain('Authors', function ($q) {
    return $q->where(...); // add conditions
});
// Use special join conditions for multiple containments in the same method call
$query->contain([
    'Authors' => [
        'foreignKey' => false,
        'queryBuilder' => function ($q) {
            return $q->where(...); // Add full filtering conditions
        }
    ],
    'Tags' => function ($q) {
        return $q->where(...); // add conditions
    }
]);

Если функция вызвана без аргументов, она вернёт массив со списком предварительно настроенных ассоциаций, которые должны содержаться в результате.

Если функция вызвана с пустым первым аргументом и $override установлено в true, предыдущий список будет очищен.

Параметры

array|string|null $associations необязательно null

Список псевдонимов таблиц, которые должны быть запрошены.

callable|boolean $override необязательно false

Билдер запроса для ассоциации, или, если associations — массив, булево значение, указывающее, нужно ли перезаписать предыдущий список значением, переданным в аргументе. По умолчанию используется объединение предыдущего списка с новым.

Возвращает

array|Cake\ORM\Query
$this

count()source public

count( )

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

Возвращает COUNT(*) для запроса. Если запрос не был изменён и счёт уже был выполнен, возвращается кэшированное значение.

Возвращает

integer

Реализация

Cake\Datasource\QueryInterface::count()

counter()source public

counter( callable|null $counter )

Регистрирует вызываемый объект, который будет выполнен при вызове метода count в этом запросе. Значение возврата функции будет установлено как значение возврата метода count.

Это особенно полезно, когда вам нужно оптимизировать запрос для возврата подсчёта, например, удаляя ненужные соединения, удаляя группировку или просто возвращая приблизительное количество строк.

Обратный вызов получит в качестве первого аргумента клон этого запроса, а не сам запрос.

Если первый параметр имеет значение null, вместо этого будет вызван встроенный счётчик.

Параметры

callable|null $counter

Значение счётчика

Возвращает

$this

delete()source public

delete( string|null $table null )

Создаёт запрос на удаление.

Изменяет тип запроса на 'delete'. Может быть объединён с методом where() для создания запросов на удаление.

Параметры

string|null $table необязательно null

Неиспользуемый параметр.

Возвращает

$this

Переопределяет

Cake\Database\Query::delete()

eagerLoader()source public

eagerLoader( Cake\ORM\EagerLoader $instance null )

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

Устаревшее

3.4.0 Используйте setEagerLoader()/getEagerLoader() вместо этого.

Параметры

Cake\ORM\EagerLoader $instance необязательно null

Ленивый загрузчик для использования. Передайте null, чтобы получить текущий ленивый загрузчик.

Возвращает

Cake\ORM\EagerLoader|Cake\ORM\Query
$this

enableAutoFields()source public

enableAutoFields( boolean $value true )

Устанавливает, будет ли ORM автоматически добавлять поля.

По умолчанию вызов select() отключит автоматические поля. Вы можете снова включить автоматические поля с помощью этого метода.

Параметры

boolean $value необязательно true

Установите true для включения, false для отключения.

Возвращает

$this

enableHydration()source public

enableHydration( boolean $enable true )

Включить/отключить гидратацию сущностей.

Если установлено в false, для запроса будут возвращены результаты в формате массива.

Параметры

boolean $enable необязательно true

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

Возвращает

$this

find()source public

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

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

Параметры

string $finder

Метод финдера для использования.

array $options необязательно []

Параметры для финдера.

Возвращает

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

См. также

\Cake\ORM\Table::find()

Реализация

Cake\Datasource\QueryInterface::find()

getEagerLoader()source public

getEagerLoader( )

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

Возвращает

Cake\ORM\EagerLoader

hydrate()source public

hydrate( boolean|null $enable null )

Включить/отключить гидратацию сущностей.

Если установлено в false, будут возвращены результаты в формате массива.

Устаревшее

3.4.0 Используйте enableHydration()/isHydrationEnabled() вместо этого.

Параметры

boolean|null $enable необязательно null

Используйте булево значение для установки режима гидратации. Значение null вернёт текущий режим гидратации.

Возвращает

boolean|Cake\ORM\Query
$this Булевое значение при чтении, и $this при установке режима.

innerJoinWith()source public

innerJoinWith( string $assoc , callable $builder null )

Создаёт INNER JOIN с переданной таблицей ассоциации, сохраняя соответствие внешнего ключа и пользовательские условия, которые были первоначально заданы для неё.

Эта функция добавит записи в граф contain.

Пример:

// Bring only articles that were tagged with 'cake'
$query->innerJoinWith('Tags', function ($q) {
    return $q->where(['name' => 'cake']);
);

Это создаст следующий SQL:

SELECT Articles.*
FROM articles Articles
INNER JOIN tags Tags ON Tags.name = 'cake'
INNER JOIN articles_tags ArticlesTags ON ArticlesTags.tag_id = Tags.id
  AND ArticlesTags.articles_id = Articles.id

Эта функция работает так же, как matching(), с той разницей, что она не будет выбирать поля из ассоциации.

Параметры

string $assoc

Ассоциация для объединения с ней

callable $builder необязательно null

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

Возвращает

$this

См. также

\Cake\ORM\Query::matching()

insert()source public

insert( array $columns , array $types [] )

Создаёт запрос на вставку.

Изменяет тип запроса на 'insert'. Обратите внимание, что вызов этого метода сбросит любые данные, ранее заданные с помощью Query::values().

Может быть объединён с методом where() для создания запросов на удаление.

Параметры

array $columns

Столбцы для вставки.

array $types необязательно []

Сопоставление столбцов и их типов данных.

Возвращает

$this

Исключения

RuntimeException
При отсутствии столбцов.

Переопределяет

Cake\Database\Query::insert()

isAutoFieldsEnabled()source public

isAutoFieldsEnabled( )

Определяет, следует ли ORM автоматически добавлять поля.

По умолчанию вызов select() отключает автоматическое добавление полей. Можно снова включить автоматическое добавление полей с помощью enableAutoFields().

Возвращает

boolean
Текущее значение.

isHydrationEnabled()source public

isHydrationEnabled( )

Возвращает текущий режим гидратации.

Возвращает

boolean

jsonSerialize()source public

jsonSerialize( )

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

Часть интерфейса JsonSerializable.

Возвращает

Cake\Datasource\ResultSetInterface
Данные для преобразования в JSON.

Реализация

JsonSerializable::jsonSerialize()

leftJoinWith()source public

leftJoinWith( string $assoc , callable $builder null )

Создаёт LEFT JOIN с указанной таблицей ассоциации, сохраняя соответствие внешних ключей и пользовательские условия, которые были первоначально заданы для неё.

Эта функция добавит записи в contain граф.

Пример:

// Get the count of articles per user
$usersQuery
    ->select(['total_articles' => $query->func()->count('Articles.id')])
    ->leftJoinWith('Articles')
    ->group(['Users.id'])
    ->enableAutoFields(true);

Вы также можете настроить условия, передаваемые в LEFT JOIN:

// Get the count of articles per user with at least 5 votes
$usersQuery
    ->select(['total_articles' => $query->func()->count('Articles.id')])
    ->leftJoinWith('Articles', function ($q) {
        return $q->where(['Articles.votes >=' => 5]);
    })
    ->group(['Users.id'])
    ->enableAutoFields(true);

Это создаст следующий SQL:

SELECT COUNT(Articles.id) AS total_articles, Users.*
FROM users Users
LEFT JOIN articles Articles ON Articles.user_id = Users.id AND Articles.votes >= 5
GROUP BY USers.id

Можно выполнить левое объединение глубоких ассоциаций, используя нотацию с точкой.

Пример:

// Total comments in articles by 'markstory'
$query
 ->select(['total_comments' => $query->func()->count('Comments.id')])
 ->leftJoinWith('Comments.Users', function ($q) {
    return $q->where(['username' => 'markstory']);
)
->group(['Users.id']);

Обратите внимание, что запросу, переданному в замыкание, будут доступны только вызовы select, where, andWhere и orWhere. Если вы хотите добавить более сложные условия, вы можете сделать это напрямую в основном запросе.

Параметры

string $assoc

Ассоциация для объединения

callable $builder опционально null

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

Возвращает

$this

matching()source public

matching( string $assoc , callable $builder null )

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

Эта функция добавит записи в contain граф.

Пример:

// Bring only articles that were tagged with 'cake'
$query->matching('Tags', function ($q) {
    return $q->where(['name' => 'cake']);
);

Можно фильтровать по глубоким ассоциациям, используя нотацию с точкой:

Пример:

// Bring only articles that were commented by 'markstory'
$query->matching('Comments.Users', function ($q) {
    return $q->where(['username' => 'markstory']);
);

Поскольку эта функция создаёт INNER JOIN, вы можете рассмотреть возможность вызова distinct для этого запроса, так как вы можете получить дублируемые строки, если ваши условия не отфильтровывают их. Это может произойти, например, если один и тот же пользователь оставил более одного комментария в одной и той же статье.

Пример:

// Bring unique articles that were commented by 'markstory'
$query->distinct(['Articles.id'])
->matching('Comments.Users', function ($q) {
    return $q->where(['username' => 'markstory']);
);

Обратите внимание, что запросу, переданному в замыкание, будут доступны только вызовы select, where, andWhere и orWhere. Если вы хотите добавить более сложные условия, вы можете сделать это напрямую в основном запросе.

Параметры

string $assoc

Ассоциация для фильтрации

callable $builder опционально null

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

Возвращает

$this

notMatching()source public

notMatching( string $assoc , callable $builder null )

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

Эта функция добавит записи в contain граф.

Пример:

// Bring only articles that were not tagged with 'cake'
$query->notMatching('Tags', function ($q) {
    return $q->where(['name' => 'cake']);
);

Можно фильтровать по глубоким ассоциациям, используя нотацию с точкой:

Пример:

// Bring only articles that weren't commented by 'markstory'
$query->notMatching('Comments.Users', function ($q) {
    return $q->where(['username' => 'markstory']);
);

Поскольку эта функция создаёт LEFT JOIN, вы можете рассмотреть возможность вызова distinct для этого запроса, так как вы можете получить дублирующие строки, если ваши условия не отфильтровывают их. Например, если одна статья имеет несколько комментариев.

Пример:

// Bring unique articles that were commented by 'markstory'
$query->distinct(['Articles.id'])
->notMatching('Comments.Users', function ($q) {
    return $q->where(['username' => 'markstory']);
);

Обратите внимание, что запросу, переданному в замыкание, будут доступны только вызовы select, where, andWhere и orWhere. Если вы хотите добавить более сложные условия, вы можете сделать это напрямую в основном запросе.

Параметры

string $assoc

Ассоциация для фильтрации

callable $builder опционально null

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

Возвращает

$this

select()source public

select( array|Cake\Database\ExpressionInterface|string|Cake\ORM\Table|Cake\ORM\Association $fields [] , boolean $overwrite false )

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

Если вы передадите экземпляр класса Cake\ORM\Table или Cake\ORM\Association, все поля в схеме таблицы или ассоциации будут добавлены в предложение select.

Параметры

array|Cake\Database\ExpressionInterface|string|Cake\ORM\Table|Cake\ORM\Association $fields опционально []

поля для добавления в список.

boolean $overwrite опционально false

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

Возвращает

$this

Переопределяет

Cake\Database\Query::select()

setEagerLoader()source public

setEagerLoader( Cake\ORM\EagerLoader $instance )

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

Параметры

Cake\ORM\EagerLoader $instance

Загрузчик с нетерпением для использования.

Возвращает

$this

sql()source public

sql( Cake\Database\ValueBinder $binder null )

Возвращает строковое представление этого объекта.

Параметры

Cake\Database\ValueBinder $binder опционально null

$generator Объект-заполнитель, который будет содержать связанные значения для выражений

Возвращает

string

Переопределяет

Cake\Database\Query::sql()

triggerBeforeFind()source public

triggerBeforeFind( )

Вызывает событие beforeFind для объекта репозитория запроса.

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

update()source public

update( string|null $table null )

Создаёт запрос обновления.

Изменяет тип запроса на 'update'. Можно комбинировать с методами set() и where() для создания запросов обновления.

Параметры

string|null $table опционально null

Неиспользуемый параметр.

Возвращает

$this

Переопределяет

Cake\Database\Query::update()

__toString()source public

__toString( )

Возвращает строковое представление этого запроса (полное SQL-выражение).

Возвращает

string

_conjugate()source protected

_conjugate( string $part , string|null|array|Cake\Database\ExpressionInterface|callable $append , string $conjunction , array $types )

Вспомогательная функция, используемая для построения условий путём композиции объектов QueryExpression.

Параметры

string $part

Имя части запроса, к которой нужно добавить новую часть

string|null|array|Cake\Database\ExpressionInterface|callable $append

Выражение или функция-построитель для добавления.

string $conjunction

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

array $types

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

_decorateStatement()source protected

_decorateStatement( Cake\Database\StatementInterface $statement )

Вспомогательная функция, используемая для обертывания исходного оператора из драйвера любыми зарегистрированными обратными вызовами.

Параметры

Cake\Database\StatementInterface $statement

для обертывания

Возвращает

Cake\Database\Statement\CallbackStatement

_makeJoin()source protected

_makeJoin( string|array $table , string|array|Cake\Database\ExpressionInterface $conditions , string $type )

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

Параметры

string|array $table

Таблица, с которой происходит присоединение

string|array|Cake\Database\ExpressionInterface $conditions

Условие для присоединения.

string $type

тип присоединения

Возвращает

array

andHaving()source public

andHaving( string|array|Cake\Database\ExpressionInterface|callable $conditions , array $types [] )

Подключает любой ранее определённый набор условий к предоставленному списку с помощью оператора AND в клаузе HAVING. Этот метод работает точно так же, как метод andWhere(). Обратитесь к документации по этому методу, чтобы узнать, как использовать каждый параметр.

Поля HAVING не подходят для использования с данными, предоставленными пользователем, так как они не очищаются с помощью конструктора запроса.

Параметры

string|array|Cake\Database\ExpressionInterface|callable $conditions

Условия AND для HAVING.

array $types необязательно []

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

Возвращает

$this

См. также

\Cake\Database\Query::andWhere()

andWhere()source public

andWhere( string|array|Cake\Database\ExpressionInterface|callable $conditions , array $types [] )

Подключает любой ранее определённый набор условий к предоставленному списку с помощью оператора AND. Эта функция принимает список условий в том же формате, что и метод where, поэтому вы можете использовать массивы, объекты выражений, функции обратного вызова или строки.

Важно отметить, что при вызове этой функции любой ранее определённый набор условий для этого запроса будет обрабатываться как один аргумент для оператора AND. Эта функция будет обрабатывать не только последнюю определённую условную клаузу, но и все условия в целом.

При использовании массива для определения условий создание ограничений для каждой записи массива будет использовать ту же логику, что и функция where(). Это означает, что каждая запись массива будет соединяться с другими с помощью оператора AND, если вы не вложите условия в массив с помощью других операторов.

Примеры:

$query->where(['title' => 'Hello World')->andWhere(['author_id' => 1]);

Что приведет к:

WHERE title = 'Hello World' AND author_id = 1

$query
  ->where(['OR' => ['published' => false, 'published is NULL']])
  ->andWhere(['author_id' => 1, 'comments_count >' => 10])

Создаёт:

WHERE (published = 0 OR published IS NULL) AND author_id = 1 AND comments_count > 10

$query
  ->where(['title' => 'Foo'])
  ->andWhere(function ($exp, $query) {
    return $exp
      ->or_(['author_id' => 1])
      ->add(['author_id' => 2]);
  });

Генерирует следующие условия:

WHERE (title = 'Foo') AND (author_id = 1 OR author_id = 2)

Параметры

string|array|Cake\Database\ExpressionInterface|callable $conditions

Условия для добавления с AND.

array $types необязательно []

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

Возвращает

$this

См. также

\Cake\Database\Query::where()
Cake\Database\Type

bind()source public

bind( string|integer $param , mixed $value , string|integer $type 'string' )

Связывает заполнитель запроса со значением и типом.

Если тип выражается как "atype[]" (обратите внимание на фигурные скобки), то это вызовет динамическое переписывание заполнителя, так что если значение является массивом, он создаст столько же заполнителей, сколько значений в нём. Например:

$query->bind(':id', [1, 2, 3], 'int[]');

Создаст 3 целых заполнителя. При использовании именованных заполнителей этот метод требует, чтобы заполнители включали : например :value.

Параметры

string|integer $param

заполнитель, который будет заменён на цитированную версию $value

mixed $value

Значение, которое нужно привязать

string|integer $type необязательно 'string'

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

Возвращает

$this

bufferResults()source public

bufferResults( boolean|null $enable null )

Включить/выключить буферизацию результатов.

При включении результаты, возвращаемые этим запросом, будут буферизованы. Это позволяет многократно итерировать набор результатов или кешировать и итерировать его.

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

Если вызов осуществляется без аргументов, он вернёт, включена ли буферизация.

Устарело

3.4.0 Используйте enableBufferedResults()/isBufferedResultsEnabled() вместо этого.

Параметры

boolean|null $enable необязательно null

Включить или выключить буферизацию

Возвращает

boolean|Cake\Database\Query
$this

clause()source public

clause( string $name )

Возвращает любые данные, которые хранились в указанной клаузе. Это полезно для изменения любой внутренней части запроса, и диалекты SQL используют это для преобразования запроса перед его выполнением. Допустимые клаузы, которые можно получить, это: delete, update, set, insert, values, select, distinct, from, join, set, where, group, having, order, limit, offset и union.

Возвращаемое значение для каждой из этих частей может быть разным. Некоторые клаузы используют QueryExpression для внутреннего хранения своего состояния, некоторые — массивы, а другие — булевы значения или целые числа. Это краткое описание типов возвращаемых значений для каждой клаузы.

• update: string Имя таблицы, подлежащей обновлению
• set: QueryExpression
• insert: array, вернёт массив, содержащий таблицу + столбцы.
• values: ValuesExpression
• select: array, вернёт пустой массив, если нет полей
• distinct: boolean
• from: массив таблиц
• join: массив
• set: массив
• where: QueryExpression, возвращает null, если не задано
• group: массив
• having: QueryExpression, возвращает null, если не задано
• order: OrderByExpression, возвращает null, если не задано
• limit: целое число или QueryExpression, null если не задано
• offset: целое число или QueryExpression, null если не задано
• union: массив

Параметры

string $name

имя клаузы, которая должна быть возвращена

Возвращает

mixed

Исключения

InvalidArgumentException
Если указанная клауза не существует.

connection()source public

connection( Cake\Database\Connection|null $connection null )

Устанавливает экземпляр соединения, который будет использоваться для выполнения и преобразования этого запроса. При вызове с аргументом null он вернёт текущий экземпляр соединения.

Устарело

3.4.0 Используйте setConnection()/getConnection() вместо этого.

Параметры

Cake\Database\Connection|null $connection необязательно null

экземпляр соединения

Возвращает

$this|\Cake\Database\Connection

decorateResults()source public

decorateResults( callable|null $callback , boolean $overwrite false )

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

Обратные вызовы выполняются лениво, если для базы данных извлекаются только 3 строки, он будет вызываться 3 раза, даже если в курсоре может быть больше строк.

Обратные вызовы складываются в том порядке, в котором они регистрируются. Если вы хотите сбросить стек, вызовите эту функцию со вторым параметром, установленным в true.

Если вы хотите удалить все декораторы из стека, установите первый параметр в null, а второй — в true.

Пример

$query->decorateResults(function ($row) {
  $row['order_total'] = $row['subtotal'] + ($row['subtotal'] * $row['tax']);
   return $row;
});

Параметры

callable|null $callback

Обратный вызов для вызова при извлечении результатов.

boolean $overwrite необязательно false

Включить ли добавление или замену всех существующих декораторов.

Возвращает

$this

distinct()source public

distinct( array|Cake\Database\ExpressionInterface|string|boolean $on [] , boolean $overwrite false )

Добавляет условие DISTINCT в запрос для удаления дубликатов из набора результатов. Это условие может быть использовано только для запросов SELECT.

Если вы хотите отфильтровать дубликаты на основе строк, содержащих определённое поле или набор полей, вы можете передать массив полей для фильтрации. Имейте в виду, что этот параметр может не поддерживаться во всех системах баз данных.

Примеры:

// Filters products with the same name and city
$query->select(['name', 'city'])->from('products')->distinct();

// Filters products in the same city
$query->distinct(['city']);
$query->distinct('city');

// Filter products with the same name
$query->distinct(['name'], true);
$query->distinct('name', true);

Параметры

массив|Cake\Database\ExpressionInterface|строка|булево $on необязательно []

Включить/отключить режим distinct или список полей для фильтрации

булево $overwrite необязательно false

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

Возвращает

$this

enableBufferedResults()source public

enableBufferedResults( boolean $enable true )

Включает/отключает буферизацию результатов.

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

При отключении буферизации потребление памяти уменьшится, так как полученные результаты не будут запоминаться для будущих итераций.

Параметры

булево $enable необязательно true

Включить или отключить буферизацию

Возвращает

$this

epilog()source public

epilog( string|Cake\Database\Expression\QueryExpression|null $expression null )

Строка или выражение, которое будет добавлен в конец сгенерированного запроса

Примеры:

$query->select('id')->where(['author_id' => 1])->epilog('FOR UPDATE');
$query
 ->insert('articles', ['title'])
 ->values(['author_id' => 1])
 ->epilog('RETURNING id');

Содержание эпилога — это сырой SQL и не подходит для использования с данными, введёнными пользователем.

Параметры

строка|Cake\Database\Expression\QueryExpression|null $expression необязательно null

Выражение, которое нужно добавить

Возвращает

$this

execute()source public

execute( )

Компилирует SQL представление этого запроса и выполняет его с использованием объекта подключения, сконфигурированного в базе данных. Возвращает объект результирующего оператора.

Выполнение запроса включает несколько шагов. На первом шаге подключение преобразует этот объект в соответствии со своей конкретной диалектикой, что может привести к генерации другого объекта Query, который будет фактически выполнен. Сразу после этого, литеральные значения передаются подключению, чтобы они были связаны с запросом безопасным образом. Наконец, результирующий оператор декорируется с использованием пользовательских объектов для выполнения обратных вызовов для каждой полученной строки, если необходимо.

Результирующий оператор итерируемый, поэтому его можно использовать в любом цикле, как вы бы использовали массив.

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

Возвращает

Cake\Database\StatementInterface

from()source public

from( array|string $tables [] , boolean $overwrite false )

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

Если передаётся массив, ключи будут использованы для алиасов таблиц, используя значение как реальное поле для алиаса. Возможны алиасы строк, объектов ExpressionInterface или даже других объектов Query.

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

Этот метод можно использовать для запросов SELECT, UPDATE и DELETE.

Примеры:

$query->from(['p' => 'posts']); // Produces FROM posts p
$query->from('authors'); // Appends authors: FROM posts p, authors
$query->from(['products'], true); // Resets the list: FROM products
$query->from(['sub' => $countQuery]); // FROM (SELECT ...) sub

Параметры

массив|строка $tables необязательно []

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

булево $overwrite необязательно false

сбросить ли таблицы с переданным списком или нет

Возвращает

$this|массив

func()source public

func( )

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

Пример:

$query->func()->count('*');
$query->func()->dateDiff(['2012-01-05', '2012-01-02'])

Возвращает

Cake\Database\FunctionsBuilder

getConnection()source public

getConnection( )

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

Возвращает

Cake\Database\Connection

getIterator()source public

getIterator( )

Выполняет этот запрос и возвращает итератор результатов. Эта функция необходима для реализации интерфейса IteratorAggregate и позволяет итерировать запрос без ручного вызова execute(), что позволяет ему выглядеть как набор результатов, а не сам запрос.

Возвращает

Cake\Database\StatementInterface|null

Реализация

IteratorAggregate::getIterator()

getSelectTypeMap()source public

getSelectTypeMap( )

Возвращает класс TypeMap, где хранятся типы для каждого поля в операторе SELECT.

Возвращает

Cake\Database\TypeMap

getValueBinder()source public

getValueBinder( )

Возвращает текущий используемый экземпляр ValueBinder.

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

Возвращает

Cake\Database\ValueBinder

group()source public

group( array|Cake\Database\ExpressionInterface|string $fields , boolean $overwrite false )

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

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

Примеры:

// Produces GROUP BY id, title
$query->group(['id', 'title']);

// Produces GROUP BY title
$query->group('title');

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

Параметры

массив|Cake\Database\ExpressionInterface|строка $fields

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

булево $overwrite необязательно false

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

Возвращает

$this

having()source public

having( string|array|Cake\Database\ExpressionInterface|callable|null $conditions null , array $types [] , boolean $overwrite false )

Добавляет условие или набор условий, которые будут использоваться в операторе HAVING для этого запроса. Этот метод работает точно так же, как и метод where(). Обратитесь к его документации, чтобы узнать, как использовать каждый параметр.

Поля having не подходят для использования с данными, введёнными пользователем, так как они не проверяются на безопасность системой построения запросов.

Параметры

строка|массив|Cake\Database\ExpressionInterface|обратный вызов|null $conditions необязательно null

Условия having.

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

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

булево $overwrite необязательно false

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

Возвращает

$this

См. также

\Cake\Database\Query::where()

innerJoin()source public

innerJoin( string|array $table , string|array|Cake\Database\ExpressionInterface $conditions [] , array $types [] )

Добавляет единственное условие INNER JOIN к запросу.

Это метод сокращенной записи для построения объединений через join().

Аргументы этого метода идентичны аргументам метода leftJoin() сокращенной записи, пожалуйста, обратитесь к описанию этого метода для получения дополнительной информации.

Параметры

string|array $table

Таблица для объединения

string|array|Cake\Database\ExpressionInterface $conditions необязательно []

Условие для объединения.

array $types необязательно []

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

Возвращает

$this

into()source public

into( string $table )

Устанавливает имя таблицы для запросов вставки.

Параметры

string $table

Имя таблицы, в которую нужно вставить данные.

Возвращает

$this

isBufferedResultsEnabled()source public

isBufferedResultsEnabled( )

Возвращает, включено/выключено ли буферирование результатов.

При включенном буферировании результаты, возвращаемые этим запросом, будут буферизованы. Это позволяет вам многократно итерировать набор результатов, или кэшировать и итерировать его.

При выключенном буферировании потребление памяти будет меньше, так как полученные результаты не запоминаются для будущих итераций.

Возвращает

boolean

join()source public

join( array|string|null $tables null , array $types [] , boolean $overwrite false )

Добавляет одну или несколько таблиц для использования в качестве условий JOIN в этом запросе. Таблицы могут быть переданы как массив строк, массив, описывающий части объединения, массив с несколькими описаниями объединений или одна строка.

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

Если тип объединения не указан, используется INNER JOIN по умолчанию: $query->join(['authors']) приведет к INNER JOIN authors ON 1 = 1

Также возможно использовать псевдонимы для объединений, используя ключ массива: $query->join(['a' => 'authors']) приведет к INNER JOIN authors a ON 1 = 1

Объединение может быть полностью описано и псевдонимизировано с помощью записи в формате массива:

$query->join([
    'a' => [
        'table' => 'authors',
        'type' => 'LEFT',
        'conditions' => 'a.id = b.author_id'
    ]
]);
// Produces LEFT JOIN authors a ON a.id = b.author_id

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

$query->join([
    'a' => [
        'table' => 'authors',
        'type' => 'LEFT',
        'conditions' => 'a.id = b.author_id'
    ],
    'p' => [
        'table' => 'publishers',
        'type' => 'INNER',
        'conditions' => 'p.id = b.publisher_id AND p.name = "Cake Software Foundation"'
    ]
]);
// LEFT JOIN authors a ON a.id = b.author_id
// INNER JOIN publishers p ON p.id = b.publisher_id AND p.name = "Cake Software Foundation"

Использование условий и типов

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

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

$query->join(['a' => [
    'table' => 'articles',
    'conditions' => [
        'a.posted >=' => new DateTime('-3 days'),
        'a.published' => true,
        'a.author_id = authors.id'
    ]
]], ['a.posted' => 'datetime', 'a.published' => 'boolean'])

Переопределение объединений

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

$query->join(['alias' => 'table']); // joins table with as alias
$query->join(['alias' => 'another_table']); // joins another_table with as alias
$query->join(['something' => 'different_table'], [], true); // resets joins list

Параметры

array|string|null $tables необязательно null

список таблиц для объединения в запросе

array $types необязательно []

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

boolean $overwrite необязательно false

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

Возвращает

$this|array

См. также

Cake\Database\Type

leftJoin()source public

leftJoin( string|array $table , string|array|Cake\Database\ExpressionInterface $conditions [] , array $types [] )

Добавляет единственное условие LEFT JOIN к запросу.

Это метод сокращенной записи для построения объединений через join().

Имя таблицы может быть передано как строка или как массив, если необходимо присвоить псевдоним:

// LEFT JOIN authors ON authors.id = posts.author_id
$query->leftJoin('authors', 'authors.id = posts.author_id');

// LEFT JOIN authors a ON a.id = posts.author_id
$query->leftJoin(['a' => 'authors'], 'a.id = posts.author_id');

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

$query->leftJoin(['a' => 'articles'], [
     'a.posted >=' => new DateTime('-3 days'),
     'a.published' => true,
     'a.author_id = authors.id'
], ['a.posted' => 'datetime', 'a.published' => 'boolean']);

См. join() для получения дополнительной информации об условиях и типах.

Параметры

string|array $table

Таблица для объединения

string|array|Cake\Database\ExpressionInterface $conditions необязательно []

Условие для объединения.

array $types необязательно []

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

Возвращает

$this

limit()source public

limit( integer|Cake\Database\ExpressionInterface $num )

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

Примеры

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

Параметры

integer|Cake\Database\ExpressionInterface $num

количество записей для возврата

Возвращает

$this

modifier()source public

modifier( array|Cake\Database\ExpressionInterface|string $modifiers , boolean $overwrite false )

Добавляет один или несколько SELECT модификаторов, которые должны использоваться в SELECT.

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

Пример:

// Ignore cache query in MySQL
$query->select(['name', 'city'])->from('products')->modifier('SQL_NO_CACHE');
// It will produce the SQL: SELECT SQL_NO_CACHE name, city FROM products

// Or with multiple modifiers
$query->select(['name', 'city'])->from('products')->modifier(['HIGH_PRIORITY', 'SQL_NO_CACHE']);
// It will produce the SQL: SELECT HIGH_PRIORITY SQL_NO_CACHE name, city FROM products

Параметры

array|Cake\Database\ExpressionInterface|string $modifiers

модификаторы, которые должны быть применены к запросу

boolean $overwrite необязательно false

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

Возвращает

$this

newExpr()source public

newExpr( mixed $rawExpression null )

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

Вы можете необязательно передать одну строку с исходным SQL-кодом или массив или выражения в любом формате, принятом \Cake\Database\Expression\QueryExpression:

$expression = $query->newExpr(); // Returns an empty expression object
$expression = $query->newExpr('Table.column = Table2.column'); // Return a raw SQL expression

Параметры

mixed $rawExpression необязательно null

Строка, массив или любой другой элемент, который нужно обернуть в объект выражения

Возвращает

Cake\Database\Expression\QueryExpression

offset()source public

offset( integer|Cake\Database\ExpressionInterface $num )

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

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

Примеры

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

Параметры

integer|Cake\Database\ExpressionInterface $num

количество записей для пропуска

Возвращает

$this

orHaving()source public

orHaving( string|array|Cake\Database\ExpressionInterface|callable $conditions , array $types [] )

Соединяет любой ранее определенный набор условий с предоставленным списком с помощью оператора OR в условии HAVING. Этот метод работает в точности так же, как метод orWhere(). Обратитесь к его документации, чтобы понять, как использовать каждый параметр.

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

Устаревший

3.5.0 Этот метод создаёт трудно предсказуемый SQL на основе текущего состояния запроса. Используйте Query::having() вместо него, так как он обладает более предсказуемым и понятным поведением.

Параметры

string|array|Cake\Database\ExpressionInterface|callable $conditions

Условия OR для HAVING.

array $types необязательно []

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

Возвращает

$this

См. также

\Cake\Database\Query::orWhere()

orWhere()source public

orWhere( string|array|Cake\Database\ExpressionInterface|callable $conditions , array $types [] )

Подключает любой ранее определенный набор условий к предоставленному списку с помощью оператора OR. Эта функция принимает список условий в том же формате, что и метод where, поэтому вы можете использовать массивы, объекты выражений, функции обратного вызова или строки.

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

При использовании массива для определения условий создание ограничений из каждой записи массива будет использовать ту же логику, что и функция where(). Это означает, что каждая запись массива будет объединена с другой с помощью оператора OR, если вы не вложены условия в массив с использованием других операторов.

Примеры:

$query->where(['title' => 'Hello World')->orWhere(['title' => 'Foo']);

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

WHERE title = 'Hello World' OR title = 'Foo'

$query
  ->where(['OR' => ['published' => false, 'published is NULL']])
  ->orWhere(['author_id' => 1, 'comments_count >' => 10])

Создаст:

WHERE (published = 0 OR published IS NULL) OR (author_id = 1 AND comments_count > 10)

$query
  ->where(['title' => 'Foo'])
  ->orWhere(function ($exp, $query) {
    return $exp
      ->or_(['author_id' => 1])
      ->add(['author_id' => 2]);
  });

Генерирует следующие условия:

WHERE (title = 'Foo') OR (author_id = 1 OR author_id = 2)

Устаревший

3.5.0 Этот метод создает трудно предсказуемый SQL на основе текущего состояния запроса. Используйте Query::where() вместо этого, так как он имеет более предсказуемое и более простое поведение.

Параметры

string|array|Cake\Database\ExpressionInterface|callable $conditions

Условия для добавления с помощью OR.

array $types optional []

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

Возвращает

$this

См. также

\Cake\Database\Query::where()
Cake\Database\Type

order()source public

order( array|Cake\Database\ExpressionInterface|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

Поля/направления сортировки не проверяются обработчиком запросов. Вы должны использовать белый список полей/направлений при передаче данных, введенных пользователем, в order().

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

Параметры

array|Cake\Database\ExpressionInterface|string $fields

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

boolean $overwrite optional false

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

Возвращает

$this

orderAsc()source public

orderAsc( string|Cake\Database\Expression\QueryExpression $field , boolean $overwrite false )

Добавляет предложение ORDER BY с направлением ASC.

Этот метод позволяет задавать сложные выражения в качестве условий сортировки в отличие от order()

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

Параметры

string|Cake\Database\Expression\QueryExpression $field

Поле для сортировки.

boolean $overwrite optional false

Нужно ли сбрасывать предложения order.

Возвращает

$this

orderDesc()source public

orderDesc( string|Cake\Database\Expression\QueryExpression $field , boolean $overwrite false )

Добавляет предложение ORDER BY с направлением DESC.

Этот метод позволяет задавать сложные выражения в качестве условий сортировки в отличие от order()

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

Параметры

string|Cake\Database\Expression\QueryExpression $field

Поле для сортировки.

boolean $overwrite optional false

Нужно ли сбрасывать предложения order.

Возвращает

$this

page()source public

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

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

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

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

Параметры

integer $num

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

integer|null $limit optional null

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

Возвращает

$this

removeJoin()source public

removeJoin( string $name )

Удаляет объединение, если оно было определено.

Полезно при повторном определении объединений или при необходимости изменить порядок предложений объединения.

Параметры

string $name

Псевдоним/имя объединения для удаления.

Возвращает

$this

rightJoin()source public

rightJoin( string|array $table , string|array|Cake\Database\ExpressionInterface $conditions [] , array $types [] )

Добавляет одно RIGHT JOIN условие к запросу.

Это метод сокращения для построения объединений с помощью join().

Аргументы этого метода идентичны аргументам сокращенного метода leftJoin(), см. описание этого метода для получения дополнительной информации.

Параметры

string|array $table

Таблица, с которой нужно объединиться

string|array|Cake\Database\ExpressionInterface $conditions optional []

Условия для использования при объединении.

array $types optional []

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

Возвращает

$this

rowCountAndClose()source public

rowCountAndClose( )

Выполняет SQL этого запроса и немедленно закрывает оператор перед возвращением количества строк измененных записей.

Этот метод может быть использован с запросами UPDATE и DELETE, но не рекомендуется для запросов SELECT и не используется для подсчета записей.

Пример

$rowCount = $query->update('articles')
                ->set(['published'=>true])
                ->where(['published'=>false])
                ->rowCountAndClose();

Приведенный выше пример изменит столбец published на true для всех записей со значением false и вернет количество обновленных записей.

Возвращает

integer

selectTypeMap()source public

selectTypeMap( Cake\Database\TypeMap $typeMap null )

Устанавливает класс TypeMap, где хранятся типы для каждого поля в предложении select.

При вызове без аргументов возвращается текущий объект TypeMap.

Устаревший

3.4.0 Используйте setSelectTypeMap()/getSelectTypeMap() вместо этого.

Параметры

Cake\Database\TypeMap $typeMap optional null

Объект карты для использования

Возвращает

$this|\Cake\Database\TypeMap

set()source public

set( string|array|callable|Cake\Database\Expression\QueryExpression $key , mixed $value null , array $types [] )

Устанавливает одно или несколько полей для обновления.

Примеры

Передача строки:

$query->update('articles')->set('title', 'The Title');

Передача массива:

$query->update('articles')->set(['title' => 'The Title'], ['title' => 'string']);

Передача функции обратного вызова:

$query->update('articles')->set(function ($exp) {
  return $exp->eq('title', 'The title', 'string');
});

Параметры

string|array|callable|Cake\Database\Expression\QueryExpression $key

Имя столбца или массив ключей + значений для установки. Это также может быть QueryExpression, содержащий фрагмент SQL. Это также может быть вызываемая функция, которая должна возвращать объект выражения.

mixed $value optional null

Значение для обновления $key. Может быть null, если $key представляет собой массив или QueryExpression. Если $key представляет собой массив, этот параметр будет использоваться в качестве $types.

array $types optional []

Типы столбцов для обработки данных.

Возвращает

$this

setConnection()source public

setConnection( Cake\Database\Connection $connection )

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

Параметры

Cake\Database\Connection $connection

Экземпляр подключения

Возвращает

$this

setSelectTypeMap()source public

setSelectTypeMap( Cake\Database\TypeMap $typeMap )

Устанавливает класс TypeMap, в котором хранятся типы для каждого поля в запросе SELECT.

Параметры

Cake\Database\TypeMap $typeMap

Объект карты для использования

Возвращает

$this

traverse()source public

traverse( callable $visitor , array $parts [] )

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

Обратный вызов получит 2 параметра: первое — значение части запроса, по которой итерируется, а второе — имя этой части.

Пример:

$query->select(['title'])->from('articles')->traverse(function ($value, $clause) {
    if ($clause === 'select') {
        var_dump($value);
    }
}, ['select', 'from']);

Параметры

callable $visitor

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

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

Операторы запроса для обхода

Возвращает

$this

Реализация

Cake\Database\ExpressionInterface::traverse()

traverseExpressions()source public

traverseExpressions( callable $callback )

Эта функция работает аналогично функции traverse(), с тем отличием, что она выполняет полное рекурсивное обход всего дерева выражения. Это выполнит предоставленную функцию обратного вызова для каждого объекта ExpressionInterface, хранящегося в этом запросе на любой глубине ввода-вывода в любой части запроса.

Обратный вызов получит в качестве первого параметра текущее посещаемое выражение.

Параметры

callable $callback

функция, которая будет выполнена для каждого ExpressionInterface, найденного в этом запросе.

Возвращает

$this|null

type()source public

type( )

Возвращает тип этого запроса (select, insert, update, delete)

Возвращает

строка

union()source public

union( string|Cake\Database\Query $query , boolean $overwrite false )

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

По умолчанию оператор UNION удалит дубликаты строк; если вы хотите включить каждую строку для всех запросов, используйте unionAll().

Примеры

$union = (new Query($conn))->select(['id', 'title'])->from(['a' => 'articles']);
$query->select(['id', 'name'])->from(['d' => 'things'])->union($union);

Создаст:

SELECT id, name FROM things d UNION SELECT id, title FROM articles a

Параметры

строка|Cake\Database\Query $query

полный SQL-запрос, который будет использоваться в операторе UNION

логическое значение $overwrite необязательно false

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

Возвращает

$this

unionAll()source public

unionAll( string|Cake\Database\Query $query , boolean $overwrite false )

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

В отличие от UNION, UNION ALL не будет удалять дубликаты строк.

$union = (new Query($conn))->select(['id', 'title'])->from(['a' => 'articles']);
$query->select(['id', 'name'])->from(['d' => 'things'])->unionAll($union);

Создаст:

SELECT id, name FROM things d UNION ALL SELECT id, title FROM articles a

Параметры

строка|Cake\Database\Query $query

полный SQL-запрос, который будет использоваться в операторе UNION

логическое значение $overwrite необязательно false

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

Возвращает

$this

valueBinder()source public

valueBinder( Cake\Database\ValueBinder|false|null $binder null )

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

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

Устарело

3.5.0 Используйте getValueBinder() для получения вместо этого.

Параметры

Cake\Database\ValueBinder|false|null $binder необязательно null

новый экземпляр для установки. Если значение не передано, будет возвращён стандартный экземпляр

Возвращает

$this|\Cake\Database\ValueBinder

values()source public

values( array|Cake\Database\Query $data )

Устанавливает значения для запроса INSERT.

Многократные вставки могут быть выполнены, вызвав values() более одного раза или передав массив наборов значений. Кроме того, $data может быть экземпляром Query для вставки данных из другого оператора SELECT.

Параметры

массив|Cake\Database\Query $data

Данные для вставки.

Возвращает

$this

Вызывает исключение

Cake\Database\Exception

если вы попытаетесь установить значения до объявления столбцов. Или если вы попытаетесь установить значения для не-запросов INSERT.

where()source public

where( string|array|Cake\Database\ExpressionInterface|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-инъекций. Однако ключи не обрабатываются как небезопасные входные данные и должны быть проверены/разрешены.

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

Параметры

строка|массив|Cake\Database\ExpressionInterface|вызываемая функция|null $conditions необязательно null

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

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

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

boolean $overwrite необязательно false

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

Возвращает

$this

См. также

Cake\Database\Type
Cake\Database\Expression\QueryExpression

_decoratorClass()source protected

_decoratorClass( )

Возвращает имя класса, который будет использоваться для оформления результатов

Возвращает

строка

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

Псевдоним по умолчанию

Возвращает

массив

eagerLoaded()source public

eagerLoaded( boolean|null $value null )

Устанавливает экземпляр запроса как запрос с отложенной загрузкой. Если аргумент не передан, возвращается текущее значение конфигурированного запроса _eagerLoaded.

Устаревшее

3.5.0 Используйте isEagerLoaded() для получения значения вместо этого.

Параметры

boolean|null $value необязательно null

Выполнять ли отложенную загрузку.

Возвращает

$this|\Cake\ORM\Query

first()source public

first( )

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

Пример:

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

Возвращает

Cake\Datasource\EntityInterface|массив|null
Первый результат из набора результатов.

firstOrFail()source public

firstOrFail( )

Получает первый результат из выполнения запроса или вызывает исключение.

Возвращает

Cake\Datasource\EntityInterface|массив
Первый результат из набора результатов.

Вызывает

Cake\Datasource\Exception\RecordNotFoundException
Когда первого записей нет.

formatResults()source public

formatResults( callable $formatter null , boolean|integer $mode 0 )

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

Функции обратного вызова форматирования получат в качестве первого параметра итератор, который можно пройти и изменить по своему усмотрению.

Функции обратного вызова обязаны возвращать объект итератора, который будет использоваться в качестве возвращаемого значения для результата этого запроса. Функции форматирования применяются после всех процедур MapReduce для этого запроса.

Если первый аргумент равен null, будет возвращен список ранее зарегистрированных функций map reduce.

Если второй аргумент равен true, он очистит предыдущие функции форматирования и заменит их переданным первым аргументом.

Пример:

// Return all results from the table indexed by id
$query->select(['id', 'name'])->formatResults(function ($results) {
  return $results->indexBy('id');
});

// Add a new column to the ResultSet
$query->select(['name', 'birth_date'])->formatResults(function ($results) {
  return $results->map(function ($row) {
    $row['age'] = $row['birth_date']->diff(new DateTime)->y;
    return $row;
  });
});

Параметры

вызываемая функция $formatter необязательно null

Функция форматирования.

boolean|целое число $mode необязательно 0

Нужно ли перезаписывать, добавлять или предварять форматировщик.

Возвращает

$this|массив

getIterator()source public

getIterator( )

Выполняет этот запрос и возвращает итератор результатов. Эта функция необходима для реализации интерфейса IteratorAggregate и позволяет итерировать по запросу без необходимости вызова execute() вручную, тем самым делая его похожим на набор результатов, а не на сам запрос.

Возвращает

Итератор

getOptions()source public

getOptions( )

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

Пример:

$query->applyOptions(['doABarrelRoll' => true, 'fields' => ['id', 'name']);
 $query->getOptions(); // Returns ['doABarrelRoll' => true]

Возвращает

массив

См. также

\Cake\ORM\Query::applyOptions() для ознакомления с опциями, которые будут обработаны этим классом и не будут возвращены этой функцией

isEagerLoaded()source public

isEagerLoaded( )

Возвращает текущее значение конфигурированного запроса _eagerLoaded.

Возвращает

boolean

mapReduce()source public

mapReduce( callable $mapper null , callable $reducer null , boolean $overwrite false )

Регистрирует новую процедуру MapReduce, которая будет выполняться над результатами базы данных. И вызываемый объект маппера, и вызываемый объект коллбэка должны быть вызываемыми объектами.

Маршрутизация MapReduce будет выполняться только при выполнении запроса и попытке получения первого результата.

Если первый аргумент установлен в null, то будет возвращен список ранее зарегистрированных процедур map reduce.

Если третий аргумент установлен в true, то предыдущие маппера и редьюсеры будут удалены, и будут заменены переданными аргументами.

Параметры

callable $mapper необязательно null

Вызываемый объект маппера.

callable $reducer необязательно null

Функция редьюсинга.

boolean $overwrite необязательно false

Установите в значение true, чтобы перезаписать существующие функции map + reduce.

Возвращаемые значения

$this|array

См. также

\Cake\Collection\Iterator\MapReduce для получения подробной информации о том, как передавать данные в map-редуктор.

repository()source public

repository( Cake\Datasource\RepositoryInterface $table null )

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

При вызове с аргументом Table объект таблицы по умолчанию будет установлен, и этот объект запроса будет возвращен для цепочки.

Параметры

Cake\Datasource\RepositoryInterface $table необязательно null

Объект таблицы по умолчанию для использования

Возвращаемые значения

Cake\Datasource\RepositoryInterface|Cake\ORM\Table|Cake\Datasource\QueryTrait
$this

setResult()source public

setResult( Cake\Datasource\ResultSetInterface $results )

Устанавливает набор результатов для запроса.

Установка набора результатов запроса сделает execute() бесполезной операцией. Вместо выполнения SQL-запроса и извлечения результатов будет возвращен набор результатов, предоставленный этому методу.

Этот метод наиболее полезен в сочетании с результатами, хранящимися в кэше.

Параметры

Cake\Datasource\ResultSetInterface $results

Результаты, которые должен возвращать этот запрос.

Возвращаемые значения

$this

toArray()source public

toArray( )

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

Возвращаемые значения

array

defaultTypes()source public

defaultTypes( array $types null )

Позволяет устанавливать типы по умолчанию при цепочечном выполнении запросов

Устарело

3.4.0 Используйте setDefaultTypes()/getDefaultTypes() вместо этого.

Параметры

array $types необязательно null

Массив типов для установки.

Возвращаемые значения

$this|array

getDefaultTypes()source public

getDefaultTypes( )

Получает типы по умолчанию текущей карты типов.

Возвращаемые значения

array

getTypeMap()source public

getTypeMap( )

Возвращает существующую карту типов.

Возвращаемые значения

Cake\Database\TypeMap

setDefaultTypes()source public

setDefaultTypes( array $types )

Позволяет устанавливать типы по умолчанию при цепочечном выполнении запросов.

Параметры

array $types

Массив типов для установки.

Возвращаемые значения

$this

setTypeMap()source public

setTypeMap( array|Cake\Database\TypeMap $typeMap )

Создает новую карту типов, если $typeMap является массивом, в противном случае меняет её на заданную.

Параметры

array|Cake\Database\TypeMap $typeMap

Создает карту типов, если массив, в противном случае устанавливает заданную карту типов

Возвращаемые значения

$this

typeMap()source public

typeMap( array|Cake\Database\TypeMap|null $typeMap null )

Создает новую карту типов, если $typeMap является массивом, в противном случае возвращает существующую карту типов или меняет её на заданную.

Устарело

3.4.0 Используйте setTypeMap()/getTypeMap() вместо этого.

Параметры

array|Cake\Database\TypeMap|null $typeMap необязательно null

Создает карту типов, если массив, в противном случае устанавливает заданную карту типов

Возвращаемые значения

$this|\Cake\Database\TypeMap

append( array|Traversable $items )

chunk( $size )

combine( $k , $v , $g )

countBy( string|callable $field )

each( callable $c )

every( callable $c )

extract( $field )

filter( callable $c )

groupBy( string|callable $field )

indexBy( string|callable $field )

isEmpty( )

last( )

map( callable $c )

max( $field , $type )

min( $field , $type )

nest( $k , $p , $n )

reduce( callable $c , $zero )

reject( callable $c )

sample( $size )

shuffle( )

skip( integer $howMany )

some( callable $c )

stopWhen( callable $c )

sumOf( string|callable $field )

take( $size , $from )

toArray( )

toList( )

zip( array|Traversable $c )

zipWith( $collections , callable $callable )

false

true