WordPress.org

Ready to get started?Download WordPress

Codex

Class Reference/ru:wpdb Class

Эта страница помечена как незавершённая. Вы можете помочь проекту, дополнив её.

Contents

Взаимодействие с базами данных

WordPress предоставляет класс функций для всех манипуляций с базами данных. Данный класс называется wpdb и основан на ezSQL свободном классе, написанном и поддерживаемом Justin Vincent.

Использование $wpdb Object

Методы класса wpdb() не должны вызываться напрямую.

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

Объект $wpdb может использоваться для чтения данных из любой таблицы в базе данных WordPress (например пользовательские таблицы), а не только стандартных таблиц которые создаёт WordPress. Например для выборки(запроса SELECT) некоторой информации из пользовательской таблицы названной "mytable", вы можете сделать следующее:

$myrows = $wpdb->get_results( "SELECT id, name FROM mytable" );

Объект $wpdb может обращаться с любым количеством таблиц, но только одной базой данных - базой данных WordPress. В редких случаях, если вам понадобится подключится к другой базе данных, вам придётся создать экземпляр нового объекта из класса wpdb с соответствующими подробностями соединения для пользовательской базы данных. Для чрезвычайно сложных установок с множеством баз данных, рассмотрите возможность использования hyperdb.

Произвольные Запросы к Базе Данных

Функция query позволяет вам выполнить любой SQL запрос к базе данных WordPress. Однако, лучше использовать более специфичные функции(смотрите ниже) для SELECT запросов.  <?php $wpdb->query('query'); ?> 

query 
(string) SQL запрос который вы хотите выполнить.

Функция возвращает целое число, соответствующее количеству затронутых/выбранных строк. При ошибке MySQL функция возвращает FALSE. (Замечание: поскольку 0 и FALSE могут возвратится, убедитесь, что вы используете корректный оператор сравнения: equality(равенство) == против identicality(идентично) ===).

Замечание: Как и во всех функциях данного класса которые выполняют SQL запросы, вы должны экранировать весь SQL ввод(e.g., wpdb->escape($user_entered_data_string)). См. раздел Protect Queries Against SQL Injection Attacks ниже.

Примеры

Удаление мета ключа 'gargle' и значения из Post 13. (Мы добавили метод 'prepare' чтобы быть уверенными, что мы не имеем дело с недопустимой операцией или символами):

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

Performed in WordPress by delete_post_meta().


Сделать страницу 7 родительской для страницы 15 Page.

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

SELECT a Variable

The get_var function returns a single variable from the database. Though only one variable is returned, the entire result of the query is cached for later use. Returns NULL if no result is found.

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

query 
(string) The query you wish to run. Setting this parameter to null will return the specified variable from the cached results of the previous query.
column_offset 
(integer) The desired column (0 being the first). Defaults to 0.
row_offset 
(integer) The desired row (0 being the first). Defaults to 0.

Examples

Retrieve and display the number of users.

<?php
$user_count = $wpdb->get_var( "SELECT COUNT(*) FROM $wpdb->users" );
echo "<p>User count is {$user_count}</p>";
?>

Retrieve and display the sum of a Custom Field value.

<?php
// set the meta_key to the appropriate custom field meta key
$meta_key = 'miles';
$allmiles = $wpdb->get_var( $wpdb->prepare( 
	"
		SELECT sum(meta_value) 
		FROM $wpdb->postmeta 
		WHERE meta_key = %s
	", 
	$meta_key
) );
echo "<p>Total miles is {$allmiles}</p>";
?> 

Выборка(SELECT) Строки

Чтобы извлечь целую строку из запроса, используйте get_row. Функция может возвращать строки как объект, ассоциативный массив или как численно индексированный массив. Если в запросе возвращается более чем одна строка, только указанная строка будет возвращена в функции, но все строки будут прокэшированны для дальнейшего использования. Возвращает ОБЪЕКТ содержащий NULL если результат не определён, учитывайте это когда используете возвращённую переменную в качестве аргумента, смотрите пример ниже.

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

query 
(string) Запрос который вы хотите выполнить.
output_type 
Одна из трёх предопределённых констант. По умолчанию OBJECT.
  • OBJECT - результат выводится как объект.
  • ARRAY_A - результат выводится как ассоциативный массив.
  • ARRAY_N - результат выводится как численно индексированный массив.
row_offset 
(integer) Требуемая строка (0 является первой). По умолчанию 0.

Примеры

Получение всей информации об Link 10.

