Codex

Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Плагины: создание таблиц БД

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

Если вы создаете плагины для WordPress, то наверняка вы сталкивались с необходимостью сохранить некоторые данные в базе данных WordPress. Существуют два типа данных, доступных для сохранения:

  • Установочная информация -- опции пользователя. Они вводятся пользователем когда он (она) задает установки плагина во время первого пользования, и впоследствии больше не увеличиваются в размерах; например, в плагине, связанного с тегами, опции пользователя в отношении формата собрания тегов в боковой колонке.
    Установочная информация обычно сохраняется с использованием WordPress options mechanism.
  • Данные -- информация которая добавляется пользователем по мере использования вашего плагина, обычно являющаяся расширенной информацией связанной с записями, категориями, загрузками и другими компонентами WordPress(например: плагины статистики, различные виды страниц, ссылки, и другие статистические данные связанные с каждой записью на вашем сайте).

Данные могут хранится в отдельной созданной MySQL таблице. Перед созданием совершенно новой таблицы, рассмотрите возможность сохранения данных Вашего плагина в WordPress' Post Meta (ранее Поля, созданные пользователем). Post Meta - это предпочитаемый метод, пользуйтесь им когда это возможно или практично.

This article describes how to have your plugin automatically create a MySQL table to store its data. Note that as an alternative to following the steps here, you could have the plugin user run an install script when they install your plugin. Another approach would be to have the user execute an SQL query on their own, using something like phpMyAdmin. But neither of those options is very satisfactory, since a user could easily forget to run the install script or screw up the query (and they might not have phpMyAdmin available).

Мы рекомендуем следовать следующим шагам для автоматического создание вашим плагином таблицы в безе данных:

  1. Напишите PHP функцию , которая создаст таблицы.
  2. Убедитесь в том, что WordPress вызывает эту функцию , при установке плагина.
  3. Создайте функцию обновления , если новая версия вашего плагина использует другую структуру таблиц БД.

Создание таблиц в базе данных

Первым шагом в автоматическом создании таблицы в базе данных вашим плагином, является создание функции PHP (в вашем плагине) , которая добавит таблицу или таблицы в базу данных WordPress (в этой статье будем будем использовать jal_install для обозначения этой функции).

Префикс таблиц в базе данных

В файле wp-config.php, владелец сайта на WordPress может определить префикс таблиц в базе данных. По умолчанию, префикс имеет вид "wp_", но Вам следует проверить актуальное значение и использовать его для определения имени Вашей таблицы. Это значение, вы узнаете из переменной $wpdb->prefix. (Если вы программируете для версий, ранних чем Wordpress 2.0, вы должны использовать глобальную переменную $table_prefix, которая является устаревшей для версий поздних 2.1).

К примеру, вы хотите создать таблицу с именем (prefix)liveshoutbox, тогда первые несколько строк вашей функции, которая создает таблицу, должны быть такими:

