Класс wpdb в WordPress (часть 1)

В этой стстье речь пойдёт про класс wpdb. Через этот класс делаются все манипуляции с базой данных в WordPress: добавление, удаление, обновление и получение данных.

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

Обращение к методам класса "wpdb" всегда проходит через глобальную переменную "$wpdb". Если нужно воспользоваться этой переменной внутри функций, то необходимо её глобализировать там:

<?php
function MouseDC(){
   global $wpdb;
}

Методы класса "wpdb" позволяют управлять всеми таблицами в базе данных WordPress, а не только системными. Потому что существует возможность выполнить произвольный SQL запрос к любой таблице:

<?php
$food = $wpdb->get_results( "SELECT * FROM food" );

Каждый объект класса "wpdb" работает с одной базой данных. Если нужно подключить к другой базе данных, то нужно создать новый объект. Продемонстрируем это:

<?php
global $db;
$db = new wpdb( 'имя_пользователя', 'пароль', 'название_базы', 'ip_адрес_базы' );

if( ! empty($db->error) ) wp_die( $db->error ); // в случае ошибки соединения

$food = $db->get_results( "SELECT * FROM food" );

Методы класса "wpdb"

Разберём все методы класса "wpdb". Сначала перечислим их:

query - делает произвольный SQL запрос
get_var - возвращает значение ячейки таблицы
get_row - возвращает строку таблицы
get_col - возвращает столбец таблицы
get_col_info - получает информацию о столбце
get_results - возвращает несколько строк таблицы
insert - добавляет строку в таблицу
update - обновление строку в таблице
replace - заменяет строку в таблице
delete - удаляет строку из таблицы
prepare - очищает данные (от возможных SQL инъекций)
esc_like - очищает данные (части LIKE в SQL запросе)
show/hide/print_error - распечатывает ошибки SQL
flush - сбрасывает кеш

Выполнение запроса "query"

Метод "query" позволяет выполнять любой запрос к базе данных. Метод возвращает число: количество строк, которые были изменены или возвращены базой данных. Если запрос не выполнится, то вернётся "false".

$wpdb->query( 'query' );

У метода всего один аргумент - строка SQL запроса. Туда можно вставлять сырой SQL запрос. К примеру, запрос, который удалит публикацию с ID равным 5:

$wpdb->query( "DELETE FROM $wpdb->posts WHERE id = 5" );

Учтите, что при выполнении запроса лучше передавать в него уже очищенную SQL команду:

$sql = "DELETE FROM $wpdb->posts WHERE id = 5";
$wpdb->query( $wpdb->prepare( $sql ) );

Получение ячейки таблицы "get_var"

С помощью метода "get_var" можно получить значение ячейки в таблице. Результат можно получить в виде массива. Если результата нет, то вернётся "null" значение.

$wpdb->get_var( 'query', $column_offset, $row_offset );

Рассмотрим аргументы этого метода:

Название	Тип данных	Описание
'query'	строка	SQL запрос для выполнения
$column_offset	число	Порядковый номер колонки. Начиная с нуля.
$row_offset	число	Порядковый номер строки. Начиная с нуля.

Получение строки "get_row"

С помощью метода "get_row" можно получить одну строку из таблицы. Результат можно получить в виде объекта или массива. Если результата нет, то вернётся "null" значение.

$wpdb->get_row( 'query', $output_type, $row_offset );

Рассмотрим аргументы этого метода:

Название	Тип данных	Описание
'query'	строка	SQL запрос для выполнения
$output_type	константа	Формат возвращаемых данных. Возможные значения: OBJECT - вернуть данные в объекте (по умолчанию) ARRAY_A - вернуть данные в ассоциативном массиве ARRAY_N - вернуть данные в массиве без ключей
$row_offset	число	Номер строки для получения (считая с нуля). По умолчанию ноль (первая строка).

Пример использования (получение данных публикаций с ID равным 5):

$wpdb->get_row( 'SELECT ID FROM $wpdb->posts WHERE ID = 5' );

Получение столбца "get_col"

С помощью метода "get_col" можно получить один столбец из таблицы. Результат можно получить в виде массива. Если результата нет, то вернётся "null" значение.

$wpdb->get_col( 'query', $column_offset );

Рассмотрим аргументы этого метода:

