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