wpdb{} WP 0.71
Позволяет производить любые операции с базой данных WordPress: вставлять, обновлять, получать или удалять данные.
WordPress предоставляет возможность удобно манипулировать своей базой данных за счет php класса wpdb.
PHP класс — относится к ООП (объектно-ориентированному программированию) и в традиционном своем понимании представляет собой полностью самодостаточный код, который должен выполнять определенную функцию. Например, в этом случае через класс wpdb мы может производить всевозможные операции с Базой Данных WordPress зная всего несколько "рычагов" управления классом, которые называются методами.
Обращаться к методам класса wpdb нужно обязательно через глобальную переменную $wpdb (это экземпляр класса wpdb). Также нужно помнить, что внутри обычных функций нужно обязательно глобализировать $wpdb, иначе она будет простой переменной внутри функции, делается это так:
global $wpdb;
C помощью методов $wpdb можно управлять произвольными таблицами в базе данных, не обязательно только теми, которые были созданы WordPress. Допустим, среди прочих таблиц WP, есть таблица newtable и нам нужно выбрать все поля id из нее. Реализовать это можно таким SQL запросом используя $wpdb:
$newtable = $wpdb->get_results( "SELECT id FROM newtable" );
Создавать свои таблицы рекомендуется с помощью функции dbDelta(). Или можно использовать обычный SQL запрос и метод $wpdb->query('CREATE TABLE ...');.
Для плагинов создание новых таблиц обычно вешается на хук активации плагина, см. register_activation_hook().
Создание отдельного подключения к базе данных
Нужно понимать, что один объект класса wpdb{}
работает с одной БД - с текущей базой данных WordPress. Если нужно работать параллельно с какой-либо другой БД, то нужно создать еще один объект класса wpdb с указанием новых параметров соединения, отличных от тех что указаны в wp-config.php. Делается это так:
global $wpdb2; $wpdb2 = new wpdb( 'имя_юзера', 'пароль', 'название_БД', 'localhost' ); // если не удалось подключиться, и нужно оборвать PHP с сообщением об этой ошибке if( ! empty($wpdb2->error) ) wp_die( $wpdb2->error ); // Готово, теперь используем функции класса wpdb $results = $wpdb2->get_results( "SELECT * FROM table" );
Для сложных соединений с несколькими БД (репликами), есть хороший плагин, который рекомендуют разработчики WP - hyperdb. Этот плагин расширяет возможности базового класса wpdb. Устанавливается он не как обычный плагин и требует определенных знаний работы с базами данных (в противном случае, толку от этого плагина не будет).
А теперь, перейдем к разбору класса wpdb.
Хуки из класса
- query — произвольный запрос к Базе Данных WordPress
- get_var — получение определенной ячейки таблицы
- get_row — выбор строки таблицы
- get_col — выбор столбца таблицы
- get_results — выбор нескольких строк таблицы
- insert — вставка новой записи (строки) в таблицу
- update — обновление записи (строки) в таблице
- replace — замена строки
- delete — удаление строки из таблицы
- prepare — защита запроса от SQL инъекций
- esc_like — очистка LIKE строки
- show/hide/print_error — показать или спрятать ошибки SQL
- get_col_info — получить информацию о колонке
- flush — сброс кэша
- Свойства (переменные) класса
- Таблицы Базы Данных WordPress
query — произвольный запрос к Базе Данных WordPress
Выполняет любые запросы к базе данных WordPress.
Этот метод подразумевает выполнение всех запросов кроме SELECT. Для SELECT есть специальные методы: $wpdb->get_results, $wpdb->get_row, $wpdb->get_col, $wpdb->get_var.
Имейте ввиду, что как и для всех функций класса wpdb, передаваемые параметры нужно очистить от SQL инъекций, сделать это можно двумя способами:
// способ 1 esc_sql( $user_entered_data_string ) // способ 2 $wpdb->prepare( 'query' , value_parameter[, value_parameter ... ] )
Подробнее читайте в секции "Защита запросов от SQL инъекций"
Возвращает
Число/true/false.
- true — для запросов CREATE, ALTER, TRUNCATE, DROP.
- Число — для задействованных строк остальных запросов (DELETE/UPDATE/SELECT).
- false — когда запрос вызвал ошибку.
Использование
global $wpdb; $wpdb->query( $query );
- $query(строка) (обязательный)
- Database query.
Примеры
#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'" );
#3. Удалить осиротевшие произвольные поля
$wpdb->query("DELETE pm FROM $wpdb->postmeta pm LEFT JOIN wp_posts wp ON wp.ID = pm.post_id WHERE wp.ID IS NULL");
#4. Изменим ключ у полей-повторителей ACF
$wpdb->query( " UPDATE $wpdb->postmeta SET meta_key = REPLACE(meta_key, 'knowledge-base-type', 'knowledge-base-list') WHERE `meta_key` LIKE '%knowledge-base-type%' " );меню
get_var — получение определенной ячейки таблицы
Получает значение одной ячейки из результата запроса. По умолчанию берется первая ячейка — это первая колонка и первая строка.
Если результат запроса содержит больше одной колонки и/или больше одной строки, то будет возвращено значение указанной ячейки (указывается во 2 и 3 параметрах). Так, чтобы получить значение второй ячейки из второй строки результата запроса, нужно указать второй и третий параметры: $column_offset = 1, $row_offset = 1.
Если вызывать метод без запроса: $query = null
, то вернется значение указанной ячейки из предыдущего запроса.
Возвращает
Строку/null. Значение ячейки таблицы базы данных в виде строки.
- Если запрос получает значение одной колонки, то функция вернет это значение (без всяких массивов).
- Если запрос получает одну строку и несколько колонок, то функция вернет значение первой колонки (ячейки).
- Если запрос получает несколько строк и колонок, то вернется значение первой строки первой колонки.
- Вернет NULL, если результата нет.
Использование
$wpdb->get_var( 'query', $column_offset, $row_offset );
- query(строка/null)
- Запрос который нужно выполнить. Можно установить этот параметр в значение null, тогда функция вернет результат последнего запроса, который был выполнен классом (сохранился в переменной).
- column_offset(число)
- Нужная колонка (отступ по колонкам). по умолчанию 0 - первая колонка.
- row_offset(число)
- Нужная строка (отступ по строкам). по умолчанию 0 - первая строка.
Примеры
#1. Выведем на экран количество пользователей
$user_count = $wpdb->get_var( "SELECT COUNT(*) FROM $wpdb->users;" ); echo '<p>Количество пользователей равно: ' . $user_count . '</p>';
#2. Выведем на экран сумму значений определенных произвольных полей
// определяем произвольный ключ, который нужно посчитать $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 — выбор строки таблицы
Получает первую строку из результата SQL запроса. Возвращает строку в виде объекта.
Используйте параметр $row_offset, чтобы получить вторую, третью, ..., n-ю строку из запроса.
Возвращает
Объект/массив/null. Вернет null, если не удалось получить данные (запрашиваемых данных нет в бд).
Использование
$wpdb->get_row( 'query', $output_type, $row_offset );
- query(строка)
- Запрос который нужно выполнить.
- output_type(константа)
Одна из трех констант. Может быть:
- OBJECT - результат будет возвращен в виде объекта.
- ARRAY_A - результат будет возвращен в виде ассоциативного массива.
- ARRAY_N - результат будет возвращен в виде пронумерованного массива.
По умолчанию OBJECT
- 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 — выбор столбца таблицы
Делает запрос и получает данные одной колонки таблицы базы данных в виде массива.
Если запрос вернул больше чем одну колонку (столбец), то функция вернет только данные первого столбца. Можно указать отступ в параметре $column_offset, чтобы получить данные не первого столбца, а например второго: $column_offset = 1.
Если указать $query = null, то функция вернет указанную колонку из предыдущего запроса. Используя это свойство можно получить данные других колонок из уже сделанного запроса.
Возвращает
Массив. Индексный массив с данными запроса. Пустой массив, когда не удалось получить данные.
Использование
global $wpdb; $wpdb->get_col( $query, $x );
- $query(строка/null)
- Запрос который нужно выполнить. Можно установить этот параметр в значение null, тогда функция вернет результат последнего запроса.
По умолчанию: NULL (предыдущий запрос) - $x(число)
- Индекс колонки данные которой нужно вернуть.
По умолчанию: 0 (первая колонка)
Примеры
#1. Пример того как работает метод и что возвращает
Допустим у нас есть такой запрос на получение всех ревизий:
// укажем в запросе одно поле $revision_ids = $wpdb->get_col( "SELECT ID FROM $wpdb->posts WHERE post_type = 'revision'" ); // укажем в запросе все поля $revision_ids = $wpdb->get_col( "SELECT * FROM $wpdb->posts WHERE post_type = 'revision'" ); /* В обоих случаях вернется одинаковый массив. Когда указываются все поля, get_col получает только первое - это ID Array( [0] => 106 [1] => 101 [2] => 102 [3] => 103 ... ) */
#2 Использование без указания $query параметра
// сначала сделаем запрос $wpdb->query( "SELECT * FROM $wpdb->posts WHERE post_type = 'revision' LIMIT 10" ); // теперь получим данные этого запроса $revision_ids = $wpdb->get_col( null ); $revision_names = $wpdb->get_col( null, 5 ); // 5 - post_title /* Array ( [0] => 9949 [1] => 9957 [2] => 10125 [3] => 10154 [4] => 10221 [5] => 10235 [6] => 10319 [7] => 10496 [8] => 10532 [9] => 10568 ) Array ( [0] => wp_tempnam [1] => Шаблоны страницы для типов записей в WP 4.7 [2] => Политика конфиденциальности [3] => walker_nav_menu_start_el [4] => Вывод пагинации [5] => enter_title_here [6] => Smart Custom Fields - простой плагин метаполей [7] => register_post_type [8] => О сайте [9] => REST API в WordPress ) */
#3 NULL вместо пустой строки
Этот метод возвращает NULL в качестве значения поля, если в значении пустая строка (проверял на версии WP 5.1.1). Но если нам нужно получить оригинальные данные (пустую строку), можно использовать такую замену get_col():
$wpdb->query( "SELECT * FROM $wpdb->posts WHERE post_type = 'revision'" ); $ids = wp_list_pluck( $wpdb->last_result, 'ID' );
#4 Выбор столбца из результатов запроса
Для этого примера представим, что у нас блог об автомобилях. Каждый пост описывает какой-либо автомобиль (например, 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 } }
#5 Список постов которые имеют определенное произвольное поле (Color)
Но отсортированы они по значению другого произвольного поля (Display_Order).
$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 — выбор нескольких строк таблицы
Получает все данные указанного запроса (все строки и колонки). Результат возвращается в виде массива. Каждый элемент массива это объект с данными отдельной строки таблицы.
Возвращает
Массив/Объект/null. Результат запроса к базе данных. Вернет:
- Массив объектов — когда
$output = OBJECT
илиOBJECT_K
. - Массив массивов — когда
$output = ARRAY_A
илиARRAY_N
. - array() — когда строк по запросу не найдено или ошибка запроса.
- NULL — когда запрос пустая строка или передан неправильный тип вывода ($output_type).
Использование
global $wpdb; $wpdb->get_results( $query, $output );
- $query(строка)
Запрос который нужно выполнить.
Можно установить этот параметр в значение null, тогда функция вернет результат последнего запроса, который был произведен.
По умолчанию: null
- $output(константа/строка)
Флаг указывающий в каком виде нужно вернуть данные. Возможны 4 варианта:
OBJECT
— вернет массив объектов с числовыми ключами - элементы массива будут объекты строк таблицы —[ 0 => object ]
.OBJECT_K
— похож на предыдущий, только в индексах главного массива будут значения первой колонки результата запроса —[ 'field' => object ]
.
Обратите внимание, если в индекс будут попадать одинаковые значения, то данные будут затираться.ARRAY_N
— вернет индексный массив, каждый элемент которого будет так же индексным массивом —[ 0 => [...] ]
.ARRAY_A
— вернет индексный массив, каждый элемент которого будет ассоциативным массивом, в котором ключом будет название колонки —[ 'field' => [...] ]
.
По умолчанию: OBJECT
Примеры
#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 } else : ?> <h2> Не найдено</h2> <?php endif; ?>
#3. Пример сложного запроса с GROUP BY (отзывов в WooCommerce)
/** * Возвращает результаты рейтинга (отзывов в WooCommerce) сгрупированный по оценкам * * @param int $post_id идентификатор поста * * @return array массив объектов, где каждый объект - сгрупированные данные по одной из оценок */ function get_cnt_rating_reviews_one_product( $post_id ){ global $wpdb; return $wpdb->get_results( $wpdb->prepare( " SELECT COUNT(meta.meta_id) as num, meta.meta_value FROM $wpdb->comments as comments INNER JOIN $wpdb->commentmeta as meta ON comments.comment_ID = meta.comment_id WHERE comments.comment_post_ID = %d AND meta_key = 'rating' GROUP BY meta.meta_value; ", $post_id ) ); } // использование get_cnt_rating_reviews_one_product( 4350 );меню
insert — вставка новой записи (строки) в таблицу
Вставляет строку (указанные данные) в указанную таблицу.
Метод очищает переданные данные и защищает от SQL инъекций, поэтому данные могут быть «грязные» (неочищенные), например: $_GET['foo']
.
После добавления данных созданное значение AUTO_INCREMENT можно получить в переменной: $wpdb->insert_id
.
Возвращает
Число/false.
число
— число вставленных строк.false
— если данные не были вставлены в таблицу.
ВНИМАНИЕ! Вернет false (без каких либо ошибок), когда передаваемая для вставки строка (значение ячейки) длинее максимально возможного. Например колонка varchar(10) (длина значения 10 символов), а в переданных данных для вставки указана строка с 11 или более символами.
Поймать такой баг очень сложно! Поэтому надо иметь это ввиду, когда все вроде бы должно работать (правильные данные передается), но wpdb::insert() возвращает false без каких-либо ошибок.
Такая проблема касается почти всех методов, это:
wpdb::replace()
wpdb::insert()
wpdb::update()
wpdb::delete()
Использование
global $wpdb; $wpdb->insert( $table, $data, $format );
- $table(строка) (обязательный)
- Название таблицы в которую будем вставлять данные.
- $data(массив)
Данные которые нужно вставить. Каждый элемент массива выглядит так:
[ 'колонка таблицы' => 'значение' ]
.Если указать в значении NULL, то в значение будет установлено NULL, указанный формат при этом игнорируется.
Передаваемые данные НЕ должны быть очищены: esc_sql().
- $format(массив/строка)
Массив форматов данных которые будут ассоциированы с указанными значениями в параметре $data. Если указана строка, то она (формат) будет ассоциирован со всеми данными. При указании формата, WordPress переводит переданные данные в указанный формат перед тем, как сохранить данные. Возможные форматы:
%s
- строка%d
- целое число%f
- дробное число
Если не указать, то для всех значений $data будет указан формат
строка
, если иное не указано в свойстве wpdb::$field_types.
По умолчанию: null
Примеры
#1. Вставим строку в таблицу БД
// вставка строки с указанием значений для двух полей (значения для остальных полей будут дефолтные) $wpdb->insert( 'table', [ 'column' => 'foo', 'field' => 'bar' ] ); // с указанием типов данных $wpdb->insert( 'table', [ 'column' => 'foo', 'field' => 1337 ], [ '%s', '%d' ] );меню
update — обновление записи (строки) в таблице
Обновляет указанные данные в указанной строке таблицы.
Метод включает защиту от SQL инъекций и данные можно передавать как есть, например: $_GET['foo']
...
Читайте также: Массив для значений поля в $where параметре $wpdb->update.
Возвращает
Число/false.
число
- сколько строк было обработано0
- запрос был выполнен корректно, но ни одна строка не была обработана. Если в БД уже есть данные и вы пытаетесь обновить, указав точно такие же данные, то wpdb::update() вернет 0.false
- запрос провалился или ошибка запроса.
Так как возвращается 0, если никакие поля не были обновлены (изменены), но запрос был выполнен корректно, проверку результата запроса на ошибку нужно делать с учетом типа возвращаемых данных $res === false
.
Использование
global $wpdb; $wpdb->update( $table, $data, $where, $format, $where_format );
- $table(строка) (обязательный)
- Название таблицы, данные в которой нужно обновить.
- $data(массив) (обязательный)
Данные, которые нужно обновить в формате
[ 'название колонки' => 'новое значение' ]
.Если в значении указать NULL, то в значение будет установлено в NULL, соответствующий формат при этом игнорируется.
- $where(массив)
- Ассоциированный массив с условием замены (WHERE) в формате
[ 'название колонки' => 'чему равно' ]
. Несколько условий будут объеденные черезAND
. Если в значении указатьNULL
то в запросе получим сравнениеIS NULL
, соответствующий формат при этом игнорируется. - $format(массив/строка)
Массив форматов данных которые будут ассоциированы с указанными значениями в параметре $data. Если указана строка, то она (формат) будет ассоциирован со всеми данными. При указании формата, WordPress переводит переданные данные в указанный формат перед созданием запроса. Возможные форматы:
%s
- строка%d
- целое число%f
- дробное число
Если не указать, то для всех значений $data будет указан формат
строка
, если иное не указано в свойстве wpdb::$field_types.
По умолчанию: null- $where_format(массив/строка)
- Тоже самое что и $format, только для $where данных.
По умолчанию: null
Примеры
#1. Обновим строку ID которой равен 1
Значение первой колонки строка, значение второй колонки число:
$wpdb->update( 'table', [ 'column1' => 'value1', 'column2' => $_GET['val'] ], [ 'ID' => 1 ] );
#2. Тоже самое с указанием типов передаваемых данных
$wpdb->update( 'table', [ 'column1' => 'value1', 'column2' => $_GET['val'] ], [ 'ID' => 1 ], [ '%s', '%d' ], [ '%d' ] );меню
replace — замена строки
Обновляет или создает строку в таблице.
Если строка с указанным ключом PRIMARY KEY уже есть все остальные указанные поля будут обновлены у строки. Если такой строки в таблице еще нет, то функция вставит (insert) новую строку.
После вставки, ID созданный для колонки AUTO_INCREMENT можно получить в свойстве $wpdb->insert_id.
Метод включает защиту от SQL инъекций и данные можно передавать неочищенные, например: $_GET['foo']
...
PRIMARY KEY может состоять из нескольких ключей. В этом случае при поиске для замены или для создания новой строки всегда будут использоваться колонки указанные в PRIMARY KEY. Например PRIMARY KEY состоит из двух колонок ID и type, т.е. ключ при создании указывался так: PRIMARY KEY (ID,type)
. Тогда для замены существующей строки в $data нужно указать значение этих двух колонок. Если например указать ID и не указать type, то существующая строка не будет найдена и будет создана новая строка с указанным ID и пустым значением type. Все остальные поля кроме полей из PRIMARY KEY в поиске существующей строки не участвуют.
Если длина строки в параметре $data больше чем допускается в ячейке таблицы MySQL, вставка провалиться и функция вернет false. При этом в свойство $wpdb->last_error сообщение об ошибке НЕ будет записано!
Поэтому очень важно убедиться, что вставляемые данные подходят под размер ячеек (колонок). Иначе просто ничего не произойдет и вы не увидите никаких ошибок или предупреждений...
Всегда заменяются все поля таблицы. Например, если у таблицы есть поля primary, one, two, three
, а мы указали в параметре $data только primary, one
, то поля two
и three
получат дефолтные значения, даже если там уже были данные.
Возвращает
Число (кол-во обработанных строк), 0 или false.
число
- сколько строк было обработано (удалено или вставлено). Если была замена (обновление), то для каждой обновленной строки вернется +2 (удаление и вставка). Если была просто вставка, то для каждой вставленной строки вернется +1.0
- запрос был выполнен корректно, но ни одна строка не была обработана.false
- запрос провалился - ошибка запроса. Или когда невозможно заменить или создать новую строку в таблице.
Вернет количество затронутых строк - это сумма вставленных и удаленных строк. Если вернулось 1 при замене одной строки - это значит что одна строка была вставлена и ни одна не была удалена. Если число больше 1 - это значит, что одна или больше строк были удалены перед вставкой новой строки.
Иногда может произойти замена сразу нескольких старых строк - это когда заменяемые данные совпадают с существующими, а уникальный индекс у старых строк при этом разный.
Использование
global $wpdb; $wpdb->replace( $table, $data, $format );
- $table(строка) (обязательный)
- Название таблицы, в которой нужно заменить данные.
- $data(массив) (обязательный)
Данные, которые нужно заменить/вставить в формате
[ 'название колонки' => 'новое значение' ]
.Если в значении указать NULL, то в значение будет установлено в NULL, соответствующий формат при этом игнорируется.
- $format(массив/строка)
Массив форматов данных которые будут ассоциированы с указанными значениями в параметре $data. Если указана строка, то она (формат) будет ассоциирован со всеми данными. При указании формата, WordPress переводит переданные данные в указанный формат перед созданием запроса. Возможные форматы:
%s
- строка%d
- целое число%f
- дробное число
Если не указать, то для всех значений $data будет указан формат
строка
, если иное не указано в свойстве wpdb::$field_types.
По умолчанию: null
Примеры
#1 Заменим строку с главным ключом ID = 1
(подразумевается что таблица состоит из трех колонок ID, column1, column2
).
Строка будет добавлена если её нет или полностью обновлена если она есть. Тут важно указывать значения для всех полей, потому что поля без значений получат дефолтные, даже если в них до этого были данные.
$wpdb->replace( 'table_name', [ 'ID' => 1, 'column1' => 'value1', 'column2' => 123 ] );
#2 Укажем форматы
$wpdb->replace( 'table', [ 'column' => 'foo', 'field' => 1337 ], [ '%s', '%d' ] );меню
delete — удаление строки из таблицы
Удаляет строки из таблицы по переданному в параметр $where условию.
Метод включает защиту от SQL инъекций и можно передавать неочищенные данные, например: $_GET['foo']
...
Возвращает
Число/0. Число удаленных строк или 0, если ничего не удалено.
Использование
global $wpdb; $wpdb->delete( $table, $where, $where_format );
- $table(строка) (обязательный)
- Название таблицы.
- $where(массив) (обязательный)
- Массив условий, по которым будут выбираться строки для удаления в формате
[ 'название колонки' => 'чему равно' ]
. Несколько условий будут объеденные черезAND
. Если в значении указатьNULL
то в запросе получим сравнениеIS NULL
, соответствующий формат при этом игнорируется. - $where_format(массив/строка)
Массив форматов данных которые будут ассоциированы с указанными значениями в параметре $where. Если указана строка, то она (формат) будет ассоциирован со всеми данными. При указании формата, WordPress переводит переданные данные в указанный формат перед созданием запроса. Возможные форматы:
%s
- строка%d
- целое число%f
- дробное число
Если не указать, то для всех значений $data будет указан формат
строка
, если иное не указано в свойстве wpdb::$field_types.
По умолчанию: null
Примеры
// Удалим строку с полем ID=1 из таблицы table $wpdb->delete( 'table', [ 'ID' => 1 ] ); // Укажем формат значения $where $wpdb->delete( 'table', [ 'ID'=>'1' ], [ '%d' ] ); // 1 будет обработано как число (%d).меню
prepare — защита запроса от SQL инъекций
Позволяет писать SQL запрос с очисткой передаваемых в него параметров.
В строке запроса вместо передаваемого параметра нужно использовать плейсхолдер: %s
, %d
или %f
. Также для каждого из плейсхолдеров указывается PHP переменная, которая заменить плейсхолдер. При замене переменная будет очищена. Синтаксис похожий на sprintf().
С WP 3.5 обязательно должны быть переданы минимум 2 параметра: запрос и значение переменной, иначе будет php ошибка (User Notice).
- Кавычки для плейсхолдеров
%s
и'%s'
. Плейсхолдеры могут быть в кавычках или без них:
WHERE field = %s
илиWHERE field = '%s'
. Кавычки принято не ставить.echo $wpdb->prepare( "foo = %s", 'a' ); // foo = 'a' echo $wpdb->prepare( "foo = '%s'", 'a' ); // foo = 'a'
- Параметр для каждого плейсхолдера.
Параметр должен быть указан для каждого плейсхолдера.
echo $wpdb->prepare( 'foo = %s AND bar = %s', 'a' ); echo $wpdb->prepare( 'foo = %1$s AND bar = %1$s', 'a' ); // в обоих случаях увидим ошибку: // User Notice: wpdb::prepare was called incorrectly. // The query does not contain the correct number of placeholders (2) // for the number of arguments passed (1).
- Порядковые плейсхолдеры
%1$s
. Для совместимости со старыми версиями: порядковые плейсхолдеры (например,
%1$s
,%5s
) обрабатываются иначе - им не добавляются кавычки, поэтому они должны быть снабжены правильными кавычками в строке запроса.echo $wpdb->prepare( 'foo = %1$s', 'a"a' ); // foo = a\"a echo $wpdb->prepare( 'foo = "%1$s"', 'a"a' ); // foo = "a\"a" echo $wpdb->prepare( 'foo = %1s', 'a"a' ); // foo = a\"a echo $wpdb->prepare( 'foo = %s', 'a"a' ); // foo = 'a\"a'
- Знак
%
Знак
%
в строке запроса, который не относится к плейсхолдеру нужно записывать так%%
.echo $wpdb->prepare( "%foo AND id = %d", 2 ); // User Notice: wpdb::prepare was called incorrectly. echo $wpdb->prepare( "%%foo AND id = %d", 2 ); // %foo AND id = 2
%
в LIKE синтаксисеПодстановочные знаки процента
%
в LIKE синтаксисе должны указываться через параметр подстановки содержащий полную LIKE строку, а не напрямую в запросе. Также смотрите wpdb::esc_like().$like = '%'. $wpdb->esc_like( 'bar' ) .'%end'; echo $wpdb->prepare( "foo LIKE %s", $like ); // foo LIKE '{fcc76a}bar{fcc76a}end'
SQL инъекция
В SQL есть такое понятие как «инъекция» (внедрение в запрос SQL кода). Cделать его можно, когда в запрос передаются динамические данные. Например, допустим в запрос передаётся значение input поля, тогда в поле формы можно указать данные, которые в итоге станут частью SQL запроса. Так можно внедриться в запрос и что-нибудь испортить или просто нарушить код самого запроса. Выглядит это так:
$sql = "SELECT * FROM table WHERE id = '$var'";
Теперь, если $var = 2' AND id = (DROP TABLE table2)
то в результате запрос получиться такой:
SELECT * FROM table WHERE id = '2' AND id = (DROP TABLE table2)
Таким образом можно внедриться в сам запрос и изменить его. Чтобы этого не произошло запросы с передаваемыми в них переменными нужно обрабатывать этой функцией:
$sql = $wpdb->prepare( "SELECT * FROM table WHERE id = %s", $var );
esc_sql()
Кроме метода $wpdb->prepare() запрос можно очистить функцией esc_sql(). Но «prepare» предпочтительнее, потому что исправляет некоторые ошибки форматирования.
$name = esc_sql( $name ); $status = esc_sql( $status ); $wpdb->get_var( "SELECT something FROM table WHERE foo = '$name' and status = '$status'" );
ВАЖНО! После esc_sql() очищенную строку можно использовать только внутри кавычек ''
или ""
. Т.е. правильно писать field = '$value'
, а не field = $value
, где $value = esc_sql( $value );
Возвращает
Строку/null. Sanitized query string, if there is a query to prepare.
Использование
global $wpdb; $wpdb->prepare( $query, ...$args );
- $query(строка) (обязательный)
Строка запроса. В нем можно использовать заменители:
%d
- число%s
- строка%f
- дробное число (число с плавающей точкой, с версии 3.3).
- ...$args(строка/число/массив)
Переменные, которые будут использованы для замены плейсхолдеров
%s %d %f
в строке запроса.Эти переменные можно указать через запятую (как дополнительные параметры функции) или в массиве:
$wpdb->prepare( 'query', $param1, $param2 )
$wpdb->prepare( 'query', [ $param1, $param2 ] )
.
Примеры
#2. Демонстрация работы
$wpdb->prepare( "SELECT * FROM `table` WHERE `column` = %s AND `field` = %d OR `other_field` LIKE %s", [ 'foo', 1337, '%bar' ] ); $wpdb->prepare( "SELECT DATE_FORMAT(`field`, '%%c') FROM `table` WHERE `column` = %s", 'foo' );
#2. Добавим произвольное поле к посту 10
Из примера видно, что с prepare() нет необходимости заботиться об экранировании кавычек и прочего, что может навредить запросу.
$metakey = "'крах' БД"; $metavalue = "WordPress может 'сломать' Базу Данных если не экранировать запрос."; $wpdb->query( $wpdb->prepare( "INSERT INTO $wpdb->postmeta ( post_id, meta_key, meta_value ) VALUES ( %d, %s, %s )", 10, $metakey, $metavalue ) );
#3. Передача параметров в виде массива
Это такой же пример, только тут все переменные передаются во втором параметре в виде массива.
Передавать параметры в виде массива, может быть полезно, когда мы заранее не знаем количество аргументов, которые нужно будет передать.
$metakey = "'крах' БД"; $metavalue = "WordPress может 'сломать' Базу Данных если не экранировать запрос."; $wpdb->query( $wpdb->prepare( "INSERT INTO $wpdb->postmeta ( post_id, meta_key, meta_value ) VALUES ( %d, %s, %s )", array( 10, $metakey, $metavalue ) ) );меню
esc_like — очистка LIKE строки
Подготавливает строку для использования в LIKE части SQL запроса. Обрабатывает спецсимволы %
и _
.
Используйте эту функцию перед wpdb::prepare() или esc_sql(). Обратный порядок опасен для защиты запроса.
Эта функция используется вместо устаревшей с WP 4.0. функции like_escape( $string ).
Возвращает
Строку. Текст для LIKE части запроса. Результат не очищен для SQL запроса, поэтому используйте wpdb::prepare() или wpdb::_real_escape() для добавления результата в запрос.
Использование
global $wpdb; $wpdb->esc_like( $text );
- $text(строка) (обязательный)
- Необработанный текст, спец-символы в котором нужно экранировать для LIKE строки. Строка не должна иметь дополнительных или удаленных слэшей.
Примеры
#1 Пример подготовки строки для LIKE запроса
$wild = '%'; $find = 'only 43% of planets'; $like = $wild . $wpdb->esc_like( $find ) . $wild; $sql = $wpdb->prepare( "SELECT * FROM $wpdb->posts WHERE post_content LIKE %s", $like ); echo $sql; // SELECT * FROM wp_posts WHERE post_content LIKE '{d710cab}only 43\\{d710cab} of planets{d710cab}'
#2 Пример с esc_sql()
$esc_like = $wpdb->esc_like( 'only 43% of planets' ); echo $esc_like; // only 43\% of planets echo esc_sql( $esc_like ); // only 43\\{f5fa52} of planets
#3 Еще пример подготовки строки для LIKE запроса
global $wpdb; $link = $wpdb->esc_like( $link ); // подготовим строку для LIKE аргумента $link = esc_sql( $link ); // очистим переменную $link = '%' . $link . '%'; // создадим полную переменную поиска LIKE // найдем комментарии в тексте или ссылке автора, есть указанная ссылка $spammy = $wpdb->query("SELECT comment_approved FROM $wpdb->comments WHERE (comment_content LIKE '$link' OR comment_author_url LIKE '$link') AND comment_approved = 'spam' LIMIT 1;" );
#4 Короткая запись с prepare()
global $wpdb; $link = '%' . $wpdb->esc_like( $link ) . '%'; $comment = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->comments WHERE comment_author_url LIKE %s LIMIT 1", $link ) );меню
show/hide/print_error — показать или спрятать ошибки SQL
Есть возможность управлять ошибками, включать или выключать показ ошибок для последнего запроса:
$wpdb->show_errors(); // включит показ ошибок $wpdb->hide_errors(); // выключит показ ошибок $wpdb->print_error(); // включит показ ошибок на экран
get_col_info — получить информацию о колонке
Получает информацию о колонках последнего запроса. Функция вернет массив с информацией об определенных в запросе колонках. Если в запросе колонки не определены, то функция вернет информацию о всех колонках таблицы. Это может пригодится, когда был возвращен объект, о данных которого мы ничего не знаем.
Работает на основе кэша, поэтому сначала нужно запустить запрос с помощью get_results(), get_col(), get_var() и т.д. а потом вызвать wpdb::get_col_info() которая вернет данные колонок последнего запроса.
$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
По умолчанию: name
- $offset(число)
Указатель, информацию о какой колонке нужно получить:
-
Если указать
-1
, то будут получена информация о всех колонках в виде массива. По умолчанию. - Если указать 0 или больше то будет возвращена информация об указанной колонке, где 0 - первая колонка, 1 - вторая и т.д.
По умолчанию: -1
-
Примеры
global $wpdb, $table_name; $wpdb->show_errors(); // включим показ SQL ошибок $results = $wpdb->get_results( "SELECT * FROM $table_name" ); $cols_name = $wpdb->get_col_info('name'); echo 'Колонки таблицы `'. $table_name .'`:'; if( is_array($cols_name) ){ foreach( $cols_name as $name ) echo " $name"; } else { echo 'Ошибка, нет данных: '; $wpdb->print_error(); } $wpdb->hide_errors(); // выключим показ SQL ошибокменю
flush — сброс кэша
Можно сбросить последние сохраненные данные в свойствах класса:
$wpdb->flush();
Эта команда очистит следующие свойства (переменные): $wpdb->last_result, $wpdb->last_query и $wpdb->col_info.
Свойства (переменные) класса
- $show_errors
- Показывать ошибки или нет, когда возвращается результат.
По умолчанию: true (да) - $suppress_errors
- Подавлять ли ошибки в процессе построения запроса.
- $last_error
- Последняя ошибка из любого запроса.
- $num_queries
- Количество запросов, которые выполняются.
- $num_rows
- Количество строк, возвращенных последним запросом.
- $rows_affected
- Сохраняет число задействованных строк из последнего запроса. Заполняется при следующих sql командах: create, alter, truncate, drop, insert, delete, update, replace - в остальных случаях заполняется свойство $num_rows.
- $insert_id
- Идентификатор (ID) сгенерированный последним запросом, для SQL параметра AUTO_INCREMENT
- $last_query
- Последний запрос, который был выполнен классом.
- $last_result
- Результат последнего запроса.
- $func_call
- Текстовое описание последнего вызова query/get_row/get_var
- $queries
- Можно сохранить все запросы которые были сделаны к БД и их время выполнения, для этого нужно определить константу SAVEQUERIES как TRUE (например в config.php). По умолчанию она выключена (false). После того как эта константа включена в эту переменную будут собираться все запросы в виде массива данных.
- $col_info
- Информация о колонках последнего запроса.
- $prefix
- Префикс таблиц БД определенный для WordPress. Может пригодиться для мульти-сайтов.
- $base_prefix
- Префикс базовой таблицы WordPress. В мультисайте для сайтов сети префик отличается. Тут хранится префикс таблиц основного сайта сети.
- $ready
- Логический. Готов ли класс к выполнению запросов.
- $blogid
- Идентификатор текущего блога.
- $siteid
- ID сайта.
- $tables
Список названий таблиц, которые используются (копируются) для каждого подсайта сети сайтов. Название таблиц будет отличаться префиксом текущего блога. Названия без префикса по умолчанию:
var $tables = array( 'posts', 'comments', 'links', 'options', 'postmeta', 'terms', 'term_taxonomy', 'term_relationships', 'termmeta', 'commentmeta', );
- $global_tables
Глобальные таблицы. Не повторяются для подсайтов.
array( 'users', 'usermeta' );
- $ms_global_tables
Глобальные таблицы в режиме MU.
var $ms_global_tables = array( 'blogs', 'blogmeta', 'signups', 'site', 'sitemeta', 'sitecategories', 'registration_log', );
- $collate
- Режим сопоставления (сравнивания) данных в колонках базы данных.
- $dbh
- PHP объект базы mysqli.
Таблицы Базы Данных WordPress

