Обновления PHP: Блокируйте регрессии с PHPStan

Что такое регрессия обновления

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

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

Установка PHPStan и расширения Deprecation Rules

Чтобы начать бороться с регрессиями обновления, первым шагом будет установка PHPStan, если вы ещё этого не сделали. Его можно установить через Composer:

composer require --dev phpstan/phpstan

Далее необходимо добавить расширение PHPStan Deprecation Rules (Правила обнаружения использования устаревших классов, методов, свойств, констант и трейтов.), помогающее отслеживать использование устаревших методов, свойств и классов в кодовой базе:

composer require --dev phpstan/phpstan-deprecation-rules

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

includes:
    - vendor/phpstan/phpstan-deprecation-rules/rules.neon

Запуск PHPStan с этой настройкой будет отмечать все устаревшие методы, свойства и классы в кодовой базе. Это важный шаг в предотвращении регрессий обновления, поскольку вы будете получать уведомления об использовании устаревшего кода. Впоследствии вы сможете провести рефакторинг этих экземпляров, чтобы приложение перешло на более новую, поддерживаемую функциональность.

Идём дальше с расширением Disallowed Calls

В то время как расширение Deprecation Rules отлавливает устаревший код, расширение Disallowed Calls предлагает способ блокировать определённые вызовы функций, методов или даже целых классов, которые больше не следует разрешать в кодовой базе. Это удобно для более тонкого контроля над кодом, например, над кодом, не имеющим предупреждения об устаревании.

composer require --dev spaze/phpstan-disallowed-calls

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

includes:
    - vendor/phpstan/phpstan-deprecation-rules/rules.neon
    # add the extension
    - vendor/spaze/phpstan-disallowed-calls/extension.neon

parameters:
    # You can see more example at https://github.com/spaze/phpstan-disallowed-calls/blob/main/docs/custom-rules.md
    disallowedMethodCalls:
        -
            method: 'PotentiallyDangerous\Logger::log()'  # `function` is an alias of `method`
            message: 'use our own logger instead'
            errorTip: 'see https://our-docs.example/logging on how logging should be used'Begin writing your own rules
    disallowedFunctionCalls:
        -
            function: 'var_dump()'  # `method` is an alias of `function`
            message: 'use logger instead'

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

Заключение

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

Комментарии