Класс WordPress для работы с Базой Данных (wpdb сlass)

Знакомство с классом wpdb

WordPress предоставляет возможность удобно манипулировать своей Базой Данных за счет php класса wpdb.

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

global $wpdb;

C помощью методов $wpdb можно управлять произвольными таблицами в Базе Данных, не обязательно только теми, которые были созданы WordPress. Например, у нас, среди прочих таблиц WP, есть таблица "newtable" и нам нужно выбрать все поля id из нее. Реализовать это можно таким SQL запросом используя $wpdb:

$newtable = $wpdb->get_results( "SELECT id FROM newtable" );

Перейдем к разбору класса wpdb. Содержание:

• query: Простой запрос к Базе Данных WordPress
• get_var: Получение определенной ячейки таблицы
• get_row: Выбор строки из таблицы
• get_col: Выбор определенного столбца таблицы
• get_results: Выборка комбинированных результатов
• insert: Вставка новой записи (строки) в таблицу
• update: Обновление записи (строки) в таблице
• prepare: Защита запроса от внедрения SQL кода
• Показать или спрятать ошибки SQL
• get_col_info: Получить информацию о колонке
• flush: Сброс кэша
• Свойства (переменные) класса
• Таблицы Базы Данных WordPress

Простой запрос к Базе Данных WordPress (query) ↑

query функция позволяет выполнять любые запросы к БД WordPress. В общем случае, она подразумевает выполнение не SELECT запросов, хотя и они могут также выполняться (просто для них сущестуют специальные функции см. ниже).

<?php $wpdb->query('query'); ?>

query (строка)

Запрос который нужно выполнить.

Функция возвращает количество строк, которые были задействованы в результате запроса (удалены/изменены/выбраны). Если запрос вызвал ошибку, то будет возвращено значение FALSE или 0.

Имейте ввиду, что как и для всех функций класса wpdb, динамические данные передаваемые этой функции, нужно пропускать через функцию escape:
$wpdb->escape($user_entered_data_string). Нужно это чтобы обезопасить и защитить запрос от ошибок. см. ниже.

Примеры

1. Удалить произвольное поле 'gargle' и его значение у поста 13

