AdmStorm

AdmStorm

Плагин для работы с server из IDE

Зачем нам
AdmStorm?

Летом 2020 года на свет появился плагин KPHPStorm, который привнёс в разработку на KPHP множество улучшений. Он позволил разработчикам удобно работать из IDE, которая отныне знала многие тонкости KPHP.

Но наши внутренние инструменты не ограничиваются KPHP, и идея сделать их использование более удобным всегда витала где-то рядом.

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

Цель этого плагина — сделать так, чтобы повседневные задачи на этом стыке решались не выходя из IDE.

IDE вместо админок

Код бэкенда — это не статичная логика.

Мы не хардкодим 640 — мы пишем Config::getInt('kbytes_will_be_enough').

Мы не хардкодим строки на русском/английском языках —
мы создаём языковые ключи и используем lang('verification_title_small').

Код не линейный, он обмазан ручками / тогглами / флагами, ветки кода скрыты за if else — и, читая код, мы каждый раз спрашиваем себя: этот блок кода исполняется на продакшене или заброшен? Какое значение прилетит из конфига? Что здесь подставится на русском языке?

Теперь не нужно копировать названия ключей, идти в админки и вставлять их в поиск: при навигации по коду значения ручек, конфдаты, лангов и т.п. доступны сразу в PHPStorm.

Ручки

Термин "ручка" значит "динамическое значение для раскатки" на какой-то процент пользователей. AdmStorm подгружает и показывает описание, текущее значение, кем и когда изменено, исключения.

По клику на название — сразу же переход в админку к нужному ключу, а по клику на пользователей — в их профиль. И везде ниже — аналогично.

part

Конфдата

Confdata — это динамическое хранилище всей конфигурации сайта, встроено в KPHP. AdmStorm распознаёт confdataGet() и подобные, показывая значения.

confdata

Config::get()

Конфиг — это вынесенный в код огромный key-value массив, на который накладывается специальная секция конфдаты. Работают Config::getInt() и все остальные.

config

StatsHouse, Logger, etc.

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

statshouse

lang() и переводы

Любая инлайн-вёрстка или формирование сообщений об ошибках теперь значительно понятнее, т.к. видя $err_txt = lang('security_error') можно кликнуть на кнопочку и посмотреть, что это за строчка по-русски и по-английски.

lang

A/B эксперименты

Если код скрыт за if'ами A/B эксперимента, то опять-таки рядом кнопочка, чтобы перейти в детали этого эксперимента.

lang

Как это работает?

Функции, которые распознаёт AdmStorm — не захардкожены. Поэтому в продуктовом коде, где есть обёртки над статистикой, языками и прочее, всё тоже будет работать, если и те функции "разметить", добавя специальный PHPDoc @admstorm-marker:

lang

Есть разные kind, функциональность которых зашита, и с помощью q мы формируем запрос. Внутри q можно использовать даже self/static и константы, благодаря чему работают обёртки над секциями в конфдате.

При клике на кнопку плагин отправляет запрос на server, он отвечает всеми текстами и ссылками (для этого нужен VPN, как и при SSH-соединении). Исходники того скрипта не сложные, но слишком VK-специфичные и в Open Source не выложены. Если другие компании захотят перенять нашу практику (ведь это реально удобно) и сделать по аналогии, им в любом случае нужно будет делать под себя, на своих технологиях.

IDE вместо консоли

Ещё одна цель AdmStorm — скрыть наличие server, перенеся действия в IDE:

Теперь те вещи, ради которых мы заходили в dev-консоль,
делаются просто кнопками в IDE.

Серверный PHPUnit

Запускайте тесты привычными средствами, будто локально —
только исполняться они будут удалённо.

Тесты напрямую в IDE

Работают кнопки Run — как для класса, так и для отдельного метода.

Навигация по тестам

По клику из дерева тестов — мгновенный переход к исходникам.

Запуск только упавших тестов

Тоже делается в один клик. И мы даже не логируем, у кого там тесты фейлятся :)

Запуск всех тестов из директории

Через нативное контекстное меню.

Специфические флаги для запуска

При необходимости указываются в настройках конфигурации.

KPHP Playground прямо в IDE

Иногда возникает необходимость проверить, как отработает тот или иной код на KPHP. Плагин встраивает возможность запускать любой файл как скрипт.

Любой php-файл — новый или существующий — теперь можно запустить через контекстное меню → Run 'KPHP Script 'filename.php'.

Можно использовать любые классы
и функции из vkcom

Для этого достаточно подключить два файла autoload.

Плагин разделяет стадию компиляции
и запуска скрипта

Чтобы видеть их вывод на разных вкладках.

Вместе с KPHP плагин запускает
скрипт и на PHP

Но это можно отключить в настройках конфигурации.

Удобно просматривайте diff между
выводом KPHP и PHP

Хотя мы конечно же считаем, что его не должно быть :)

Просматривайте сгенерированный С++ код

Плагин встраивает знания об инспекторе KPHP, который к тому же теперь умеет искать в строгом режиме.

