waModel

Корректный вызов методов этого класса возможен только для его классов-наследников (классов модели приложения или плагина), в которых определено значение свойства класса $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 способа указания значений плейсхолдеров — в зависимости от способа указания самих плейсхолдеров:

  1. Если плейсхолдеры указаны в виде символов ? или в виде тип:номер, то значения для плейсхолдеров необходимо передавать методу exec() в виде отдельных параметров. Порядок передачи значений методу должен соответствовать порядку расположения плейсхолдеров в тексте SQL-запроса. Нумерация значений для плейсхолдеров вида тип:номер начинается с 0 (например, i:0, s:1 и т. д.).
  2. При использовании именованных плейсхолдеров параметр $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)

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

Пример

(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

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

  1. Элементы массива должны представлять собой ассоциативные подмассивы элементов типа 'field' => 'value'. В базу данных будут вставлены записи, соответствующие каждому из элементов массива.
  2. Элементы массива должны иметь вид 'field' => 'value'. Если в качестве значения одного из элементов указан простой массив значений, то в таблицу будет вставлено столько записей, сколько значений указано в таком подмассиве — по одной для каждого значения. В противном случае вызов метода аналогичен выполнению метода insert.
• $mode

  Режим выполнения SQL-запроса для случаев вставки значений, совпадающих со значениями уникальных полей в индексах PRIMARY и UNIQUE:

  • null: никакие данные не добавляются в таблицу.
  • waModel::INSERT_EXPLICIT: никакие данные не добавляются в таблицу и выбрасывается исключение waDbException.
  • waModel::INSERT_IGNORE: применяется ключевое слово SQL IGNORE.
  • Массив имён полей таблицы: значения в перечисленных полях перезаписываются значениями с этими ключами из параметра $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);