$wpdb->query("
	DELETE FROM $wpdb->postmeta WHERE post_id = '13'
	AND meta_key = 'gargle'");

2. Установить родительскую страницу 7 для страницы 15

$wpdb->query("
	UPDATE $wpdb->posts SET post_parent = 7
	WHERE ID = 15 AND post_status = 'static'");

Получение определенной ячейки таблицы (get_var) ↑

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

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

query (строка)

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

column_offset (число)

Нужная колонка (отступ по колонкам). по умолчанию 0 - первая колонка.

row_offset (число)

Нужная строка (отступ по строкам). по умолчанию 0 - первая строка.

Примеры

1. Выведем на экран количество пользователей

<?php
$user_count = $wpdb->get_var($wpdb->prepare("SELECT COUNT(*) FROM $wpdb->users;"));
echo '<p>Количество пользователей равно: ' . $user_count . '</p>';
?>

2. Выведем на экран количество определенных произвольных полей

<?php
// определяем произвольный ключ, который нужно посчитать
$meta_key = 'miles';
$allmiles=$wpdb->get_var($wpdb->prepare("SELECT sum(meta_value) FROM $wpdb->postmeta WHERE meta_key = %s", $meta_key));
echo '<p>Общее количество произвольных полей miles: '.$allmiles . '</p>';
?>

3. Набор выводов статистики блога

### Общее Количество авторов блога
function get_totalauthors() {
	global $wpdb;
	$totalauthors = intval($wpdb->get_var("SELECT COUNT(ID) FROM $wpdb->users LEFT JOIN $wpdb->usermeta ON $wpdb->usermeta.user_id = $wpdb->users.ID WHERE $wpdb->users.user_activation_key = '' AND $wpdb->usermeta.meta_key = '".$wpdb->prefix."user_level' AND (meta_value+0.00) > 1"));

	return $totalauthors;
}

### Общее Количество постов
function get_totalposts() {
	global $wpdb;
	$totalposts = intval($wpdb->get_var("SELECT COUNT(ID) FROM $wpdb->posts WHERE post_type = 'post' AND post_status = 'publish'"));

	return $totalposts;
}

### Общее Количество страниц
function get_totalpages() {
	global $wpdb;
	$totalpages = intval($wpdb->get_var("SELECT COUNT(ID) FROM $wpdb->posts WHERE post_type = 'page' AND post_status = 'publish'"));

	return $totalpages;
}

### Общее Количество комментариев
function get_totalcomments() {
	global $wpdb;
	$totalcomments = intval($wpdb->get_var("SELECT COUNT(comment_ID) FROM $wpdb->comments WHERE comment_approved = '1'"));

	return $totalcomments;
}

### Общее Количество коментаторов
function get_totalcommentposters() {
	global $wpdb;
	$totalcommentposters = intval($wpdb->get_var("SELECT COUNT(DISTINCT comment_author) FROM $wpdb->comments WHERE comment_approved = '1' AND comment_type = ''"));

	return $totalcommentposters;
}

### Общее Количество ссылок
function get_totallinks() {
	global $wpdb;
	$totallinks = intval($wpdb->get_var("SELECT COUNT(link_id) FROM $wpdb->links"));

	return $totallinks;
}

Выбор строки из таблицы (get_row) ↑

get_row - возвращает строку таблицы в виде массива данных. Если результат запроса содержит больше одной строки, то будет возвращена первая строка (можно изменить).

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

query (строка)

Запрос который нужно выполнить.

output_type

Одна из трех констант. OBJECT.
* OBJECT - результат будет возвращен в виде объекта. Установлена по умолчанию
* ARRAY_A - результат будет возвращен в виде ассоциативного массива.
* ARRAY_N - результат будет возвращен в виде пронумерованного массива.

row_offset (число)

Номер возвращаемой строки результата запроса. 0 - это первая строка (установлено по умолчанию)

Примеры

1. Получим всю информацию о ссылке 10

$mylink = $wpdb->get_row("SELECT * FROM $wpdb->links WHERE link_id = 10");
// Теперь, свойства (переменные) $mylink - это названия
//колонок из таблицы $wpdb->links со значениями полей таблицы:
echo $mylink->link_id; // выведет на экран "10"

2. С использованием константы:

$mylink = $wpdb->get_row("SELECT * FROM $wpdb->links WHERE link_id = 10", ARRAY_A);
// результатом будет ассоциативный массив
echo $mylink['link_id']; // выведет на экран "10"

или

$mylink = $wpdb->get_row("SELECT * FROM $wpdb->links WHERE link_id = 10", ARRAY_N);
// результатом будет пронумерованный массив
echo $mylink[1]; // выведет на экран"10"

Выбор определенного столбца таблицы (get_col) ↑

Функция выбирает данные целой колонки таблицы и возвращает их в виде одномерного массива. Если в запрос вернул больше чем одну колонку (столбец), то функция вернет только данные одного, указанного столбца, остальное можно будет получить из переменной last_result.

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

query (строка)

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

column_offset (число)

Флаг указывающий какую колонку возвращать. По умолчанию 0 (первая колонка).

Примеры

1. Для этого примера представим, что у нас блог об автомобилях. Каждый пост описывает какой-либо автомобиль (например, Ford Mustang 1969 года). Для каждого поста предусмотрено по 3 произвольных поля: manufacturer (производитель), model(модель) и year(год выпуска). Этот пример выведет на экран заголовки постов, отфильтрованых по производителю (ford) и отсортированных по модели и году.

get_col здесь используется для того, чтобы получить массив ID всех записей, удовлетворяющих определенным критериям и отсортированных в нужном порядке. Затем через цикл foreach мы выводим заголовки по имеющимся у нас ID:

<?php
$meta_key1 = 'model';
$meta_key2 = 'year';
$meta_key3 = 'manufacturer';
$meta_key3_value = 'Ford';

$postids=$wpdb->get_col($wpdb->prepare("
SELECT      key3.post_id
FROM        $wpdb->postmeta key3
INNER JOIN  $wpdb->postmeta key1
            on key1.post_id = key3.post_id
            and key1.meta_key = %s
INNER JOIN  $wpdb->postmeta key2
            on key2.post_id = key3.post_id
            and key2.meta_key = %s
WHERE       key3.meta_key = %s
            and key3.meta_value = %s
ORDER BY    key1.meta_value, key2.meta_value",$meta_key1, $meta_key2, $meta_key3, $meta_key3_value)); 

if ($postids) {
  echo 'List of ' . $meta_key3_value . '(s), sorted by ' . $meta_key1 . ', ' . $meta_key2;
  foreach ($postids as $id) {
    $post=get_post(intval($id));
    setup_postdata($post);?>
    <p><a href="<?php the_permalink() ?>" rel="bookmark" title="Permanent Link to <?php the_title_attribute(); ?>"><?php the_title(); ?></a></p>
    <?php
  }
}
?>

2. Список постов которые имеют определенное произвольное поле (Color), но отсортированы они по значению другого произвольного поля (Display_Order).

<?php
$meta_key1 = 'Color';
$meta_key2 = 'Display_Order';

$postids=$wpdb->get_col($wpdb->prepare("
SELECT      key1.post_id
FROM        $wpdb->postmeta key1
INNER JOIN  $wpdb->postmeta key2
            on key2.post_id = key1.post_id
            and key2.meta_key = %s
WHERE       key1.meta_key = %s
ORDER BY    key2.meta_value+(0) ASC",
         $meta_key2,$meta_key1)); 

if ($postids) {
  echo 'List of '. $meta_key1  . ' posts, sorted by ' . $meta_key2 ;
  foreach ($postids as $id) {
    $post=get_post(intval($id));
    setup_postdata($post);?>
    <p><a href="<?php the_permalink() ?>" rel="bookmark" title="Permanent Link to <?php the_title_attribute(); ?>"><?php the_title(); ?></a></p>
    <?php
  }
}
?>

Выборка комбинированных результатов (get_results) ↑

Различные данные из нескольких строк таблицы могут быть получены при использовании метода get_results. Функция возвращает результат запроса в массиве, каждый элемент которого представляет собой результат функции get_row, т.е. в каждом элементе массива находятся все запрашиваемые данные одной строки.

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

query (строка)

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

output_type (строка)

Флаг указывающий как нужно вернуть данные. По умолчанию OBJECT. есть 4 варианта:
* OBJECT - вернет двумерный пронумерованный массив, каждый вложенный элемент которого представлен в виде объекта данных.
* OBJECT_K - вернет ассоциативный двумерный массив (в виде объекта), значение первой колонки таблицы будет ключом (одинаковые будут удалены). Каждый вложенный элемент представлен в виде ассоциативного массива (в виде объекта).
* ARRAY_A - вернет нумерованный двумерный массив, каждый вложенный элемент которого будет ассоциативным массивом, в котором ключом будет название колонки.
* ARRAY_N - вернет нумерованный двумерный массив, каждый вложенный элемент которого будет так же нумерованным массивом.

Примеры

1. Получим ID и заголовки черновиков, ID автора которых равен 5 и выведем на экран заголовки постов.

$fivesdrafts = $wpdb->get_results("SELECT ID, post_title FROM $wpdb->posts
	WHERE post_status = 'draft' AND post_author = 5");

foreach ($fivesdrafts as $fivesdraft) {
	echo $fivesdraft->post_title;
}

2. Выведем на экран ссылки на черновики автора с ID = 5

<?php
$fivesdrafts = $wpdb->get_results("SELECT * FROM $wpdb->posts
	WHERE post_status = 'draft' AND post_author = 5");
if ($fivesdrafts) :
	foreach ($fivesdrafts as $post) :
		setup_postdata($post);
?>
	<h2><a href="<?php the_permalink(); ?>" rel="bookmark"
		title="Permanent Link to <?php the_title(); ?>"><?php the_title(); ?></a></h2>
<?php
	endforeach;
else :
?>
    <h2> Не найдено</h2>
<?php endif; ?>

Вставка новой записи (строки) в таблицу (insert) ↑

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

table (строка)

название таблицы в которую будем вставлять данные.

data (строка)

Данные которые нужно вставить ('колонка куда вставлять' => 'что вставлять').

format (строка)

Формат данных который будет ассоциирован с указанными значениями в параметре $data. Возможные форматы данных: %s - строка; %d - целое число и %f - дробное число.

После того, как данные будут вставлены новое значение AUTO_INCREMENT можно получить в переменной: $wpdb->insert_id

Функция возвращает false, если данные не были вставлены в таблицу.

Пример

Вставим в значение в строку таблицы table, где первое значение строка, а второе число:

$wpdb->insert(
	'table',
	array( 'column1' => 'value1', 'column2' => 123 ),
	array( '%s', '%d' )
)

Обновление записи (строки) в таблице (update) ↑

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

table (строка)

название таблицы которую нужно обновить.

data (массив)

данные которые нужно обновить ('название колонки' => 'новое значение').

where (массив)

Ассоциированный массив с условием для замены (WHERE) ( 'название колонки' => 'чему равно').

format (массив/строка)

Формат данных который будет ассоциирован с указанными значениями в параметре $data.

where_format (массив/строка)

Формат данных который будет ассоциирован с указанными значениями в параметре $where.

Пример

Обновим строку ID которой равен 1, значение первой колонки строка, значение второй колонки число:

$wpdb->update( 'table',
	array( 'column1' => 'value1', 'column2' => 'value2' ),
	array( 'ID' => 1 ),
	array( '%s', '%d' ),
	array( '%d' )
)

Защита запроса от внедрения SQL кода (prepare) ↑

В SQL есть такое понятие как "внедрение в запрос SQL кода", сделать это можно когда в запрос передаются динамические данные. Например запрос содержит переменную, которая определяется пользователем, тогда в эту переменную можно передать данные, которые в итоге станут частью SQL запроса. Так можно внедриться в БД и что-нибудь испортить или просто нарушить код самого запроса. Визуально это выглядит примерно так:

SELECT * FROM table WHERE 1=1 AND id='$var'
//если $var будет равно например 2' AND id=(DROP TABLE table2)
//то в итоге у нас получиться
SELECT * FROM table WHERE 1=1 AND id='2' AND id=(DROP TABLE table2)'

Пример может не совсем удачный и я не уверен сработает ли он. Но не в этом суть, важно, что таким образом можно внедриться в сам запрос и изменить его. Чтобы этого не произошло динамические запросы в WordPress нужно защищать методом prepare:

<?php $sql = $wpdb->prepare( 'query' [, value_parameter, value_parameter ... ] ); ?>

query (строка)

Запрос. В нем можно использовать заменители %s и %d. Любые другие заменители % могут вызвать ошибку, чтобы например использовать команду LIKE знак % нужно претворять, еще одним %: LIKE %%вхождение%%.

value_parameter (строка/чило/массив)

Значения для замены в заменителях. Можно указывать через запятую как в php функции sprintf или передать массив для замены вторым параметром.

Пример

Добавим произвольное поле к посту 10:

$metakey = "'крах' БД";
$metavalue = "WordPress может 'сломать' Базу Данных если не экранировать запрос.";

$wpdb->query(
  $wpdb->prepare(
     "INSERT INTO $wpdb->postmeta ( post_id, meta_key, meta_value ) VALUES ( %d, %s, %s )",
     10, $metakey, $metavalue
  )
);

Как видно из примера, с prepare() нет необходимости заботиться об экранировании кавычек и прочего, что может навредить запросу.

Показать или спрятать ошибки SQL ↑

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

<?php $wpdb->show_errors(); ?> // включит показ ошибок
<?php $wpdb->hide_errors(); ?> // выключит показ ошибок

Так же можно вывести на экран саму ошибку, если таковая имеется:

<?php $wpdb->print_error(); ?>

Получить информацию о колонке (get_col_info) ↑

Есть возможность узнать информацию о колонках последнего запроса, для этого нужно использовать метод get_col_info. Это может пригодится, когда был возвращен объект, о данных которого мы ничего не знаем. Функция вернет массив с информацией об определенных в запросе колонках. Если в запросе колонки не определены, то функция вернет инфу о всех колонках таблицы.

<?php $wpdb->get_col_info('type', offset); ?>

type (строка)

В этом параметре указывается какую информацию нам нужно получить. По умолчанию: name. Вот список возможных вариантов:

• name - название колонки.
• table - название таблицы к которой принадлежит колонка.
• max_length - максимальная длинна данных колонки
• not_null - 1 если ячейка колонки не может принимать значение NULL
• primary_key - 1 если колонка является первичным ключем
• unique_key - 1 если ячейки колонки должны быть всегда уникальны
• multiple_key - 1 если ячейки колонки могут быть не уникальны
• numeric - 1 если колонка содержит числовые данные
• blob - 1 если колонка содержит данные типа BLOB (двоичные данные)
• type - тип колонки
• unsigned - 1 если колонка имеет тип данных UNSIGNED
• zerofill - 1 если колонка имеет тип данных ZEROFILL

offset (число)

Флаг для указания инфомацию о какой колонке нужно получить. По умолчанию -1 (все колонки). Если указать 0, то будет возвращена информация о первой колонке.

Сброс кэша (flush) ↑

Можно сбросить последние сохраненные данные в свойствах класса:

<?php $wpdb->flush(); ?>

Эта команда очистит следующие свойства (переменные): $wpdb->last_result, $wpdb->last_query и $wpdb->col_info.

Свойства (переменные) класса ↑

$show_errors

Показывать ошибки или нет, когда возвращается результат.
По умолчанию: Да (true)

$num_queries

Количество запросов которые выполняются.

$last_query

Последний запрос, который был выполнен классом.

$queries

Можно сохранить все запросы которые были сделаны к БД и их время выполнения, для этого нужно определить константу SAVEQUERIES как TRUE (например в config.php). По умолчанию она выключена (false). После того как эта константа включена в эту переменную будут собираться все запросы в виде массива данных.

$last_result

Результат последнего запроса.

$col_info

Информация о колонках последнего запроса.

$insert_id

Идентификатор (ID) сгенерированный последним запросом, для SQL параметра AUTO_INCREMENT

$num_rows

Количество строк возвращенных последним запросом.

$prefix

Префикс таблиц БД определенный для WordPress. Может пригодиться для мульти-сайтов.

$blogid

Идентификатор текущего блога.

Таблицы Базы Данных WordPress ↑

$wpdb->posts

Таблица куда записываются посты, постоянные страницы, произвольные типы записей, вложения и т.п.

$wpdb->users

Таблица с данными о зарегистрированных пользователях (индексные данные).

$wpdb->comments

Таблица с записями комментариев.

$wpdb->links

Таблица с записями ссылок.

$wpdb->options

Таблица опций (настроек).

$wpdb->postmeta

Таблица с записями о произвольных полях.

$wpdb->usermeta

Дополнительная информация о пользователях, такая как Имя, Ник, права и прочее.

$wpdb->terms

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

$wpdb->term_taxonomy

Таблица с информацией о различных таксономиях их описание.

$wpdb->term_relationships

Таблица связывающая таксономии с сонтентом (постами, записями и т.п.)