Чтобы перейти к С++ коду, просто поставьте курсор на нужную строчку и вызовите контекстное меню → Go To Compiled C++.

Плагин откроет файл на строчке C++ кода, которая соответствует строчке на PHP.

Для некоторых вещей плагин не сможет найти исходный код (например, для лямбд), в таком случае он покажет уведомление.

В С++ коде, встроенные функции, макросы, типы и ключевые слова будут подсвечены своими цветами для удобства чтения.

Локальный git == git на server

Плагин внедряет проверки, что состояние гита локально равно состоянию гита на server. Благодаря этому, перейдя на server с локали или наоборот, вы можете быть уверены, что находитесь в одном и том же окружении.

В дополнение к этому, плагин добавляет несколько функций для работы с Gitlab.

Три уровня синхронизации

Что совпадают ветки

Делали необходимые правки на server и затем переключились в IDE? Плагин подскажет, если ветки различаются.

Вы можете выбрать, куда переключиться, а при конфликтах здесь же их разрешить.

Что совпадают коммиты

Возможно, вы создали несколько коммитов непосредственно на server? Плагин подскажет, какие коммиты отсутствуют локально.

Вы сможете увидеть эти коммиты и сразу подтянуть их.

Что нет диффа по файлам

Изменили или удалили несколько файлов на server? Плагин подскажет, какие файлы различаются.

Их можно сразу синхронизировать, использовав локальную версию или скачав с server.

Плагин старается автоматически поддерживать синхронизацию — в рамках того, насколько удалось встроиться в IDE.

Например, при переключении ветки она также переключается и на server. Считается, что у вас включен SFTP upload — а значит, при изменении локальных файлов они будут заливаться средствами IDE.

В идеале, рассинхрон появляется только если что-то делать в консоли на server. А если работать только из IDE, то вообще не придётся сталкиваться с этими окошками.

Автоматические проверки

При открытии IDE

Если вы работали на server, а потом перешли в IDE для дальнейшей работы — плагин сразу проверит, совпадает ли окружение.

Перед запуском инструментов

Если вы что-то меняли локально и не загрузили изменения на server, плагин найдёт расхождения и покажет вам окно для синхронизации.

После возвращения в IDE

Если вы что-то поменяли через консоль на server, а потом вернулись обратно в IDE для дальнейшей работы — плагин сразу проверит, совпадает ли окружение.

Быстрый pull и push

Pull Gitlab → server → local

Новая кнопка подтягивает Gitlab в один клик. Плагин сначала подгрузит изменения на server, а затем оттуда в локальный репозиторий.

Push local → server → Gitlab

И наоборот тоже. Все pre-push хуки запускаются на server, а их вывод показывается в отдельной консоли внутри IDE.

Сразу создавайте Merge Request

После успешного пуша будет быстрое действие с созданием нового Merge Request из запушенной ветки.

Проверка git status

Для консистентности, git status на server должен быть пустым. Если нет, будет диалоговое окно с действиями.

--no-phplinter и другие

Их можно разово указать в Push parameters. Там же есть force push в выпадающем списке кнопки push.

PHP Linter

Предупреждения в удобном формате

Плагин покажет найденные предупреждения на отдельной вкладке. Для каждого предупреждения есть несколько дополнительных действий.

Быстро переходите к найденным предупреждениям

Откройте контекстное меню для выбранного предупреждения и выберите Jump To Source или используйте сочетание ⌘↓ (Cmd+↓).

Просматривайте описание проверки прямо в IDE

В контекстном меню выберите пункт Show Problem Description или ⌘I (Cmd+I), и плагин покажет краткое описание проверки.

Создавайте различные конфигурации линтера

Для проверки всего сайта или только отдельных файлов.

Запускайте линтер в полном режиме как в Teamcity

Это занимает больше времени, но результаты точно будут идентичны билд-агентам.

Запускайте линтер как в Teamcity во время пуша в Gitlab

Для этого в настройках поставьте галочку около пункта Run PHP Linter as in Teamcity.

Запуск KPHP — привычные способы

Ошибки компиляции в удобном формате

Плагин покажет найденные ошибки на отдельной вкладке. Весь вывод компиляции будет доступен на первой вкладке.

Быстро переходите к найденным ошибкам

Выберите Jump To Source в контекстном меню или нажмите ⌘↓ (Cmd+↓), чтобы перейти к строке с ошибкой.

Различные конфигурации запуска KPHP

Сохраняйте частоиспользуемые конфигурации для быстрого запуска.

Hastebin

Для любого файла

В контекстном меню любого файла теперь есть пункт Create Hastebin. Плагин загрузит файл и скопирует ссылку в буфер обмена.

Из вывода инструментов

На тулбаре в окне вывода также появилась кнопка. Это удобно, если вы хотите поделиться им, например, в чате.

Хотите добавить свой инструмент
или есть идея?

Приходите в команду KPHP или в чатик PHPStorm.
Мы всегда рады новым идеям.