function jal_install () {
   global $wpdb;

   $table_name = $wpdb->prefix . "liveshoutbox";

Таблица уже существует?

Убеждаемся в том, что созданная нами таблица успешно добавлена в базу данных. Выполняя проверку по if и SQL-запросу SHOW TABLES, просматриваем таблицы и ищем, в результате выдачи запроса, имя нашей таблицы:

    if($wpdb->get_var("SHOW TABLES LIKE '$table_name'") != $table_name) {

Создание или Обновление таблицы

Следующий шаг - фактическое создание таблицы. Вместо того, чтобы напрямую делать SQL запрос, мы будем использовать функцию dbDelta из файла wp-admin/includes/upgrade.php (необходимо загрузить этот файл, так как он не подгружается по умолчанию). Функция dbDelta проверяет существующую структуру таблиц в БД, сравнивает ее с необходимой плагину структурой и, если это необходимо, вносит изменения в таблицы, (для примеров использования функции dbDelta смотри файл wp-admin/upgrade-schema.php). Необходимо заметить, что функция dbDelta "придирчива" к формату входных данных. Например:

  • В выражении SQL необходимо писать каждое поле в отдельной строке.
  • Необходимы два пробела между словами PRIMARY KEY и определением primary key.
  • Необходимо использовать ключевое слово KEY , а не его синоним INDEX . Так же, необходимо обозначить как минимум один KEY.

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

$sql = "CREATE TABLE " . $table_name . " (
	  id mediumint(9) NOT NULL AUTO_INCREMENT,
	  time bigint(11) DEFAULT '0' NOT NULL,
	  name tinytext NOT NULL,
	  text text NOT NULL,
	  url VARCHAR(55) NOT NULL,
	  UNIQUE KEY id (id)
	);";

require_once(ABSPATH . 'wp-admin/includes/upgrade.php');
dbDelta($sql);

Добавление Исходных Данных

Теперь Вам может потребоваться добавить данные в только что созданную таблицу. Сделать это можно так:

  $welcome_name = "Mr. Wordpress";
  $welcome_text = "Поздравляю, установка прошла успешно!";

  $rows_affected = $wpdb->insert( $table_name, array( 'time' => current_time('mysql'), 'name' => $welcome_name, 'text' => $welcome_text ) );

ВНИМАНИЕ: Даже если Вы сами определили переменные $welcome_name и $welcome_text в этой функции и знаете что они не содержат специальных SQL символов, хорошим тоном будет всегда обрабатывать переменную функцией $wpdb->escape перед передачей её в базу данных для предотвращения проблем безопасности и случайных ошибок. Вы можете использовать функцию $wpdb->prepare function syntax, или в данном случае, мы используем $wpdb->insert. Подробнее об использовании WPDB, смотрите Function_Reference/wpdb_Class.

Версия

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

add_option("jal_db_version", "1.0");

Функция в целом

Эта функция завершена. Давайте посмотрим как она выглядит в целом. Обратите внимание, что номер версии теперь хранится в глобальной переменной.


global $jal_db_version;
$jal_db_version = "1.0";

function jal_install () {
   global $wpdb;
   global $jal_db_version;

   $table_name = $wpdb->prefix . "liveshoutbox";
   if($wpdb->get_var("show tables like '$table_name'") != $table_name) {
      
      $sql = "CREATE TABLE " . $table_name . " (
	  id mediumint(9) NOT NULL AUTO_INCREMENT,
	  time bigint(11) DEFAULT '0' NOT NULL,
	  name tinytext NOT NULL,
	  text text NOT NULL,
	  url VARCHAR(55) NOT NULL,
	  UNIQUE KEY id (id)
	);";

      require_once(ABSPATH . 'wp-admin/includes/upgrade.php');
      dbDelta($sql);

      $rows_affected = $wpdb->insert( $table_name, array( 'time' => current_time('mysql'), 'name' => $welcome_name, 'text' => $welcome_text ) );
 
      add_option("jal_db_version", $jal_db_version);

   }
}

Вызов функции

Теперь когда мы инициализировали определение функции, мы хотим убедиться, что WordPress вызывает функцию когда плагин активируется администратором WordPress. Чтобы сделать это мы воспользуемся хуком действия activate_. Если файл вашего плагина wp-content/plugins/plugindir/pluginfile.php, добавьте следующую строку в тело вашего плагина:

register_activation_hook(__FILE__,'jal_install');

Смотрите подробнее в Function_Reference/register_activation_hook.

Добавление Функции Обновления

За время жизни вашего плагина, вы можете обнаружить, что вам нужно изменить структуру базы данных плагина в обновленной версии. Чтобы сделать это, вам понадобится создать код обновления в вашем плагине, который будет определять что была установлена новая версия и обновлять структуру базы данных. Простейший способ сделать это - добавить код в функцию jal_install которую мы только что создали.

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

Давайте предположим что функция обновляющая базу данных с версии 1.0 до 1.1 расширяет поле URL до 100 символов вместо 55). Вам понадобится добавить следующие строки в конец вашей функции jal_install для проверки версии и обновления если это необходимо:


   $installed_ver = get_option( "jal_db_version" );

   if( $installed_ver != $jal_db_version ) {

      $sql = "CREATE TABLE " . $table_name . " (
	  id mediumint(9) NOT NULL AUTO_INCREMENT,
	  time bigint(11) DEFAULT '0' NOT NULL,
	  name tinytext NOT NULL,
	  text text NOT NULL,
	  url VARCHAR(100) NOT NULL,
	  UNIQUE KEY id (id)
	);";

      require_once(ABSPATH . 'wp-admin/includes/upgrade.php');
      dbDelta($sql);

      update_option( "jal_db_version", $jal_db_version );
  }

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

Ресурсы

Для получения дополнительной информации по разработке плагинов посетите исчерпывающий список ресурсов. Вы также можете найти полезным данный пост из Списка рассылки wp-hackers : WordPress Hackers Mailing List: Answer to Plugin Requires Additional Tables