Класс Query

__clonesource public

__clone( )

Выполняет глубокое клонирование этого объекта.

Будет клонировать все объекты выражений, используемые в каждой из клауз, а также valueBinder.

__constructsource public

__construct( Cake\Datasource\ConnectionInterface $connection )

Конструктор.

Параметры

Cake\Datasource\ConnectionInterface $connection

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

__debugInfosource public

__debugInfo( )

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

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

array
массив

__toStringsource public

__toString( )

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

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

string
строка

_conjugatesource protected

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

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

Параметры

строка $part

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

строка|null|массив|Cake\Database\ExpressionInterface|обратный вызов $append

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

строка $conjunction

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

массив $types

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

_decorateStatementsource protected

_decorateStatement( Cake\Database\StatementInterface $statement )

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

Параметры

Cake\Database\StatementInterface $statement

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

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

Cake\Database\Statement\CallbackStatement
\Cake\Database\Statement\CallbackStatement

_dirtysource protected

_dirty( )

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

_makeJoinsource protected

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

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

Параметры

строка|массив $table

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

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

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

строка $type

тип объединения

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

array
массив

andHavingsource public

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

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

Параметры

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

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

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

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

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

mixed
$this

См. также

Cake\Database\Query::andWhere()

andWheresource 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
      ->add(['author_id' => 1])
      ->or_(['author_id' => 2]);
  });

Получаемые условия:

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

Параметры

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

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

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

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

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

mixed
$this

См. также

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

bindsource public

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

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

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

Параметры

строка|целое число $param

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

смешанное $value

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

строка|целое число $type необязательно 'string'

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

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

mixed
$this

bufferResultssource public

bufferResults( boolean|null $enable null )

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

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

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

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

Параметры

логическое|null $enable необязательно null

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

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

boolean|$this
$this

clausesource public

clause( string $name )

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

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

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

Параметры

строка $name

название фрагмента запроса, который нужно вернуть

Возвращает

mixed
смешанный тип

connectionsource public

connection( Cake\Datasource\ConnectionInterface $connection null )

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

Параметры

Cake\Datasource\ConnectionInterface $connection необязательно null

экземпляр

Возвращает

mixed
$this|\Cake\Datasource\ConnectionInterface

decorateResultssource public

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

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

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

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

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

Пример

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

Параметры

null|вызов $callback

Обратный вызов для вызова, когда результаты извлекаются.

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

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

Возвращает

mixed
$this

deletesource public

delete( string $table null )

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

Может быть объединён с from(), where() и другими методами для создания запросов на удаление со специфическими условиями.

Параметры

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

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

Возвращает

mixed
$this

distinctsource 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

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

Возвращает

mixed
$this

epilogsource public

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

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

Примеры:

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

Параметры

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

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

Возвращает

mixed
$this

executesource public

execute( )

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

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

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

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

Возвращает

Cake\Database\StatementInterface
\Cake\Database\StatementInterface

fromsource public

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

Параметры

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

Таблицы для добавления в список

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

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

Возвращает

mixed
$this

funcsource public

func( )

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

Пример:

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

Возвращает

Cake\Database\FunctionsBuilder
\Cake\Database\FunctionsBuilder

getIteratorsource public

getIterator( )

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

Возвращает

Iterator
\Iterator

Реализация

IteratorAggregate::getIterator()

groupsource 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

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

Возвращает

mixed
$this

havingsource public

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

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

Параметры

string|array|Cake\Database\ExpressionInterface|callable $conditions необязательный null

Условия HAVING.

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

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

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

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

Возвращает

mixed
$this

См. также

Cake\Database\Query::where()

innerJoinsource 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 необязательный []

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

Возвращает

mixed
$this

insertsource public

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

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

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

Параметры

array $columns

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

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

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

Возвращает

mixed
$this

Исключения

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

intosource public

into( string $table )

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

Параметры

string $table

Имя таблицы для вставки.

Возвращает

mixed
$this

joinsource 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

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

Возвращает

mixed
$this

См. также

Cake\Database\Type

leftJoinsource 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 необязательный []

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

Возвращает

mixed
$this

limitsource 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

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

Возвращает

mixed
$this

modifiersource 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

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

Возвращает

mixed
$this

newExprsource 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
\Cake\Database\Expression\QueryExpression

offsetsource 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

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

Возвращает

mixed
$this