Записи — подробнее здесь
- $wpdb->posts
- Таблица куда записываются посты, постоянные страницы, произвольные типы записей, вложения и т.п.
- $wpdb->postmeta
- Дополняет таблицу
$wpdb->posts
. Хранит дополнительные данные записей (постов) их еще называют метаполя.
Пользователи
- $wpdb->users
- Таблица с данными о зарегистрированных пользователях.
- $wpdb->usermeta
- Дополнительная информация о пользователях, такая как Имя, Ник, права и прочее.
Мета поля для таблицы $wpdb->users.
Комментарии
- $wpdb->comments
- Таблица с записями комментариев.
- $wpdb->commentmeta
- Мета поля для таблицы $wpdb->comments.
Таксономии — подробнее
- $wpdb->terms
- Таблица содержащая в себе информацию о названии категорий, меток, категорий ссылок и других таксономий.
- $wpdb->termmeta
- Таблица содержащая в себе дополнительные поля для таблицы $wpdb->terms.
- $wpdb->term_taxonomy
- Таблица с информацией о различных таксономиях их описание.
- $wpdb->term_relationships
- Таблица связывающая таксономии с контентом (постами, записями и т.п.)
Остальные таблицы
- $wpdb->links
- Таблица с записями ссылок.
- $wpdb->options
- Таблица опций (настроек).
Таблицы Multisite сборки
- $wpdb->blogs
- Все сайты подсети.
- $wpdb->blog_versions
- Содержит текущую версию базы данных каждого сайта. Данные обновляются при обновлении БД для каждого сайта сети.
- $wpdb->registration_log
- Содержит данные администраторов сайтов, которые создаются при создании сайтов.
- $wpdb->signups
- Содержит пользователей, которые были зарегистрированы через базовую регистрацию WordPress со страницы:
Администрация > Супер Админ > Настройки
. - $wpdb->site
- Содержит, адреса основных сайтов.
- $wpdb->sitemeta
- Данные сайтов: различные опции, включая администратора сайта.
- $wpdb->users
- Список пользователей всех сайтов сети. Это общая таблица пользователей для всей сети. Это привычная таблица, только в мультисайт версии добавляются еще 2 поля: spam и delete.
- $wpdb->usermeta
- Содержит мета-данные пользователей. Настройки пользователя для разных сайтов сети отличаются префиксом в индексе ключа. Например роли хранятся в таких метаполях: wp_capabilities, wp_1_capabilities, wp_2_capabilities ...
- Базовые таблицы каждого сайта сети
- Таблицы сайта сети: wp_posts, wp_options и т.д.. Для каждого сайта сети создаются одинаковые таблицы, но с разным префиксом, например: wp_options, wp_1_options, wp_2_options...
—
Много быстрых и качественных подписчиков на свой канал в Телеграмм можно приобрести на сервисе https://doctorsmm.com/. Здесь, при покупке ресурса, Вы сможете подобрать для себя наиболее приемлемый формат аудитории и скоростной режим, в котором подписчики будут поступать к Вам в сообщество за более чем приятные глазу цены. Теперь развиваться в Телеграмме стало еще проще, быстрее и дешевле!
Список изменений
С версии 0.71 | Введена. |