waModel

Работа с базой данных

Содержание...

Корректный вызов методов этого класса возможен только для его классов-наследников (классов модели приложения или плагина), в которых определено значение свойства класса $table, содержащее имя существующей таблицы в базе данных фреймворка, как показано ниже:

protected $table = 'table_name';
Это ограничение не распространяется на методы exec и query.

В качестве основного идентификатора записей в таблице по умолчанию используется поле с именем id. Если в классе-наследнике waModel в качестве идентификатора необходимо использовать поле с другим именем, это имя нужно указать в качестве значения свойства $id в классе модели:

protected $id = 'product_id';

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

protected $id = array('product_id', 'order_id');

Методы

  • countAll

    Возвращает количество записей в таблице.

  • countByField

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

  • deleteByField

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

  • deleteById

    Удаляет запись, значение поля-идентификатора которого совпадает с указанным значением.

  • escape

    Подготавливает данные для безопасного сохранения в базе данных.

  • exec

    Выполняет SQL-запрос, не возвращая его результат.

  • fieldExists

    Проверяет наличие поля в таблице.

  • getAll

    Возвращает все содержимое таблицы в виде массива.

  • getByField

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

  • getById

    Возвращает содержимое записей с указанным значением поля-идентификатора.

  • getEmptyRow

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

  • getTableId

    Возвращает название поля-идентификатора таблицы модели.

  • getTableName

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

  • insert

    Добавляет запись с указанными значениями.

  • multipleInsert

    Добавляет несколько записей с указанными значениями.

  • ping

    Восстанавливает подключение к серверу баз данных в случае его прерывания.

  • query

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

  • replace

    Заменяет запись в таблице с помощью SQL-оператора REPLACE.

  • updateByField

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

  • updateById

    Обновляет содержимое записи с указанным значением идентификатора.

public function countAll()

Возвращает количество записей в таблице.

Пример

$model = new myappModel();
$model->countAll();

Результат

156 //в таблице, имя которой указано в некотором классе модели 'myappModel', содержится всего 156 записей

public function countByField ($field, $value = null)

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

Параметры

  • $field

    Имя поля, содержимое которого необходимо проверить.

  • $value

    Значение, наличие которого в указанном поле проверяется во всех записях таблицы.

Пример

$model = new myappModel();
$model->countByField('name', 'John');

Результат

12 //в таблице 12 записей, в поле 'name' которых указано 'John'

public function deleteByField ($field, $value = null)

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

Параметры

  • $field

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

  • $value

    Значение, наличие которого в указанном поле проверяется во всех записях таблицы. Значение этого параметра не учитывается, если в поле $field указан массив.

Пример

$model = new myappModel();
$model->deleteByField('name', 'John');

Пример

$model = new myappModel();
$model->deleteByField(array(
    'name', 'John',
    'age',  '24',
));

public function deleteById ($value)

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

Параметры

  • $value

    Значение (или массив значений), наличие которого в поле-идентификаторе проверяется во всех записях таблицы.

Пример

$model = new myappModel();
$model->deleteById(123); //удаляется запись, значение поля-идентификатора (по умолчанию поля 'id') которой равно 123

public function escape ($data, $type = null)

Подготавливает данные для безопасного сохранения в базе данных.

Параметры

  • $data

    Одиночное значение или массив значений.

  • $type

    Тип, к которому необходимо привести данные. Допустимые обозначения типов данных:

    • 'int': целочисленное значение
    • 'like': подготовка строковых данных для использования с ключевым словом LIKE: символы \\ заменяются на \\\\, применяется PHP-функция addslashes(), символы подчеркивания _ и символы процента % экранируются.
    • null: вариант по умолчанию — применяется PHP-функция addslashes().

Пример

$model = new waModel();
$model->escape($data);

public function exec ($sql, $params = null)

Выполняет SQL-запрос, не возвращая его результат.

Параметры

  • $sql

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

    Плейсхолдеры могут указываться 2 способами: в виде символа ? либо в виде тип:имя (такие плейсхолдеры называются именованными), например: i:id или s:name. Тип указывается в соответствии с типом данных, которые нужно вставить в содержимое запроса, а имя должно соответствовать одному из ключей ассоциативного массива в значении параметра $params.

    Допустимые обозначения типов данных:

    • i: целое число или массив чисел; если указан массив, то его значения будут приведены к целочисленному типу и склеены в строку с использованием запятой
    • b: булево значение, которое будет конвертировано в 1 либо 0
    • l: строковое значение, в котором символы % и _ будут экранированы символом \
    • f: дробное значение, в котором запятые будут заменены на точку
    • s: строковое значение или массив строковых значений; если указан массив, то его значения будут обернуты одинарными кавычками и склеены в строку с помощью запятой
    Если тип значения не указан, то по умолчанию указанное значение будет воспринято как строковое.
  • $params

    Один или более необязательных параметров, используемых для подстановки значений в содержимое SQL-запроса вместо плейсхолдеров (при их использовании). Допускается 2 способа указания значений плейсхолдеров — в зависимости от способа указания самих плейсхолдеров:

    1. Если плейсхолдеры указаны в виде символов ?, то значения для плейсхолдеров необходимо передавать методу exec в виде отдельных параметров. Порядок передачи значений методу должен соответствовать порядку расположения плейсхолдеров в тексте SQL-запроса.
    2. При использовании именованных плейсхолдеров параметр $params должен содержать ассоциативный массив элементов следующего вида:
      • Ключ элемента массива должен соответствовать одному из имен плейсхолдеров, указанных в SQL-запросе.
      • Значение элемента массива будет подставлено в содержимое SQL-запроса вместо плейсхолдеров, имена которых соответствуют ключу данного элемента.

      Порядок расположения элементов в массиве не имеет значения.

