Корректный вызов методов этого класса возможен только для его классов-наследников (классов модели приложения или плагина), в которых определено значение свойства класса $table
, содержащее имя существующей таблицы в базе данных фреймворка, как показано ниже:
protected $table = 'table_name';
Это ограничение не распространяется на методы exec и query.
В качестве основного идентификатора записей в таблице по умолчанию используется поле с именем id
. Если в классе-наследнике waModel
в качестве идентификатора необходимо использовать поле с другим именем, это имя нужно указать в качестве значения свойства $id
в классе модели:
protected $id = 'product_id';
Если для точной идентификации записей необходимо использовать несколько полей таблицы, их имена следует указать в виде массива:
protected $id = ['product_id', 'order_id'];
Методы
-
countAll
Возвращает количество записей в таблице.
-
countByField
Возвращает количество записей, значение указанного поля в которых совпадает с указанным значением.
-
deleteByField
Удаляет записи, значение указанного поля в которых совпадает с указанным значением.
-
deleteById
Удаляет запись, значение поля-идентификатора которого совпадает с указанным значением.
-
escape
Подготавливает данные для безопасного сохранения в базе данных.
-
exec
Выполняет SQL-запрос, не возвращая его результат.
-
fieldExists
Проверяет наличие поля в таблице.
-
getAll
Возвращает все содержимое таблицы в виде массива.
-
getByField
Возвращает содержимое записей, значение указанного поля в которых совпадает с указанным значением.
-
getById
Возвращает содержимое записей с указанным значением поля-идентификатора.
-
getEmptyRow
Возвращает массив, соответствующим всем полям таблицы и содержащий значения полей по умолчанию.
-
getTableId
Возвращает название поля-идентификатора таблицы модели.
-
getTableName
Возвращает имя таблицы, определенное в классе модели.
-
insert
Добавляет запись с указанными значениями.
-
isEmpty
Проверяет отсутствие записей в таблице.
-
multipleInsert
Добавляет несколько записей с указанными значениями.
-
ping
Восстанавливает подключение к серверу баз данных в случае его прерывания.
-
query
Выполняет запрос к базе данных и возвращает результат.
-
replace
Заменяет запись в таблице с помощью SQL-оператора
REPLACE
. -
updateByField
Обновляет содержимое записей с указанными значениями полей.
-
updateById
Обновляет содержимое записи с указанным значением идентификатора.
public function countAll()
Возвращает количество записей в таблице.
Пример
(new myappModel())->countAll();
Результат
156 //в таблице, имя которой указано в классе модели 'myappModel', содержится всего 156 записей
public function countByField ($field, $value = null)
Возвращает количество записей, значение указанного поля в которых совпадает с указанным значением.
Параметры
-
$field
Имя поля, содержимое которого необходимо проверить.
-
$value
Значение, наличие которого в указанном поле проверяется во всех записях таблицы.
Пример
(new myappModel())->countByField('name', 'John');
Результат
12 //в таблице 12 записей, в поле 'name' которых указано 'John'
public function deleteByField ($field, $value = null)
Удаляет записи, значение указанного поля в которых совпадает с указанным значением.
Параметры
-
$field
Имя поля, содержимое которого необходимо проверить, либо ассоциативный массив имен полей и проверямых значений.
-
$value
Значение, наличие которого в указанном поле проверяется во всех записях таблицы. Значение этого параметра не учитывается, если в поле
$field
указан массив.
Пример
(new myappModel())->deleteByField('name', 'John');
Пример
(new myappModel())->deleteByField([ 'name', 'John', 'age', '24', ]);
public function deleteById ($value)
Удаляет запись, значение поля-идентификатора которого совпадает с указанным значением во всех записях таблицы, которые необходимо удалить.
Параметры
-
$value
Значение (или массив значений), наличие которого в поле-идентификаторе проверяется во всех записях таблицы.
Пример
(new myappModel())->deleteById(123); //удаляется запись, значение поля-идентификатора (по умолчанию поля 'id') которой равно 123
public function escape ($data, $type = null)
Подготавливает данные для безопасного сохранения в базе данных.
Параметры
-
$data
Одиночное значение или массив значений.
-
$type
Тип, к которому необходимо привести данные. Допустимые обозначения типов данных:
'int'
: целочисленное значение'like'
: подготовка строковых данных для использования с ключевым словомLIKE
: символы \\ заменяются на \\\\, применяется PHP-функцияaddslashes()
, символы подчеркивания _ и символы процента % экранируются.null
: вариант по умолчанию — применяется PHP-функцияaddslashes()
.
Пример
(new waModel())->escape($data);
public function exec ($sql, $params = null)
Выполняет SQL-запрос, не возвращая его результат.
Параметры
-
$sql
Текст SQL-запроса, который может (необязательно) содержать плейсхолдеры. Плейсхолдеры используются для безопасной вставки пользовательских данных в текст запроса, что позволяет исключить написание небезопасных запросов к базе данных. Плейсхолдеры представляют собой специальные метки в тексте SQL-запроса, вместо которых в содержимое запроса при его выполнении будут вставлены конкретные значения, указанные в значении параметра
$params
.Плейсхолдеры могут указываться 3 способами: а) в виде символа
?
, б) в видетип:номер
, либо в) в видетип:имя
(такие плейсхолдеры называются именованными, например:i:id
илиs:name
).Тип
указывается в соответствии с типом данных, которые нужно вставить в содержимое запроса.Имя
должно совпадать с одним из ключей ассоциативного массива в значении параметра$params
.Допустимые обозначения типов данных:
i
: целое число или массив чисел; если указан массив, то его значения будут приведены к целочисленному типу и склеены в строку с использованием запятой;b
: булево значение, которое будет конвертировано в 1 либо 0;l
: строковое значение, в котором символы % и _ будут экранированы символом \;f
: дробное значение, в котором запятые будут заменены на точку;s
: строковое значение или массив строковых значений; если указан массив, то его значения будут обернуты одинарными кавычками и склеены в строку с помощью запятой.
Если тип значения не указан, то по умолчанию указанное значение будет воспринято как строковое.
-
$params
Один или более необязательных параметров, используемых для подстановки значений в содержимое SQL-запроса вместо плейсхолдеров (при их использовании). Допускается 2 способа указания значений плейсхолдеров — в зависимости от способа указания самих плейсхолдеров:
- Если плейсхолдеры указаны в виде символов
?
или в видетип:номер
, то значения для плейсхолдеров необходимо передавать методуexec()
в виде отдельных параметров. Порядок передачи значений методу должен соответствовать порядку расположения плейсхолдеров в тексте SQL-запроса. Нумерация значений для плейсхолдеров видатип:номер
начинается с 0 (например,i:0
,s:1
и т. д.). - При использовании именованных плейсхолдеров параметр
$params
должен содержать ассоциативный массив элементов следующего вида:- Ключ элемента массива должен соответствовать одному из имен плейсхолдеров, указанных в SQL-запросе.
- Значение элемента массива будет подставлено в содержимое SQL-запроса вместо плейсхолдеров, имена которых соответствуют ключу данного элемента.
Порядок расположения элементов в массиве не имеет значения.
- Если плейсхолдеры указаны в виде символов
Пример
// содержимое переменной $customer_name будет в виде строки подставлено вместо ? (new waModel())->exec('INSERT INTO table_name (name) VALUES (?)', $customer_name);
Пример
// содержимое переменных $name и $id будет подставлено вместо символов ? именно в том порядке, // в котором эти переменные указаны при вызове метода exec() (new waModel())->exec('UPDATE table_name SET name = ? WHERE id = ?', $name, $id); // этот пример аналогичен предыдущему, но здесь используются плейсхолдеры с указанием типа (new waModel())->exec('UPDATE table_name SET name = s:0 WHERE id = i:1', $name, $id);
Пример
$data = [ 'name' => 'John', 'id' => 25, ]; // значения элементов массива $data с ключами 'name' и 'id' будут подставлены в SQL-запрос вместо плейсхолдеров с соответствующими именами; // эти значения будут приведены к указанным для них типам: 'name' — строка (s:), 'id' — целое число (i:) (new waModel())->exec('UPDATE table_name SET name = s:name WHERE id = i:id', $data);
Пример
$data = [ 'name' => 'John', 'id' => 25, ]; // для плейсхолдера с именем 'name' не указан тип значения (:name), // поэтому значение для него из массива $data будет воспринято по умолчанию как строка (new waModel())->exec('UPDATE table_name SET name = :name WHERE id = i:id', $data);
public function fieldExists ($field)
Проверяет наличие поля в таблице.
Параметры
-
$field
Имя поля в таблице модели.
Пример
(new myappModel())->fieldExists('extra_description');
public function getAll ($key = null, $normalize = false)
Возвращает содержимое таблицы в виде массива, элементами которого являются подмассивы значений, соответствующие отдельным записям таблицы.
Параметры
-
$key
Имя поля, по значению которого необходимо группировать содержимое записей таблицы. Ключами элементов возвращаемого массива в этом случае будут являться значения указанного поля.
-
$normalize
Режим группировки полученных значений для случаев, когда указано значение для параметра
$key
; допустимые обозначения режимов:- 0 или
false
: если в таблице содержится несколько записей с одинаковым значением указанного поля, то в возвращаемый массив будет включена только первая запись из каждой такой группы - 1 или
true
: аналогично предыдущему режиму; кроме того, из каждого подмассива возвращаемого массива удаляется элемент, ключ которого совпадает со значением указанного поля - 2: если в таблице содержится несколько записей с одинаковым значением указанного поля, то в массив, возвращаемый методом, будут включены все записи таблицы: записи с одинаковыми значениями указанного поля группируются в виде элементов подмассивов, ключами которых являются значения указанного поля, и из каждого подмассива записи удаляется элемент, ключ которого совпадает со значением указанного поля (так же, как для режима 1/
true
)
- 0 или
Примеры для этого метода приведены с учетом следующих значений:
id | name | age |
---|---|---|
1 | John | 25 |
2 | Mary | 26 |
3 | Bill | 25 |
4 | Michael | 19 |
5 | Jane | 26 |
Пример
(new myappModel())->getAll();
Результат
[ [ id => '1' name => 'John' age => '25' ], [ id => '2' name => 'Mary' age => '26' ], [ id => '3' name => 'Bill' age => '25' ], [ id => '4' name => 'Michael' age => '19' ], [ id => '5' name => 'Jane' age => '26' ], ]
Пример
// элемент 'id' удаляется из содержимого подмассивов (myappModel())->getAll('id', 1);
Результат
[ [ name => 'John' age => '25' ], [ name => 'Mary' age => '26' ], [ name => 'Bill' age => '25' ], [ name => 'Michael' age => '19' ], [ name => 'Jane' age => '26' ], ]
Пример
// значения группируются по содержимому поля 'age' (new myappModel())->getAll('age', 2);
Результат
[ 25 => [ 0 => [ id => '1' name => 'John' ], 1 => [ id => '3' name => 'Bill' ], ], 26 => [ 0 => [ id => '2' name => 'Mary' ], 1 => [ id => '5' name => 'Jane' ], ], 19 => [ 0 => [ id => '4' name => 'Michael' ], ], ]
public function getByField ($field, $value = null, $all = false, $limit = false)
Возвращает содержимое записей, значение указанного поля в которых совпадает с указанным значением. Допускается 2 режима передачи параметров: для одного поля таблицы и для нескольких полей.
Параметры (для одного поля)
-
$field
Имя поля, значение которого нужно проверять.
-
$value
Значение поля.
-
$all
Флаг, обозначающий необходимость вернуть содержимое всех найденных записей. Вместо булева значения
true
можно указывать название поля, значения которого в результирующем массиве должны использоваться в качестве ключей массива. По умолчанию (false
) метод возвращает первую найденную запись. -
$limit
Количество записей, которое необходимо вернуть, если запрашиваются все записи, соответствующие указанным значениям полей. По умолчанию (
false
) это ограничение отключено.
Параметры (для нескольких полей)
-
$field
Ассоциативный массив значений полей с именами полей в качестве ключей массива.
-
$all
Флаг, обозначающий необходимость вернуть содержимое всех найденных записей. Вместо булева значения
true
можно указывать название поля, значения которого в результирующем массиве должны использоваться в качестве ключей массива. По умолчанию (false
) метод возвращает первую найденную запись. -
$limit
Количество записей, которое необходимо вернуть, если запрашиваются все записи, соответствующие указанным значениям полей. По умолчанию (
false
) это ограничение отключено.
Пример
// вернуть первые 10 записей, в которых значение поля 'age' равно 25 (new myappModel())->getByField('age', 25, true, 10);
Пример
$data = [ 'age' => 25, 'name' => 'John', ]; // вернуть все записи с указанными значениями полей (new myappModel())->getByField($data, true);
public function getById ($value)
Возвращает содержимое записей с указанным значением поля-идентификатора.
Параметры
-
$value
Значение поля-идентификатора.
Пример
(new myappModel())->getById(4);
public function getEmptyRow()
Возвращает массив, соответствующим всем полям таблицы и содержащий значения полей по умолчанию.
Пример
(new myappModel())->getEmptyRow();
Результат
[ id => '' name => '' age => '' ]
public function getTableId()
Возвращает название поля-идентификатора таблицы модели.
Пример
(new myappModel())->getTableId();
Результат
id //название поля-идентификатора, используемое по умолчанию, если иное не определено в классе модели
public function getTableName()
Возвращает имя таблицы, определенное в классе модели.
Пример
(new myappModel())->getTableName();
public function insert ($data, $type = 0)
Добавляет запись с указанными значениями.
Параметры
-
$data
Ассоциативный массив значений, ключами элементов которого являются имена полей таблицы.
-
$type
Режим выполнения SQL-запроса
INSERT
для вставки данных:- 0: запрос выполняется без дополнительных условий (значение по умолчанию)
- 1: при выполнении запроса используется условие
ON DUPLICATE KEY UPDATE
- 2: при выполнении запроса используется ключевое слово
IGNORE
Пример
$data = [ 'id' => 6, 'age' => 25, 'name' => 'John', ]; (new myappModel())->insert($data, 1);
public function isEmpty()
Проверяет отсутствие записей в таблице.
Пример
$no_records_available = (new myappModel())->isEmpty();
public function multipleInsert ($data, $mode = null)
Добавляет несколько записей с указанными значениями.
Параметры (отдельно для каждой записи)
-
$data
Массив значений для записи в базу данных, которые можно указать несколькими способами:
- Элементы массива должны представлять собой ассоциативные подмассивы элементов типа
'field' => 'value'
. В базу данных будут вставлены записи, соответствующие каждому из элементов массива. - Элементы массива должны иметь вид
'field' => 'value'
. Если в качестве значения одного из элементов указан простой массив значений, то в таблицу будет вставлено столько записей, сколько значений указано в таком подмассиве — по одной для каждого значения. В противном случае вызов метода аналогичен выполнению метода insert.
- Элементы массива должны представлять собой ассоциативные подмассивы элементов типа
-
$mode
Режим выполнения SQL-запроса для случаев вставки значений, совпадающих со значениями уникальных полей в индексах PRIMARY и UNIQUE:
null
: никакие данные не добавляются в таблицу.waModel::INSERT_EXPLICIT
: никакие данные не добавляются в таблицу и выбрасывается исключениеwaDbException
.waModel::INSERT_IGNORE
: применяется ключевое слово SQLIGNORE
.- Массив имён полей таблицы: значения в перечисленных полях перезаписываются значениями с этими ключами из параметра
$data
. - Ассоциативный массив в формате «поле → значение»: значения полей, указанных в ключах массива, перезаписываются их значениями из этого массива.
- Любой другой массив строк: каждый элемент — строка с одним выражений, перечисленных через запятую в SQL-запросе после ключевых слов
ON DUPLICATE KEY UPDATE
.
Пример
$data = [ [ 'name' => 'bag', 'color' => 'red', ], [ 'name' => 'bag', 'color' => 'green', ], [ 'name' => 'bag', 'color' => 'blue', ], ]; // будут вставлены 3 записи, соответствующие элементам массива (myappModel())->multipleInsert($data);
Пример
$data = [ 'name' => 'bag', 'color' => [ 'red', 'green', 'blue', ], ]; // будут вставлены 3 записи, соответствующие значениям элемента 'color'; // значение 'name' у всех этих записей будет одинаковым (new myappModel())->multipleInsert($data);
Пример
// перезаписать значения поля `color` с существующими парами `id` + `name` // значениями из указанного массива, // если поля `id` и `name` входят в индекс PRIMARY или UNIQUE (new myappModel())->multipleInsert([ [ 'id' => 1, 'name' => 'John', 'color' => 'white', ], [ 'id' => 2, 'name' => 'Mary', 'color' => 'blue', ], [ 'id' => 3, 'name' => 'Bill', 'color' => 'red', ], ], [ 'color' ]);
Пример
// перезаписать значения поля `color` с существующими парами `id` + `name` // одинаковым значением из 2-го массива, // если поля `id` и `name` входят в индекс PRIMARY или UNIQUE (new myappModel())->multipleInsert([ [ 'id' => 1, 'name' => 'John', 'color' => 'white', ], [ 'id' => 2, 'name' => 'Mary', 'color' => 'blue', ], [ 'id' => 3, 'name' => 'Bill', 'color' => 'red', ], ], [ 'color' => 'green', ]);
public function ping()
Восстанавливает подключение к серверу баз данных в случае его прерывания. Можно использовать для устранения ошибки «MySQL server has gone away» в ходе выполнения долгих циклов вычислений.
Пример
(new myappModel())->ping();
public function query ($sql)
Выполняет запрос к базе данных и возвращает результат в виде экземпляра класса waDbResultSelect
, waDbResultInsert
, waDbResultUpdate
, waDbResultDelete
или waDbResultReplace
. Для доступа к значениям результата SQL-запроса необходим вызов публичных методов класса, соответствующего типу выполненного запроса.
Параметры
-
$sql
Обязательный параметр — строка SQL-запроса. Если SQL-запрос содержит плейсхолдеры для подстановки значений, то в метод необходимо передать значения плейсхолдеров — так же, как это описано для метода exec.
Пример
// метод fetchAll() допустим для получения результатов запроса типа 'SELECT', потому что описан в классе waDbResultSelect; // в частности, этот метод возвращает массив значений, извлеченных указанным SQL-запросом, которые можно использовать в PHP-коде (new waModel())->query('SELECT * FROM table_name')->fetchAll();
public function replace ($data)
Заменяет запись в таблице с помощью SQL-оператора REPLACE
.
Параметры
-
$data
Массив значений.
Пример
$data = [ [ 'item_id' => 18, 'order_id' => 984, ], ]; (new myappModel())->replace($data);
public function updateByField ($field, $value, $data = null, $options = null, $return_object = false)
Обновляет содержимое записей с указанными значениями полей. Допускается несколько режимов передачи параметров:
Параметры (проверка значений одного поля)
-
$field
Имя поля в таблице модели, содержимое которого необходимо обновить.
-
$value
Значение указанного поля, которое необходимо заменить. Вместо одного значения допускается указать массив — в этом случае содержимое поля будет заменено для всех записей, значения которых совпадают с одним из элементов массива
$value
. -
$data
Ассоциативный массив новых значений полей для найденных записей.
-
$options
Необязательные ключевые слова для SQL-запроса
UPDATE
:LOW_PRIORITY
иIGNORE
. -
$return_object
Флаг, обозначающий необходимость вернуть экземпляр класса
waDbResultUpdate
для доступа к его публичным методам с целью получения содержимого ответа, возвращаемого сервером баз данных. По умолчанию (false
) метод возвращает булево значение, обозначающее успешность выполнения запроса, либоnull
— в случае передачи некорректных данных в качестве параметров.
Параметры (проверка значений нескольких полей)
-
$field
Ассоциативный массив значений полей таблицы, по которым необходимо искать записи в таблице.
-
$data
Ассоциативный массив новых значений произвольно указанных полей для найденных записей.
-
$options
Необязательные ключевые слова для SQL-запроса
UPDATE
:LOW_PRIORITY
иIGNORE
.
Пример
// в поле 'name' значения 'John' заменить на 'Johnny' (new myappModel())->updateByField('name', 'John', ['name' => 'Johnny']);
Пример
$values = [ 'John', 'Johnny', ]; $data = [ 'mood' => 'bright', ]; // для записей, в которых значение 'name' равно 'John' или 'Johnny', заменить значение поля 'mood' на 'bright' (new myappModel())->updateByField('name', $values, $data);
Пример
$fields = [ 'name' => 'John', 'age' => 25, ]; $data = [ 'mood' => 'bright', ]; // для записей, в которых значение 'name' равно 'John', а значение 'age' равно 25, заменить значение поля 'mood' на 'bright' (new myappModel())->updateByField($fields, $data);
public function updateById ($id, $data, $options = null, $return_object = false)
Обновляет содержимое записи с указанным значением идентификатора.
Параметры
-
$id
Значение идентификатора, используемого классом модели, при нахождении которого в записи будут заменены значения полей, указанные в параметре
$data
. -
$data
Ассоциативный массив новых значений указанных полей для найденной записи.
-
$options
Необязательные ключевые слова для SQL-запроса
UPDATE
:LOW_PRIORITY
иIGNORE
. -
$return_object
Флаг, обозначающий необходимость вернуть экземпляр класса
waDbResultUpdate
для доступа к его публичным методам с целью получения содержимого ответа, возвращаемого сервером баз данных. По умолчанию (false
) метод возвращает булево значение, обозначающее успешность выполнения запроса, либоnull
— в случае передачи некорректных данных в качестве параметров.
Пример
$data = [ 'name' => 'John', 'age' => 25, ]; (new myappModel())->updateById(6, $data);