Latest Posts

Options API

Функции Options API

add_option( $name, $value, $deprecated, $autoload )

get_option( $option, $default )

delete_option($name)

update_option( $option_name, $newvalue, $autoload )

Settings API

Функции Settings API

add_settings_error()

add_settings_field()

add_settings_section()

do_settings_fields()

do_settings_sections()

get_settings_errors()

register_setting()

settings_errors()

settings_fields()

unregister_setting()

Добавление полей опций

Добавление секции опций

Регистрация опций

Вывод секции опций на экран

Options API

Creating Options Pages

Settings API

API настроек (опций)

API упрощает создание, получение, обновление и удаление параметров. Все данные сохраняются в таблице wp_options под указанным пользовательским именем. Список параметров по умолчанию может быть найден в справочнике параметров

Обратите внимание, что функции, содержащие в названии код _site_, делают то же самое, что и их версии без этого кода. Единственное различие между ними возникает в случае использования технологии WP Multisite, когда параметры применяются ко всей сети сайтов и данные сохраняются в таблице wp_sitemeta под указанным пользовательским именем

Функции Options API

add_option() — добавляет настройку (название и значение опции) в базу данных и ничего не делает если эта опция уже установлена

delete_option() — удаляет настройки (запись из таблицы wp_options в БД)

get_option() — получает значение указанной настройки (опции)

update_option() — обновляет значение настройки (опции) в базе данных

wp_load_alloptions() — загружает в кэш все авто-загружаемые опции WordPress, получает все опции сайта

admin_url() — получает URL админ-панели сайта, учитывает протоколы (http и https)

get_bloginfo() — возвращает информацию о блоге из настроек. Копия bloginfo(), только эта функция получает результат в переменную, а не выводит его на экран

get_home_url() — получает url-ссылку на главную страницу сайта, без закрывающего слэша, можно указать ID сайта в сети, идентична функции home_url()

get_site_url() — получает URL сайта

home_url() — возвращает URL главной страницы сайта, учитывает протокол SSL

is_ssl() — условный тег, проверяет используется ли защищенный протокол SSL

site_url() — получает URL сайта (где установлено ядро движка WordPress) и соответствующим протоколом (https, если срабатывает условие is_ssl)

add_option( $name, $value, $deprecated, $autoload );

Добавляет настройку (название и значение опции) в базу данных. Ничего не делает, если опция уже существует.
Если данные нужно сериализовать, для хранение в БД, то они будут автоматически сериализованы перед добавлением опции. Так, в настройках можно хранить массивы.
Можно создавать опции с пустым значением и добавлять значение позже.

хуки

added_option

add_option

add_option_(option)

default_option_(option)

возвращает true — если удалось добавить настройку и false — если нет

$name(строка) (обязательный)

Название опции, которую будем добавлять. Для названий используйте подчеркивание _ для разделения слов и не используйте буквы в ВЕРХНЕМ РЕГИСТРЕ.
По умолчанию: нет

$value(строка/массив/число/объект/логический) значение опции, ограничение 232 байта

$deprecated(строка) Запрещен с версии 2.3

$autoload(строка)

Автозагрузка (загрузка опции в кэш). Нужно ли загружать эту опцию функцией wp_load_alloptions() (добавляет опцию в массив опций, при генерации страницы, затем опция берется из массива). Может быть yes или no.
По умолчанию: ‘yes’

например <?php add_option( ‘my_option’, ‘255’ ); ?>

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

get_option( $option, $default );

получает значение указанной настройки (опции)

например

<?php echo get_option(‘blogname’); ?>

Функция получает данные из кэша, если это возможно, если нет, то данные берутся из Базы Данных.

возвращает значение опции или false, если указанной опции не существует или не удалось получить значение

$option — это название опции, значение которой нужно получить:

admin_email — email администратора блога

blogname — название блога, устанавливается в настройках

blogdescription — описание блога, устанавливается в настройках

blog_charset — кодировка блога, устанавливается в настройках

date_format — формат даты, устанавливается в настройках

default_category — категория постов по умолчанию, устанавливается в настройках

home — адрес домашней страницы блога, устанавливается в основных настройках

siteurl — адрес WordPress, устанавливается в основных настройках, отличается от get_bloginfo(‘siteurl’) (который возвращает url домашней страницы блога) и не отличается от get_bloginfo(‘wpurl’)

template — название текущей темы

start_of_week — день с которого начинается неделя, устанавливается в основных настройках