Пример

$model = new waModel();
$model->exec('INSERT INTO table_name (name) VALUES (?)', $customer_name); //содержимое переменной $customer_name будет в виде строки подставлено вместо ?

Пример

$model = new waModel();
$model->exec('UPDATE table_name SET name = ? WHERE id = ?', $name, $id); //содержимое переменных $name и $id будет подставлено вместо символов ? именно в том порядке, в котором эти переменные указаны при вызове метода exec

Пример

$model = new waModel();
$data = array(
    'name' => 'John',
    'id' => 25,
);
$model->exec('UPDATE table_name SET name = s:name WHERE id = i:id', $data); //значения элементов массива $data с ключами 'name' и 'id' будут подставлены в SQL-запрос вместо плейсхолдеров с соответствующими именами; эти значения будут приведены к указанным для них типам: 'name' — строка (s:), 'id' — целое число (i:)

Пример

$model = new waModel();
$data = array(
    'name' => 'John',
    'id' => 25,
);
$model->exec('UPDATE table_name SET name = :name WHERE id = i:id', $data); //для плейсхолдера с именем 'name' не указан тип значения (:name), значит, значение для него из массива $data будет воспринято по умолчанию как строка

public function fieldExists ($field)

Проверяет наличие поля в таблице.

Параметры

  • $field

    Имя поля в таблице модели.

Пример

$model = new myappModel();
$model->fieldExists('extra_description');

public function getAll ($key = null, $normalize = false)

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

Параметры

  • $key

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

  • $normalize

    Режим группировки полученных значений для случаев, когда указано значение для параметра $key; допустимые обозначения режимов:

    • 0 или false: если в таблице содержится несколько записей с одинаковым значением указанного поля, то в возвращаемый массив будет включена только первая запись из каждой такой группы
    • 1 или true: аналогично предыдущему режиму; кроме того, из каждого подмассива возвращаемого массива удаляется элемент, ключ которого совпадает со значением указанного поля
    • 2: если в таблице содержится несколько записей с одинаковым значением указанного поля, то в массив, возвращаемый методом, будут включены все записи таблицы: записи с одинаковыми значениями указанного поля группируются в виде элементов подмассивов, ключами которых являются значения указанного поля, и из каждого подмассива записи удаляется элемент, ключ которого совпадает со значением указанного поля (так же, как для режима 1/true)

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

idnameage
1John25
2Mary26
3Bill25
4Michael19
5Jane26

Пример

$model = new myappModel();
$model->getAll();

Результат

Array
(
  0 => Array
  (
    id => '1'
    name => 'John'
    age => '25'
  )
  1 => Array
  (
    id => '2'
    name => 'Mary'
    age => '26'
  )
  2 => Array
  (
    id => '3'
    name => 'Bill'
    age => '25'
  )
  3 => Array
  (
    id => '4'
    name => 'Michael'
    age => '19'
  )
  4 => Array
  (
    id => '5'
    name => 'Jane'
    age => '26'
  )
)

Пример

$model = new myappModel();
$model->getAll('id', 1); //элемент 'id' удаляется из содержимого подмассивов

Результат

Array
(
  1 => Array
  (
    name => 'John'
    age => '25'
  )
  2 => Array
  (
    name => 'Mary'
    age => '26'
  )
  3 => Array
  (
    name => 'Bill'
    age => '25'
  )
  4 => Array
  (
    name => 'Michael'
    age => '19'
  )
  5 => Array
  (
    name => 'Jane'
    age => '26'
  )
)

Пример

$model = new myappModel();
$model->getAll('age', 2); //значения группируются по содержимому поля 'age'

Результат

