[FR] Add support for Twig auto-completion AND goto file behavior in plugins and modules

[BenParizek]

Adding the Symfony Support plugin to PhpStorm adds some neat features when working with Craft such as Twig variable auto-completion as described in this article Auto-Complete Craft CMS 3 APIs in Twig with PhpStorm.

One feature, however, that the Symfony Support plugin seems to have support for but that does not currently work in Craft is to auto-complete templates and jump to them when you command+click on the file name like you can when jumping between classes or method names in PhpStorm.

In my tests, it appears this feature is almost supported but the syntax that Symfony supports for targeting paths in Twig is slightly different than what Craft expects, especially when it comes to plugins and modules where template paths are prefixed by the module name.

It appears, if we could optionally place an @ sign at the beginning of template paths before the module name, the Symfony plugin would allow us to add support for auto-completion AND goto template behavior.

I'm not advocating that this is the only way to support this. The more general feature request is simply to support Twig auto-completion AND goto behavior.

---

Here's an example of how this almost works:

Once the Symfony Support plugin is added to a project, you can add an ide-twig.json file to the root of your project to configure paths for the Symfony plugins settings in: Languages & Frameworks -> PHP -> Symfony -> Twig / Template.

The ide-twig.json file might look like this:

{
    "namespaces": [
        {
            "path": "vendor/craftcms/cms/src/templates"
        }
    ]
}

The Craft templates folder auto-completion and goto behavior works out of the box, as no namespace is required and no module prefix is required in the template path.

{% extends "_layouts/base.html" %}
{% import "_includes/forms.html" as forms %}

When adding support for plugins and modules, however, the path does not get recognized with the configuration above because the module ID is required in the template path:

{% extends "sprout-forms/_layouts/base.twig" %}
{% import 'sprout-base/_includes/sproutcp.twig" as sprout %}

If we add namespaces to our ide-twig.json file, we can get very close to the same naming conventions:

{
    "namespaces": [
        {
            "path": "vendor/craftcms/cms/src/templates"
        },
        {
            "namespace": "sprout-forms",
            "path": "vendor/barrelstrength/sprout-forms/src/templates"
        },
        {
            "namespace": "sprout-base",
            "path": "vendor/barrelstrength/sprout-base/src/templates"
        }
    ]
}

Once those namespaces are in place, we can get autocompletion using the following syntax – the only difference being the @ symbol at the beginning of the module ID string:

{% extends "@sprout-forms/_layouts/base.twig" %}
{% import '@sprout-base/_includes/sproutcp.twig" as sprout %}

Example of autocompletion working for paths in separate plugins or modules:
http://share.barrelstrength.co/01f917439107

While this gives us auto-completion in templates for our plugins and modules, the templates do not load any longer as the @ syntax is not recognized and throws an "Unable to find the template" error.

If Craft could support an optional @ symbol at the beginning of module IDs when loading templates, I believe we could have auto-completion AND goto template support when we command+click on a template filename in the IDE.

[rob-baker-ar]

Did this ever get implemented?

This: #4846 was closed but not clear what the result was.

It would be very helpful.

[brandonkelly]

#4846 was converted to this discussion.

[BenParizek]

I don't believe it ever got solved. It might be possible to add support via a custom Twig Loader that just routes any templates that starts with @ to the same place. But I have yet to get around to trying that out.

[rob-baker-ar]

I did try exactly this. It works - PHPStorm understands all the paths after this change as long as each module id is set-up in the IDE settings.

Loosely speaking, a new loader class implements the Twig Loader interface, accepts Craft's Twig loader in it's constructor and proxies all the interface's methods to Craft's methods having first (in every case) checked for a truthy name and removed any prefixed @ character.

If this was being implemented in a more generalised / safer way, the code that checks for the @ sign should also check the string following the @ (but before the first directory separator) is also a valid module id, but the simple "dumb" check is enough for us.

The loader class is then injected like this in a module:

use module\custom\twig\Loader;

Event::on(
    View::class,
    View::EVENT_AFTER_CREATE_TWIG,
    function(CreateTwigEvent $event) {
        /** @var TemplateLoader $current */
        $current = $event->twig->getLoader();
        $event->twig->setLoader(new Loader($current));
    }
);