Создание плагина разрешения ссылок для PhpStorm (IntelliJ IDEA)

Я работаю веб-программистом, пишу на PHP и использую фреймворк Kohana. Для разработки использую потрясающую, на мой взгляд, среду PhpStorm.

При работе с большими и не очень проектами меня всегда угнетало, что я много времени трачу на навигацию по проекту, на поиск того или иного файла (контроллера или шаблона) в дереве проекта. Ctrl+Shift+N, к сожалению, удобен далеко не всегда.

Для начала мне захотелось сделать так, чтобы можно было переходить из файла контроллера по нажатию Ctrl+B (или Ctrl+Click) над именем шаблона, передаваемого в кохановский View::factory(), непосредственно в файл шаблона:


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

Подготовка окружения

Нам потребуются:
— IntelliJ IDEA Community Edition или Ultimate.
— JDK ( необходимо скачать версию, с которой собран PhpStorm, иначе плагин не запустится, в моем случае это была Java 1.6);

Поскольку документация по созданию плагинов IDEA очень скудна, рекомендуется также обзавестись копией исходных кодов Intellij IDEA, и использовать ее в качестве наглядной документации :)

Настройка инструментов:

Необходимо настроить Java SDK и IntelliJ IDEA Plugin SDK:
— запускаем IntelliJ IDEA
— открываем пункт меню File | Project Structure
— выбираем вкладку SDKs, жмем на плюсик и выбираем путь к JDK

— выбираем вкладку Project
— нажимаем на new, далее IntelliJ IDEA Plugin SDK и в открывшемся меню — выбираем путь к PhpStorm (можно и к IntelliJ IDEA, но тогда мы не сможем отлаживать плагин в PhpStorm)


Также необходимо создать Run/Debug Configuration, чтобы можно было отлаживать плагин в PhpStorm.

Создадим проект

File | new project: Выбираем «Create from scratch», Вводим имя, выбираем тип Plugin Module, выбираем SDK, который мы настроили ранее, создаем проект.

Добавляем пафосные копирайты в файл plugin.xml (без этого никак!)

    <name>KohanaStorm</name>
    <description>KohanaStorm framework integration for PhpStorm<br/>
        Authors: zenden2k@gmail.com
    </description>
    <version>0.1</version>
    <vendor url="http://zenden.ws/" email="zenden2k@gmail.com">zenden.ws</vendor>
    <idea-version since-build="8000"/>

Чтобы наш плагин запускался не только под IDEA, но и в PhpStorm, добавим в plugin.xml следующую зависимость:

<depends>com.intellij.modules.platform</depends>

Основы

Для каждого файла IntelliJ IDEA строит дерево PSI.

PSI (Program Structure Interface) — это структура, представляющая содержимое файла как иерархию элементов определенного языка программирования. PsiFile является общим родительским классом для всех PSI файлов, а конкретные языки программирования представлены в виде классов, унаследованных от PsiFile. Например, класс PsiJavaFile представляет файл java, класс XmlFile представляет XML файл. Дерево PSI можно посмотреть, используя инструмент PSI Viewer (Tools -> View PSI Structure):

Разработка плагина

Итак, мне захотелось, чтобы можно было переходить из файла контроллера по Ctrl+B (или Ctrl+Click) по View::factory('имя_шаблона') непосредственно в файл шаблона.


 

Как реализовать задуманное?

Для разрешения ссылок нам нужно создать 3 класса, унаследованных от:

PsiReference — объект, реализующий этот интерфейс, представляет собой ссылку. Он содержит в себе данные о местонахождении в родительском элементе (положение в тексте) и данные (текст ссылки), позволяющие в дальнейшем «разрешить ссылку». Ссылка должна уметь сама себя разрешать, т.е. ее метод resolve() должен уметь найти элемент, на который она указывает.

PsiReferenceProvider — класс, который находит ссылки внутри одного элемента PSI дерева. Он возвращает массив объектов PsiReference.

PsiReferenceContributor — класс, который будет регистрировать наш PsiReferenceProvider как обработчик PSI элементов.

1. Создаем класс ссылки MyReference, реализующий интерфейс PsiReference, и в нем переопределить следующие методы

public class MyReference implements PsiReference  {
@Override
        public String toString() {    
        }

        public PsiElement getElement() {
        }

        public TextRange getRangeInElement() {
            return textRange;
        }

