Что нового в PHPStan 1.0?
В начале ноября 2021 года PHPStan получил важный выпуск с новыми функциями, дополнительными правилами и множеством оптимизаций производительности. Это означает, что ведущий статический анализатор PHP теперь считается стабильным и поставляется с обещанием обратной совместимости для будущих обновлений.
Поскольку это серьезное изменение, PHPStan 1.0 также содержит некоторые критические изменения, которые могут повлиять на ваши существующие сканирования. К ним относятся дополнительные правила и некоторые замененные или удаленные параметры конфигурации.
Новый уровень 9
PHPStan сканирует ваш исходный код PHP, чтобы найти потенциальные проблемы без фактического запуска кода. Наряду с модульными и сквозными тестами это дает вам представление о качестве вашего кода, выявляя проблемы до того, как с ними столкнутся пользователи.
Уровни PHPStan используются для настройки строгости анализатора. Серия выпусков v0.x предлагала восемь уровней, из которых 0 — самый расслабленный, а 8 — самый строгий. Хотя для наилучшего охвата предпочтительнее использовать максимально строгий уровень, менее строгие уровни могут помочь вам ввести PHPStan в несовершенную кодовую базу.
PHPStan 1.0 добавляет уровень 9 в качестве новой опции. Он включает в себя все правила уровня 8 и ниже, а также одну дополнительную проверку: строгое mixed сравнение типов.
Тип mixed появился в PHP 8.0 как способ явного указания типа для «любого» значения. Поскольку mixed по существу эквивалентен нетипизированному значению, небезопасно делать какие-либо предположения о том, как выглядит значение типа mixed.
Девятый уровень PHPStan будет строго следить за этим, сообщая об ошибке, если вы попытаетесь активно использовать значение mixed в своем коде. Доступ к свойству или вызов метода запрещены, поскольку вы не можете знать, будут ли они существовать. Вы можете передавать значения через другие подсказки типа mixed, только когда это правило активно.
Чтобы принять новое поведение, вам нужно изменить level: 8 на level: 9 в файле конфигурации phpstan.neon. . PHPStan также поддерживает level: max в качестве псевдонима для самого высокого уровня. Если вы уже используете max, вы автоматически получите уровень 9 при обновлении до PHPStan 1.0.
Лучшая осведомленность в блоках Try-Catch-Finally
PHPStan теперь имеет улучшенный вывод типов и понимание переменных для блоков try-catch-finally. Он будет использовать тег docblock @throws для проверки типов исключений, создаваемых каждой функцией в вашей кодовой базе. Это понимание используется для проверки доступности переменных в блоках try-catch.
Вот пример, демонстрирующий, почему это важно:
/**
* @throws DemoException
*/
function first() {
throw DemoException();
}
/**
* @throws OtherException
*/
function second() {
throw OtherException();
}
try {
$first = first();
$second = second();
}
catch (DemoException $ex) {
error_log($second);
}
catch (Exception $ex) {
error_log("General exception");
}Первый блог catch обращается к $second, но этого не будет, когда будет перехвачено DemoException. PHPStan v1.0 использует оператор @throws, чтобы реализовать это, поэтому вы будете проинформированы, когда ваши блоки catch ссылаются на, возможно, неопределенные переменные. Функции без аннотаций @throws обычно ведут себя так же, как и раньше.
В результате этого изменения необязательный параметр polluteCatchScopeWithTryAssignments был удален. Раньше это позволяло вам получать доступ к переменным, установленным в блоке try в следующем catch; в этом больше нет необходимости, так как теперь PHPStan может определять, какие переменные доступны.
Обнаружение неиспользуемого кода
PHPStan стал лучше находить и сообщать о некоторых формах неиспользуемого кода в вашем проекте. Он выделяет свойства, методы и константы частного класса, которые никогда не вызываются и к которым никогда не обращаются.
Их присутствие почти всегда непреднамеренно. Если вы хотите сохранить мертвый код дольше, попробуйте закомментировать его или добавить комментарий @phpstan-ignore-next-line, чтобы обойти проверку.
Улучшения запоминаемых значений
v1.0 повышает согласованность памяти PHPStan для возвращаемых значений функций. Он лучше понимает, когда функция вызывается во второй раз, предлагая лучшее ожидание идентичных возвращаемых значений.
Это приводит к улучшенному обнаружению мертвого кода, когда условие повторяется несколько раз. PHPStan предупредит, когда блок станет избыточным, потому что выполнение прервано более ранней ветвью с тем же условием:
if ($demo -> isActive()) {
return;
}
if ($demo -> isActive()) {
recordDemoActivity();
}Второй блок никогда не запустится, так как первый всегда завершается. Однако есть предположение: isActive() всегда должен возвращать одно и то же значение на протяжении всего времени существования $demo. Говоря более конкретно, isActive() должна быть чистой функцией, в которой повторяющиеся входные данные всегда дают идентичный результат.
PHPStan предполагает, что функции по умолчанию являются чистыми. Если это не так, вы можете добавить аннотацию @phpstan-impure в блок документации над определением функции. Это отключит память возвращаемых значений для этой функции. Вам нужно будет использовать это в приведенном выше примере, если isActive() может возвращать разные значения для каждого вызова, то есть первая проверка может равняться false и разрешать вторую ветка для запуска.
/** @phpstan-impure */
public function isActive() : bool {
return (date("Y") === "2021");
}Другие улучшения правил
К существующим уровням с 1 по 6 добавлено несколько новых правил. К ним относятся проверки переопределения констант и свойств, попытка расширения класса final и обнаружение всегда истинного и всегда ложного условия цикла while.
Типы теперь рекурсивно проверяются на отсутствующие подсказки. Это означает, что определения PHPDoc, такие как array, не будут приняты, поскольку в них отсутствует определение внутреннего типа. Вам также потребуется указать ожидаемые значения элементов массива второго уровня, например array.
Помимо проверки исходного содержимого, PHPStan 1.0 также проверяет общую достоверность файлов .php. Уровень 0 получает проверку на начальные и конечные пробелы в файлах и спецификацию, поскольку неуместные символы до или после пары тегов <?php ... ?> могут привести к неожиданному выводу во время выполнения.
Производительность и стабильность
Производительность была улучшена в нескольких областях за счет оптимизации определенных операций и устранения некоторых утечек памяти. Это должно способствовать более быстрому и надежному сканированию больших кодовых баз.
Поскольку версия 1.0 официально считается стабильной, она гарантирует, что будущие второстепенные версии (1.1, 1.2, 1.3 и т. д.) будут обратно совместимы. Хотя для перехода с версии 0.x на версию 1.0 могут потребоваться некоторые настройки конфигурации, в будущем у вас будет более простой путь миграции.
Разработчики расширений PHPStan и пользовательских наборов правил также выигрывают от наличия более стабильной кодовой базы, которая с меньшей вероятностью изменится. Документация для разработчиков также была расширена, включая более доступное описание создания настраиваемых правил. Должно быть проще начать работу при внедрении собственных правил вашей команды в анализ PHPStan.
Хотя это является хорошим предзнаменованием для будущей поддержки, как пользователи, так и разработчики расширений сталкиваются с серьезными изменениями при переходе на версию 1.0. Некоторые параметры конфигурации сканирования были переименованы или изменены: bootstrap стал bootstrapFiles, а excludes_analyse заменен на excludePaths.
Внутренне API расширений был значительно переработан, поэтому многие классы и методы были изменены или удалены. Полный список обратно несовместимых изменений доступен в журнале изменений версии 1.0.
Краткое содержание
PHPStan v1.0 совершенствует проект, оптимизируя производительность, добавляя новые правила и устраняя некоторые нарушения обнаружения. Эволюция PHPStan за последние несколько лет способствовала более широкому переходу PHP-сообщества к использованию концепций типизированного языка. Добавление таких функций, как типизированные свойства и типы объединения, привело к созданию языка, способного поддерживать расширенный внешний контроль, а также подробный внутренний анализ посредством отражения.
Переход на несколько стабильных версий должен способствовать дальнейшему внедрению PHPStan в сообществе. Переход на новую версию должен быть достаточно безболезненным для современных проектов, которые уже используют строгий уровень правил PHPStan.
Вы можете перейти на PHPStan v1.0 уже сегодня, запустив composer require phpstan/phpstan в своих проектах. Рекомендуется сначала прочитать примечания к выпуску, чтобы определить критические изменения, которые необходимо устранить. Наличие дополнительных правил на каждом существующем уровне может привести к тому, что ваша кодовая база начнет не проходить тесты, даже если она прошла с PHPStan v0.x. Вы можете временно отключить новые правила, добавив их в базовый план, чтобы исключить их из результатов сканирования.