IT-Storm

В глубинах PHP-кода, где каждая строка — как шифр в кодовом замке, вступает в игру инструмент, который берется за анализ, как опытный детектив за дело. Добро пожаловать в мир PHPStan — оружия, способного выявить даже самые искусно скрытые недостатки в вашем коде.

PHPStan требует PHP >= 7.2. Вам необходимо запустить его в среде PHP 7.x, но реальный код не обязательно должен использовать функции PHP 7.x. (Код, написанный для PHP 5.6 и более ранних версий, может работать на 7.x практически без изменений.)

PHPStan лучше всего работает с современным объектно-ориентированным кодом. Чем более строго типизирован ваш код, тем больше информации вы предоставляете PHPStan для работы.

Не забывайте, что правильно аннотированный и типизированный код (свойства классов, аргументы функций и методов, возвращаемые типы) помогает понять его не только инструментам статического анализа, но и другим людям, работающим с кодом.

 

Установка
В корневом каталоге вашего проекта выполнить:

Первый запуск
Чтобы позволить PHPStan проанализировать вашу кодовую базу, вам нужно использовать команду анализа и указать ей правильные каталоги.
Так, например, если ваши классы находятся в каталогах src и tests, вы можете запустить PHPStan следующим образом:
vendor/bin/phpstan analyse src tests

Анализировать следует только файлы с кодом, который вы написали сами. Нет необходимости анализировать каталог vendor со сторонними зависимостями, потому что не в ваших силах исправить все ошибки, допущенные разработчиками, с которыми вы не работаете напрямую.

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

По умолчанию PHPStan выполняет только самые базовые проверки. Далее, можно посмотреть «Уровни правил» и узнать, как включить более строгие проверки.

Фаил настроек

По умолчанию, PHPStan ищет фаил настроек в каталоге, из которого его запускают. Так как мы запускае проверку из корневого каталога проекта -  создадим файл настроек в корне проекта:
nano phpstan.neon

 

Пример содержимого файла phpstan.neon:

parameters:
     level: 5
     paths:
           - app/code
           - src
           - tests
     #phpVersion: 70400 # PHP 7.4

В данном примере указано следующее: 
level - уровень проверки 5 (подробнее об уровнях проверки - ниже);
paths - пути каталогов в которых нужно проверить php файлы;
phpVersion - версия php на базе которой будет проверяться код. В приведённом приере эта опция закомментирована (#) и PHPStan будет использовать дефолтное поведение - проверять код на базе вашей текущей установленной версии php.

 

Уровни правил (0-9)

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

Уровни суммируются - например, прохождение уровня 5 также дает вам все проверки уровней 0-4.

 

0. базовые проверки, неизвестные классы, неизвестные функции, неизвестные методы, вызываемые для $this, неправильное количество аргументов, переданных этим методам и функциям, всегда неопределенные переменные

1. возможно, неопределенные переменные, неизвестные магические методы и свойства в классах с __call и __get

2.неизвестные методы проверены для всех выражений (не только $this), проверка PHPDocs

3.возвращаемые типы, типы, присвоенные свойствам

4. базовая проверка мертвого кода — всегда ложные проверки instanceof и других типов, мертвые ветки else, недостижимый код после возврата; и т. д.

5. проверка типов аргументов, передаваемых методам и функциям

6. сообщить об отсутствующих подсказках

7. сообщать о частично неправильных типах объединения - если вы вызываете метод, который существует только для некоторых типов в типе объединения, уровень 7 начинает сообщать об этом;

другие возможные некорректные ситуации

8. сообщить о вызове методов и доступе к свойствам типов, допускающих значение NULL

9. будьте строги в отношении смешанного типа — единственная разрешенная операция, которую вы можете сделать с ним, — это передать его другому смешанному типу.

 

 

Пример использования утилиты PHPStan в работе на Magento 2 проекте

Если доделываем чужой модуль, то действовать так:

 

1. Перед началом работы создать ветку с утилитой (если её ещё нет):

    git checkout -m ms_code_check

и установить утилиту (п.1)

 

1.1. Если ветка ms_code_check с установленной утилитой уже есть, то становимся на неё и мержим в неё ветку на которой 

изначальное состояние модуля, с которым собираемся работать:

    git checkout ms_code_check

    git merge <имя ветки с модулем>

 

1.2. Создать "base-line" (ошибок, которые будут игнорироваться). Чтобы в дальнейшем в отчёт проверки не лезли уже существующие ошибки:

    vendor/bin/phpstan analyse --configuration=var/phpstan.neon --debug --generate-baseline=var/phpstan-baseline.neon

В результате будет создан фаил var/phpstan-baseline.neon со всеми найденными ошибками.

 

1.3. Указываем путь к этому файлу в файле настроек (в самом верху), после чего фаил будет выглядеть примерно так:

includes:

- phpstan-baseline.neon

 

parameters:

        level: 5

        paths:

                - ../app/code/KWA/CustomerService/

        phpVersion: 70400 # PHP 7.4

 

1.4. Повторный запуск предыдущей команды (с параметром --generate-baseline=var/phpstan-baseline.neon) - полностью пересоздаст фаил var/phpstan-baseline.neon

    (это может пригодиться когда нужно будет приступить к новой задаче)

 

2. Теперь можно переключиться на ветку в которой будем работать и работать.

 

3. Перед пушем (или когда понадобиться проверить на ошибки) смержить ветки как в п.1.1.

 

3.1. Выполнить:

    vendor/bin/phpstan analyse --configuration=var/phpstan.neon --debug

 

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

 

3.2. Снова перключаемся на рабочую ветку и правим ошибки. Делаем:

    git commit --amend

 

после чего снова мержим ветки п.1.1. и пересоздаём hpstan-baseline.neon , если надо п.4

 

4. После исправления ошибок, и если остались ошибки которые нужно будет игнорировать в дальнейшем - можно пересоздать var/phpstan-baseline.neon фаил:

    vendor/bin/phpstan analyse --configuration=var/phpstan.neon --debug --generate-baseline=var/phpstan-baseline.neon

 

PHP

Сергей Москаленко