Конструктор запросов


Оглавление



Введение #

К оглавлению

Конструктор запросов представлен компонентом DbCommand. По умолчанию он использует драйвер PDO и СУБД MySQL. Если нужна другиая СУБД, то можно прописать настройку в конфигурации.
1
2
3
4
5

          'db_command'    => [ 
                               'db_type' => 'Postgre'   // Тип используемой СУБД 
          ], 



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

Конструктор запросов предоставляет объектно-ориентированный способ написания SQL-запросов. Он позволяет разработчику использовать методы и свойства класса для того, чтобы указать отдельные части SQL-запроса. Затем конструктор собирает отдельные части в единый SQL-запрос. Следующий код показывает типичное использование конструктора для создания SQL-запроса SELECT:
1
2
3
4
5
6
7
8
9

        $command = \ABC::newService(\ABC::DB_COMMAND); 

        $user = $command->select('id, username, profile') 
                        ->from('user u') 
                        ->innerJoin('profile p', 'u.id=p.user_id') 
                        ->where('id=:id',  [':id' => $id] ) 
                        ->queryRow(); 


Этот код сгенерирует и выполнит следующий запрос:
1
2
3
4
5
6

SELECT `id` , `username` , `profile`
FROM `abc_user` `u`
INNER JOIN `abc_profile` `p` ON `u`.`id` = `p`.`user_id`
WHERE id = '5'


Конструктор запросов лучше всего использовать в том случае, когда необходимо собрать SQL-запрос, следуя некоторой условной логике приложения. Основными достоинствами конструктора запросов являются:

  • Возможность собрать сложный SQL-запрос программно.

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

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

  • Слой абстракции, упрощающий переход на другие СУБД.

Существуют два способа работы с SQL-запросами. C помощью методов конструктора, как показано выше, либо с помощью метода createCommand():

