Класс Query

__clone()source public

__clone( )

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

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

__construct()source public

__construct( Cake\Database\Connection $connection )

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

Параметры

Cake\Database\Connection $connection

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

__debugInfo()source public

__debugInfo( )

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

Возвращает

массив

__toString()source public

__toString( )

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

Возвращает

строка

_conjugate()source protected

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

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

Параметры

строка $part

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

строка|null|массив|Cake\Database\ExpressionInterface|callable $append

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

строка $conjunction

тип союза для использования в операции части

массив $types

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

_decorateStatement()source protected

_decorateStatement( Cake\Database\StatementInterface $statement )

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

Параметры

Cake\Database\StatementInterface $statement

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

Возвращает

Cake\Database\Statement\CallbackStatement

_dirty()source protected

_dirty( )

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

_makeJoin()source protected

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

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

Параметры

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

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

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

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

строка $type

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

Возвращает

массив

andHaving()source public

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

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

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

Параметры

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

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

массив $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)

Параметры

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

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

массив $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.

Параметры

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

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

смешанное $value

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

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

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

Возвращает

$this

bufferResults()source public

bufferResults( boolean|null $enable null )

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

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

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

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

Устарело

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

Параметры

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

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

Возвращает

логическое значение|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: строка Имя таблицы для обновления
• 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

имя пункта, которое нужно вернуть

Возвращает

смешанное

Исключения

InvalidArgumentException
При отсутствии пункта с указанным именем.

connection()source public

connection( Cake\Database\Connection|null $connection 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;
});

Параметры

функция обратного вызова|null $callback

Функция обратного вызова, которая будет вызвана при извлечении результатов.

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

Указывает, будет ли добавлен или заменён весь существующий декоратор.

Возвращает

$this

delete()source public

delete( string|null $table null )

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

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

Параметры

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

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

Возвращает

$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-представление этого запроса и выполняет его с помощью объекта подключенного соединения. Возвращает объект полученного оператора.

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

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

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

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

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(), пожалуйста, обратитесь к описанию этого метода для получения дополнительной информации.

Параметры

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

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

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

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

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

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

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

$this

insert()source public

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

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

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

Параметры

массив $columns

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

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

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

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

$this

Исключения

RuntimeException
Если количество столбцов равно 0.

into()source public

into( string $table )

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

Параметры

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

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

Возвращает

$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().

Параметры

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

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

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

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

Возвращает

$this

orderAsc()source public

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

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

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

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

Параметры

строка|Cake\Database\Expression\QueryExpression $field

Поле, по которому нужно выполнить сортировку.

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

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

Возвращает

$this

orderDesc()source public

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

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

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

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

Параметры

строка|Cake\Database\Expression\QueryExpression $field

Поле, по которому нужно выполнить сортировку.

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

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

Возвращает

$this

page()source public

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

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

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

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

Параметры

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

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

целое число|null $limit необязательно null

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

Возвращает

$this

removeJoin()source public

removeJoin( string $name )

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

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

Параметры

строка $name

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

Возвращает

$this

rightJoin()source public

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

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

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

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

Параметры

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

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

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

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

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

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

Возвращает

$this

rowCountAndClose()source public

rowCountAndClose( )

Выполняет SQL-запрос и немедленно закрывает оператор, прежде чем возвращать количество строк изменённых записей.

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

Пример

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

В приведённом примере столбец published будет изменён на true для всех записей, где он был false, и будет возвращено количество обновлённых записей.

Возвращает

целое число

select()source public

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

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

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

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

По умолчанию эта функция добавляет все переданные аргументы в список полей для выбора, если только второй аргумент не установлен в значение 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::enableAutoFields() для выбора полей по умолчанию из таблицы.

Параметры

массив|Cake\Database\ExpressionInterface|строка|вызываемый объект (callable) $fields необязательно []

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

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

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

Возвращает

$this

selectTypeMap()source public

selectTypeMap( Cake\Database\TypeMap $typeMap null )

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

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

Устарело

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

Параметры

Cake\Database\TypeMap $typeMap необязательно 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']);

Передача вызываемого объекта (callable):

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

Параметры

строка|массив|вызываемый объект (callable)|Cake\Database\Expression\QueryExpression $key

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

смешанный тип $value необязательно null

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

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

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

Возвращает

$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

sql()source public

sql( Cake\Database\ValueBinder $generator null )

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

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

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

Параметры

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

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

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

string

Реализация

Cake\Database\ExpressionInterface::sql()

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)

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

string

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

Параметры

string|Cake\Database\Query $query

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

boolean $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

Параметры

string|Cake\Database\Query $query

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

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

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

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

$this

update()source public

update( string|Cake\Database\ExpressionInterface $table )

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

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

Параметры

string|Cake\Database\ExpressionInterface $table

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

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

$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 )

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

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

Параметры

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

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

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

$this

Исключения

Cake\Database\Exception

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

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

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

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

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

Возвращает

$this

См.

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

defaultTypes()source public

defaultTypes( array $types null )

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

Устаревшее

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

Параметры

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

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

Возвращает

$this|массив

getDefaultTypes()source public

getDefaultTypes( )

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

Возвращает

массив

getTypeMap()source public

getTypeMap( )

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

Возвращает

Cake\Database\TypeMap

setDefaultTypes()source public

setDefaultTypes( array $types )

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

Параметры

массив $types

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

Возвращает

$this

setTypeMap()source public

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

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

Параметры

массив|Cake\Database\TypeMap $typeMap

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

Возвращает

$this

typeMap()source public

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

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

Устаревшее

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

Параметры

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

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

Возвращает

$this|\Cake\Database\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'

false

true