Зміст циклу статей «Повне керівництво по налаштуванню WordPress API»:
Якщо ви тільки приєдналися до нас, то прочитайте попередні статті з даного циклу статей, де ми постаралися дати повний огляд WordPress Settings API і зв’язаних з ними функцій.
Ми обговорили налаштування, опції навігації та меню. Ми також відпрацювали практичні приклади, що відображають реалізацію усіх питань, які ми обговорювали.
Ми вже майже закінчили. У двох заключних статтях з цієї серії, ми поговоримо про валідації, очищення та основних елементах введення, які використовуються в плагінах і теми WordPress.
Примітка: стаття припускає, що ви вже знайомі з Settings API і опціями теми. Рекомендується спочатку ознайомитись з попередніми статтями циклу.
Поняття валідації очищення
Перед написанням якогось коду, необхідно розібратися з тим, що таке валідація та очищення. Якщо говорити простою мовою, то це механізми, які дозволяють безпечно і правильно зчитувати і записувати дані зі сторінок опцій і з бази даних.
Ми більш докладно вивчимо кожен елемент вводу і розберемо відповідні приклади, але спочатку давайте з’ясуємо деякі поняття:
- Валідація це процес перевірки даних, що надходять зі сторінки опцій, а точніше з полів користувальницьких елементів вводу, на предмет того, чи підходять вони для запису або ні;
- Очищення — це процес перевірки даних на предмет їх безпеки і відповідності заданим форматом при читанні з бази даних.
Найважливіше це те, що валідація повинна бути зроблена до запису у базу даних, а очищення – між читанням даних і відправленням їх на висновок в браузер.
Найчастіше, валідація ставиться до збереження даних, а очищення – до їх читання, але остання можлива також і після проходження валідації, щоб пересвідчитися в тому, що в базу даних не буде збережена зайва або небезпечна інформація.
Коли ми самі працюємо над проектом, це питання вирішується простіше; однак не можна завжди залежати від інших і побоюватися неправильного введення даних, тому цей процес потрібно автоматизувати і організувати заздалегідь.
Модифікація нашого проекту
Щоб краще зрозуміти, що таке валідація та очищення, давайте створимо нову закладку на нашій сторінці налаштувань. Якщо ви вже створили меню верхнього рівня, то слід додати новий підпункт. Давайте зробимо це прямо зараз.
Знайдіть функцію sandbox_example_theme_menu і додайте підпункт меню:
add_submenu_page(
‘sandbox_theme_menu’,
‘Приклади полів вводу’,
‘Приклади полів вводу’,
‘administrator’,
‘sandbox_theme_input_examples’,
create_function null, ‘sandbox_theme_display( «input_examples» );’ )
);
Далі, ми визначаємо функцію, яка буде створювати групу опцій для нової закладки. Я думаю, ви знайомі з попередніми статтями і для вас це буде дуже просто:
function sandbox_theme_initialize_input_examples() {
if( false == get_option( ‘sandbox_theme_input_examples’ ) ) {
add_option( ‘sandbox_theme_input_examples’ );
} // Кінець конструкції if
} // Кінець функції sandbox_theme_initialize_input_examples
add_action( ‘admin_init’, ‘sandbox_theme_initialize_input_examples’ );
Далі, оновимо функцію sandbox_theme_display і змусимо її виводити закладку і переходити на відповідну сторінку при кліці на пункті меню, за аналогією з прикладами в попередніх статтях.
Змінимо умовну конструкцію, яка перевіряє рядок запиту і аргументи функції. Це особливо важливо для управління регістром тексту в елементах введення. Змінений код повинен виглядати наступним чином:
if( isset( $_GET[ ‘tab’ ] ) ) {
$active_tab = $_GET[ ‘tab’ ];
} else if( $active_tab == ‘social_options’ ) {
$active_tab = ‘social_options’;
} else if( $active_tab == ‘input_examples’ ) {
$active_tab = ‘input_examples’;
} else {
$active_tab = ‘display_options’;
} // Кінець конструкції if/else
Далі, потрібно додати нову закладку. Оновіть контейнер nav-tab-wrapper включивши в нього теги посилань наступного виду:
І нарешті, додамо ще одна умова до формі, в якій виводяться опції. Оновіть умова і приведіть його до наступного вигляду:
if( $active_tab == ‘display_options’ ) {
settings_fields( ‘sandbox_theme_display_options’ );
do_settings_sections( ‘sandbox_theme_display_options’ );
} elseif( $active_tab == ‘social_options’ ) {
settings_fields( ‘sandbox_theme_social_options’ );
do_settings_sections( ‘sandbox_theme_social_options’ );
} else {
settings_fields( ‘sandbox_theme_input_examples’ );
do_settings_sections( ‘sandbox_theme_input_examples’ );
} // Кінець конструкції if/else
Якщо ви все зробили правильно, то адміністративна панель буде виглядати наступним чином:
Тепер ми готові створити елементи вводу і приступити до реалізації механізмів валідації очищення даних. Якщо код вище вам не ясний, то уважно вивчіть попередні статті циклу, присвячені налаштувань, сторінок меню і закладок.
Типи елементів вводу
Є п’ять базових елементів введення, які можуть бути використані на сторінках налаштувань WordPress. Це однорядкові поля введення (inputs), багаторядкові текстові поля (textareas), чекбокси (checkboxes), радіокнопки (radio buttons) та випадаючі списки (select boxes).
У даній статті ми розглянемо однорядкові і багаторядкові текстові поля, решта три типи елементів – в останній статті циклу.
Поле введення
Елементи вводу ідеальні для ситуацій, коли нам необхідно отримати від користувача коротку рядок тексту. Це може бути ім’я, телефонний номер, або щось більш складне – URL — чи email-адресу.
Насправді, ми вже використали поля введення на сторінці «Опції соціальних мереж» для отримання від користувача інформації про його профілі в соціальних мережах.
Валідація полів введення може бути досить складною операцією, особливо якщо ви хочете, щоб інформація задовольняла жорстким умовам.
Наприклад, телефонні номери мають визначений формат і, якщо ви просите користувача ввести номер телефону, то бажано налаштувати функцію, яка буде визначати, чи відповідає введений номер заданому формату. В рамках цієї статті ми не можемо охопити всі можливі способи застосування полів введення, оскільки ця тема дуже обширна.
Замість цього ми розглянемо функції, які усувають потенційно шкідливий код до його запису в базу даних. Це означає, що коли користувач вводить текст в полі вводу, ми автоматично видаляємо всі HTML-теги і потенційно проблемні символи. Але перед цим, давайте створимо нову опцію розмітку, і подивимося, що відбувається, коли ми не здійснюємо ніякої валідації.
Створюємо нову секцію і поле, використовуючи функцію sandbox_theme_initialize_input_examples:
add_settings_section(
‘input_examples_section’,
‘Input Examples’,
‘sandbox_input_examples_callback’,
‘sandbox_theme_input_examples’
);
add_settings_field(
‘Input Element’,
‘Input Element’,
‘sandbox_input_element_callback’,
‘sandbox_theme_input_examples’,
‘input_examples_section’
);
register_setting(
‘sandbox_theme_input_examples’,
‘sandbox_theme_input_examples’
);
Далі, визначимо callback-функції:
function sandbox_input_examples_callback() {
echo ‘
Подання прикладу з п’ятьма базовими елементами введення.
‘;
}
Нарешті, створимо елемент вводу, який ми збираємося використовувати для зчитування введених даних:
function sandbox_input_element_callback() {
$options = get_option( ‘sandbox_theme_input_examples’ );
// Вивід на екран
echo «;
}
Зараз ваша сторінка опцій повинна виглядати так, як показано на зображенні нижче:
Створення розмітки
Раніше, ми вже створювали елементи введення, і я сказав, що ми обговоримо всі атрибути в наступних статтях циклу. У цій статті ми розглянемо значення атрибутів id і name.
Зауважте, що на початку функції ми зчитуємо опції для закладки, використовуючи функцію WordPress get_option. Вона повертає опції у вигляді масиву. Атрибут id елемента вводу ідентифікує значення елемента в масиві. Атрибут name-це ім’я масиву, пов’язаного з ID.
Щоб було зрозуміло, узагальнимо:
- WordPress створить масив, еквівалентний імені секції, яку ви визначили. В даному випадку це sandbox_theme_input_examples;
- Кожен елемент буде ідентифікуватися за атрибутом id. В нашому випадку, це input_example;
- Ви можете прочитати значення цього масиву, звернувшись до нього з використанням конструкції sandbox_theme_input_examples[input_example].
Атрибут id являє собою ключ, що вказує на значення в масиві опцій, а атрибут name – ім’я масиву з ключем, що вказує на значення елемента в масиві.
Реалізація механізмів валідації очищення
Тепер, ми можемо ввести значення у полі введення і зберегти опцію. Спробуйте це зробити – встановіть значення, натисніть кнопку «Зберегти зміни» і ви побачите поле введення, у якому буде відображено введене вами значення. Але є проблема: спробуйте вставити в поле вводу що-небудь на зразок цього:
А тепер, перейдіть до файлу index.php і додайте наступний блок коду:
Оновіть головну сторінку вашого сайту, і ви побачите тег
Здавалося б – невеликий недолік, але насправді це те, чого слід строго уникати. Ми не хочемо, щоб користувачі мали контроль над базою даних, сторінками сайту і так далі. Звичайно, збереження простий рядки з тегом
Ще серйозніше виглядає ситуація, коли користувачі можуть вставити шкідливий SQL-код і пошкодити/вкрасти інформацію з вашої бази даних.
Тому, давайте додамо код, що реалізує валідацію. Як було відмічено вище, завдання полягає у видаленні будь-який HTML-розмітки і проблемних символів. Щоб це зробити, нам спершу потрібно визначити callback-функції для нашої секції з елементами введення. Ми переопределим виклик функції register_setting наступним чином:
register_setting(
‘sandbox_theme_input_examples’,
‘sandbox_theme_input_examples’,
‘sandbox_theme_validate_input_examples’
);
Тепер визначимо саму функцію:
function sandbox_theme_validate_input_examples( $input ) {
} // Кінець функції sandbox_theme_validate_input_examples
Зауважте, що ця функція приймає єдиний параметр input. Цей аргумент являє собою не пройшов валідацію масив опцій, який WordPress передає функції зі сторінки опцій, яку ми тільки що зберегли.
Так як ми додали додатковий елемент опцій, будемо використовувати ту ж функцію.
Створення функції валідації відбувається в три кроки:
- Створення масиву, який буде використовуватися для зберігання пройшли валідацію опцій;
- Валідація (і якщо необхідно, чистка) всіх вступників опцій;
- Повернення масиву, створеного раніше.
Давайте реалізуємо цей алгоритм. Погляньте на наступний код, звертаючи особливу увагу на коментарі:
function sandbox_theme_validate_input_examples( $input ) {
// Створення масиву для зберігання пройшли валідацію опцій
$output = array();
// Цикл для обробки всіх вхідних опцій
foreach( $input as $key => $value ) {
// Перевірка на те, чи має поточна опція значення чи ні. Якщо так, то обробляємо її
if( isset( $input[$key] ) ) {
// Вирізаємо всі HTML — та PHP-теги, а також правильним чином обробляємо рядка в лапках
$output[$key] = strip_tags( stripslashes( $input[ $key ] ) );
} // Кінець конструкції if
} // Кінець конструкції foreach
// Повернення обробленого масиву
return apply_filters( ‘sandbox_theme_validate_input_examples’, $output, $input );
}
Велика частина вищенаведеного коду досить зрозуміла, але є кілька моментів, які слід розглянути. Це вираз всередині умовного оператора і код, який повертає масив.
- Ми використовуємо функцію strip_tags, яка вбудована в PHP і видаляє всі HTML — та PHP-теги;
- Також використовується функція stripslashes, ще одна рідна функція PHP, яка правильно обробляє рядка в лапках.
Нарешті, ми можемо просто повернути масив $output наприкінці функції, але повернення результату роботи функції apply_filters краще.
Тепер, спробуйте ввести що-небудь в поле вводу. Спробуйте ввести просту рядок, телефонний номер, email-адреса, URL-адресу, блок HTML-коду, рядок JavaScript і так далі. Відмінно працює, чи не так?
І на завершення, давайте змінимо щось в файлі index.php і подивимося, як можна здійснювати очищення при виведенні. Рекомендується очищати опції перед виведенням.
Знайдіть наступний рядок:
І замініть її на:
Функція sanitize_text_field є ще однією вбудованою функцією WordPress, яка спеціально заточена під очищення введених користувачем у текстові поля даних чи значень, що знаходяться в базі даних.
Багаторядкове поле вводу (textarea)
Багато принципів роботи, застосовні до многострочным полями введення, також підходять і для інших елементів введення. Ми не повинні довго возитися з кожним елементом.
А зараз, давайте створимо багаторядкове поле вводу. В нашому випадку, цей елемент дозволить користувачам вводити кілька пропозицій – наприклад, коротку біографію. Додамо наступний виклик функції sandbox_theme_initialize_input_examples:
add_settings_field(
‘Багаторядковий елемент вводу’,
‘Багаторядковий елемент вводу’,
‘sandbox_textarea_element_callback’,
‘sandbox_theme_input_examples’,
‘input_examples_section’
);
Далі, давайте визначимо callbackфункцію, необхідну для відображення нашого поля:
function sandbox_textarea_element_callback() {
$options = get_option( ‘sandbox_theme_input_examples’ );
// Вивід на екран
echo » . $options[ ‘textarea_example’ ] . «;
}
Цей виклик дуже схожий на наведений вище. Ми додали атрибут id для завдання ключа в масиві опцій, а також визначили ім’я і ключ в атрибуті name. Також, ми задали розмір поля введення, хоча це і умовність.
Нагадаємо, що, так як цей елемент належить тій же секції, що і однорядкове поле введення, то він обробляється з використанням тієї ж функції валідації. Таким чином, ми отримуємо вже готовий механізм валідації. Спробуйте зберегти скрипти, розмітку і інші типи коду в цьому полі.
Нарешті, давайте змінимо головну сторінку нашої теми, щоб вона запитувала це значення і правильно очищала його для подальшого виведення. В файл index.phpдодайте наступний блок коду:
Хоча багаторядкове поле вводу практично ідентично однорядкового, нам потрібно переконатися, що процедури валідації очищення проходять правильно.
Висновок
Ми розглянули лише два елемента вводу даних, але вже відповіли на безліч різних питань. Ми реалізували базовий механізм валідації, а також почали досліджувати питання очищення даних WordPress.
У заключній статті циклу, ми поговоримо про трьох типах елементів вводу і про те, як застосовувати до них валідацію і очищення. А поки, поекспериментуйте з матеріалом, представленим у цій статті.
Переклад статті «The Complete Guide To The WordPress Settings API, Part 7: Validation, Sanitisation, Input and I» був підготовлений дружною командою проекту Сайтостроение від А до Я.