1
2
3
4
5
6
7
8
9

        $command = \ABC::newService(\ABC::DB_COMMAND); 

        $result = $command->createCommand("SELECT * FROM abc_user u     
                                            INNER JOIN abc_profile p ON u.id = p.user_id    
                                            WHERE id = :id")  
                          ->bindValue(':id',  5) 
                          ->queryRow();



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

Хотя этот метод автоматически не экранирует поля, его использование предпочтительнее, если требуется экономия ресурсов. Он рекомендован тогда, когда не нужно собирать запрос динамически. А так же тогда, когда не требуются универсальные запросы для разных СУбД. Так как позволяет писать любые запросы с учетом специфики выбранной базы данных.

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

Если нужен универсальный для всех баз код, вы можете использовать следующий синтаксис экранирования
  • [[column name]]: заключайте имя столбца в двойные квадратные скобки;
  • {{table name}}: заключайте имя таблицы в двойные фигурные скобки.


1
2
3
4
5
6
7
8

        $command = \ABC::newService(\ABC::DB_COMMAND); 

        $result = $command->createCommand("SELECT [[id]] FROM {{table}}   
                                            WHERE [[id]] = :id") 
                          ->bindValue(':id',  5) 
                          ->queryRow(); 



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

Для каждого нового запроса типа SELEСT нужно использовать либо новый объект конструктора, либо очищать старый методом reset()



Конструктор запросов предоставляет следующие публичные методы #

К оглавлению

1 addOrder() Добавляет дополнительные параметры к существующему ORDER BY
2 addGroup() Добавляет дополнительные параметры к существующему GROUP BY.
3 addSelect() Добавляет дополнительные параметры к существующему SELECT
4 andHaving() Добавляет дополнительное условие к существующему HAVING через AND
5 andWhere() Добавляет дополнительное условие к существующему WHERE через AND
6 batchInsert() Множественная вставка
7 beginTransaction() Стартует транзакцию
8 bindParam() Связывает значение с параметром по ссылке
9 bindValue() Связывает значение с параметром
10 bindValues() Связывает список значений с соответствующими параметрами
11 close() Освобождает ресурсы, выделенные для выполнения текущего запроса
12 commit() Фиксирует транзакцию
13 count() Возвращает количество строк текущего запроса
14 createCommand() Выполняет произвольный запрос
15 crossJoin Добавляет часть CROSS JOIN к запросу
16 delete() Удаляет строки
17 execute() Выполняет инструкцию SQL
18 expression() Создает объект выражения
19 from() Устанавливает часть запроса FROM
20 getSql() Получает текст запроса
21 group() Устанавливает часть запроса GROUP BY
22 having() Устанавливает часть запроса HAVING
23 innerJoin() Добавляет часть INNER JOIN к запросу
24 insert() Вставляет строки
25 join() Добавляет часть (XXX) JOIN к запросу
26 leftJoin() Добавляет часть LEFT JOIN к запросу
27 limit() Устанавливает часть запроса LIMIT
28 naturalJoin() Добавляет часть NATURAL JOIN к запросу
29 offset() Устанавливает часть запроса OFFSET
30 order() Устанавливает часть запроса LIMIT
31 orHaving() Добавляет дополнительное условие к существующему HAVING через OR
32 orWhere() Добавляет дополнительное условие к существующему WHERE через OR
33 queryAll() Выполняет запрос и возвращает все строки
34 queryColumn() Выполняет запрос и возвращает одну колонку
35 queryObject() Выполняет запрос и возвращает результат в виде объекта
36 queryOne() Псевдоним для queryRow()
37 queryRow() Выполняет запрос и возвращает ряд результата
38 queryScalar() Выполняет запрос и возвращает значение одной клонки одного ряда
39 reset() Очищает объект конструктора для нового запроса
40 rightJoin() Добавляет часть RIGHT JOIN к запросу
41 rollback() Откат транзакции
42 select() Устанавливает часть запроса SELECT
43 selectDistinct() Устанавливает часть запроса SELECT с включенным флагом DISTINCT
44 setDb() Устанавливает новую базу данных
45 setPrefix() Устанавливает новый префикс таблиц
46 subQuery() Возвращает новый объект компонента для вложенного запроса
47 test() Тестирует запрос
48 transaction() Оборачивает запросы в транзакцию
49 union() Добавляет операцию SQL, используя оператор UNION
50 unsetPrefix() Удаляет префиксы таблиц
51 update() Обновляет данные в строках
52 where() Устанавливает часть запроса WHERE


Запросы на выборку данных #

К оглавлению

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

  • select(): часть запроса после SELECT.
  • selectDistinct(): часть запроса после SELECT. Добавляет DISTINCT.
  • addSelect(): дополнительные параметры для SELECT.
  • from(): часть запроса после FROM.
  • join(): добавляет к запросу (XXX) JOIN.
  • innerJroin(): добавляет к запросу INNER JOIN.
  • leftJoin(): добавляет к запросу LEFT JOIN.
  • rightJoin(): добавляет к запросу RIGHT JOIN.
  • crossJoin(): добавляет к запросу CROSS JOIN.
  • naturalJoin(): добавляет к запросу NATURAL JOIN.
  • where(): часть запроса после WHERE.
  • andWhere(): дополнительные условия для WHERE через AND.
  • orWhere(): дополнительные условия для WHERE через OR.
  • group(): часть запроса после GROUP BY.
  • addGroup(): добавляет параметры для GROUP BY.
  • having(): часть запроса после HAVING.
  • andHaving(): дополнительные условия для HAVING через AND.
  • orHaving(): дополнительные условия для HAVING через OR.
  • order(): часть запроса после ORDER BY.
  • addOrder(): добавляет параметры для ORDER BY.
  • limit(): часть запроса после LIMIT.
  • offset(): часть запроса после OFFSET.
  • union(): часть запроса после UNION.




select() public method

Устанавливает часть запроса SELECT.

К разделу

Метод select() задаёт часть запроса от SELECT. Параметр $columns определяет выбираемые поля и может быть либо списком имён выбираемых полей, разделённых запятой, либо массивом имён полей. Имена могут содержать префиксы таблиц и псевдонимы полей. Метод автоматически экранирует имена, если в них нет скобок (что означает использование выражения).

public DbCommand::select ( $columns = '*', $options = '' )
$columns mixed Столбцы для выбора. По умолчанию используется значение '*', что означает все столбцы. Столбцы могут быть указаны либо в строке (например, 'id, имя'), либо в массиве (например, ['id', 'name']). Столбцы могут содержать префиксы таблиц (например, 'tbl_user.id') и / или псевдонимы столбцов (например, 'tbl_user.id AS user_id'). Метод автоматически процитирует имена столбцов, если только столбец не содержит скобок (что означает, что столбец содержит выражение DB).
Чтобы передать в метод выражение, можно воспользоваться методом expression()
Когда поля указаны как массивы, вы также можете использовать ключи массива в качестве псевдонимов (если полю не нужен псевдоним, не используйте строковый ключ).
См. примеры.
$options string Дополнительная опция, которая может быть добавлена к ключевому слову 'SELECT'. Например, в MySQL можно использовать опцию 'SQL_CALC_FOUND_ROWS'.
return object Текущий объект компонента.


Примеры: #

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

// SELECT *  
 ->select()  

// SELECT `id`, `username`  
 ->select('id, username')  

// SELECT `tbl_user`.`id`, `username` AS `name`  
 ->select('tbl_user.id, username as name')  

// SELECT `id`, `username`  
 ->select(array('id', 'username'))  

// SELECT `tbl_user`.`id`, count(*) as num  
 ->select(array('tbl_user.id', 'count(*) as num')) 

// SELECT `tbl_user`.`username` `u`, `profile` `p` 
 ->select(array('u' => 'tbl_user.username', 'p' => 'profile')) 

// SELECT FOUND_ROWS() 
 ->select($command->expression('FOUND_ROWS()')) 

// SELECT COUNT(*) `num`  
 ->select(array('num' => $command->expression('COUNT(*)')))  

//SELECT SQL_CALC_FOUND_ROWS `id`, `username` 
 ->select('id, username', 'SQL_CALC_FOUND_ROWS'





addSelect() public method

Добавляет параметры к существующему SELECT.

К разделу

Метод добавит через запятую одно или несколько полей в уже сформированую часть SELECT.

public DbCommand::addSelect ( $columns = '*' )
$columns mixed Столбцы для выбора. По умолчанию используется значение '*', что означает все столбцы. Столбцы могут быть указаны либо в строке (например, 'id, имя'), либо в массиве (например, ['id', 'name']). Столбцы могут содержать префиксы таблиц (например, 'tbl_user.id') и / или псевдонимы столбцов (например, 'tbl_user.id AS user_id'). Метод автоматически процитирует имена столбцов, если только столбец не содержит скобок (что означает, что столбец содержит выражение DB).
Чтобы передать в метод выражение, можно воспользоваться методом expression()
Когда поля указаны как массивы, вы также можете использовать ключи массива в качестве псевдонимов (если полю не нужен псевдоним, не используйте строковый ключ).
См. примеры.
return object Текущий объект компонента.




selectDistinct() public method

Устанавливает часть запроса SELECT.

К разделу

То же самое, что и select(), только с добавлением флага DISTINCT.

public DbCommand::selectDistinct ( $columns = '*', $options = '' )
$columns mixed Столбцы для выбора. По умолчанию используется значение '*', что означает все столбцы. Столбцы могут быть указаны либо в строке (например, 'id, имя'), либо в массиве (например, ['id', 'name']). Столбцы могут содержать префиксы таблиц (например, 'tbl_user.id') и / или псевдонимы столбцов (например, 'tbl_user.id AS user_id'). Метод автоматически процитирует имена столбцов, если только столбец не содержит скобок (что означает, что столбец содержит выражение DB).
Чтобы передать в метод выражение, можно воспользоваться методом expression()
Когда поля указаны как массивы, вы также можете использовать ключи массива в качестве псевдонимов (если полю не нужен псевдоним, не используйте строковый ключ).
См. примеры.
$options string Дополнительная опция, которая может быть добавлена к ключевому слову 'SELECT'. Например, в MySQL можно использовать опцию 'SQL_CALC_FOUND_ROWS'.
return object Текущий объект компонента.




from() public method

Устанавливает часть запроса FROM.

К разделу

Метод from() задаёт часть запроса после FROM. Параметр $tables определяет, из каких таблиц производится выборка, и может быть либо списком имён таблиц, разделённых запятыми, либо массивом имён таблиц. Имена могут содержать префиксы схемы (такие, как public.tbl_user) и псевдонимы таблиц (такие, как tbl_user u). Метод автоматически экранирует имена, если в них нет скобок (что означает использование подзапроса или выражения).

public DbCommand::from ( $tables )
$tables string|array Таблица (ы), которую нужно выбрать. Это может быть строка (например, 'user') или массив (например, ['user', 'profile']), указывающий одно или несколько имен таблиц. Имена таблиц могут содержать префиксы схем (например, 'public.user') и/или псевдонимы таблиц (например, 'user u'). Метод будет автоматически экранировать имена таблиц, если он не содержит скобок (это означает, что таблица задана в виде подзапроса или выражения DB).
Когда таблицы указаны как массивы, вы также можете использовать ключи массива в качестве псевдонимов таблицы (если таблице не нужен псевдоним, не используйте строковый ключ).
Для представления подзапроса можно использовать новый объект компонента, либо воспользоваться методом subQuery(). В этом случае соответствующий ключ массива будет использоваться в качестве псевдонима для подзапроса.
return object Текущий объект компонента.


Примеры: #

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// FROM `user` `u`, `profile`   
 ->from('user u', 'profile')   

// FROM `user` `u`, `profile` `p`   
 ->from(array('u' => 'user', 'p' => 'profile'))   

// FROM `user`, (SELECT * FROM profile) p   
 ->from(array('user', '(SELECT * FROM profile) p')) 

// FROM `table`.`user` `u`, `profile` `p`   
 ->from(array('u' => 'table.user', 'profile p')) 

// FROM (SELECT * FROM `user`)  `u`   
$subquery = $command->subQuery()->select()->from('user');   
 ->from(array('u' => $subquery))   
 
 






where() public method

Устанавливает часть запроса WHERE.

К разделу

Метод where() задаёт часть запроса после WHERE. Параметр $conditions определяет условия запроса, а $params — параметры, которые подставляются в запрос. Значение параметра $conditions может быть как строкой (например, id=1), так и массивом следующего вида:
array(operator, operand1, operand2, ...)


Операторы могу быть:

  • and: операнды соединяются при помощи AND. Если операнд является массивом, то он будет преобразован в строку с использованием описанных здесь правил. Данный метод ничего НЕ экранирует.

  • or: то же, что и and, но для OR.

  • in: первый операнд должнен быть столбцом или выражением, второй — массивом, содержащим список значений, в которые должно входить значение поля или выражения. Метод экранирует имя столбца и значения в списке.

  • not in: то же, что и in, но вместо IN используется NOT IN.

  • like: первый операнд должен быть именем поля или выражением, второй — строкой или массивом, содержащим список значений, на которые должно быть похоже значение поля или выражения. Когда список значений является массивом, генерируется несколько LIKE, соединённых при помощи AND. Метод экранирует имена полей и значения в списке.

  • not like: то же, что и like, но вместо LIKE генерируется NOT LIKE.

  • or like: то же, что и like но для соединения LIKE используется OR.

  • or not like: то же, что и not like но для соединения NOT LIKE используется OR.

  • >, <= , или другие валидные операторы БД, которые требуют двух операндов: первый операнд должен быть именем столбца, второй операнд это значение.
    Например, ['>', 'id', 5] сформирует id > 5.

public DbCommand::where ( $conditions, $params = [] )
$conditions string|array|object Условия, которые должны быть включены в часть WHERE
$params array Параметры (name => value) должны быть привязаны к запросу
return object Текущий объект компонента.


Примеры: #

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

// WHERE id=1 or id=2   
 ->where('id=1 or id=2')   

// WHERE id=:id1 or id=:id2   
 ->where('id=:id1 or id=:id2', array(':id1'=>1, ':id2'=>2))   

// WHERE id=1 OR id=2   
 ->where(array('or', 'id=1', 'id=2'))   

// WHERE id=1 AND (type=2 OR type=3)   
 ->where(array('and', 'id=1', array('or', 'type=2', 'type=3')))   

// WHERE `id` IN ('1', '2')   
 ->where(array('in', 'id', array(1, 2)))   

// WHERE `id` NOT IN ('1', '2')   
 ->where(array('not in', 'id', array(1, 2)))   

// WHERE `name` LIKE '%Qiang%'   
 ->where(array('like', 'name', '%Qiang%'))   

// WHERE `name` LIKE '%Qiang' AND `name` LIKE '%Xue'   
 ->where(array('like', 'name', array('%Qiang', '%Xue')))   

// WHERE `name` LIKE '%Qiang' OR `name` LIKE '%Xue'   
 ->where(array('or like', 'name', array('%Qiang', '%Xue')))   

// WHERE `name` NOT LIKE '%Qiang%'   
 ->where(array('not like', 'name', '%Qiang%'))   

// WHERE `name` NOT LIKE '%Qiang%' OR `name` NOT LIKE '%Xue%'   
 ->where(array('or not like', 'name', array('%Qiang%', '%Xue%'))) 

// WHERE `id` > 5  
 ->where(array('>', 'id', 5)) 

// WHERE `user` = 'anonimus' 
 ->where(array('=', 'user', ':user'), array(':user' => 'anonimus')) 





andWhere() public method

Добавляет дополнительное условие WHERE к существующему.

К разделу

Существующие и новые условия будут объеденены через оператор AND.


public DbCommand::andWhere ( $conditions, $params = [] )
$conditions string|array|object Условия, которые должны быть добавлены в часть WHERE. Oбратитесь к документации where() для более подробной информации о определении условий.
$params array Параметры (name => value) должны быть привязаны к запросу
return object Текущий объект компонента.




orWhere() public method

Добавляет дополнительное условие WHERE к существующему.

К разделу

Существующие и новые условия будут объеденены через оператор OR.


public DbCommand::orWhere ( $conditions, $params = [] )
$conditions string|array|object Условия, которые должны быть добавлены в часть WHERE. Oбратитесь к документации where() для более подробной информации о определении условий.
$params array Параметры (name => value) должны быть привязаны к запросу
return object Текущий объект компонента.




join() public method

Добавляет к запросу часть JOIN.

К разделу

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


public DbCommand::join ( $type, $table, $on = '' )
$type string Тип присоединения, такой как INNER JOIN, LEFT JOIN и т.д.
$table string Имя таблицы, которая должна быть присоединена
$on string|array|object Необязательное условие объединения, то есть фрагмент ON. Может быть либо строкой, либо массивом.
Пожалуйста, обратитесь к документации для where() для более подробной информации о определении условий. Отметим, что синтаксис массивов не работает для задания условий для столбцов, то есть ['user.id' => 'comment.userId'] будет означать условие, где ID пользователя должен быть равен строке 'comment.userId'.
Вместо этого стоит указывать условие в виде строки 'user.id = comment.userId'.
Так же может быть объектом, сформированным методом expression()
return object Текущий объект компонента.


Примеры: #

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// ... INNER JOIN  `post`  
 ->join('INNER JOIN', 'post'); 

// ... LEFT JOIN  `post` ON `post`.`user_id` = `user`.`id` 
 ->join('LEFT JOIN', 'post', 'post.user_id = user.id'); 

// ... RIGHT JOIN  `abc_post` `p` ON (id=1 AND (p.type=2 OR p.type=3))     
 ->join('RIGHT JOIN', 'post p', array('and', 'id=1', array('or', 'p.type=2', 'p.type=3'))) 

// ... INNER JOIN  `post` `p` ON (p.date < NOW())  
 ->join('INNER JOIN', 'post p', $command->expression('p.date < NOW()')) 






innerJoin() public method

Добавляет к запросу часть INNER JOIN.

К разделу

Добавляет к запросу INNER JOIN. В отличие от join() не требует указания типа и имеет два параметра


public DbCommand::innerJoin ( $table, $on = '' )
$table string Имя таблицы, которая должна быть присоединена
$on string|array|object Необязательное условие объединения, то есть фрагмент ON. Может быть либо строкой, либо массивом.
Пожалуйста, обратитесь к документации для where() для более подробной информации о определении условий. Отметим, что синтаксис массивов не работает для задания условий для столбцов, то есть ['user.id' => 'comment.userId'] будет означать условие, где ID пользователя должен быть равен строке 'comment.userId'.
Вместо этого стоит указывать условие в виде строки 'user.id = comment.userId'.
Так же может быть объектом, сформированным методом expression()
return object Текущий объект компонента.




leftJoin() public method

Добавляет к запросу часть LEFT JOIN.

К разделу

Добавляет к запросу LEFT JOIN. В отличие от join() не требует указания типа и имеет два параметра


public DbCommand::leftJoin ( $table, $on = '' )
$table string Имя таблицы, которая должна быть присоединена
$on string|array|object Необязательное условие объединения, то есть фрагмент ON. Может быть либо строкой, либо массивом.
Пожалуйста, обратитесь к документации для where() для более подробной информации о определении условий. Отметим, что синтаксис массивов не работает для задания условий для столбцов, то есть ['user.id' => 'comment.userId'] будет означать условие, где ID пользователя должен быть равен строке 'comment.userId'.
Вместо этого стоит указывать условие в виде строки 'user.id = comment.userId'.
Так же может быть объектом, сформированным методом expression()
return object Текущий объект компонента.




rightJoin() public method

Добавляет к запросу часть RIGHT JOIN.

К разделу

Добавляет к запросу RIGHT JOIN. В отличие от join() не требует указания типа и имеет два параметра


public DbCommand::rightJoin ( $table, $on = '' )
$table string Имя таблицы, которая должна быть присоединена
$on string|array|object Необязательное условие объединения, то есть фрагмент ON. Может быть либо строкой, либо массивом.
Пожалуйста, обратитесь к документации для where() для более подробной информации о определении условий. Отметим, что синтаксис массивов не работает для задания условий для столбцов, то есть ['user.id' => 'comment.userId'] будет означать условие, где ID пользователя должен быть равен строке 'comment.userId'.
Вместо этого стоит указывать условие в виде строки 'user.id = comment.userId'.
Так же может быть объектом, сформированным методом expression()
return object Текущий объект компонента.




crossJoin() public method

Добавляет к запросу часть CROSS JOIN.

К разделу

Добавляет к запросу CROSS JOIN. В отличие от join() не требует указания типа и имеет два параметра


public DbCommand::crossJoin ( $table, $on = '' )
$table string Имя таблицы, которая должна быть присоединена
$on string|array|object Необязательное условие объединения, то есть фрагмент ON. Может быть либо строкой, либо массивом.
Пожалуйста, обратитесь к документации для where() для более подробной информации о определении условий. Отметим, что синтаксис массивов не работает для задания условий для столбцов, то есть ['user.id' => 'comment.userId'] будет означать условие, где ID пользователя должен быть равен строке 'comment.userId'.
Вместо этого стоит указывать условие в виде строки 'user.id = comment.userId'.
Так же может быть объектом, сформированным методом expression()
return object Текущий объект компонента.




naturalJoin() public method

Добавляет к запросу часть NATURAL JOIN.

К разделу

Добавляет к запросу NATURAL JOIN. В отличие от join() не требует указания типа и имеет два параметра


public DbCommand::naturalJoin ( $table, $on = '' )
$table string Имя таблицы, которая должна быть присоединена
$on string|array|object Необязательное условие объединения, то есть фрагмент ON. Может быть либо строкой, либо массивом.
Пожалуйста, обратитесь к документации для where() для более подробной информации о определении условий. Отметим, что синтаксис массивов не работает для задания условий для столбцов, то есть ['user.id' => 'comment.userId'] будет означать условие, где ID пользователя должен быть равен строке 'comment.userId'.
Вместо этого стоит указывать условие в виде строки 'user.id = comment.userId'.
Так же может быть объектом, сформированным методом expression()
return object Текущий объект компонента.




group() public method

Формирует часть запроса после GROUP BY

К разделу

Метод определяет фрагмент GROUP BY SQL запроса.


public DbCommand::group ( $columns)
$columns string|array|object Столбцы, которые нужно сгруппировать.
Столбцы могут быть указаны либо в строке (например, 'id, name'), либо в массиве (например, ['id', 'name']). Метод автоматически экранирует имена столбцов, если только столбец не содержит скобок (что означает, что столбец содержит выражение DB).
Обратите внимание, что если ваша группа - это выражение, содержащее запятые, вы всегда должны использовать массив для представления информации по группам. В противном случае метод не сможет правильно определить столбцы группы.
Так же может быть объектом, сформированным методом expression()
return object Текущий объект компонента.


Примеры: #

1
2
3
4
5
6
7
8
9
10
11
12
13

// ... GROUP BY `date`  
 ->group('date')  

// ... GROUP BY `tbl`.`date` ASC, `tbl`.`user` DESC  
 ->group('tbl.date asc, tbl.user desc')  

// ... GROUP BY `tbl`.`date` ASC, `tbl`.`user` DESC  
 ->group(array('asc' => 'tbl.date', 'tbl.user desc')) 

// ... GROUP BY date DESC  
 ->group($command->expression('date DESC'))  





addGroup() public method

Добавляет поля в GROUP BY

К разделу

К разделу-align: justify;">Метод добавляет поля или выражения в сформированную методом group() часть GROUP BY SQL запроса.


public DbCommand::addGroup ( $columns)
$columns string|array|object Столбцы, которые нужно сгруппировать.
Столбцы могут быть указаны либо в строке (например, 'id, name'), либо в массиве (например, ['id', 'name']). Метод автоматически экранирует имена столбцов, если только столбец не содержит скобок (что означает, что столбец содержит выражение DB).
Обратите внимание, что если ваша группа - это выражение, содержащее запятые, вы всегда должны использовать массив для представления информации по группам. В противном случае метод не сможет правильно определить столбцы группы.
Так же может быть объектом, сформированным методом expression()
return object Текущий объект компонента.




having() public method

Устанавливает часть запроса HAVING.

К разделу

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

public DbCommand::having ( $conditions, $params = [] )
$conditions string|array|object Условия, которые должны быть включены в часть HAVING. Oбратитесь к документации where() для более подробной информации о определении условий.
$params array Параметры (name => value) должны быть привязаны к запросу
return object Текущий объект компонента.




andHaving() public method

Добавляет дополнительное условие HAVING к существующему.

К разделу

Существующие и новые условия будут объеденены через оператор AND.


public DbCommand::andHaving ( $conditions, $params = [] )
$conditions string|array|object Условия, которые должны быть добавлены в часть HAVING. Oбратитесь к документации where() для более подробной информации о определении условий.
$params array Параметры (name => value) должны быть привязаны к запросу
return object Текущий объект компонента.




orHaving() public method

Добавляет дополнительное условие HAVING к существующему.

К разделу

Существующие и новые условия будут объеденены через оператор OR.


public DbCommand::orHaving ( $conditions, $params = [] )
$conditions string|array|object Условия, которые должны быть добавлены в часть HAVING. Oбратитесь к документации where() для более подробной информации о определении условий.
$params array Параметры (name => value) должны быть привязаны к запросу
return object Текущий объект компонента.




order() public method

Формирует часть запроса после ORDER BY

К разделу

Метод определяет фрагмент ORDER BY SQL запроса.


public DbCommand::order ( $columns)
$columns string|array|object Столбцы, которые нужно сгруппировать.
Столбцы могут быть указаны либо в строке (например, 'id, name'), либо в массиве (например, ['id', 'name']). Метод автоматически экранирует имена столбцов, если только столбец не содержит скобок (что означает, что столбец содержит выражение DB).
Обратите внимание, что если ваша группа - это выражение, содержащее запятые, вы всегда должны использовать массив для представления информации по группам. В противном случае метод не сможет правильно определить столбцы группы.
Так же может быть объектом, сформированным методом expression()
return object Текущий объект компонента.


Примеры: #

1
2
3
4
5
6
7
8
9
10
11
12
13

// ... ORDER BY `date`  
 ->order('date')  

// ... ORDER BY `tbl`.`date` ASC, `tbl`.`user` DESC  
 ->order('tbl.date asc, tbl.user desc')  

// ... ORDER BY `tbl`.`date` ASC, `tbl`.`user` DESC  
 ->order(array('asc' => 'tbl.date', 'tbl.user desc')) 

// ... ORDER BY date DESC  
 ->order($command->expression('date DESC'))  





addOrder() public method

Добавляет поля в ORDER BY

К разделу

Метод добавляет поля или выражения в сформированную методом order() часть ORDER BY SQL запроса.


public DbCommand::addOrder ( $columns)
$columns string|array|object Столбцы, которые нужно сгруппировать.
Столбцы могут быть указаны либо в строке (например, 'id, name'), либо в массиве (например, ['id', 'name']). Метод автоматически экранирует имена столбцов, если только столбец не содержит скобок (что означает, что столбец содержит выражение DB).
Обратите внимание, что если ваша группа - это выражение, содержащее запятые, вы всегда должны использовать массив для представления информации по группам. В противном случае метод не сможет правильно определить столбцы группы.
Так же может быть объектом, сформированным методом expression()
return object Текущий объект компонента.




limit() public method

Определяет фрагмент LIMIT

К разделу

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


public DbCommand::limit ( $limit, $offset = '')
$limit integer Значение ограничения числа записей
$offset integer Необязательный параметр, задающий смещение. Если не задан, отсчет начинается с первой записи.
return object Текущий объект компонента.


Примеры: #

1
2
3
4
5
6
7

// LIMIT 5 
 ->limit(5) 

// LIMIT 5 OFFSET 10 
 ->limit(5, 10) 





offset() public method

Определяет фрагмент OFFSET

К разделу

Задает смещение (номер строки, с которой начинать выборку).


public DbCommand::offset ( $offset )
$offset integer Параметр, задающий смещение.
return object Текущий объект компонента.


Примеры: #

1
2
3
4

// OFFSET 10 
 ->offset(10)





union() public method

Определяет фрагмент UNION

К разделу

Метод добавляет $sql к сгенерированному запросу, используя UNION. Несколько вызовов union() добавят несколько частей запроса.


public DbCommand::union ( $sql )
$sql string|array|object Текст запроса, который будет соединен с общим через оператор UNION. Может быть простой строкой, либо массивом из нескольких подзапросов. Так же может принимать объект, сформированный методом subQuery()
return object Текущий объект компонента.


Примеры: #

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// ... UNION SELECT * FROM users 
 ->union('SELECT * FROM users') 

// ... UNION SELECT * FROM table_1 UNION SELECT * FROM table_2 
 ->union(array('SELECT * FROM table_1', 'SELECT * FROM table_2')) 
  
// ... UNION SELECT * FROM `users` 
 ->union($command->subQuery()->select()->from('users'))  
  
// ... UNION SELECT * FROM `table_1` UNION SELECT * FROM `table_2` 
 $subquery1 = $command->subQuery()->select()->from('table_1'); 
 $subquery2 = $command->subQuery()->select()->from('table_2'); 

 ->union(array($subquery1, $subquery2)) 
 




Запросы на изменение данных #

К оглавлению

К запросам для изменения данных относятся SQL-запросы для вставки, обновления и удаления данных из базы. В конструкторе запросов есть соответствующие методы insert, batchInsert, update и delete.
Эти методы подготавливают запросы на изменение данных в таблицах. Они не выполняют запросы, для выполнения нужно вызвать метод execute().

  • insert(): Вставляет строку
  • batchInsert(): Вставляет несколько строк
  • update(): Изменяет данные в строках
  • delete(): Удаляет строки




insert() public method

Cтроит SQL-запрос INSERT.

К разделу

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


public DbCommand::insert ( $table, $columns )
$table string Таблица, в которую будут вставлены новые строки.
$columns array Данные столбца (name => value), которые должны быть вставлены в таблицу.
return object Текущий объект компонента.


Примеры: #

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

/*
    INSERT INTO `guest`
        (`author`, `text`, `date`) 
      VALUES 
        ('user', 'example', NOW())
*/
    $command->insert('guest', [
                               'author' => 'user',
                               'text'   => 'example',
                               'date'   => $command->expression('NOW()')
                              ]
              )->execute();
                
 





batchInsert() public method

Осуществляет множественную вставку командой INSERT.

К разделу

Параметр $table указывает, в какую таблицу производится вставка, а $columns является массивом имен полей. Третьим параметром нужно передать массив строк. Каждый элемент, это массив значений для строки. Сколько массивов будет передано, столько строк будет вставлено. Количество элементов в массивах строк должно совпадать с количеством элементов массива $columns.
Метод экранирует имя таблицы.


public DbCommand::batchInsert ( $table, $columns, $values )
$table string Таблица, в которую будут вставлены новые строки.
$columns array Имена полей, куда должны быть вставлены данные.
$values array Массив строк.
return object Текущий объект компонента.


Примеры: #

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

/*                
    INSERT INTO `guest`
        (`author`, `text`) 
      VALUES 
        ('user1', 'First text'),
        ('user2', 'Second text'),
        ('user3', 'Third text') 
*/                
    $command->batchInsert('guest', ['author', 'text'],
                            [
                                ['user1', 'First text'],
                                ['user2', 'Second text'],
                                ['user3', 'Third text']
                            ]
             )->execute();
                
 





update() public method

Метод строит SQL-запрос UPDATE.

К разделу

Параметр $table указывает обновляемую таблицу; $columns является массивом пар имя-значение, задающим значения обновляемых полей; $conditions и $params эквивалентны аналогичным параметрам в where() и определяют часть запроса UPDATE после WHERE.
Метод экранирует имя таблицы и использует параметры для обновляемых значений.


public DbCommand::update ( $table, $columns, $conditions = '', $params = [] )
$table string Таблица, в которой нужно изменить данные.
$columns array Данные столбца (name => value), которые должны быть изменены.
$values array Условия, которые будут помещены в часть WHERE. Пожалуйста, обратитесь документации where()
$params array Параметры, которые должны быть привязаны к запросу.
return object Текущий объект компонента.


Примеры: #

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

/* 
    UPDATE `guest`  
       SET `author` = 'user', 
           `text`   = 'New text', 
           `date`   = NOW()  
       WHERE id='5'     
*/         
    $command->update('guest', [ 
                                'author' => 'user', 
                                'text'   => "New text", 
                                'date'   => $command->expression('NOW()') 
                              ], 
                        'id=:id', [':id' => 5] 
              )->execute(); 

//  ИЛИ 

    $command->update('guest', [   
                                'author' => 'user',   
                                'text'   => "New text",   
                                'date'   => $command->expression('NOW()')   
                              ], 
                     'id=:id'   
              )->bindParam(':id', $id);   

    $id = 5;            
    $command->execute(); 





delete() public method

Метод строит SQL-запрос DELETE.

К разделу

Параметр $table указывает обновляемую таблицу; $columns является массивом пар имя-значение, задающим значения обновляемых полей; $conditions и $params эквивалентны аналогичным параметрам в where() и определяют часть запроса UPDATE после WHERE.
Метод экранирует имя таблицы и использует параметры для обновляемых значений.


public DbCommand::delete ( $table, $conditions = '', $params = [] )
$table string Таблица, из которой нужно удалить строки.
$values array Условия, которые будут помещены в часть WHERE. Пожалуйста, обратитесь документации where()
$params array Параметры, которые должны быть привязаны к запросу.
return object Текущий объект компонента.


Примеры: #

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

/*    
    DELETE FROM `guest` 
       WHERE id = '5'
*/
    $command->delete('guest', 'id = :id', [':id' => 5])
            ->execute();
            
            
/*    
    DELETE FROM `guest` 
       WHERE author = 'user' 
       LIMIT 1  
*/
    $command->delete('guests', 'author = :author')
            ->bindParam(':author', $author)
            ->limit(1);

    $author = 'user';         
    $command->execute();
 





Запросы на изменение таблиц #

К оглавлению

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





createTable() public method

Создает таблицу в базе данных

К разделу

Параметр $table задает имя создаваемой таблицы. Префиксы будут дбавлены автоматически; $columns является массивом пар имя-значение, задающим значения создаваемых полей и их типы;
$keys - массив ключей, задающий значения создаваемых ключей и их типы (ключ => тип);
$options, это строка, которая будет добавлена в конец запроса;
$exists добавит выражение IF NOT EXISTS
Метод экранирует имя таблицы.


public DbCommand:: createTable ( $table, $columns, $keys = [], $options = '', $exists = false )
$table string Имя создаваемой таблицы.
$columns array Массив столбцов, где в каждом элементе (name => type) задается имя колонки и ее тип.
$keys array Массив ключей, где в каждом элементе (name => type) задается имя ключа и его тип.
$options string Строка с опциями таблицы, которая будет добавлена в конец запроса.
$exists boolean Если значение true, будет добавлено выражение IF NOT EXISTS
return object Текущий объект компонента.


Примеры: #

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

    $command->createTable('news', [ 
                              'id'        => 'int(10) NOT NULL AUTO_INCREMENT',
                              'date'      => 'date NOT NULL',
                              'title'     => 'varchar(250) COLLATE utf8mb4_general_ci NOT NULL',
                              'text'      => 'text COLLATE utf8mb4_general_ci NOT NULL', 
                            ],
                                [ 
                                  'id'    => 'PRIMARY KEY'
                            ],
                          'ENGINE=InnoDB DEFAULT CHARSET=utf8mb4', true );


/*

CREATE TABLE IF NOT EXISTS  `news` (
    `id` int(10) NOT NULL AUTO_INCREMENT,
    `date` date NOT NULL,
    `title` varchar(250) COLLATE utf8mb4_general_ci NOT NULL,
    `text` text COLLATE utf8mb4_general_ci NOT NULL,
    PRIMARY KEY (`id`)
)
ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 

*/





renameTable() public method

Переименовывает таблицу БД

К разделу

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


public DbCommand:: renameTable ( $table, $newname )
$table string Имя переименовываемой таблицы
$newname string Новое имя таблицы
return object Текущий объект компонента.


Примеры: #

1
2
3
4
5

    $command->renameTable('news', 'world_news');
    
//  RENAME TABLE `news` TO `world_news`    





truncateTable() public method

Очищает таблицу

К разделу

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


public DbCommand:: truncateTable ( $table )
$table string Имя очищаемой таблицы
return object Текущий объект компонента.


Примеры: #

1
2
3
4
5
6

    $command->truncateTable('news');

//  TRUNCATE `news` 






dropTable() public method

Удаляет таблцу базы данных.

К разделу

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


public DbCommand:: dropTable ( $table )
$table string Имя удаляемой таблицы
return object Текущий объект компонента.


Примеры: #

1
2
3
4
5

    $command->dropTable('news');
    
//  DROP TABLE `news`





addColumns() public method

Добавляет колонки в таблицу.

К разделу

Метод предназначен для добавления новых столбцов в таблицу базы данных. Столбцы указываются в виде массива (имя => тип).


public DbCommand:: addColumns ( $table, $columns, $after = '')
$table string Имя удаляемой таблицы
$columns array Массив столбцов, где в каждом элементе (name => type) задается имя колонки и ее тип.
$after string Имя колонки, после которой начнется вставка. Если не указана, вставка начнется сначала таблицы.
return object Текущий объект компонента.


Примеры: #

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

    $command->addColumns('news',  [ 
                              'author'     => 'varchar(250) COLLATE utf8mb4_general_ci NOT NULL',
                              'public'     => 'int(1) NOT NULL DEFAULT \'0\'',
                          ], 
                          'text'
                        );
/*

ALTER TABLE `news` 
ADD     `author` varchar(250) COLLATE utf8mb4_general_ci NOT NULL AFTER `text`,
ADD     `public` int(1) NOT NULL DEFAULT '0' AFTER `author` 

*/

    $command->addColumns('news',  [    
                              'first'     => 'int(1) NOT NULL DEFAULT \'0\'',                            
                              'author'     => 'varchar(250) COLLATE utf8mb4_general_ci NOT NULL',
                          ]
                        );
/*

ALTER TABLE `news` 
ADD     `author` varchar(250) COLLATE utf8mb4_general_ci NOT NULL FIRST,
ADD     `public` int(1) NOT NULL DEFAULT '0' AFTER `first` 

*/






renameColumn() public method

Переименовывает колонку в таблице БД.

К разделу

Метод предназначен для изменения имени колонки. Типы сохраняются. Префикс таблицы подставляется автоматически.


public DbCommand:: renameColumn ( $table, $name, $newname)
$table string Имя таблицы, в которой переименовывается колонка
$name string Имя переименовываемой колонки.
$newname string Новое имя колонки.
return object Текущий объект компонента.


Примеры: #

1
2
3
4
5
6
7
8
9

        
    $command->renameColumn('news', 'text', 'content');

//    ALTER TABLE `news` RENAME COLUMN `text` TO `content`








afterColumn() public method

Переименовывает колонку в таблице БД.

К разделу

Метод предназначен для изменения имени колонки. Типы сохраняются. Префикс таблицы подставляется автоматически.


public DbCommand:: afterColumn ( $table, $name, $type)
$table string Имя таблицы, в которой переименовывается колонка
$name string Имя колонки, для которой меняется тип.
$type string Новый тип, который будет присвоен колонке.
return object Текущий объект компонента.


Примеры: #

1
2
3
4
5
6
7
8
9
10

        
        $command->afterColumn('news', 'date', 'datetime NOT NULL DEFAULT CURRENT_TIMESTAMP');


//    ALTER TABLE `mr_news` CHANGE `date` `date` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP








dropColumns() public method

Удаляет колонки из таблицы БД.

К разделу

Безвозвратно удалит указанные колонки вместе с данными. В параметре $columns можно перечислить удаляемые колонки через запятую, либо в виде массива. Убедитесь в сохранности данных.


public DbCommand:: dropColumns ( $table, $columns )
$table string Имя таблицы, из которой удаляются колонки.
$columns string|array Имена удаляемых колонкок через запятую либо массивом.
return object Текущий объект компонента.


Примеры: #
1
2
3
4
5
6
7
8
9
10
11
12
13
14

        
        $command->dropColumns('news', 'date, title');    
// ИЛИ
        $command->dropColumns('news', ['date', 'title']);    
    
/*

ALTER TABLE `news` 
     DROP `date`,
     DROP `title`
     
*/





addPrimaryKey() public method

Устанавливает первичный ключ.

К разделу

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


public DbCommand:: addPrimaryKey ( $table, $name )
$table string Имя таблицы, в которой устанавливается первичный ключ.
$name string Имя колонки, для которой установится первичный ключ.
return object Текущий объект компонента.


Примеры: #
1
2
3
4
5
6

    $command->addPrimaryKey('news', 'id');    
    
//    ALTER TABLE `news` ADD PRIMARY KEY  (`id`)






dropPrimaryKey() public method

Удаляет первичный ключ.

К разделу

Метод удалит первичный ключ из указанной таблицы


public DbCommand:: dropPrimaryKey ( $table )
$table string Имя таблицы, из которой удаляется первичный ключ.
return object Текущий объект компонента.


Примеры: #
1
2
3
4
5

    $command->dropPrimaryKey($table, $columns, $keys = [], $options = '', $exists = false );    
    
//    ALTER TABLE `news` DROP PRIMARY KEY





createIndex() public method

Создает индекс.

К разделу

Создаст индекс для указанных колонок.


public DbCommand:: createIndex ( $table, $columns, $name = '', $unique = false )
$table string Имя таблицы, для которой создается индекс.
$columns string|array Имена колонкок через запятую либо массивом, для которых будет создан индекс.
$name string Имя индекса. Если не будет указан, присвоится имя первой колонки, перечисленной в параметре $columns
$unique string Если установить опцию в true, индекс будет уникальным.
return object Текущий объект компонента.


Примеры: #
1
2
3
4
5
6
7
8
9

    $command->createIndex('news', 'date');
    
//    CREATE INDEX `date` ON `news` (`date`)
    
    $command->createIndex('news', ['date', 'title'], 'today', true);

//  CREATE UNIQUE INDEX `today` ON `news` (`date`, `title`) 





createUniqueIndex() public method

Создает индекс уникальный индекс.

К разделу

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


public DbCommand:: createUniqueIndex ( $table, $columns, $name = '' )
$table string Имя таблицы, для которой создается индекс.
$columns string|array Имена колонкок через запятую либо массивом, для которых будет создан уникальный индекс.
$name string Имя индекса. Если не будет указан, присвоится имя первой колонки, перечисленной в параметре $columns
return object Текущий объект компонента.


Примеры: #
1
2
3
4
5
6
7
8
9

    $command->createUniqueIndex('news', 'date');
    
//    CREATE UNIQUE INDEX `date` ON `news` (`date`)
    
    $command->createIndex('news', ['date', 'title'], 'today');

//  CREATE UNIQUE INDEX `today` ON `news` (`date`, `title`) 





dropIndex() public method

Удаляет индекс.

К разделу

Метод удалит индекс из указанной таблицы


public DbCommand:: dropIndex ( $table, $name )
$table string Имя таблицы, из которой удаляется индекс.
$name string Имя удаляемого индекса.
return object Текущий объект компонента.


Примеры: #
1
2
3
4
5

    $command->dropIndex('news', 'today');
    
//    DROP INDEX `today` ON `news`









Привязка значений и параметров #

К оглавлению

Для предотвращения SQL-инъекций и повышения производительности при выполнении однотипных SQL-запросов мы можем «подготавливать» SQL-выражения, используя маркеры параметров (placeholders), которые в процессе привязки будут заменяться на реальные значения.

  • bindValue(): Связывает значение с параметром
  • bindValues(): Связывает список значений с соответствующими параметрами
  • bindParam(): Связывает значение с параметром по ссылке




bindValue() public method

Метод привязывает значение к маркеру

К разделу

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


public DbCommand::bindValue ( $name, $value, $dataType = ABC_PARAM_STR )
$name string|integer Идентификатор параметра. Для подготовленного запроса с использованием именованных плэйсхолдеров это будет имя параметра вида :name.
C использованием вопросительного знака это будет позиция параметра.
$value mixed Значение для привязки к параметру
$dataType boolean SQL-тип данных параметра. Определяется предустановленными константами фреймворка.
По умолчанию строковый.
return object Текущий объект компонента.


Примеры: #

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

/* 
    SELECT * FROM guest 
       WHERE author = 'user' 
*/ 
    $command->createCommand("SELECT * FROM guest 
                              WHERE author = :author ") 
            ->bindValue(':author', 'user') 
            ->queryAll(); 
            
/* 
    SELECT * FROM guest 
       WHERE id = 5
*/ 
    $command->createCommand("SELECT * FROM guest 
                              WHERE id = :id ") 
            ->bindValue(':id', $id, ABC_PARAM_INT) 
            ->queryAll();
            
/*    
    SELECT * FROM guest 
      WHERE author = 'user' 
        AND date = NOW()  
*/ 
    $command->createCommand("SELECT * FROM guest 
                              WHERE author = ? 
                                AND date   = ? ") 
            ->bindValue(1, 'user') 
            ->bindValue(2, $command->expression('NOW()')) 
            ->queryAll();





bindValues() public method

Метод привязывает список значений к соответствующим маркерам

К разделу

То же, что и bindValue() с той разницей, что параметры можно передать списком.


public DbCommand::bindValues ( $values )
$values array Значения, которые должны быть связаны. Это должно быть задано массивом с ключами, являющимися именами параметров, и значениями.
Например, [':name' => 'John', ':age' => 25]
Если используются разименованные плэйсхолдеры (знаки вопроса), то нужно помнить, что в массиве отсчет начинается с нуля. И как минимум первый ключ нужно задать явно. Например, [1 => 'John', 25]
Тип параметра можно указать ключем значения, если его передать массивом. Определяется предустановленными константами.
Например, ['id' => [ABC_PARAM_INT => $id]]
По умолчанию строковый.
return object Текущий объект компонента.


Примеры: #

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

/*   
    SELECT * FROM guest
      WHERE author = 'user'
        AND date = NOW() 
*/
    $command->createCommand("SELECT * FROM guest
                              WHERE author = ?
                                AND date   = ? ")
            ->bindValues([
                            1 => 'user', 
                            2 => $command->expression('NOW()')
                        ])
            ->queryAll(); 
            
/*   
    SELECT * FROM guest
      WHERE author = 'user'
        AND posts > 5 
*/
    $command->createCommand("SELECT * FROM guest
                               WHERE author = :author
                                AND  posts  > :posts ")
            ->bindValues([
                            ':author' => 'user', 
                            ':posts'  => [ABC_PARAM_INT => $posts]
                        ])
            ->queryAll(); 





bindParam() public method

Метод привязывает значение к маркеру

К разделу

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


public DbCommand::bindParam ( $name, $value, $dataType = ABC_PARAM_STR )
$name string|integer Идентификатор параметра. Для подготовленного запроса с использованием именованных плэйсхолдеров это будет имя параметра вида :name.
C использованием вопросительного знака это будет позиция параметра.
$value mixed Переменная со значением. Онт будет передано по ссылке.
$dataType boolean SQL-тип данных параметра. Определяется предустановленными константами фреймворка.
По умолчанию строковый.
return object Текущий объект компонента.


Примеры: #

1
2
3
4
5
6
7
8
9
10
11
12
13
14

/*   
    SELECT * FROM guest 
      WHERE id = 1 OR id = 2
*/
    $command->createCommand("SELECT * FROM guest 
                              WHERE id = :id1 OR id = :id2 ")
            ->bindParam(':id1', $id1, ABC_PARAM_INT)
            ->bindParam(':id2', $id2, ABC_PARAM_INT);
            
    $id1 = 1;  
    $id2 = 2; 
    $command->queryAll();



Выполнение запроса и получение результата #

К оглавлению

  • execute(): выполняет запрос.
  • queryAll(): выполняет запрос и возвращает все строки.
  • queryRow(): выполняет запрос и возвращает ряд результата
  • queryColumn(): выполняет запрос и возвращает одну колонку
  • queryScalar(): выполняет запрос и возвращает значение одной клонки одного ряда
  • queryObject(): выполняет запрос и возвращает результат в виде объекта
  • count(): возвращает количество строк результата текущего запроса




execute() public method

Выполняет запрос.

К разделу

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

Этот метод не требует вызова execute(), но не очищает компонент. Для очистки пользуйтесь методом reset().


public DbCommand::execute ( )
return integer Количество затронутых изменениями строк


Примеры: #

1
2
3
4
5
6
7
8
9
10
11
12

    $command->createCommand("INSERT INTO guest SET author = 'user1'")
            ->execute();
            
            
    $cnt = $command->update('guest', ['author' => 'user2'])
                   ->execute();
                   
    var_dump($cnt);
// int 5






queryAll() public method

Выполняет запрос и возвращает все строки

К разделу

Возвращает результат в виде массива строк.

Этот метод не требует вызова execute(), но не очищает компонент. Для очистки пользуйтесь методом reset().


public DbCommand::queryAll ( $dataType = ABC_FETCH_ASSOC )
$dataType boolean Стиль вывода результата. Определяется предустановленными константами фреймворка.
По умолчанию ассоциативный массив.
return boolean|array Массив, где каждый элемент - строка.
Строки представлены в виде массивов, где каждый элемент - колонка вида
['name' => 'value'].
Если передать аргументом значение предустановленной константы, будет учтен этот параметр.
Если запрос не вернул результата, метод вернет false.


Примеры: #

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

    $result = $command->createCommand("SELECT author, text FROM guest") 
                      ->queryAll(); 

    var_dump($result);
/*     
    array (size=3) 
      0 =>  
        array (size=2) 
          'author' => string 'user1' (length=5) 
          'text'   => string 'One' (length=3) 
      1 =>  
        array (size=2) 
          'author' => string 'user2' (length=5) 
          'text'   => string 'Two' (length=3) 
      2 =>  
        array (size=2) 
          'author' => string 'user3' (length=5) 
          'text'   => string 'Three' (length=5) 
*/ 


    $result = $command->select('author, text') 
                      ->from('guest') 
                      ->queryAll(ABC_FETCH_NUM);

    var_dump($result); 
/* 
    array (size=3) 
      0 =>  
        array (size=2) 
          0 => string 'user1' (length=5) 
          1 => string 'One' (length=3) 
      1 =>  
        array (size=2) 
          0 => string 'user2' (length=5) 
          1 => string 'Two' (length=3) 
      2 =>  
        array (size=2) 
          0 => string 'user3' (length=5) 
          1 => string 'Three' (length=5) 
*/





queryRow() public method

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

К разделу

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

Этот метод не требует вызова execute(), но не очищает компонент. Для очистки пользуйтесь методом reset().


public DbCommand::queryRow ( $dataType = ABC_FETCH_ASSOC )
$dataType boolean Стиль вывода результата. Определяется предустановленными константами фреймворка.
По умолчанию ассоциативный массив.
return boolean|array Массив, где каждый элемент - колонка одного ряда.
Если передать аргументом значение предустановленной константы, будет учтен этот параметр.
Каждый следующий вызов вернет следующий ряд.
Если запрос не вернул результата или кончились ряды, метод вернет false.


Примеры: #

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

    $result = $command->select('author, text')  
                      ->from('guest')  
                      ->queryRow();  

    var_dump($result); 
/*      
    array (size=2)  
      'author' => string 'user1' (length=5)  
      'text'   => string 'One' (length=3)  
*/  

    $command->createCommand("SELECT author, text FROM guest");                        

    while ($row = $command->queryRow(ABC_FETCH_NUM)) {  
        var_dump($row);  
    }  
/*      
    array (size=2)  
      0 => string 'user1' (length=5)  
      1 => string 'One' (length=3)  
        
    array (size=2)  
      0 => string 'user2' (length=5)  
      1 => string 'Two' (length=3)  
        
    array (size=2)  
      0 => string 'user3' (length=5)  
      1 => string 'Three' (length=5)  
*/  





queryColumn() public method

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

К разделу

Возвращает содержимое колонки в виде строки.

Этот метод не требует вызова execute(), но не очищает компонент. Для очистки пользуйтесь методом reset().


public DbCommand::queryColumn ( $num = 0 )
$num integer Номер колонки по порядку. Нумерация начинается как в массиве - с нуля. Считаются те колонки, которые перечислены в SELECT запроса.
return boolean|string Содержимое одной колонки одного ряда в виде строки.
Каждый следующий вызов вернет колонку следующего ряда.
Если запрос не вернул результата или кончились ряды, метод вернет false.


Примеры: #

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

    $result = $command->createCommand("SELECT author, text FROM guest ")
                      ->queryColumn();

    var_dump($result);
// string 'user1' (length=4)

    $command->select('author, text')
            ->from("guest");
            
    while ($column = $command->queryColumn(1))
    {
        var_dump($column);
    }
/*    
    string 'One' (length=3)
    string 'Two' (length=3)
    string 'Three' (length=5)
*/





queryScalar() public method

Выполняет запрос и возвращает первую колонку первой строки результата

К разделу

Возвращает содержимое колонки в виде скалярной строки.

Этот метод не требует вызова execute(), но не очищает компонент. Для очистки пользуйтесь методом reset().


public DbCommand::queryScalar ( )
return boolean|string При любом вызове вернет содержимое первой колонки первого ряда в виде строки.


Примеры: #

1
2
3
4
5
6
7
8
9

    $command->select('author, text')
            ->from("guest");
            
    var_dump($command->queryScalar());
    // string 'user1' (length=5)
    var_dump($command->queryScalar());
    // string 'user1' (length=5)





queryObject() public method

Выполняет запрос и извлекает следующую строку, возвращая ее в виде объекта.

К разделу

Возвращает содержимое колонки в виде строки.

Этот метод не требует вызова execute(), но не очищает компонент. Для очистки пользуйтесь методом reset().


public DbCommand::queryObject ( $className = null, $ctorArgs = [] )
$className string Имя класса создаваемого объекта
$ctorArgs array Элементы этого массива будут переданы в конструктор класса.
return object Возвращает новый объект указанного класса, имена свойств которого соответствуют именам столбцов результирующего набора или FALSE в случае возникновения ошибки.


Примеры: #

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20


    $result = $command->createCommand("SELECT * FROM abc_guest");
            
    var_dump($command->queryObject());
/*    
    object(stdClass)[41]
        public $id => "1" (length=1)
        public $author => "user1" (length=2)
        public $text => "One" (length=3)
*/
    var_dump($command->queryObject());
/*    
    object(stdClass)[41]
        public $id => "2" (length=1)
        public $author => "user2" (length=5)
        public $text => "Two" (length=3)
*/
    





count() public method

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

К разделу

Метод выполняет SELECT COUNT() для текущего запроса и возвращает полученый результат. Этот метод не влияет на результат выборки, до или после его вызова можно вызвать любой метод получения результата.

Этот метод не требует вызова execute(), но не очищает компонент. Для очистки пользуйтесь методом reset().


public DbCommand::count ( $column = * )
$column string Название колонки для аргумента COUNT()
return integer Количество строк текущего запроса.


Примеры: #

1
2
3
4
5
6
7
8
9
10
11

    $cnt = $command->createCommand("SELECT * FROM guest")
                   ->count();
    var_dump($cnt); 
// string '6' (length=1)
    $result = $command->queryAll();
// Result
    var_dump($command->count());
// string '6' (length=1)
    



Транзакции #

К оглавлению

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







transaction() public method

Оборачивает запросы транзакцией.

К разделу

Принимает параметром callback-функцию, внутри которой должны помещаться методы конструктора запросов, составляющих транзакцию. Callback-функция принимает параметром объект текущего компонента. Метод вернет результат, возвращаемый функцией.
Если в любом из запросов произойдёт ошибка, база данных откатится на состояние, которое было до выполнения запросов.
См. пример


public DbCommand::transaction ( $callable )
$callable callable Анонимная функция, в которой находятся запросы, помещаемые в транзакцию.
return mixed Параметр, взвращаемый callback-функцией.


Примеры: #

1
2
3
4
5
6
7
8
9

    $command->transaction(function($command) use ($sql1, $sql2) { 
      
        $command->createCommand($sql1)->execute();    
        $command->createCommand($sql2)->execute(); 
     
    });     
    





beginTransaction() public method

Стартует транзакцию.

К разделу


Все запросы после вызова метода будут помещены в транзакцию. Ошибки в запросах будут выброшены в виде исключений (exception), которые можно отловить и обработать по своему.


public DbCommand::beginTransaction ( )
return object Объект текущей транзакции


Примеры: #

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

     $transaction = $command->beginTransaction();
    
    try {
    
        $command->createCommand($sql1)->execute();
        $command->createCommand($sql2)->execute();
        $transaction->commit();
        
    } catch (\Exception $e) {
    
        $transaction->rollBack();
        throw $e;
        
    } catch (\Throwable $e) {
    
        $transaction->rollBack();
    }
    
//В коде ради совместимости с PHP 5.x и PHP 7.x использованы два блока catch. 
//\Exception реализует интерфейс \Throwable interface начиная с PHP 7.0. 
//Если вы используете только PHP 7 и новее, можете пропустить блок с \Exception.





commit() public method

Фиксирует транзакцию.

К разделу

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


public DbCommand::commit ( )
return void Метод ничего не возвращает






rollback() public method

Откатывает транзакцию.

К разделу

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


public DbCommand::rollback ( )
return void Метод ничего не возвращает




Изменение настроек #

К оглавлению

Конструктор не требует отдельного соединения с сервером БД. Он пользуется уже настроенными конфигурацией компонентами. Однако может потребоваться коннект с другой базой данных.

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

  • setDb(): устанавливает соединение с другой базой данных
  • setPrefix(): добавляет к имени таблицы новый префикс
  • unsetPrefix(): удаляет текущий префикс




setDb() public method

Заменяет текущую базу на другую.

К разделу

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


public DbCommand::setDb ( $db )
$db object
return object Текущий объект компонента.


Примеры: #

1
2
3
4
5
6
7

    $command->setDb(['dsn'  => 'mysql:dbname=cms;host=localhost', 
                     'user' => 'root',  
                     'pass' => ''
                    ]);






setPrefix() public method

Устанавливает новый префикс

К разделу

Если в базе данных имеются таблицы с разными префиксами, их можно изменить, вызвав этот метод перед началом построения запроса. Для этого нужно использовать следующий синтаксис для названия таблиц: {{%table}}
Этот метод добавит префикс к текущему, если он прописан в настройках конфигурации. Другими словами он добавляет суффикс.
Для того, чтобы сменить префикс на новый, нужно прежде удалить старый методом unsetPrefix().
Методы reset() и execute() не удаляют новые префиксы.


public DbCommand::setPrefix ( $prefix )
$prefix string Новый префикс таблицы
return object Объект текущего компонента.


Примеры: #

1
2
3
4
5
6
7
8
9
10
11
12

//    Общий префикс abc_
        
    $command->setPrefix('users_'); 
    
    $result = $command->select()
                      ->from('{{%avatars}}')
                      ->queryAll();
                      
//  SELECT * FROM `abc_users_avatars` 






unsetPrefix() public method

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

К разделу

Если в базе данных имеются таблицы с разными префиксами, их можно изменить, вызвав этот метод перед началом построения запроса. Для этого нужно использовать следующий синтаксис для названия таблиц: {{%table}}
Этот метод добавит удалит все префиксы, установленные ранее. Как в конфигурационных файлах, так и методом setPrefix().


public DbCommand::unsetPrefix ( $callable )
return object Объект текущего компонента.


Примеры: #

1
2
3
4
5
6
7
8
9
10
11
12
13

//    Общий префикс abc_ 

    $command->unsetPrefix();         
    $command->setPrefix('users_');  

    $result = $command->select() 
                      ->from('{{%avatars}}') 
                      ->queryAll(); 
                       
//  SELECT * FROM `users_avatars`






Сециальные методы #

К оглавлению

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

  • createCommand(): выполняет произвольный запрос
  • expression(): создает выражение
  • subQuery(): создает подзапрос
  • reset(): очищает объект компонента для нового запроса
  • getSql(): возвращает текст запроса
  • test(): тестирует запрос






createCommand() public method

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

К разделу

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

Этот метод ничего автоматически не экранирует. Однако если требуется универсальный для разных СУБД запрос, то можно пользоваться псевдосинтаксисом:

  • [[column name]]: заключайте имя столбца в двойные квадратные скобки;
  • {{table name}}: заключайте имя таблицы в двойные фигурные скобки.

Так же действуют правила для префиксов.
Можно пользоваться привязкой параметров.


public DbCommand::createCommand ( $sql )
$sql string Текст произвольного запроса
return object Объект текущего компонента.


Примеры: #

1
2
3
4
5
6
7
8
9
10
11
12
13
14

//  INSERT INTO `abc_guest` (`author`) VALUES ('user')
    $command->createCommand("INSERT INTO `abc_guest` (`author`) VALUES ('user')")
            ->execute();
// или так
    $command->createCommand("INSERT INTO {{%guest}} ([[author]]) VALUES ('user')")
            ->execute(); 

//  SELECT * FROM `guest` WHERE `id` = '5'
    $result = $command->createCommand("SELECT * FROM `guest` WHERE `id` = :id ")
                      ->bindValue(':id', 5)
                      ->queryAll();






expression() public method

Метод построения выражений.

К разделу

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


public DbCommand::expression ( $expression )
$expression string Текст выражения
return object Объект с выражением.


Примеры: #

1
2
3
4
5
6
7
8
9
10
11
12

/*
    SELECT  `author`, `text` 
      FROM `abc_guest` 
       WHERE active IS NOT NULL
*/
    $result = $command->select('author, text')
                      ->from('guest')
                      ->where('active :check', [':check' => $command->expression('IS NOT NULL')])
                      ->queryAll();






subQuery() public method

Метод построения подзапроса.

К разделу

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


public DbCommand::subQuery ( )
return object Новй объект конструктора


Примеры: #

1
2
3
4
5
6
7
8
9
10

// SELECT `id`, (SELECT COUNT(`id`) FROM `user`) AS `count` FROM `guest`
    $result = $command->select(['id', 
                                'count' => $command->subQuery() 
                                                   ->select('COUNT(`id`)') 
                                                   ->from('user')
                              ]) 
                      ->from('guest') 
                      ->queryAll();





reset() public method

Очищает объект для нового запроса.

К разделу

Методы выборки, в отличие от execute(), не очищают объект. Поэтому для каждого нового запроса SELECT нужно создавать новый объект конструктора.
Но можно так же очистить текущий. Это экономит память. Сделать это можно с помощью данного метода.


public DbCommand::reset ( )
return void Метод ничего не возвращает


Примеры: #

1
2
3
4
5
6
7
8
9

    $posts = $command->createCommand('SELECT * FROM guest')
                     ->queryAll();
            
    $command->reset();
    
    $users = $command->createCommand('SELECT * FROM user')
                     ->queryAll();





getSql() public method

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

К разделу

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


public DbCommand::getSql ( )
return string Текст запроса


Примеры: #

1
2
3
4
5
6
7
8
9
10
11

    $result = $command->createCommand('SELECT * FROM guest')
                      ->queryAll();
            
    $textSql = (string)$command;       
// Или    
    $textSql = $command->getSql(); 
   
    var_dump($textSql);
// string 'SELECT * FROM guest' (length=23)





test() public method

Тестирует запрос.

К разделу

Можно не только получить текст запроса с помощью метода getSql(), но и протестировать запрос с помощью встроенного SQL-дебаггера.
Для этого нужно вызвать этот метод перед началом построения запроса или перед его исполнением.


public DbCommand::test ( )
return object Текущий объект компонента


Примеры: #

1
2
3
4
5
6
7
8
9
10
11
12

    $command->test();
        
    $result = $command->createCommand('SELECT * FROM abc_guest')
                      ->queryAll();
                      
// Или                  
                 
    $result = $command->createCommand('SELECT * FROM abc_guest')
                      ->test()
                      ->queryAll();