$mylink = $wpdb->get_row("SELECT * FROM $wpdb->links WHERE link_id = 10");

Свойствами объекта $mylink являются имена столбцов полученные в результате SQL запроса (в данном примере все столбцы из таблицы $wpdb->links, но вы также можете запросить только определённые столбцы).

echo $mylink->link_id; // prints "10"

в противоположность этому, использование

$mylink = $wpdb->get_row("SELECT * FROM $wpdb->links WHERE link_id = 10", ARRAY_A);

выведет результат в качестве ассоциативного массива:

echo $mylink['link_id']; // prints "10"

или

$mylink = $wpdb->get_row("SELECT * FROM $wpdb->links WHERE link_id = 10", ARRAY_N);

численно индексированного массива:

echo $mylink[1]; // prints "10"

Если записи с ID 10 не существует в данной таблице, будет возвращено null. Следующее может быть ложным:

if ($mylink != null) {
  // какие-либо действия с ссылкой 
  return true;
} else {
  // ссылка не найдена
  return false;
}

SELECT a Column

To SELECT a column, use get_col. This function outputs a one dimensional array. If more than one column is returned by the query, only the specified column will be returned by the function, but the entire result is cached for later use. Returns an empty array if no result is found.

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

query 
(string) the query you wish to execute. Setting this parameter to null will return the specified column from the cached results of the previous query.
column_offset 
(integer) The desired column (0 being the first). Defaults to 0.

Examples

For this example, assume the blog is devoted to information about automobiles. Each post describes a particular car (e.g. 1969 Ford Mustang), and three Custom Fields, manufacturer, model, and year, are assigned to each post. This example will display the post titles, filtered by a particular manufacturer (Ford), and sorted by model and year.

The get_col form of the wpdb Class is used to return an array of all the post ids meeting the criteria and sorted in the correct order. Then a foreach construct is used to iterate through that array of post ids, displaying the title of each post. Note that the SQL for this example was created by Andomar.

<?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
	} 
}
?>

This example lists all posts that contain a particular custom field, but sorted by the value of a second custom field.

<?php
// List all posts with custom field Color, sorted by the value of custom field Display_Order
// does not exclude any 'post_type'
// assumes each post has just one custom field for Color, and one for 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
	}
}
?>

Выборка(SELECT) Generic Results

Generic, mulitple row results can be pulled from the database с помощью get_results. Функция возвращает весь результат запроса как массив, или NULL если результат отсутствует. Каждый элемент данного массива соответствует одной строке результата запроса и, подобно get_row, может быть ОБЪЕКТОМ, ассоциативным массивом, или целочисленным массивом.

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

query 
(string) Запрос который вы хотите выполнить. При выставлении этого параметра как null функция вернёт данные из кэшированного результата предыдущего запроса.
output_type 
Одна из четырёх предопределённых констант. По умолчанию - OBJECT. Смотрите Выборка(SELECT) Строки и примеры для подробной информации.
  • OBJECT - результат будет выводиться как численно индексированный массив объектов строк.
  • OBJECT_K - результат будет выводиться как ассоциативный массив объектов строк, используя значения первого столбца в качестве ключей (дубликаты будут проигнорированы).
  • ARRAY_A - результат будет выводиться как численно индексированный массив ассоциативных массивов, используя имена столбцов в качестве ключей.
  • ARRAY_N - результат будет выводиться как численно индексированный массив численно индексированных массивов.

Поскольку эта функция использует функцию '$wpdb->query()' все переменные класса установлены правильно. The results count for a 'SELECT' query will be stored in $wpdb->num_rows.

Примеры

Получение 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;
}

Получение всей информации о черновиках Пользователя с 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="Permalink: <?php the_title(); ?>">
				<?php the_title(); ?>
			</a>
		</h2>
		<?php
	}
	else
	{
		?>
		<h2>Not Found</h2>
		<?php
	}
}
?>

Вставка(INSERT) строк

Вставка строки в таблицу.

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

table 
(string) Имя таблицы для вставки.
data 
(array) Данные для вставки (в паре "столбец => значение"). Данные столбец и значение должны быть "сырыми" (не должны быть экранированы).
format 
(array|string) (не обязательно) Множество форматов для сопоставления с каждым из значений в $data. Если строка - этот формат будет использоваться для всех значений в $data. Если опущено - все значения в $data будут обрабатываться как строки если иное не предусмотрено в wpdb::$field_types.

