sanitize_option()

2.0.5 wp-includes / formatting.php / Кодекс WordPress

Очищает значение опции в зависимости от того, что это за опция.

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

sanitize_option( $option, $value )

Параметры

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

Правила очистки

Итак, прежде всего, если в качестве значения параметра $option вы передали ключ, который не присутствует в данной таблице, то с его значением ничего происходить не будет, разве что оно будет пропущено через хук sanitize_option_{$option}

Название опции	Как очищается
`admin_email`, `new_admin_email`	Сначала очищается функцией sanitize_email(), затем проверяется на корректность функцией is_email().
`thumbnail_size_w`, `thumbnail_size_h`, `medium_size_w`, `medium_size_h`, `medium_large_size_w`, `medium_large_size_h`, `large_size_w`, `large_size_h`, `mailserver_port`, `comment_max_links`, `page_on_front`, `page_for_posts`, `rss_excerpt_length`, `default_category`, `default_email_category`, `default_link_category`, `close_comments_days_old`, `comments_per_page`, `thread_comments_depth`, `users_can_register`, `start_of_week`, `site_icon`	Очищается как целое неотрицательное значение функцией absint().
`posts_per_rss`, `posts_per_page`	Очищается как целое положительное, но с возможностью принимать значение `-1`. Если не существует или равно нулю, то принимает значение по умолчанию `1`.
`default_ping_status`, `default_comment_status`	Если равно пустой строке или нулю, устанавливается в значение `closed`.
`blogdescription`, `blogname`	Экранируется HTML функцией esc_html().
`blog_charset`	Удаляет все символы кроме `a-zA-Z0-9_-`
`blog_public`	Очищается как целое число, если равно `null`, то устаналивается в значение `1`.
`date_format`, `time_format`, `mailserver_url`, `mailserver_login`, `mailserver_pass`, `upload_path`	Удаляются HTML-теги функцией `strip_tags()`.
`ping_sites`	Из каждого значения удаляются лишние пробелы на концах плюс очистка функцией esc_url_raw().
`gmt_offset`	Удаляет все символы кроме `0-9:.-`
`siteurl`, `home`	Проверяет, что указан URL. Если да, очистка esc_url_raw().
`WPLANG`	Проверяет, что значение находится в массиве доступных `get_available_languages()`
`illegal_names`	Из каждого значения удаляются лишние пробелы на концах.
`limited_email_domains`, `banned_email_domains`	Удаляет пробелы на концах плюс проверяет корректность каждого значения.
`timezone_string`	Проверяет, что значение не пустое и находится в массиве доступных `timezone_identifiers_list()`
`permalink_structure`, `category_base`, `tag_base`	Очистка функцией esc_url_raw(), затем удаляет вхождения `http://`, если они присутствуют. `permalink_structure` также проверяется по регулярному выражению `/%[^\/%]+%/`
`default_role`	Если указанной роли не существует, то установит значение по умолчанию `subscriber`.
`moderation_keys`, `disallowed_keys`	Очищает пробелы на концах у каждого значения.

Кроме того, каждое из этих значение будет проверено на то, не содержит ли оно запрещённых символов для колонки option_value в базе данных.

Примеры

Сама по себе функция sanitize_option() по большей части используется именно в ядре WordPress и нужна при очистки значений стандартных опций.

Я конечно могу показать вам пример наподобие этого:

echo sanitize_option( 'thumbnail_size_w', '150px' ); // 150

… но его практическое применение без контекста может быть не совсем понятно.

Другие дело, если мы попробуем навесить свой фильтр на эту опцию.

Хуки

sanitize_option_{$option}

Перед тем, как функция возвращает значение, к нему применяется фильтр-хук:

apply_filters( "sanitize_option_{$option}", $value, $option, $original_value );

Благодаря ему мы создать своё собственное правило очистки для любой опции. Давайте это и сделаем.

Предположим, что у нас на сайте есть опция с ключом true_slider_height, которая задаёт высоту в пикселях для какого-то слайдера, скажем.

Создадим правило очистки!

add_filter( 'sanitize_option_true_slider_height', 'true_slide_height_sanitize', 25, 3 );
 
function true_slide_height_sanitize( $value, $option, $original_value ) {
 
	// $original_value – это значение вообще без очистки
	// $value – это значение, которое уже могло бы быть очищено до того, как дело дошло до фильтра
 
	// так как название опции и так есть в названии фильтра, то условие не обязательно
	// if( 'true_slider_height' === $option ) {
 
	$value = absint( $value );
	return $value;
 
}

Готово! Теперь, когда ваша опция будет обновляться функцией update_option() или добавляться функцией add_option(), её значение автоматически будет очищаться по этому правилу.

На всякий случай, если вдруг вы не знакомы с механизмом фильтров в WordPress, вот вам ссылка на видеоурок.

Миша

Впервые познакомился с WordPress в 2009 году. Организатор и спикер на конференциях WordCamp. Преподаватель в школе Нетология.

Пишите, если нужна помощь с сайтом или разработка с нуля.

Параметры
Правила очистки
Примеры
Хуки
1. sanitize_option_{$option}