        public PsiElement handleElementRename(String newElementName)      
        }

        public PsiElement bindToElement(PsiElement element) throws IncorrectOperationException { 
        }

        public boolean isReferenceTo(PsiElement element) {
            return resolve() == element;
        }

        public Object[] getVariants() {
            return new Object[0];
        }

        public boolean isSoft() {
            return false;
        }

    @Nullable
    public PsiElement resolve() {
    }

    @Override
    public String getCanonicalText() {
    }
}

В этом классе самое большое значение имеет метод resolve(). В нем мы должны вернуть те элементы, на которые указывает наша ссылка. В нашем случае мы возвращаем ссылку на php-файл, но в общем случае это может быть любой элемент psi- дерева или языковой модели, лежащей над ним, например класс, метод, переменная и т.д.

2. Создаем класс, унаследованный от PsiReferenceProvider и переопределить метод getReferencesByElement:

public class MyPsiReferenceProvider extends PsiReferenceProvider { 
@Override
public PsiReference[] getReferencesByElement(@NotNull PsiElement element, @NotNull final ProcessingContext context) {
}
}

Метод getReferencesByElement должен возвратить список ссылок (PsiReference), которые содержатся в переданном ему элементу PsiElement. В нашем случае возвращается только одна ссылка, но в общем случае их может быть несколько, при этом каждая ссылка должна будет содержать соответствующий textRange (начальный индекс и конечный индекс нахождения ссылки внутри текста psi-элемента)

Основной проблемой при разработке этого метода стало то, что JetBrains не открыла плагинам доступа к языковому API (в нашем случае PHP). Но тут на помощь пришел Reflection. Что мы знаем об объекте element? То, что он должен быть экземпляром класса StringLiteralExpressionImpl.

 public PsiReference[] getReferencesByElement(@NotNull PsiElement element, @NotNull final ProcessingContext context) {
        Project project = element.getProject();

        PropertiesComponent properties = PropertiesComponent.getInstance(project);

        String kohanaAppDir = properties.getValue("kohanaAppPath", "application/");

        VirtualFile appDir = project.getBaseDir().findFileByRelativePath(kohanaAppDir);

        if (appDir == null) {
            return PsiReference.EMPTY_ARRAY;
        }
        String className = element.getClass().getName();
        Class elementClass = element.getClass();
        // определяем, что объект является экземпляром StringLiteralExpressionImpl
        if (className.endsWith("StringLiteralExpressionImpl")) {
            try {
               // Вызываем метод getValueRange, чтобы получить символьный диапазон, в котором находится наша ссылка
                Method method = elementClass.getMethod("getValueRange");
                Object obj = method.invoke(element);
                TextRange textRange = (TextRange) obj;
                Class _PhpPsiElement = elementClass.getSuperclass().getSuperclass().getSuperclass();
                // Вызываем метод getText, чтобы получить значение PHP-строки
                Method phpPsiElementGetText = _PhpPsiElement.getMethod("getText");
                Object obj2 = phpPsiElementGetText.invoke(element);
                String str = obj2.toString();
                String uri = str.substring(textRange.getStartOffset(), textRange.getEndOffset());
                int start = textRange.getStartOffset();
                int len = textRange.getLength();
                // Проверяем, подходит ли нам данная PHP-строка (путь к шаблону) или нет
                if (uri.endsWith(".tpl") || uri.startsWith("smarty:") || isViewFactoryCall(element)) {
                    PsiReference ref = new MyReference(uri, element, new TextRange(start, start + len), project, appDir);
                    return new PsiReference[]{ref};
                }

            } catch (Exception e) {
            }
        }

        return PsiReference.EMPTY_ARRAY;
    }

Чтобы определить, что нам попался не просто PHP-литерал, а строка, переданная именно в View::factory(), снова воспользуемся магией рефлекшн:

public static boolean isViewFactoryCall(PsiElement element) {
        PsiElement prevEl = element.getParent();

        String elClassName;
        if (prevEl != null) {
            elClassName = prevEl.getClass().getName();
        }
        prevEl = prevEl.getParent();
        if (prevEl != null) {
            elClassName = prevEl.getClass().getName();
            if (elClassName.endsWith("MethodReferenceImpl")) {
                try {
                 
                    Method phpPsiElementGetName = prevEl.getClass().getMethod("getName");
                    String name = (String) phpPsiElementGetName.invoke(prevEl);
                    if (name.toLowerCase().equals("factory")) {
                      
                        Method getClassReference = prevEl.getClass().getMethod("getClassReference");
                        Object classRef = getClassReference.invoke(prevEl);
                        PrintElementClassDescription(classRef);
                        String phpClassName = (String) phpPsiElementGetName.invoke(classRef);
                        if (phpClassName.toLowerCase().equals("view")) {
                            return true;
                        }

                    }
                } catch (Exception ex) {

                }
            }
        }
        return false;
    }