orHavingsource public

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

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

Параметры

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

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

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

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

Возвращает

mixed
$this

См. также

Cake\Database\Query::orWhere()

orWheresource 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
      ->add(['author_id' => 1])
      ->or_(['author_id' => 2]);
  });

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

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

Параметры

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

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

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

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

Возвращает

mixed
$this

См. также

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

ordersource 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

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

Параметры

array|Cake\Database\ExpressionInterface|string $fields

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

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

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

Возвращает

mixed
$this

orderAscsource public

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

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

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

Параметры

string|Cake\Database\Expression\QueryExpression $field

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

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

Нужно ли сбрасывать условия сортировки.

Возвращает

mixed
$this

orderDescsource public

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

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

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

Параметры

string|Cake\Database\Expression\QueryExpression $field

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

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

Нужно ли сбрасывать условия сортировки.

Возвращает

mixed
$this

pagesource public

page( integer $num , integer $limit null )

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

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

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

Параметры

integer $num

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

integer $limit необязательно null

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

Возвращает

mixed
$this

removeJoinsource public

removeJoin( string $name )

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

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

Параметры

string $name

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

Возвращает

mixed
$this

rightJoinsource 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 необязательно []

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

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

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

Возвращает

mixed
$this

selectsource public

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

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

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

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

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

Примеры:

$query->select(['id', 'title']); // Produces SELECT id, title
$query->select(['author' => 'author_id']); // Appends author: SELECT id, title, author_id as author
$query->select('id', true); // Resets the list: SELECT id
$query->select(['total' => $countQuery]); // SELECT id, (SELECT ...) AS total
$query->select(function ($query) {
    return ['article_id', 'total' => $query->count('*')];
})

По умолчанию поля не выбраны. Если у вас есть экземпляр Cake\ORM\Query и вы хотите добавить поля, вам также нужно вызвать Cake\ORM\Query::autoFields() для выбора стандартных полей из таблицы.

Параметры

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

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

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

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

Возвращает

mixed
$this

setsource 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 необязательно null

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

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

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

Возвращает

mixed
$this

sqlsource public

sql( Cake\Database\ValueBinder $generator null )

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

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

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

Параметры

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

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

Возвращает

string
строка

Реализация

Cake\Database\ExpressionInterface::sql()

traversesource 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

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

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

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

Возвращает

mixed
$this

Реализация

Cake\Database\ExpressionInterface::traverse()

traverseExpressionssource public

traverseExpressions( callable $callback )

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

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

Параметры

callable $callback

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

Возвращает

mixed
$this|null

typesource public

type( )

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

Возвращает

string
строка

unionsource 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

Параметры

string|Cake\Database\Query $query

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

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

должен ли список запросов быть сброшен

Возвращает

mixed
$this

unionAllsource 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

Параметры

string|Cake\Database\Query $query

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

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

должен ли список запросов быть сброшен

Возвращает

mixed
$this

updatesource public

update( string $table )

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

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

Параметры

string $table

Таблица, которую вы хотите обновить.

Возвращает

mixed
$this

valueBindersource public

valueBinder( Cake\Database\ValueBinder $binder null )

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

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

Параметры

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

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

Возвращает

mixed
$this|\Cake\Database\ValueBinder

valuessource public

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

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

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

Параметры

array|Cake\Database\Query $data

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

Возвращает

mixed
$this

Исключения

Cake\Database\Exception
если вы попытаетесь установить значения до объявления столбцов. Или если вы попытаетесь установить значения для запросов, не являющихся insert.

wheresource 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])->type('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 необязательно []

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

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

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

Возвращает

mixed
$this

См. также

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

defaultTypessource public

defaultTypes( array $types null )

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

Параметры

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

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

Возвращает

mixed
$this|массив

typeMapsource public

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

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

Параметры

массив|Cake\Database\TypeMap $typeMap необязательно null

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

Возвращает

mixed
$this|TypeMap

false

[
    'delete' => true,
    'update' => [],
    'set' => [],
    'insert' => [],
    'values' => [],
    'select' => [],
    'distinct' => false,
    'modifier' => [],
    'from' => [],
    'join' => [],
    'where' => null,
    'group' => [],
    'having' => null,
    'order' => null,
    'limit' => null,
    'offset' => null,
    'union' => [],
    'epilog' => null
]

[]

'select'

true