Не буду вам рассказывать о всех прелестях использования статических анализаторов, на мой взгляд это очевидно. Об их разновидностях для PHP интересно рассказано, например здесь. А я расскажу о том как можно расширить их функциональность под ваши нужды, на примере Psalm.
В своих проектах я использую несколько анализаторов, но к сожалению столкнулся с одной проблемой, с которой ни один не смог помочь. И здесь я решил попробовать расширить его функциональность. Собственно об опыте написания подобного расширения возможностей и будет статья.
Немного о проблеме
Если вы когда нибудь пользовались JMS Serializer то знаете на сколько это удобная штука. Вы просто описываете класс определенным образом, и через вызов метода можете получить объект из JSON/XML данных, где все свойства будут смаплены согласно вашему описанию, и наоборот, из объекта получить JSON/XML.
Вот так может выглядеть описание объекта для сериализации или дессериализации.
<?php
class ExampleDTO
{
/**
* @JMS\Type("int")
*/
public $id;
/**
* @JMS\Type("\ExampleTypeDTO")
*/
public $type;
}Основная проблема здесь в том, что класс для $type описан как строка, и ни один линтер не видит его, и вообще не может понять что здесь описан именно класс.
И когда вы проводите рефакторинг, то случайно можете переименовать или переместить его. И если у вас не написаны тесты, и вы плохо провели тестирование, то получите ошибку при попытке сериализации, в тестинге или хуже, в продакшене.
Как начать?
Начал я с официальной документации из которой узнал что уже есть скелет плагина на гитхабе.
Как здорово что разработчики псалма позаботились обо мне, подумал я, и решил что все будет легко.
Создав проект из скелета, я в первую очередь озаботился возможностью написания тестов. Так как документация не раскрывает всех возможностей, то придется много копаться в коде, чтобы понять что и как должно работать. Поэтому очень хотелось описать какой нибудь файл как фикстуру и через тесты уже запускать и экспериментировать с возможностями.
К сожалению я не увидел легкой возможности написать юнит тест на работу плагина. Заглянув в код почти всех существующих расширений, я попробовал разобраться как они тестировали свою функциональность. Везде все реализовывали тесты по разному. Но спустя несколько часов разбора я собрал более менее подходящую мне конфигурацию, и написал свой первый тест.
Как выяснилось позже, я сам допустил ошибку, так как долгое время не писал ничего кроме юнит и Testsuite тестов, и не заметил в скелете приложения ключевого слова acceptance! Мог бы сэкономить пару часов )
Оказывается разработчики позаботились о том, чтобы я легко мог протестировать то что сделал, я просто не знал куда смотреть.
В итоге у меня получился примерно такой тест
Feature: basics
Test my plugin
Background:
Given I have the following config
"""
<?xml version="1.0"?>
<psalm totallyTyped="true">
<projectFiles>
<directory name="."/>
</projectFiles>
<plugins>
<pluginClass class="Tooeo\PsalmPluginJms\Plugin" />
</plugins>
</psalm>
"""
Scenario: run without errors
Given I have the following code
"""
<?php
namespace Tooeo\PsalmPluginJms\Tests\Fixtures;
class SomeTestFile
{
/**
* @JMS\Type(array<\Api\User\Dto\CurrencyError>);
* @psalm-suppress PropertyNotSetInConstructor
*/
public string $errorArray;
}
"""
When I run Psalm
Then I see these errors
| Type | Message |
| UndefinedDocblockClass | Class \Api\User\Dto\CurrencyError does not exists |
And I see no other errors
Замечательно, просто описываем в файле то что нужно, и все работает.
# запускаем тесты
codecept build && codecept --ansi run acceptance
.....
✔ basics: run without errors (1.84s)
✔ basics: run with errors (0.98s)
✔ basics: run with suppressed errors (0.98s)
------------------------------------------------------------
Time: 00:03.825, Memory: 10.00 MB
OK (3 tests, 0 assertions)В общем я дописал и приемочные тесты к моим уже готовым юнит тестам.
Пишем проверки
Из документации я узнал что нужно создать и зарегистрировать хендлер(или хук). В исходниках псалма и других плагинах нашел примеры, и выглядеть это должно примерно так:
<?php
class Plugin implements PluginEntryPointInterface
{
public function __invoke(RegistrationInterface $psalm, ?SimpleXMLElement $config = null): void
{
require_once __DIR__ . '/src/Hooks/JmsAnnotationCheckerHook.php';
$psalm->registerHooksFromClass(JmsAnnotationCheckerHook::class);
}
}Данный хендлер должен имплементировать один из интерфейсов, что определяет в какой момент и с каким набором данных он будет вызываться.
Я довольно много провозился подбирая нужный мне, так как в документации не особо раскрыто назначение каждого из интерфейсов.
Для себя я выбрал AfterClassLikeAnalysisInterface что позволяет запускать мой хук сразу после завершения анализа класса.
Достаем данные для анализа
Если вы имплементируете класс AfterClassLikeAnalysisInterface, то обязаны реализовать метод afterStatementAnalysis принимающий объект AfterClassLikeAnalysisEvent
<?php
class JmsAnnotationCheckerHook implements AfterClassLikeAnalysisInterface
{
public static function afterStatementAnalysis(AfterClassLikeAnalysisEvent $event)
{
/**
* Здесь можно найти информацию о классе
* Например:
* - информация о неймспейсе
* - список свойств
* - список методов
* - список трейтов
* - список атрибутов
*/
$stmt = $event->getStmt();
/**
* Здесь можно найти информацию связанную с классом полученную в результате анализа
* Например:
* - все интерфейсы которые имплементирует класс
* - родительские классы
* - местонахождение класса в файловой системе
* - все подключенные неймспейсы
* .....
* Вообще там много чего, стоит в него заглянуть
*/
$storage = $event->getClasslikeStorage();
}
}Этого мне было достаточно для моей задачи. Циклом я прошелся по всем свойствам и проверил комментарии и атрибуты к ним на наличие аннотации в стиле JMS Serializer, и если находил то пробовал понять, а класс ли описан в типе или нет.
Для того чтобы это понять, я исключил все стандартные типы, а все остальное считал классами.
Небольшой пример того какими могут быть описания свойств
/*
* @JMS\Type(DateTime<\'Y-m-d\'>)
* @JMS\Type("DateTime<\'d.m.Y H:i:s\', \'UTC\'>")
* @JMS\Type('string')
* @JMS\Type(name="string")
* @JMS\Type(name=array<int, enum<JmsDto::class>>)
* @JMS\Type('\Fixture\JmsDto')
* @JMS\Type(array<array<string, DateTime<\'d.m.Y H:i:s\', \'UTC\'>>>)
*/Как видно, объекты могут быть любой вложенности, и из приведенного примера мне нужно проверить только JmsDto::class.
Для определения, существует ли он, я искал его во всех включенных неймспейсах. То есть, брал все что указано в use и текущий неймспейс, прикреплял к нему название класса и проверял на class_exists.
Лучше приведу пример реализации:
<?php
namespace Tooeo\PsalmPluginJms\Tests\Fixtures;
use Tooeo\PsalmPluginJms\Tests\Fixtures\JmsDto;
use Tooeo\PsalmPluginJms\Tests\Fixtures\JmsDto as JmsDtoAlias;
/**
* @var string $class - название класса который спарсили из комментария.
* Может принимать значения:
* - Tooeo\PsalmPluginJms\Tests\Fixtures\JmsDto
* - JmsDtoAlias
* - FixturesAlias\JmsDto::class
* - SameNamespace::class
*
* @var array $uses - список подключаемых неймспейсов
* Может принимать значения:
* $uses = [
* 'jmsdto' => 'Tooeo\PsalmPluginJms\Tests\Fixtures\JmsDto',
* 'jmsdtoalias' => 'Tooeo\PsalmPluginJms\Tests\Fixtures\JmsDto',
* ];
* @var string $namespace - текущий неймспейс
* Может принимать значения:
* - Tooeo\PsalmPluginJms\Tests\Fixtures
*/
public static function isClassExists(string $class, array $uses, string $namespace): bool
{
$class = explode('::', $class)[0];
foreach ($uses as $flipped => $use) {
if ($flipped === strtolower($class)) {
$class = $use;
break;
}
}
foreach ($uses as $flipped => $use) {
if (preg_match("#^$flipped#i", $class)) {
$class = preg_replace("#$flipped#i", $use, $class);
break;
}
}
return preg_match('#interface$#i', $class)
? interface_exists($class) || interface_exists($namespace.'\\'.$class)
: class_exists($class) || class_exists($namespace.'\\'.$class);
}Реализация логики моего плагина не совсем относится к теме статьи, поэтому не буду уделять этому много времени, весь код можно посмотреть на гитхабе.
Конфигурация плагина
Когда я запустил проверку на своем проекте, выяснилось, что в JMS Serializer можно указывать кастомные типы. А их к сожалению не опишешь. Поэтому я начал разбираться как же можно конфигурировать мой плагин.
Это оказалось не сложным, разработчики уже обо всем подумали. В __invoke метод моего плагина передавался объект SimpleXMLElement $config, и в нем есть вся конфигурация которую можно описать при его подключении.
Выглядит это у так:
<pluginClass xmlns="https://getpsalm.org/schema/config" class="Tooeo\PsalmPluginJms\Plugin">
<ignoringTypes>
<ignored>FeatureBasedDateTime</ignored>
<ignored>MixedType</ignored>
<ignored>ArrayOrString</ignored>
<ignored>float_amount</ignored>
<ignored>ContractType</ignored>
<ignored>DateTimeRFC3339</ignored>
</ignoringTypes>
</pluginClass>А разбор примерно так:
<?php
public function __invoke(RegistrationInterface $psalm, ?SimpleXMLElement $config = null): void
{
foreach ($config?->ignoringTypes ?? [] as $toIgnore) {
// Собственно здесь находится вся конфигурация
}
}Информация об ошибке
Теперь мы умеем анализировать класс и находить несуществующие классы в описании. И нам нужно как то сообщить Psalm о том что есть ошибка.
Делается это через метод IssueBuffer::maybeAdd().
Для своей задачи я нашел класс описывающий ошибку UndefinedDocblockClass но вы можете создать свой кастомный класс конкретно под вашу.
Особых проблем здесь я не испытал, стоит только сказать что 2-м параметром в метод maybeAdd нужно передать все найденные в классе Suppressed, иначе ошибка будет проигнорирована.
Можно сделать это примерно так:
<?php
// Это псевдокод для того чтобы показать как может быть реализовано.
class CheckerHook implements AfterClassLikeAnalysisInterface
{
public static function afterStatementAnalysis(AfterClassLikeAnalysisEvent $event)
{
foreach ($event->getClasslikeStorage()->properties as $name => $propertyStorage) {
// Получаем свойство для анализа
if (!$property = $event->getStmt()->getProperty($name)) {
continue;
}
// Соберем все что хотим в данный момент заигнорить, это информация из класса(общая) и конкретно проверяемого свойства
$suppressed = array_merge(
$event->getClasslikeStorage()->suppressed_issues,
$propertyStorage->suppressed_issues
);
// Вызываем метод возможного добавления ошибки.
// Он проверит $suppressed и если не найдет противоречий то добавит ошибку
IssueBuffer::maybeAdd(
new UndefinedDocblockClass(
'My first validation Issue',
$propertyStorage->stmt_location,
$name // если честно, не разобрался что это за параметр, и на что он влияет. Может в комментах подскажете?
),
$suppressed,
true
);
}
}
}В итоге, запустив проверку с включенным плагином я нашел реальные проблемы в коде. Да это был легаси код который не использовался в продакшене, но в любой момент кто то мог начать его использовать и получил бы проблемы.
Итог
Я хотел показать, что расширить функциональность линтера под свои нужды не так сложно как может показаться. Если вы сталкиваетесь с какими-то проблемами в разработке, и эту проблему можно закрыть используя статический анализатор, то не нужно бояться, нужно просто написать плагин, это ведь так просто И возможно, когда плагинов станет много, баги во всех продакшенах мира исчезнут :)
Еще хотел бы выразить респект разработчикам Psalm, за то что они позаботились о том, чтобы расширять их функциональность было легко. Еще бы документацию сделали получше, было бы прям идеально.