Чтобы было понятнее, с чем мы имеем дело, картинка:

Данный код определяет, что наш элемент действительно вложен в вызов метода (MethodReference), который называется «factory» и находится в классе «view».

3. Создать класс, унаследованный от PsiReferenceContributor и переопределить следующий метод:

   @Override
    public void registerReferenceProviders(PsiReferenceRegistrar registrar) {
        registrar.registerReferenceProvider(StandardPatterns.instanceOf(PsiElement.class), provider);
    }

Всё, что делает наш класс — регистрирует наш PsiReferenceProvider в неком реестре, и задает шаблон, к какому типу (подклассу) PsiElement его надо применять. Если бы нужный нам элемент документа был, скажем, значением XML-атрибута, всё было бы проще:

 registrar.registerReferenceProvider(StandardPatterns.instanceOf(XmlAttributeValue.class), provider);

Но поскольку JetBrains не открыла доступа к языковому API (в нашем случае PHP), нам приходится подписываться на абсолютно все элементы PsiElement, чтобы затем динамически определить, нужный нам это элемент или нет.

4. Зарегистрировать Contributor в файле plugin.xml:

  <extensions defaultExtensionNs="com.intellij">
    <psi.referenceContributor implementation="MyPsiReferenceContributor"/>
</extensions>

Создаем страницу настроек

 
В phpstorm настройки бывают двух типов — относящиеся к проекту и глобальные. Чтобы создать страницу настроек для нашего плагина, создадим класс KohanaStormSettingsPage, реализующий интерфейс Configurable. Метод getDisplayName должен возвращать название таба, которое будет отображаться в списке настроек PhpStorm. Метод createComponent должен возвращать нашу форму. В методе apply мы должны сохранить все настройки.

public class KohanaStormSettingsPage  implements Configurable  {

    private JTextField appPathTextField;
    private JCheckBox enableKohanaStorm;
    private JTextField secretKeyTextField;
    Project project;

    public KohanaStormSettingsPage(Project project) {
        this.project = project;
    }

    @Nls
    @Override
    public String getDisplayName() {
        return "KohanaStorm";
    }

    @Override
    public JComponent createComponent() {

        JPanel panel = new JPanel();
        panel.setLayout(new BoxLayout
                (panel,  BoxLayout.Y_AXIS));
        JPanel panel1 = new JPanel();
        panel1.setLayout(new BoxLayout(panel1, BoxLayout.X_AXIS));

        enableKohanaStorm = new JCheckBox("Enable Kohana Storm for this project");

...

        PropertiesComponent properties = PropertiesComponent.getInstance(project);
        appPathTextField.setText(properties.getValue("kohanaAppPath", DefaultSettings.kohanaAppPath));

        return panel;
    }

    @Override
    public void apply() throws ConfigurationException {
        PropertiesComponent properties = PropertiesComponent.getInstance(project);
        properties.setValue("kohanaAppPath", appPathTextField.getText());
        properties.setValue("enableKohanaStorm", String.valueOf(enableKohanaStorm.isSelected()) );
        properties.setValue("kohanaStormSecretKey", secretKeyTextField.getText());

    }

    @Override
    public boolean isModified() {
        return true;
    }

    @Override
    public String getHelpTopic() {
        return null;
    }

    @Override
    public void disposeUIResources() {

    }

    @Override
    public void reset() {

    }
}

Зарегистрируем нашу страницу настроек в файле plugin.xml:

<extensions defaultExtensionNs="com.intellij">
    <psi.referenceContributor implementation="MyPsiReferenceContributor"/>
    <projectConfigurable  implementation="KohanaStormSettingsPage"></projectConfigurable >

</extensions>

(если бы мы наша страница настроек была глобальной, мы бы использовали applicationConfigurable)

Хранение настроек

Наименее замороченный способ хранения настроек для плагина — использование класса PropertiesComponent и методов setValue и getValue. Более сложный способ описан в документации.

Установка плагина

После того, как разработка плагина будет завершена, необходимо выполнить
Build -> Prepare plugin for deployment. После этого в папке проекта появится файл с именем jar, который можно будет распространять.
Установить в phpstorm его можно выполнив (File->Settings->Plugins->Install From Disk)

Скачать плагин и исходные коды