Название	Тип данных	Описание
'query'	строка	SQL запрос для выполнения
$column_offset	число	Номер столбца для получения (считая с нуля). По умолчанию ноль (первый столбец).

Пример использования (получение списка id ревизий публикаций):

$wpdb->get_col( "SELECT ID FROM $wpdb->posts WHERE post_type = 'revision'" );

Получение информации о столбце "get_col_info"

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

$wpdb->get_col_info( $type, $offset );

Рассмотрим аргументы этого метода:

Название	Тип данных	Описание
$type	строка	Какую именно информацию получать. Возможные значения: table - название таблицы. name - название колонки. type - тип колонки max_length - максимальная длинна данных колонки. not_null - вернёт "1" если ячейка колонки не может принимать значение NULL primary_key - вернёт "1" если колонка является первичным ключом unique_key - вернёт "1" если значения должны быть уникальны multiple_key - вернёт "1" если значения могут быть не уникальны numeric - вернёт "1" если колонка содержит число blob - вернёт "1" если колонка содержит данные типа BLOB unsigned - вернёт "1" если колонка имеет тип данных UNSIGNED zerofill - вернёт "1" если колонка имеет тип данных ZEROFILL
$offset	число	Номер столбца для получения (считая с нуля). По умолчанию ноль (первый столбец). Если указать "-1", то будет возвращена информация о всех колонках в виде массива.

Получение нескольких строк "get_results"

С помощью метода "get_results" можно получить несколько строку из таблицы. Результат можно получить в виде объекта или массива, элементами которого представляют собой результат выполнения метода "get_row". Если результата нет, то вернётся "null" значение.

$wpdb->get_results( 'query', $output_type );

Рассмотрим аргументы этого метода:

Название	Тип данных	Описание
'query'	строка	SQL запрос для выполнения
$output_type	константа	Формат возвращаемых данных. Возможные значения: OBJECT - вернуть данные в объекте (по умолчанию) ARRAY_A - вернуть данные в ассоциативном массиве ARRAY_N - вернуть данные в массиве без ключей

Добавление данных "insert"

С помощью метода "insert" можно добавлять данные в таблицу. Метод использует защиту от SQL инъекций, поэтому запрос можно передавать в сыром виде. В результате добавления возвращается либо число вставленных строк, либо "false".

$wpdb->insert( $table, $data, $format );

Рассмотрим аргументы этого метода:

Название	Тип данных	Описание
$table	строка	Название таблицы, куда вставляются данные.
$data	строка	Данные, которые необходимо вставить.
$format	строка	Формат данных. Возможные значения: %s - строка %d - целое число %f - дробное число

Пример использования (добавление данных типа "строка" и "число"):

$wpdb->insert(
   'название_таблицы',
   array( 'столбец1' => 'значение1', 'столбец2' => 5 ),
   array( '%s', '%d' )
);

Обновление данных "update"

С помощью метода "update" можно обновлять данные в таблице. Метод использует защиту от SQL инъекций, поэтому запрос можно передавать в сыром виде. В результате добавления возвращается либо число обновлённых строк, либо "false" при появлении ошибки. Если возвращён ноль "0", то не было обновлено ни одной строки.

$wpdb->update( $table, $data, $where, $format = null, $where_format = null );

Рассмотрим аргументы этого метода:

Название	Тип данных	Описание
$table	строка	Название таблицы, кде происходит обновление данных.
$data	массив	Данные, которые необходимо обновить ('название_колонки' => 'значение').
$where	массив	Массив с условием для замены WHERE ('название_колонки' => 'значение').
$format	строка/массив	Формат данных, который указан в аргументе $data.
$where_format	строка/массив	Формат данных, который указан в аргументе $where.

Пример использования (обновление данных типа "строка" и "число" в строке с ID равным 10):

$wpdb->update(
   'название_таблицы',
   array( 'столбец1' => 'значение1', 'столбец2' => 5 ),
   array( 'ID' => 10 ),
   array( '%s', '%d' )
   array( '%d' )
);

Замена данных "replace"

Метод "replace" обновляет данные, если они есть и добавляет их, если нет. Фактически, метод работает как "update" и "insert". Метод использует защиту от SQL инъекций, поэтому запрос можно передавать в сыром виде.

В результате работы возвращается:

Число "1", если была обновлена строка.
Число больше единицы, если были удалены строки перед вставкой новой.
Число ноль "0", если не было обновлено/добавлено ни одной строки.
Логическое "false" при появлении ошибки.

$wpdb->replace( $table, $data, $format = null );

Рассмотрим аргументы этого метода:

Название	Тип данных	Описание
$table	строка	Название таблицы, кде происходит обновление данных.
$data	массив	Данные, которые необходимо обновить ('название_колонки' => 'значение').
$format	строка/массив	Формат данных, который указан в аргументе $data.

Пример использования (обновление данных в столбцах "столбец1" и "столбец2" в строке с ID равным 10):

$wpdb->replace(
   'название_таблицы',
   array( 'ID' => 10, 'столбец1' => 'значение1', 'столбец2' => 5 )
);

Удаление строки "delete"

Метод "delete" позволяет удалить строку из таблицы. В результате работы возвращается количество удалённых строк (цифра).

$wpdb->delete( $table, $where, $where_format = null );

Рассмотрим аргументы этого метода:

Название	Тип данных	Описание
$table	строка	Название таблицы, кде происходит обновление данных.
$where	массив	Массив условий, по которому будут выбираться данные для удаления ('название_колонки' => 'значение').
$where_format	строка/массив	Формат данных, который указан в аргументе $where.

Пример использования (удаление строки с ID равным 10):

$wpdb->delete(
   'название_таблицы',
   array( 'ID' => 10 )
);

Оббезараживание SQL строки "prepare"

Метод "prepare" позволяет обеззаразить SQL команду. В метод передаётся SQL команда и параметры, которые необходимо вставть в неё (параметров может быть несколько). Возвращает обеззараженную SQL команду, которую можно далее использовать:

$wpdb->prepare( 'query' param1, param2... );

Рассмотрим аргументы этого метода:

Название	Тип данных	Описание
query	строка	SQL запрос, в котором принимаемые значения заменены на указатели типа данных: %s - строка %d - целое число %f - дробное число
param1	строка/число/массив	Переменная, которая будет использована в запросе.

Пример использования (очистка SQL запроса для получение записи с ID равным 5):

$sql = $wpdb->prepare(
   'SELECT * FROM table WHERE ID = %1$s', 
   '5' 
);

Оббезараживание данных для SQL через "esc_sql"

Функция "esc_sql" позволяет обеззаразить данные, которые использются для SQL команды. Он выполняет ту же функцию, что и метод "prepare", но используется только на переменных, возвращая их обеззараженное значение.

Пример использования (очистка SQL запроса для удаления записи с принимаемым в GET параметре ID):

$id = esc_sql( $_GET['id'] );
$wpdb->get_var( "DELETE FROM $wpdb->posts WHERE ID = '$id' " );

Очищенную строку использовать только в обрамлении кавычек " " или ' ' . То есть в нашем случае из примера необходимо ставить в запрос "$id" или '$id'.

Очистка LIKE части запроса "esc_like"

Метод "esc_like" позволяет очистить данные данные, которые использются для LIKE части запроса SQL команды.

Пример использования (очистка SQL запроса для получение записи с названием, принимаемым в GET параметре 'name'):

$name = '%' . $wpdb->esc_like( $_GET['name'] ) . '%';
$wpdb->get_var( "SELECT * FROM $wpdb->posts WHERE post_name LIKE '$name' " );

Вывод ошибок "get_col_info"

С помощью метода "get_col_info" можно скрыть или показать ошибки, возникающие в просессе работы с классом "$wpdb":

$wpdb->show_errors(); // включить показ ошибок
$wpdb->hide_errors(); // выключить показ ошибок
$wpdb->print_error(); // вывести последнюю ошибку

Сброс кеша "flush"

При выполнении запросов в свойствах объекта класса "wpdb" сохраняется кеш возвращённых значений. Его можно сбросить с помощью метода "flush":

$wpdb->get_row( 'query', $output_type, $row_offset );

Грубо говоря, этот метод устанавливает следующие значения:

<?php
$wpdb->last_result = array();
$wpdb->col_info = null;
$wpdb->last_query = null;
$wpdb->rows_affected = 0;
$wpdb->num_rows = 0;
$wpdb->last_error = '';