Возможные значения 'format': %s как строка; %d как десятичное число; и %f как число с плавающей точкой.

После вставки, сгенерированный ID для столбца AUTO_INCREMENT может быть доступно с:

$wpdb->insert_id

Эта функция возвращает false если строка не может быть вставлена.

Примеры

Вставка двух столбцов в строку, первое значение является строкой, а второе - числом:

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

UPDATE строки

Обновление строки в таблице. Возвращает false при ошибке или номер обновлённой строки при успешном обновлении.

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

table 
(string) Имя таблицы для обновления.
data 
(array) Данные для обновления (в паре столбец => значение). $data столбец и $data значение должны быть "сырыми" (не должны быть экранированы).
where 
(array) A named array of WHERE clauses (in column => value pairs). Multiple clauses will be joined with ANDs. Both $where columns and $where values should be "raw".
format 
(array|string) (optional) An array of formats to be mapped to each of the values in $data. If string, that format will be used for all of the values in $data.
where_format 
(array|string) (optional) An array of formats to be mapped to each of the values in $where. If string, that format will be used for all of the items in $where.

Possible format values: %s as string; %d as decimal number and %f as float. If omitted, all values in $where will be treated as strings.

This function returns the number of rows updated, or false if there is an error.

Examples

Update a row, where the ID is 1, the value in the first column is a string and the value in the second column is a number:

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

Attention: %d can't deal with comma values - if you're not using full numbers, use string/%s.

Защита Запросов от Атак типа SQL Injection

Для более полного обзора SQL экранирования в WordPress, смотрите database Data Validation. Эта статья Data Validation является must-read для каждого автора кода и плагинов для WordPress.

Все данные в SQL запросе должны быть экранированы прежде чем SQL запрос будет выполнен чтобы предотвратить атаки SQL injection. Это может быть удобно выполнено с помощью метода prepare, который поддерживает как sprintf()-подобный, так и vsprintf()-подобный синтаксис.

Обратите внимание: По состоянию на версию 3.5, wpdb::prepare() навязывает минимум 2 аргумента. [подробная информация]

<?php $sql = $wpdb->prepare( 'query' , value_parameter[, value_parameter ... ] ); ?>
query 
(string) SQL запрос который вы хотите выполнить, с заполнителями %s и %d. Другие % символы могут вызвать ошибку обработки, если они не экранированы. Все символы % внутри строкового литерала SQL, включая LIKE шаблоны, должны быть продублированы(%%).
value_parameter 
(int|string|array) Значения подставляемые в заполнители. Many values may be passed by simply passing more arguments in a sprintf()-like fashion. Alternatively the second argument can be an array containing the values as in PHP's vsprintf() function. Необходимо соблюдать осторожность, чтобы не допустить прямого ввода пользователем данного параметра, который бы позволил манипулировать массивом любого запроса с несколькими заполнителями. Значения не должны быть уже экранированы.

Примеры

Add Meta key => value pair "Harriet's Adages" => "WordPress' database interface is like Sunday Morning: Easy." to Post 10.

$metakey	= "Harriet's Adages";
$metavalue	= "WordPress' database interface is like Sunday Morning: Easy.";

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

Performed in WordPress by add_meta().

The same query using vsprintf()-like syntax.

$metakey = "Harriet's Adages";
$metavalue = "WordPress' database interface is like Sunday Morning: Easy.";

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

Note that in this example we pack the values together in an array. This can be useful when we don't know the number of arguments we need to pass until runtime.

Notice that you do not have to worry about quoting strings. Instead of passing the variables directly into the SQL query, use a %s placeholder for strings and a %d placedolder for integers. You can pass as many values as you like, each as a new parameter in the prepare() method.

Attention: You can't pass integers/numbers that have comma values via %d. If you need comma values, use %s instead.

Show and Hide SQL Errors

You can turn error echoing on and off with the show_errors and hide_errors, respectively.

 <?php $wpdb->show_errors(); ?> 
 <?php $wpdb->hide_errors(); ?> 

You can also print the error (if any) generated by the most recent query with print_error.

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

Note: If you are running WordPress Multisite, you must define the DIEONDBERROR constant for database errors to display like so:
 <?php define'DIEONDBERROR'true ); ?> 

Getting Column Information

You can retrieve information about the columns of the most recent query result with get_col_info. This can be useful when a function has returned an OBJECT whose properties you don't know. The function will output the desired information from the specified column, or an array with information on all columns from the query result if no column is specified.

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

