Создание модуля из папки
В контекстом меню папки New -> Modulite from Folder....
Если папка большая, нужно чуть подождать, пока плагин сканирует содержимое. Покажется форма создания:
Там указывается имя модуля (по умолчанию по имени папки) и видимость символов галочками.
Отмеченные это export, неотмеченные internal.
Мы оперируем конкретными символами: никаких масок "по звёздочке" (что при создании, что впоследствии).
Символы — это не только классы. Это также обычные функции, глобальные константы, дефайны.
Да, Modulite оперирует символами гранулярно: зато можно насоздавать дефайнов в модуле,
и если они internal, то внешний код их не увидит.
Также в форме есть namespace и folder — но это скорее для сверки, они неизменяемы.
Если модуль вложенный, то ещё информация про родительский.
Плагин автоматически сгенерирует requires, а также если нужно, перегенерирует зависимости других модулей.
После нажатия "OK" откроется созданный .modulite.yaml.
Если вы сделали все символы публичными, то код остался валиден.
Если же некоторые приватные и есть внешний код, который их использует — компиляция упадёт с ошибкой.
Делаем символы internal и обратно
Возле символов модуля @name есть надпись exported from @name
(или internal in @name). Менять состояние можно либо через Alt+Enter,
либо контекстным меню прям на этом хинте.
Область видимости есть не только у классов: у методов, у обычных функций и даже у дефайнов.
Также помним, что все новые символы по умолчанию приватные (т.к. не экспортированы),
о чём подсказки лишний раз напоминают.
Кстати, эти хинты справа интерактивные: на @name можно кликнуть и перейти в yaml-файл.
Правила видимости следующие:
- все новые символы по умолчанию — приватные; нужен явный export;
- если класс exported, то все его методы/поля/константы по дефолту тоже exported;
- даже в exported-классе зафорсить internal для его статик-поля/статик-метода/константы;
- инстанс-поля и инстанс-методы отдельно не контролируются и вообще не анализируются плагином:
иначе будут расхождения в выводе типов между IDE и KPHP.
Делаем internal уже используемый класс
Представим ситуацию: есть класс SortPolicy в @messi-folders,
он по идее деталь реализации и должен быть приватным, но уже где-то внешний код его уже использует.
Если просто сделать его internal, то существующий код перестанет компилироваться. Что делать?
Ответ такой: можно сделать его internal, но добавить конкретные места, которые есть уже сейчас,
в исключения. Таким образом, существующий код будет работать (и от исключений в будущем нужно избавиться),
а новый код уже не сможет использовать internal-класс. Таким образом, мы зафиксируем текущее состояние,
но не позволим ему становиться хуже.
Действие "Make internal in @name" делает это автоматически!
Плагин анализирует использования в текущем коде и добавляет их в исключения.
После этого хинт будет "internal in @name (visible for ...)", а само использование
хоть и разрешено, но перечёркнуто, будто бы deprecated.
Физически это привело к тому, что в конфиг добавилось allow-internal-access:
Разрешаем символ самостоятельно
Выше мы доверялись плагину в открытии доступа ко внутренним символам извне.
Однако мы можем сделать это и вручную.
Например, мы хотим разрешить использовать SortPolicy не в конкретной глобальной функции,
а во всём модуле @api. Можно нажать "Allow internal access for specific modulite"
и там уже выбрать из списка.
В любом случае, это сводится к изменению конфига.
Если каких-то действий в UI не хватает, можно поменять ручками.
Скрываем члены публичного класса
Вряд ли это будет частым, но иногда хочется запретить доступ к конкретному методу снаружи,
оставив его public. Спрашивается, зачем, ведь можно сделать метод private? Не всегда.
Если это класс, который используется из других классов модуля — то модификатор доступа не подходит.
При этом сам класс зачем-то должен быть export.
Вряд ли это хорошая архитектура — но напомню, что модульность в первую очередь обеспечивает
потребности уже существующего кода с порой сомнительной архитектурой, чтобы не допускать ещё хуже.
Здесь на помощь приходит форсирование internal для членов класса.
Опять-таки, это можно сделать как через Alt+Enter, так и мышкой на хинте.
Это привело к модификации конфига, а конкретнее — секции force-internal:
Если у метода уже были внешние использования, то как и раньше, плагин это обнаружит
и также дополнит allow-internal-access.
Новый код и require
Надеюсь, вы помните, что в секции require конфига указываются все вншение символы,
разрешённые к использованию. При первичном создании модуля плагин его создаёт автоматически.
Что там перечисляется:
- другие модули
@another-modulite
- композер-пакеты
#some/package
- внешние классы
\Some\External\Class
- статические методы классов
\Some\External\Class::itsMethod()
- внешние глобальные функции
\externalGlobalFunction()
- внешние дефайны и константы
\SOME_DEFINE
- все глобальные переменные
$global_var
Плагин при просмотре yaml-файлика удобно группирует зависимости, хотя это сплошной список по сути.
Согласно yaml-синтаксису, для строк требуется экранирование слешей, однако все символы кликабельные,
будто в обычном PHP-коде.
При написании нового кода плагин будет проверять, что используются только указанные зависимости,
иначе ошибка, что символ не прописан в requires. Есть quick fix для исправления,
это приведёт к изменению yaml-файлика — явная фиксация новой зависимости,
что видно на ревью и остаётся в гите.
Если подключен другой модуль — можно использовать любой его символ, аналогично с композер-пакетами.
Если подключен класс — можно использовать его константы, поля, и инстанс-методы,
а вот статик-методы нужно перечислять отдельно каждый.
Quick fix обо всём этом знает и будет предлагать "Add @api to requires",
если обращаешься к любому символу из @api.
В текущем VKCOM-коде, пока модулей мало, каждый новый модуль будет содержать десятки внешних зависимостей
на глобал классы и функции. С течением времени, когда всё больше кода будет оформляться в модули,
зависимости на конкретные символы будут переделываться на зависимости от модулей.
В идеале, модули должны стремиться только к зависимостям от других модулей и пакетов.
Так, в примере выше явно перечисляются \Messinger\Kernel\... символы.
А вот когда Месси сделает из этого модуль, то эти зависимости схлопнутся в одну
(опять-таки автоматически при создании @messi-kernel):
Таким образом, заглядывая в yaml-файлик, мы всегда видим глазами,
насколько модуль привязан к внешнему коду — и к какому конкретно.
Регенерация зависимостей модуля
По мере рефакторинга, некоторые символы в requires
становятся уже не нужны, то есть список устаревает.
Чтобы привести его в актуальное состояние, полезно иногда нажимать "click to regenerate" —
над пунктом или в контекстном меню:
Плагин заново пересчитает зависимости, проапдейтит yaml-файл и выдаст сообщение справа внизу.
Клик по "Show details" покажет, что конкретно изменилось:
Вложенные модули, подмодули
Модули могут быть вложены друг в друга. При этом имя подмодуля должно начинаться
с имени его родителя. Например, если родительский @messi, то дочерние
@messi/folders и т.п.
С точки зрения родительского, подмодуль может быть как экспортирован наружу, так и приватным.
Пусть есть структура мессенджера, с тремя модулями:
Messinger/
Channels/
...
Folders/
...
Kernel/
...
В таком виде, это 3 независимых модуля, объединённых только общим namespace, но не общими правилами.
Внешний код может использовать любой из них (в рамках разрешённых export'ов).
Иными словами, в этой структуре админка может лезть в ядро мессенджера,
и ровно по тем же правилам, что и каналы.
Грамотнее — не так. Грамотнее — сделать внешний модуль @messi и 3 подмодуля.
При этом @messi/kernel чтоб был приватным.
Такая структура не позволит админке лезть в ядро мессенджера,
а каналы и папки будут работать по-прежнему:
Messinger/
Channels/
...
Folders/
...
Kernel/
...
Итого, просто делаем "New Modulite from Folder" и настраиваем галочки:
Выглядит это так:
Обратите внимание, что все дочерние модули переменовались: @any-child
стал называться @messi/any-child. Вероятно, их захочется вручную укоротить,
чтобы было лаконичнее. Это легко делать через Rename, когда курсор на имени модуля в yaml-файлике.
Допустим, мы переименовали все три, и в итоге добились нужной структуры:
Как и ожидается, из админки @messi/kernel недоступно, даже если указать вручную в requires.
А вот из каналов и других внутренностей мессенджера — по-прежнему без проблем
(конечно же, следуя правилам на export, которые наложены kernel'ом).
По сути, вложенный модуль тоже может быть атомарной деталью реализации.
Вообще, это нормальный (и даже рекомендуемый) процесс: сначала делать модулями какие-нибудь небольшие
и внутренние вещи, называя модули длинно, по типу @feed-smart-blocks-proxy.
А потом по мере того как код рефакторится и появляется структура,
уже оформлять родительские модули, укорачивая дочерние.
Кстати, внешний код может подключать как @messi/folders и другие подмодули поодиночке,
так и подключить @messi целиком и использовать все доступные публичные символы,
которые существуют сейчас и появятся в будущем.
Find usages внутри модуля
Одной из важных фичей плагина является возможность отвечать на вопросы "Где?" и "Что?".
Допустим, вы лазите по коду и видите вызов currentUser().
Либо смотрите yaml-файлик и видите его в requires.
И сразу же возникает вопрос: окей, мой модуль зависит от этой функции, но насколько сильно?
Если там пара вызовов, это легко переделать, а если 100, то печаль.
В контекстом меню любого символа, помимо обычного "Find usages", добавляется новый пункт:
"Find usages in @{current}...":
Будет показано нативное окошко — только с фильтрацией внутри текущего модуля.
И даже если в проекте символ используется тысячи раз, а внутри модуля только два — будет видно только два.
Пунктом ниже в том же меню есть "Find usages in Modulite...".
Выскочит окошко, где нужно выбрать модуль, и поиск будет идти внутри него, а не в текущем.
Степень зависимости от другого модуля
Мы же помним, что когда используем символ из модуля, то добавляем в requires сам модуль.
Так, для использования MsgDatabase подключаем @messi/kernel.
Впоследствии, если используем другие символы из модуля, requires уже менять не нужно.
И бывает, хочется узнать: насколько сильно я завишу от @messi/kernel?
Возможно, я использую только один класс оттуда, а возможно, целых десять.
Делается в контекстном меню на интересующем модуле в yaml-файлике:
Плагин чуть подумает и выдаст окошко с публичными символами интересующего модуля.
Сереньким будут те, зависимости от которых нет.
А для остальных можно даблкликом поискать конкретно его в текущем модуле — как в разделе выше.
Это очень удобный способ визуально оценить, от скольких символов чужого модуля вы зависите.
Имена модулей в интерфейсе
Интерфейс IDE чуть модифицируется, чтобы визуально подсвечивать наличие модулей.
Во-первых, возле классов, статик-методов и некоторых других символов всегда пишется
напоминание, internal он или нет. При этом, если вложенность длинная, то
хинт сворачивается до @.../childname, а при клике на многоточие раскрывается.
Хинты кликабельные, можно перейти в любого родителя прям здесь:
В дереве файлов тоже отображаются имена модулей, пропуская родительские, для читаемости.
То же самое и в строке навигации.
В дереве файлов есть постфикс (internal).
Меняются иконки папок-модулей: если нет дочерних, то один квадратик, а если есть, то четыре;
если экспортирован из родителя, то яркий, иначе оранжевый.
Плагин — это удобный UI над конфигом (файликом .modulite.yaml).
Всё это можно делать и без плагина — просто не так удобно.
Именно файлик хранится под гитом, именно изменения в нём
видны на ревью при добавлении зависимостей или исключений.