upload_path — каталог загрузки по умолчанию, устанавливается в настройках

posts_per_page — максимальное число постов на странице, устанавливается в настройках чтения

posts_per_rss —  максимальное число постов выводимых в фид, устанавливается в настройках чтения

полный список опций смотрите в кодексе WordPress

хуки

default_option_(option)

option_(option)

pre_option_(option)

delete_option($name);

удаляет настройки (запись из таблицы wp_options в БД), эта функция создана для безопасного удаления настроек из базы данных

возвращает true если настройка была найдена и удалена, false в противном случае

например <?php delete_option(«myoption»); ?>

хуки

deleted_option

delete_option

delete_option_(option)

update_option( $option_name, $newvalue, $autoload )

обновляет значение настройки (опции) в базе данных

эта функция может быть использована для того, чтобы добавлять новые опции, вместо add_options()

update_option сначала проверяет существует ли указанная опция, если нет, то работа передается add_options(). Название опции очищается перед тем как опция добавляется в базу данных

до версии 4.2 нельзя было указать параметр $autoload, это значит что нельзя было указать функции, что добавляемая опция является частной и её не следует загружать в память вместе со всеми опциями (см. описание add_option) и для этого приходилось использовать функцию add_option()

если указанное значение опции равно старому значение, функция ничего не обновляет и обрывает свою работу

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

хуки

default_option_(option)

pre_update_option

pre_update_option_(option)

updated_option

update_option

update_option_(option)

возвращает true, если значение изменилось и false, если в БД ничего не поменялось, а также в случае ошибки

для включения autoload укажите в этом параметре true, yes или что-то еще кроме null, false и no

 чтобы отключить указать false или no, по умолчанию null (‘yes’)

например <?php update_option( ‘my_option’, ‘новое значение’ ); ?>

Settings API

API позволяет создавать поля форм (опции), которые будут обрабатываться автоматически (сохраняться в БД и выводиться на экран). Такой подход дает возможность удобно добавлять свои опции и блоки опций в уже существующие страницы настроек (Общие, Чтение, Медиафайлы и т.д.). Или можно создавать страницы настроек плагинов без использования лишнего кода.
Несмотря на все удобства, регистрация и проверка значений полей никуда не исчезла — все это нужно делать вручную. Использование API позволяет избежать многих багов связанных с созданием страниц настроек плагинов в админке.

Функции Settings API

add_settings_error() — регистрирует сообщение о проверке опции, чтобы позднее показать это сообщение пользователю, обычно такое сообщение — это ошибка проверки данных

add_settings_error( $setting, $code, $message, $type );

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

по умолчанию сообщение выводятся автоматически для всех подстраниц в разделе «Настройки», но если изменение опций выводятся на других страницах которые регистрируются функциями: add_menu_page() или add_submenu_page() то сообщения об обновлении опций или ошибке не будут показаны автоматически

add_settings_field() — создает поле опции для указанной секции (указанного блока настроек)

add_settings_field( $id, $title, $callback, $page, $section, $args );

создает поле опции для указанной секции (указанного блока настроек)

эта функция используется в комплексе с другими функциями API настроек, которые упрощают создание страницы настроек плагина

для этой функции уже должны быть известны параметры $page (страница плагина или админки) и $section (блок на странице, где поле будет выводиться)

add_settings_section() — создает новый блок (секцию), в котором выводятся поля настроек, т.е. в этот блок затем добавляются опции, с помощью add_settings_field()

add_settings_section( $id, $title, $callback, $page );

do_settings_fields( $page, $section );

создает поле опции для указанной секции (указанного блока настроек)

эта функция используется в комплексе с другими функциями API настроек, которые упрощают создание страницы настроек плагина

для этой функции уже должны быть известны параметры $page (страница плагина или админки) и $section (блок на странице, где поле будет выводиться)

важно: каждая опция должна быть зарегистрирована функцией register_setting(), а эта функция отвечает только за добавление поля опции (HTML кода) на страницу в нужную секцию

функция обратного вызова (параметр $callback) должна выводить поля формы input и заполнять их существующими в базе данных данными

do_settings_fields() — выводит на экран поля опций, относящихся к указанной секции

do_settings_fields( $page, $section );

создает новый блок (секцию), в котором выводятся поля настроек, т.е. в этот блок затем добавляются опции, с помощью add_settings_field()

такой блок вы можете видеть на страницах настроек WordPress или плагинов — это группы настроек разделенные заголовком

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

