IT-Storm

Это не баг — это незадокументированная фича

Menu

Phpstan: Утилита проверки php кода

Phpstan: Утилита проверки php кода

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

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

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

 
Установка
В корневом каталоге вашего проекта выполнить:
composer require --dev 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