Array
(
  25 => Array
  (
    0 => Array
    (
      id => '1'
      name => 'John'
    )
    1 => Array
    (
      id => '3'
      name => 'Bill'
    )
  )
  26 => Array
  (
    0 => Array
    (
      id => '2'
      name => 'Mary'
    )
    1 => Array
    (
      id => '5'
      name => 'Jane'
    )
  )
  19 => Array
  (
    0 => Array
    (
      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) это ограничение отключено.

Пример

$model = new myappModel();
$model->getByField('age', 25, true, 10); //вернуть первые 10 записей, в которых значение поля 'age' равно 25

Пример

$model = new myappModel();
$data = array(
    'age' => 25,
    'name' => 'John',
);
$model->getByField($data, true); //вернуть все записи с указанными значениями полей

public function getById ($value)

Возвращает содержимое записей с указанным значением поля-идентификатора.

Параметры

  • $value

    Значение поля-идентификатора.

Пример

$model = new myappModel();
$model->getById(4);

public function getEmptyRow()

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

Пример

$model = new myappModel();
$model->getEmptyRow();

Результат

Array
(
  id => ''
  name => ''
  age => ''
)

public function getTableId()

Возвращает название поля-идентификатора таблицы модели.

Пример

$model = new myappModel();
$model->getTableId();

Результат

id //название поля-идентификатора, используемое по умолчанию, если иное не определено в классе модели

public function getTableName()

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

Пример

$model = new myappModel();
$model->getTableName();

public function insert ($data, $type = 0)

Добавляет запись с указанными значениями.

Параметры

  • $data

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

  • $type

    Режим выполнения SQL-запроса INSERT для вставки данных:

    • 0: запрос выполняется без дополнительных условий (значение по умолчанию)
    • 1: при выполнении запроса используется условие ON DUPLICATE KEY UPDATE
    • 2: при выполнении запроса используется ключевое слово IGNORE

Пример

$model = new myappModel();
$data = array(
    'id' => 6,
    'age' => 25,
    'name' => 'John',
);
$model->insert($data, 1);

public function multipleInsert ($data)

Добавляет несколько записей с указанными значениями.

Параметры (отдельно для каждой записи)

  • $data

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

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

Пример

$model = new myappModel();
$data = array(
    array(
        'name' => 'bag',
        'color' => 'red',
    ),
    array(
        'name' => 'bag',
        'color' => 'green',
    ),
    array(
        'name' => 'bag',
        'color' => 'blue',
    ),
);
$model->multipleInsert($data); //будут вставлены 3 записи, соответствующие элементам массива

Пример

$model = new myappModel();
$data = array(
    'name' => 'bag',
    'color' => array(
        'red',
        'green',
        'blue',
    ),
);
$model->multipleInsert($data); //будут вставлены 3 записи, соответствующие значениям элемента 'color'; значение 'name' у всех этих записей будет одинаковым

public function ping()

Восстанавливает подключение к серверу баз данных в случае его прерывания. Можно использовать для устранения ошибки «MySQL server has gone away» в ходе выполнения долгих циклах вычислений.

Пример

$model = new myappModel();
$model->ping();

public function query ($sql)

Выполняет запрос к базе данных и возвращает результат в виде экземпляра класса waDbResultSelect, waDbResultInsert, waDbResultUpdate, waDbResultDelete или waDbResultReplace. Для доступа к значениям результата SQL-запроса необходим вызов публичных методов класса, соответствующего типу выполненного запроса.

Параметры

  • $sql

    Обязательный параметр — строка SQL-запроса. Если SQL-запрос содержит плейсхолдеры для подстановки значений, то в метод необходимо передать значения плейсхолдеров — так же, как это описано для метода exec.

Пример

$model = new waModel();
$model->query('SELECT * FROM table_name')->fetchAll() //метод fetchAll допустим для получения результатов запроса типа 'SELECT', потому что описан в классе waDbResultSelect;
//в частности, этот метод возвращает массив значений, извлеченных указанным SQL-запросом, которые можно использовать в PHP-коде

public function replace ($data)

Заменяет запись в таблице с помощью SQL-оператора REPLACE.

Параметры

  • $data

    Массив значений.

Пример

$model = new myappModel();
$data = array(
    array(
        'item_id' => 18,
        'order_id' => 984,
    ),
);
$model->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.

Пример

$model = new myappModel();
$model->updateByField('name', 'John', array('name' => 'Johnny')); //в поле 'name' значения 'John' заменить на 'Johnny'

Пример

$model = new myappModel();
$values = array(
    'John',
    'Johnny',
);
$data = array(
    'mood' => 'bright',
);
$model->updateByField('name', $values, $data); //для записей, в которых значение 'name' равно 'John' или 'Johnny', заменить значение поля 'mood' на 'bright'

Пример

$model = new myappModel();
$fields = array(
    'name' => 'John',
    'age' => 25,
);
$data = array(
    'mood' => 'bright',
);
$model->updateByField($fields, $data); //для записей, в которых значение 'name' равно 'John', а значение 'age' равно 25, заменить значение поля 'mood' на 'bright'

public function updateById ($id, $data, $options = null, $return_object = false)

Обновляет содержимое записи с указанным значением идентификатора.

Параметры

  • $id

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

  • $data

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

  • $options

    Необязательные ключевые слова для SQL-запроса UPDATE: LOW_PRIORITY и IGNORE.

  • $return_object

    Флаг, обозначающий необходимость вернуть экземпляр класса waDbResultUpdate для доступа к его публичным методам с целью получения содержимого ответа, возвращаемого сервером баз данных. По умолчанию (false) метод возвращает булево значение, обозначающее успешность выполнения запроса, либо null — в случае передачи некорректных данных в качестве параметров.

Пример

$model = new myappModel();
$data = array(
    'name' => 'John',
    'age' => 25,
);
$model->updateById(6, $data);