do_settings_sections() — выводит на экран все блоки опций, относящиеся к указанной странице настроек в админ-панели

do_settings_sections( ‘primer_page’ );

выводит на экран HTML код блоков с полями формы do_settings_sections( $page )

вывод секций настроек на странице настроек

get_settings_errors() — получает сообщения зарегистрированные функцией add_settings_error()

get_settings_errors( $setting, $sanitize );

получает сообщения зарегистрированные функцией add_settings_error()
эта функция является одной из группы функций API настроек. И является вспомогательной функцией для settings_errors()
проверяет массив $wp_settings_errors на наличие в нем добавленных при загрузке страницы сообщений (ошибок) и возвращает их
есть возможность сохранять сообщения во временную опцию: set_transient( ‘settings_errors’ ), чтобы используя get_transient() при перезагрузке страницы или новом заходе на страницу настроек мы могли получить ошибки предыдущих проверок данных  WordPress понимает эту временную опцию и если в параметре GET запроса будет установлен параметр ?settings-updated=true (если он устанавливается автоматически при удачном сохранении опций то наша временная опция с сохраненными в ней сообщениями будет слита с текущем массивом сообщений и временная опция settings_errors будет удалена

// If settings passed back from options.php then use them

if ( isset( $_GET[‘settings-updated’] ) && $_GET[‘settings-updated’] && get_transient( ‘settings_errors’ ) )

{$wp_settings_errors = array_merge( (array) $wp_settings_errors, get_transient( ‘settings_errors’ ) ); 

delete_transient( ‘settings_errors’ );}

возвращает массив, содержащий данные о сообщениях:
array(
‘setting’ =>  $setting,
‘code’    =>  $code,
‘message’ =>  $message,
‘type’    =>  $type
);

register_setting() — регистрирует новую опцию и callback функцию (функцию обратного вызова) для обработки значения опции при её сохранении в БД

register_setting( $option_group, $option_name, $sanitize_callback );

используется в связке с другими функциями API настроек: add_settings_field(), add_settings_section(), которые упрощают создание страницы настроек

функция также может использоваться для регистрации новой опции, которая будет добавлена на базовую страницу настроек WordPress, опция добавляется в существующую секцию при помощи функции add_settings_field() или можно создать новую секцию функцией add_settings_section() и добавить опцию туда

settings_errors() — выводит на экран сообщения (уведомления и ошибки) зарегистрированные функцией add_settings_error()

settings_errors( $setting, $sanitize, $hide_on_update );

settings_errors() функция вызывается WordPress автоматически, когда загружается любая страница настроек (страница раздела админ-панели «Параметры»), если в массиве ошибок global $wp_settings_errors есть зарегистрированные сообщения они будут выведены в admin_notice

сообщения о результатах проверки опций нужно регистрировать в момент обработки этих значений — это параметр $sanitize_callback в функции register_setting( $option_group, $option_name, $sanitize_callback )

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

settings_fields() — выводит скрытые поля формы на странице настроек (option_page, _wpnonce, …)

settings_fields( $option_group );

функция используется в связке с функциями из API настроек, в её задачи входит вывод всех необходимых полей для правильной работы и защиты формы

функция должна вызываться внутри тега <form> для страницы опций

unregister_setting() — позволяет отменить зарегистрированные ранее настройки (опции). Чаще всего используется с функцией деактивации плагина: register_deactivation_hook()

например

function add_option_field_to_general_admin_page(){

$option_name = ‘my_option’;

// регистрируем опцию

register_setting( ‘general’, $option_name );

// добавляем поле

add_settings_field( ‘myprefix_setting-id’, ‘Название опции’, ‘myprefix_setting_callback_function’, ‘general’, ‘default’,

array(

‘id’ => ‘myprefix_setting-id’,

‘option_name’ => ‘my_option’

));}

add_action(‘admin_menu’, ‘add_option_field_to_general_admin_page’);

 

function myprefix_setting_callback_function( $val ) {

$id = $val[‘id’];

$option_name = $val[‘option_name’];

?><input type=»text» name=»<? echo $option_name ?>» id=»<? echo $id ?>» value=»<? echo esc_attr( get_option($option_name) ) ?>»/<?}

 

<div class=»wrap»><?php screen_icon(); ?>  

<h2>Настройки плагина Primer</h2>  

<form action=»options.php» method=»POST»>  

<?php settings_fields( ‘option_id’ ); ?>

<?php do_settings_sections( ‘primer_page’ ); ?>

<?php submit_button(); ?>  

</form></div>