Эффективный рефакторинг PHP-кода
Рефакторинг меняет устройство кода, сохраняя его наблюдаемое поведение. Чтобы провести его в рабочем PHP-приложении, сначала зафиксируйте контракт тестами, затем меняйте структуру небольшими шагами. Начните с участка, который уже приходится часто править или долго разбирать.
Выберите участок и зафиксируйте контракт
Возьмите один сценарий, в котором изменения регулярно задевают соседнюю логику. Например, правило бесплатной доставки приходится искать в контроллере, обработчике заказа и шаблоне. Сформулируйте конкретный результат работы: порог и стоимость доставки определяются в одном месте, а клиент получает те же суммы и ошибки на тех же входных данных. По такому критерию можно понять, когда работу пора закончить.
В контракт входят возвращаемые значения, исключения, HTTP-статусы, записи в БД и события, которые получают другие компоненты. Иногда важен и порядок действий. Если письмо раньше отправлялось только после фиксации транзакции, перенос вызова внутрь транзакции может отправить письмо о заказе, который затем откатится. Зафиксируйте эту границу до переноса кода.
Если попутно обнаружится ошибка, воспроизведите её отдельно. Например, бесплатная доставка начинается со следующей копейки после порога, хотя бизнес-правило включает сам порог. Сначала сохраните текущее поведение при переносе расчёта, затем поправьте правило отдельным коммитом с тестом на новое ожидание. При ревью будет видно, где менялась структура, а где сумма для клиента.
Зафиксируйте старое поведение тестами
Для кода без тестов начните с ближайшей стабильной точки входа. Это может быть публичный метод сервиса, HTTP-обработчик или команда. Подайте известные данные и проверьте наблюдаемый результат. Если публичный метод возвращает итог заказа, проверяйте сумму и состав ответа. Тогда тест продолжит работать после переноса формулы в другую функцию.
- Для расчётов проверьте обычное значение, границу и по одному значению по обе стороны. Если порог равен 50 000 копеек, возьмите 49 999, 50 000 и 50 001.
- Для входных данных проверьте отсутствующее поле,
nullи неожиданное значение, если такие данные доходят до выбранной точки входа. - Для записи в БД или отправки события проверьте успешный путь, отказ и повторный вызов, если он предусмотрен сценарием. При работе с очередью учитывайте повторную доставку сообщения.
Вычисление удобно покрыть модульным тестом. Сохранение заказа и его откат лучше проверять интеграционным тестом с тестовой БД, поскольку подмена репозитория не воспроизведёт ограничения схемы и поведение транзакции. Запустите выбранные тесты на исходной реализации, проверьте, что они чувствительны к ошибке, и повторяйте прогон после каждого небольшого изменения.
Извлекайте операции с ясными входами и результатом
Хорошие кандидаты на извлечение видны по данным. Формуле доставки нужны сумма заказа, порог и тариф. Подготовке HTTP-ответа нужны уже рассчитанные значения. Если разделить эти операции, формулу можно проверить без запроса, контейнера зависимостей и базы данных. Вот извлечение для случая, где действующее правило включает сам порог, а суммы уже хранятся в копейках.
<?php
declare(strict_types=1);
function deliveryFee(int $subtotal, int $freeFrom, int $standardFee): int
{
// Ровно на пороге доставка уже бесплатна.
return $subtotal >= $freeFrom ? 0 : $standardFee;
}
$subtotal = 49_999;
$delivery = deliveryFee($subtotal, 50_000, 399);
$total = $subtotal + $delivery;
echo $total; // 50398 копеекПри первом переносе сохраните исходный оператор сравнения, единицы измерения и момент округления. Переход с дробных рублей на целые копейки может изменить итог на границе, поэтому его стоит выполнить отдельно с тестами на округление. Оставьте получение тарифа там, где оно было, пока тесты не подтвердят, что новое место даст те же значения в тех же сценариях.
Одна ответственность у метода означает, что его можно описать одним действием на языке задачи. Метод оформления заказа может координировать расчёт, сохранение и публикацию события. Внутри него лучше оставить видимым порядок этих операций, а правила расчёта и детали записи держать в соответствующих функциях или объектах. Если после извлечения пять методов просто передают друг другу одну переменную, верните связанный код в одно место.
Усиливайте типизацию на границах
Для кода, который должен работать на PHP 8.3–8.5, выбирайте синтаксис, доступный на минимальной версии проекта. В новых файлах с типизированным прикладным кодом уместно ставить declare(strict_types=1); первой инструкцией. Для передачи скалярных аргументов в пользовательские функции режим определяется файлом, откуда выполняется вызов. Добавление директивы в файл с объявлением функции само по себе не переведёт все существующие вызовы в строгий режим.
Поля HTTP-формы приходят строками, а при чтении JSON тип зависит от того, как записано значение. На входе разберите и проверьте данные, затем передайте прикладному коду int, bool или другой подходящий тип. Явная проверка позволяет сохранить прежний ответ для некорректного ввода. Например, если обработчик возвращал 422 для неверного количества, проверьте этот статус после добавления сигнатуры. Приведение (int) без валидации может принять строку с числовым префиксом, а необработанный TypeError может превратить ошибку ввода в ответ 500.
Где новый тип меняет контракт, начните с внутренней функции и сохраните прежнюю точку входа как обёртку. Например, оставьте публичный метод, принимающий строковый статус, и передавайте во внутренний метод enum после разбора. При использовании tryFrom() обработайте null в соответствии с действующим контрактом. Перед изменением сигнатур проверьте позиционные и именованные вызовы, реализации интерфейсов и наследников. Имя публичного параметра уже может использоваться в клиентском коде.
Вводите классы ради состояния или инвариантов
Оставьте чистый расчёт функцией, если ему достаточно нескольких параметров. Класс полезен, когда данные передаются вместе и подчиняются общим правилам. Например, сумма и валюта могут образовать объект-значение, если код регулярно сравнивает и складывает суммы. Тогда правило совместимости валют живёт рядом с арифметикой, и вызывающим методам больше не нужно повторять одну и ту же проверку.
Для объекта-значения с целочисленной суммой и строковым кодом валюты подходит readonly. Перед заменой массива объектом проверьте его потребителей. Контроллеру может по-прежнему требоваться JSON с теми же полями и типами, а репозиторию — отдельные значения для записи. Оставьте преобразование на границе. Если предметное правило допускает отрицательные суммы для возвратов, учтите это в модели и в тестах до переноса проверки в конструктор.
Удаляйте мёртвый код и уточняйте документацию
Начните с неиспользуемых локальных переменных, приватных методов и веток, недостижимость которых подтверждается условиями. Поиск по проекту и статический анализ PHPStan или Psalm помогают найти кандидатов. Перед удалением метода проверьте маршруты, конфигурацию контейнера, подписчиков событий, задания очереди и вызовы по имени. Старый обработчик может оставаться нужен для сообщений, поставленных в очередь до развёртывания новой версии.
У неиспользуемой переменной проверьте правую часть присваивания. Если при вычислении значения вызывается запись в БД или отправляется событие, удаление всей строки изменит поведение. В таком случае сохраните вызов без присваивания. Для старой интеграции с внешними потребителями сначала выведите из эксплуатации точку входа и удаляйте реализацию после подтверждения, что потребители перешли на замену.
Документируйте то, что сигнатура выразить не может: единицы измерения, правила округления, форму массива и причину соблюдать порядок операций. Например, PHPDoc с @return array{subtotal: int, delivery: int, total: int} помогает статическому анализатору проверять ключи массива. Комментарий рядом с расчётом может объяснить, применяется ли порог до или после скидки. Изменили правило или перенесли его в другое место — обновите связанный тест и комментарий в том же коммите.
Чек-лист перед слиянием
- Назовите сценарий, который стало проще менять, и перечислите его наблюдаемые результаты.
- Убедитесь, что тесты проходили до изменений и проходят после. Проверьте границы условий, ошибки и побочные эффекты.
- Проверьте изменённые сигнатуры, именованные аргументы и вызовы из конфигурации. Для новой типизации проверьте реальные входные данные от HTTP-обработчиков, очередей и БД.
- Просмотрите diff по смысловым шагам. Для изменений поведения оставьте отдельные коммиты с явными ожиданиями в тестах.
- Запустите статический анализ и тесты на минимальной заявленной версии PHP и на версии, используемой в продакшене.
- Откройте изменённый сценарий с его точки входа. Если правило теперь можно найти в одном месте, тесты покрывают его границы, а клиент получает прежний результат, задачу можно закрыть.
Частые вопросы
С чего начать рефакторинг PHP-кода без тестов?
Выберите один сценарий и зафиксируйте его текущее поведение через стабильную точку входа. Проверьте обычный случай, пограничные значения и важные побочные эффекты. После этого сделайте одно структурное изменение и повторите прогон.
Нужно ли включать strict_types сразу во всём проекте?
В существующем проекте включайте строгий режим по файлам. Начните с участка, для которого известны типы входных данных, и проверьте вызовы из HTTP-обработчиков, очередей и команд. Разбирайте внешние значения до передачи в типизированную функцию.
Когда выносить логику в отдельный класс?
Выносите её в класс, когда нужно хранить связанное состояние, обеспечивать инвариант или явно передавать зависимость. Для самостоятельного расчёта, который получает все данные аргументами и возвращает значение, часто достаточно функции.