PHP: полный мануал с примерами, функциями и ООП

От одной проверки к работающей форме: что запускать и какие файлы читать

Задача проекта — принять обращение посетителя и сохранить его один раз. Раньше небольшая страница формы только показывала результат проверки; здесь к ней добавлены постоянное хранение и защита от повторной отправки. Начните с одной части: запустите настоящую проверку полей без браузера и базы. Так результат проверки можно увидеть до чтения большого HTTP-обработчика.

Нужная база: массив с именованными полями, вход и результат функции, подключение соседнего PHP-файла. Запись PracticalForm\Validation — полное имя готового класса; пространство имён отличает его от чужих Validation. Писать новый класс в этом опыте не требуется.

<?php
declare(strict_types=1);

require __DIR__ . '/Validation.php';

$submitted = [
    'name' => '  Анна  ',
    'email' => '  reader@example.test  ',
    'message' => '  Нужна помощь с заказом.  ',
];
$checked = PracticalForm\Validation::contact($submitted);

echo 'Ошибок: ', count($checked['errors']), "\n";
echo 'Имя: ', $checked['values']['name'], "\n";
echo 'Email: ', $checked['values']['email'], "\n";
echo 'Сообщение: ', $checked['values']['message'], "\n";

Ошибок: 0
Имя: Анна
Email: reader@example.test
Сообщение: Нужна помощь с заказом.

Измените одно поле. Поставьте message равным «Коротко». Число ошибок станет 1: сообщение короче десяти символов. Чтобы увидеть текст, выведите $checked['errors']['message']. Остальные проверенные значения останутся доступны для повторного показа. В настоящем обработчике наличие ошибок не должно вести к сохранению.

Теперь скачайте полный проект формы, распакуйте весь архив и запустите команду ниже из его корня: php -S 127.0.0.1:8770 -t public. Для проекта нужны mbstring и pdo_sqlite; для первого опыта выше достаточно mbstring. Откройте http://127.0.0.1:8770/. Остановка сервера — Ctrl+C. Папка public является доступной браузеру частью; src, templates и var остаются за её пределами.

Форма отправляет application/x-www-form-urlencoded и получает HTML либо перенаправление. Этот проект не принимает JSON-запрос вместо формы: такой формат получает 415. SQLite хранит запись в var/contacts.sqlite; JSON здесь не является ни HTTP-ответом, ни форматом файла базы. В ContactStore JSON используется внутри вычисления отпечатка нормализованных полей — это отдельная внутренняя задача.

Читайте проект по пути запроса, а не пытаясь запомнить все файлы сразу. Сначала найдите в шаблоне name="email", затем чтение $_POST и вызов Validation::contact в index.php, затем развилку errors и вызов save. Разделы ниже объяснят CSRF, ключ операции, транзакцию и повтор. Для одного только разбора проверки полей эти механизмы пока можно изучать по одному.

Запуск и устройство проекта

Соберём форму обращения для небольшого сайта. Посетитель вводит имя, email и сообщение, сервер проверяет данные и сохраняет обращение в SQLite. Это законченный учебный проект: форма работает после распаковки, а база создаётся вне публичного каталога. Он показывает несколько независимых механизмов в одном запросе и позволяет увидеть, в какой момент каждый нужен.

Используйте вымышленные данные. Пример не отправляет письма, не подключается к платёжным системам и не публикует список обращений. Его можно исследовать без внешних учётных записей. Политика полей намеренно конкретна: имя 2–80 символов, ASCII-email до 254 байт и сообщение 10–2000 символов. В своём продукте сначала согласуйте этот договор: технически корректный email не подтверждает владение ящиком, а международный адрес может требовать другой политики.

php -m
php -S 127.0.0.1:8770 -t public

Три разные проверки: запрос, CSRF и ключ операции

Сначала сервер проверяет метод: чтение формы разрешено через GET, изменение — через POST, остальные методы получают 405 с Allow. Затем проверяется тип тела и размер. Content-Length недостаточно: он может отсутствовать или не совпадать с фактическим телом. Пример читает не более лимита плюс один байт. В рабочем окружении первый лимит должен стоять ещё на веб-сервере: PHP получает уже принятый запрос, а POST-парсер имеет собственные ограничения post_max_size и max_input_vars.

После запуска сессии создаётся случайный CSRF-токен. При POST он должен быть строкой ожидаемой длины и совпасть с токеном сессии через hash_equals. До сравнения нельзя вслепую приводить массив к строке. SameSite=Lax и HttpOnly полезны, но это не замена токену и не защита от XSS на вашем домене. Флаг Secure зависит от настоящего HTTPS. За обратным прокси нужен доверенный источник информации о TLS; принимать произвольный X-Forwarded-Proto от клиента нельзя.

Ключ операции решает другую задачу. Он связывает повтор запроса с одним сохранением. Сервер выдаёт его заранее и держит до десяти ключей с часовым сроком действия; старые вкладки могут получить понятную ошибку 409. Это выбранный для примера компромисс между несколькими вкладками и ограниченным объёмом сессии. В магазине срок и правила повторов нужно согласовывать с жизнью заказа и платёжной операции.

Проверка полей и безопасный повторный показ

Проверка вынесена в отдельный класс, чтобы её можно было запускать без браузера и сессии. Для каждого поля сначала проверяются тип и UTF-8, затем ограничивается сырой размер, потом выполняется trim и проверяется длина. Значения и ошибки возвращаются отдельно. Неправильное поле не превращается в успешное пустое значение, а корректные поля сохраняются для повторного показа.

<?php
declare(strict_types=1);

require 'Validation.php';
use PracticalForm\Validation;
$valid = ['name'=>'Анна', 'email'=>'reader@example.test', 'message'=>'Нужна помощь с заказом.'];
echo count(Validation::contact($valid)['errors']), "\n";
$wrong = $valid;
$wrong['name'] = ['Анна'];
$wrong['email'] = 'not-an-email';
echo implode(',', array_keys(Validation::contact($wrong)['errors'])), "\n";

0
name,email

<?php
declare(strict_types=1);

require 'Validation.php';
use PracticalForm\Validation;
$result = Validation::contact([
    'name'=>'<b>Анна</b>',
    'email'=>'bad',
    'message'=>'Хочу узнать о доставке.'
]);
echo htmlspecialchars($result['values']['name'], ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8'), "\n";
echo array_key_exists('email', $result['errors']) ? "email: ошибка\n" : "OK\n";

<b>Анна</b>
email: ошибка

Сохранение и повтор операции

Хранилище получает уже проверенные значения и PDO. Оно не знает о $_POST: поэтому его можно использовать из HTTP, CLI или теста. Уникальный индекс operation_key защищает от второго сохранения того же ключа на уровне базы. Проверка «сначала SELECT, потом INSERT» без такого ограничения имела бы окно гонки. В примере SQLite используется INSERT … ON CONFLICT(operation_key) DO NOTHING, а затем читается существующая запись.

Ключ хранится вместе с SHA-256 нормализованного набора полей. Если тот же ключ пришёл с другим содержимым, система возвращает конфликт: нельзя молча показать успех для другого сообщения. Это хеш сравнения, а не шифрование и не способ скрыть персональные данные. Секретность ключа обеспечивается случайностью и проверкой принадлежности сессии. Для нескольких побочных эффектов, например письма и записи в базе, одного такого INSERT недостаточно: потребуются отдельные правила доставки, outbox и идемпотентный потребитель.

<?php
declare(strict_types=1);

require 'ContactStore.php';
use PracticalForm\ContactStore;
$pdo = new PDO('sqlite::memory:');
$store = new ContactStore($pdo);
$data = ['name'=>'Анна','email'=>'reader@example.test','message'=>'Нужна помощь с заказом.'];
echo $store->save('example-operation-1', $data), "\n";
echo $store->save('example-operation-1', $data), "\n";
$data['message'] = 'Изменённое сообщение';
try { $store->save('example-operation-1', $data); }
catch (DomainException) { echo "Конфликт\n"; }
echo $pdo->query('SELECT COUNT(*) FROM contacts')->fetchColumn(), "\n";

1
1
Конфликт
1

Ошибки, PRG и доступность формы

При ошибках полей сервер отвечает 422 и снова показывает форму: значения экранированы, сообщение связано с полем через aria-describedby, неверное поле получает aria-invalid. Общий список ошибок содержит ссылки на соответствующие поля. Клиентская валидация в учебном проекте отключена атрибутом novalidate, чтобы можно было увидеть серверные ветки; в рабочей форме её можно добавить как удобство, сохранив проверки сервера.

После успешного сохранения сервер кладёт короткое сообщение результата в сессию, закрывает её через session_write_close и отдаёт 303 Location на фиксированный локальный адрес. Следующий запрос уже GET. В URL нет имени и email; обновление страницы результата не повторяет POST. Сообщение читается один раз, поэтому после обновления оно исчезает — это поведение flash, а не потеря записи. Для постоянного просмотра результата нужна защищённая страница с проверкой права доступа.

Упражнение: добавить номер заказа

Расширьте форму полем «номер заказа». Принимайте его как необязательную строку только из цифр заданной длины. Не преобразуйте значение с ведущими нулями в int, если это внешний идентификатор. Добавьте поле в договор, проверку, схему, запрос и HTML. Затем проверьте отсутствие, пустую строку, корректное значение и массив вместо строки.

Предлагаемое решение. Сначала определите нормальную форму: отсутствующий или пустой номер становится null, непустой обязан соответствовать заданному формату. Добавьте тесты валидатора до SQL. В хранилище включите номер в payload_hash, иначе повтор с другим номером ошибочно сочтётся одинаковым. Изменение схемы оформите миграцией; создание таблицы IF NOT EXISTS не добавит новую колонку в уже существующую базу.