type 
(string) What information you wish to retrieve. May take on any of the following values (list taken from the ezSQL docs). Defaults to name.
  • name - column name. Default.
  • table - name of the table the column belongs to
  • max_length - maximum length of the column
  • not_null - 1 if the column cannot be NULL
  • primary_key - 1 if the column is a primary key
  • unique_key - 1 if the column is a unique key
  • multiple_key - 1 if the column is a non-unique key
  • numeric - 1 if the column is numeric
  • blob - 1 if the column is a BLOB
  • type - the type of the column
  • unsigned - 1 if the column is unsigned
  • zerofill - 1 if the column is zero-filled
offset 
(integer) Specify the column from which to retrieve information (with 0 being the first column). Defaults to -1.
  • -1 - Retrieve information from all columns. Output as array. Default.
  • Non-negative integer - Retrieve information from specified column (0 being the first).

Clearing the Cache

You can clear the SQL result cache with flush.

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

This clears $wpdb->last_result, $wpdb->last_query, and $wpdb->col_info.

Class Variables

$show_errors 
Whether or not Error echoing is turned on. Defaults to TRUE.
$num_queries 
The number of queries that have been executed.
$last_query 
The most recent query to have been executed.
$last_error 
The most recent error text generated by MySQL.
$queries 
You may save all of the queries run on the database and their stop times by setting the SAVEQUERIES constant to TRUE (this constant defaults to FALSE). If SAVEQUERIES is TRUE, your queries will be stored in this variable as an array.
$last_result 
The most recent query results.
$col_info 
The column information for the most recent query results. See Getting Column Information.
$insert_id 
ID generated for an AUTO_INCREMENT column by the most recent INSERT query.
$num_rows 
The number of rows returned by the last query.
$prefix 
The assigned WordPress table prefix for the site.
$base_prefix 
The original prefix as defined in wp-config.php. For multi-site: Use if you want to get the prefix without the blog number appended.

Multi-Site Variables

If you are using Multi-Site, you also have access to the following:

$blogid 
The id of the current site (blog).

Tables

The WordPress database tables are easily referenced in the wpdb class.

$posts 
The table of Posts.
$postmeta 
The Meta Content (a.k.a. Custom Fields) table.
$comments 
The Comments table.
$commentmeta 
The table contains additional comment information.
$terms 
The terms table contains the 'description' of Categories, Link Categories, Tags.
$term_taxonomy 
The term_taxonomy table describes the various taxonomies (classes of terms). Categories, Link Categories, and Tags are taxonomies.
$term_relationships 
The term relationships table contains link between the term and the object that uses that term, meaning this file point to each Category used for each Post.
$users 
The table of Users.
$usermeta 
The usermeta table contains additional user information, such as nicknames, descriptions and permissions.
$links 
The table of Links.
$options 
The Options table.

Multisite Tables

These tables are used only in multisite installations.

$blogs 
The Blogs table contains a list of the separate blogs (sites) that have been set up within the network(s).
$signups 
The Signups table.
$site 
The Site table contains a list of the networks (previously known as "sites" in WPMU) that are set up in the installation (usually there is only one site listed in this table).
$sitemeta 
The Network Options (Site Meta) table contains any options that are applicable to the entire multisite installation.
$sitecategories 
The Site Categories table.
$registration_log 
The Registration Log table.
$blog_versions 
The Blog Versions table.

Related

Articles

Code Documentation

  • Class: WP_Query - Detailed Overview of class WP_Query
  • Object: $wpdb - Overview on the use of the $wpdb object
  • Function: get_query_var()
  • Function: query_posts() - Create additional custom query
  • Function: get_post() - Take an ID of an item and return the records in the database for that article
  • Function: get_posts() - A specialized function that returns an array of items
  • Function: get_pages() - A specialized function that returns an array of pages
  • Function: have posts() - a condition that determines whether the query returned an article
  • Function: the_post() - Used to automatically set the loop after a query
  • Function: rewind_posts() - Clears the current loop
  • Function: setup_postdata() - Sets the data for a single query result within a loop
  • Function: wp_reset_postdata() - Restores the previous query (usually after a loop within another loop)
  • Function: wp_reset_query()
  • Function: is_main_query() - Ensures that the query that is being changed is only the main query
  • Action Hook: pre_get_posts - Change WordPress queries before they are executed
  • Action Hook: the_post - Modify the post object after query
  • Filter Hook: found_posts - Changes the value of the object found_posts WP_Query
See also index of Class Reference and index of Function Reference.