Download the PHP package one234ru/form-validator without Composer

Проверка корректности заполнения веб-форм на стороне сервера

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

Клиентская часть библиотеке описана здесь.

Массив ошибок имеет вид:

В случае корректно заполненной формы массив пуст.

Проверка осуществляется на основании специальной конфигурации и параметров HTTP-запроса.

Стандартные проверки

Предположим, что в форме есть три поля — имя, телефона и электронная почта с именами name, phone и email соответственно. Тогда конфигурация для проверки примет вид:

Ключи массива должны совпадать со значениями атрибута name полей в HTML-коде.

Простая проверка на заполненность

Единственный параметр этой проверки — текст ошибки, который будет показан пользователю в случае, если поле не заполнено или вообще отсутствует среди параметров HTTP-запроса. Проверка не будет пройдена, если значением поля является 0, а не пустая строка. Пробельные символы в начале и в конце перед проверкой отбрасываются.

Существует два вида объявления проверки: краткий — в виде строки и полный — в виде массива с ключом *.

Предположим, мы требуем указать имя и телефон, а электронную почту — по желанию.

В примере ниже для поля name использован сокращённый вид, а для phone - полный:

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

Посмотрим, что будет, если на проверку отправить пустой HTTP-запрос:

Результат (отформатирован для удобочитаемости):

Как видим, каждому из полей соответствует массив со списком сообщений об ошибках. value во всех случаях содержит null, поскольку соответствующий элемент в HTTP-запросе отсутствовал.

Краткая и полная форма записи действуют совершенно одинаково. Как правило, если нет других проверок, удобнее использовать краткую форму.

Проверка содержимого с помощью регулярного выражения

Теперь предположим, что мы не только хотим проверить, что поля заполнены, но и убедиться в том, что они содержат корректные по формату значения. Например, телефон должен состоять строго из десяти цифр, а e-mail — соответствовать определенному формату.

В этом нам поможет проверка регулярным выражением. Чтобы задать такую, нужно добавить в массив проверок элемент, ключом которого является регулярное выражение (ограничитель — /), а значением — текст ошибки:

Метка {*value*} в тесте ошибки будет заменена на значение поля (с кодированием функцией htmlspecialchars()).

Посмотрим, как будут выглядеть ошибки:

Проверка регулярным выражением будет выполняться только в том случае, если пройдена проверка на заполненность. В этом легко убедиться:

Таким образом, поле email по-прежнему не является обязательным и проверяться будет только в случае, если содержит непустое значение.

Проверки с помощью произвольных функций

Такие проверки делятся на два типа — первичные и вторичные.

Вторичные проверки выполняются только в случае, если успешно пройдены все остальные проверки для этого поля.

Предположим, введенный в форму телефон нужно проверить на наличие в некой базе данных. В этом случае инструкции проверки будут выглядеть так:

Как видно из примера, в качестве аргумента функции передается значение поля. В ответ она должна вернуть строку-сообщение об ошибке либо пустое значение, если ошибок нет.

Первичные проверки выполняются всегда, независимо от заполненности поля и наличия других проверок.

Их декларация отличается лишь тем, что в массиве вместо безымянного ключа элемента используется '*'. Есть и сокращенная форма записи:

При записи в полной форме первичную проверку можно сочетать с другими проверками.

Допустим, мы решили локализовать все проверки телефона внутри одной функции. Вот как это будет выглядеть:

Формат данных результатов проверки остаётся прежним. Не зависит он и от формы записи — краткой или полной.

Сводные проверки

Проверку можно построить на основании значений нескольких полей.

Объявляются такие проверки с помощью функций, которые помещаются внутри безымянного элемента на верхнем уровне конфигурации. В качестве аргумента такие функции принимают полный массив параметров HTTP-запроса.

Результатом работы такой функции является список выявленных ошибок. Каждая ошибка в нём представлена в виде массива со следующими элементами:

• name — имя поля
• value — значение поля
• message — текст сообщения об ошибке

Предположим, в нашем примере каждому номеру телефона в некой базе данных соответствует определенный e-mail, и при заполнении формы это соответствие нужно проверять. Вот как будет выглядеть подобная проверка:

Результат:

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

Декларация их отличается так же, как и в случае отдельных полей: первичные объявляются с ключом '*', вторичные — с безымянным числовым ключом:

Элементов, содержащих сводные проверки, может быть несколько:

Ошибки без отношения к конкретному полю

В ряде случаев ошибки не относятся к какому-то конкретному полю (например, в случае сбоя при обращении к какой-то внешней системе).

Добавить их в список можно с помощью общих проверок, не указывая name и value или вообще вернув вместо массива строку — текст ошибки.

Оформление ошибки в таком виде повлияет на её отображение на клиенте: она будет расположена в какой-то общей области формы (как правило, рядом с кнопкой отправки), а не у конкретного поля.

Другой способ добавить общую ошибку в список — вызов метода addError(), см. ниже.

Проверки однородных полей — []

Под однородными понимаются поля с одинаковым атрибутом name, содержащим на конце [], каждое из которых подчиняется одинаковой логике проверки.

Хороший пример таких полей — промо-коды, которые пользователь может ввести в форму в произвольном количестве. Для ввода каждого промо-кода в форме будет текстовое поле с именем promo_codes[], с помощью кнопки типа «Ввести ещё один промо-код» пользователь может самостоятельно добавлять поля новых промо-кодов.

В HTTP-запросе этим полям будет соответствовать ключ promo_codes, содержащий массив строк:

В конфигурации проверки однородных полей указываются с помощью ключа []:

Результат:

Проверки, указанные в ключе [], осуществляются по тем же правилам, что и обычные проверки одиночных полей.

Сокращенная форма записи вида

соответствует полной

Наряду с [] возможна общая проверка на наличие полей в запросе как таковое. Её нужно размещать на одном уровне с []:

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

Обратите внимание, что name в данном случае не содержит [] в конце, т.к. проверка проводилась на уровне общего ключа HTTP-запроса, а не отдельных полей. Это будет важно при размещении ошибок на клиенте.

Важно отметить, что содержимое HTTP-запроса перед проверками очищается от пустых однородных полей (с предварительным отбрасыванием пробелов по краям). Пустые значения из массива будут исключены.

Подключение конфигурации проверок в качестве дочерней — children

Бывают случаи, когда форма включается в качестве подраздела в другую, более крупную форму с сохранением всех правил по заполнению полей.

Например, в интернет-магазине форма для редактирования личной информации клиента может входить в форму заказа в виде раздела клиентских полей. При этом имена полей будут изменены так, чтобы в HTTP-запрос их значения вошли не на верхнем уровне, а внутри некоторого ключа. Например, <input name="phone"> может превратиться в <input name="client[phone]">, <input name="email"> — в <input name="client[email]"> и так далее.

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

Результат:

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

addError() — ручное дополнение списка ошибок

Метод позволяет вручную дополнить список в обход общей логики проверок.

Это бывает нужно, например, при взаимодействии с внешними системами, запрос к которым строится на основании данных формы. Перед его отправкой нужно убедиться в корректности введённых данных, поэтому проверки проводятся до того, как отправляется запрос. Однако результат запроса также может содержать сообщения об ошибках, которые в таком случае необходимо включить в список. Для этого и служит addError().

В качестве аргументов ему передаются, именно в таком порядке:

• текст сообщения об ошибке или их список в виде массива
• имя поля (необязательно)
• значение (необязательно)

Пример:

Результат по виду такой же, как при обычной проверке:

Порядок аргументов addError() делает особенно удобным добавление общей ошибки, позволяя указать её текст в качестве единственного аргумента:

Изменение конфигурации проверки, очистка списка ошибок

В объект можно загрузить другую конфигурацию для проверки с помощью метода setConfigTo().

Если после этого запустить проверку, вновь выявленные ошибки заменят существующие. Чтобы этого не произошло, нужно передать методу getErrors() второй аргумент со значением false:

Это может пригодиться, если конфигурация для проверки генерируется динамически, и на момент определения некоторых ошибок ясна не до конца:

Прочие возможности

После проведения проверок можно определять по имени поля, корректно ли оно заполнено: