KPHPStorm — это плагин для PhpStorm, внедряющий знание о KPHP.
KPHP — это компилятор, на нём работает VK. Он ускоряет PHP-код в разы.
Синтаксически оставаясь PHP, KPHP внедряет новые функции, типы и директивы.
Раньше IDE не знала наших тонкостей и иногда не понимала код.
Теперь многие ошибки видны сразу во время разработки, есть подсказки, а рефакторинг безопасен.
Типы любой сложности, парсятся независимо от пробелов.
Смотрите скрины!
Внутри tuple и shape IDE подсказывает названия классов и примитивов. Ctrl+click и usages тоже работают.
tuple, shape, mixed, callable, future, future_queue, any
— всё понимается, подсказывается и дополняется.
Теперь IDE понимает (int|false)[]|false
и любые другие вложенности и скобочные последовательности.
Понимаем ?string, ?tuple(…) и т.п. в phpdoc.
Напомню, что ?T равносильно T|null.
Если f() : tuple(int,A), то
f()[1]→ подскажет члены класса A.
Важно! Это честный вывод типов, а не просто подсказки. Т.е. работают parameter hints, go to method, find usages и т.п.
Больше не нужны никакие @var над присваиваниями в list:
вывод типов трекает всё поэлементно.
Теперь не нужно бояться, что при рефакторинге IDE не найдёт использование.
Вывод типов умеет работать для всего, даже для просто вызова
tuple(…) без phpdoc. И даже массивы tuple или вложенные tuple.
IDE подскажет в зависимости от контекста.
Так, @kphp-sync можно над функциями, но не над классами.
А при написании нового кода (над ничем) — попробует догадаться.
Автодополнение умное: к примеру, при @kphp-serialized-field автоматом
подставится следующий индекс.
В настройках Editor > Color Scheme > KPHP можно настроить,
чтобы @kphp-теги отличались от обычных.
Там же детальная подсветка в целом.
IDE знает, если тег используется неуместно или содержит неправильный формат значения.
Очень редкие @kphp-теги парсятся, но намеренно не подсказываются.
И наконец, если нужного тега не хватает — это видно без компиляции. И можно исправить одним действием.
Очень много внимания уделено type compatibility. Нативные средства PhpStorm слишком нестрогие (например, подсветят передачу инстанса вместо числа, но вместо строки уже не подсветят). Это не косяк, для PHP это валидно, но для нас — нет. Плагин отключает кучу стандартных инспекций и вместо них использует свои.
Плагин знает, что все поля класса должны иметь тип или дефолт; аргументы
функций должны быть типизированы, если это не лямбды;
если нет @return, то предполагается void и т.п.
Прямо в редаторе вы видите, где не хватает типов — и это можно исправить одним действием.
Всё как и при компиляции: нельзя передавать строки вместо чисел, нельзя
?string в string,
но можно числа в mixed, можно int[] в float[], но нельзя
A[] в mixed[] и т.д.
При сравнении типов здесь и далее учитываются вложенности, различия между PHP и KPHP, частично работают смарткасты.
Всё происходит локально в IDE, за счёт phpdoc. Когда тип не выводится, предполагается
any, который совместим с любым.
Когда слева от присваивания свойство класса, идут все те же проверки.
Тип поля класса определяется из @var, из type declaration, из дефолта —
ровно так, как и в KPHP.
return ...; внутри функций плагин проверяет на соответствие с
@return или type hint
— и проверки всё те же строгие.
mixed в KPHP — это не “всё что угодно”, как в нативном PhpStorm.
Поэтому присваивать туда можно только обобщающееся до mixed.
Плагин даже замечает вещи, валидные для KPHP.
Например, string|string[] для KPHP это mixed, а плагин ругается,
если передаёшь туда int (и даже mixed).
IDE корректно выводит типы для функций, типизацию которых не опишешь через phpdoc.
Инстанс по имени класса, not_null(), array_first_value(), ...
В частности, @return tuple(…) проверяется детально, по ключам,
а не просто что это какой-то tuple.
Мы неоднократно сталкивались, что PhpStorm иногда считает, что array_filter()
возвращает int или ещё странности.
Плагин обрабатывает многие “сложные” функции самостоятельно, исправляя их.
Это не всё. Ещё есть проверки на индексацию, излишние касты и т.д. и т.п. Поскольку вывод типов умеет в tuple и вложенности, все эти проверки срабатывают и после взятия их элементов. Это самый сложный и важный раздел в плагине: теперь мы видим ошибки без запуска компилятора.
Если @param лишь дублирует type hint — он не нужен.
IDE подсветит как weak warning такие места, а по Alt+Enter его можно сразу удалить.
Аналогично с @return.
Если @param/@return содержат примитив или инстанс,
это лучше поместить в type hint — и снова плагин покажет места и сделает одной клавишей.
Используйте ?T вместо T|null,
tuple вместо \tuple и т.п.
Все возможные упрощения — одним действием:
При вызове функций, принимающих shape — IDE подсказывает, какие там есть поля.
При использовании шейпов — тоже.
При наведении мышки PhpStorm показывает quick documentation. Но она слишком тяжеловесная (и у многих отключена). Плагин делает свою реализацию, где только нужное.
В PhpStorm 2020.2 появилось действие Type Info. Очень полезное! Плагин его тоже перегружает :) Дефолтное поведение не устраивает, т.к. плагин хранит типы по-другому.
Плагины в IDE ставятся глобально, а проектов может быть открыто несколько одновременно. Поэтому KPHPStorm старается “не мешаться” обычным PHP проектам.
При открытии любого проекта плагин автоматически определяет, базируется ли он на KPHP. Если да, производит автонастройку, включая полную функциональность.
Плагины в IDEA-продуктах принципиально умеют только расширять функциональность, но не подменять. То, насколько удалось в итоге влезть во внутренности PhpStorm — это колоссально. Изначально не думалось, что так получится. Но многое поведение изменить принципиально нельзя.
Плагин расширяет вывод типов PhpStorm, но не подменяет
(исправление багов в php stdlib это опять-таки хак, который работает почти всегда, но не совсем всегда).
А у PhpStorm есть косяки, особенно в части смарткастов и is_array.
Поэтому иногда подсвечиваются ошибки несходимости типов, хотя по факту их нет.
Это не исправить плагином, это нужно репортить в JB (и как workaround — @noinspection).
Пришлось кое-где использовать недокументированное API (изучив декомпилированные java-исходники). Разработчики JB активно внедряют новые вещи и переписывают существующие, поэтому в следующих релизах PhpStorm что-то может отваливаться, нужно заранее смотреть EAP'ы.
В PHP нет enum’ов, а нам всегда их не хватало. Так же, как не хватало шаблонных классов. Модульности.
Когда-нибудь мы подумаем над всем этим. Причём синтаксически это будет базироваться на том, как это можно обыграть в IDE.
По первости я брал консультации у JetBrains и пару раз с ними созванивался — большое спасибо ребятам за помощь. Они и подтвердили, что некоторые хотелки сделать нереально.
Многие вещи в PhpStorm некастомизируемы — иногда потому, что это никому не нужно. Может быть, разработчики завезут кое-где точки расширения, если это сильно понадобится.
Наш линтер noverify не имеет отношения к KPHP, а больше следит за code style: когда валидный с точки зрения компиляции код на самом деле ошибочный либо подозрительный.
Можно несколько проверок линтера продублировать в IDE, чтобы видеть косяки сразу, а не на prepush-хуке.
Есть ещё много идей, как нам упрощать разработку. Но моя основная работа — это собственно сам KPHP, оптимизации кода сайта и наша команда. А плагин был и остаётся pet project’ом. Поэтому кто хочет помочь — welcome.