sanitize_option()

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

Подробнее – в правилах очистки.

Функция (логично предположить) возвращает очищенное значение. Если с очисткой что-то пошло не так, то регистрирует соответствующую ошибку для отображения на страницах настроек в админке функцией 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. Преподаватель в школе Нетология.

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

Чтобы оставить комментарий, пожалуйста, зарегистрируйтесь или войдите.

Миша Рудрастых и WordPress

Полезности из мира WordPress и жизни студии.

Мой телеграм-канал