Drupal 11.3: Introducing the TwigAllowed Attribute for Safer Twig Templates

With Drupal 11.3, the way Twig templates access object methods has received a significant upgrade. The new TwigAllowed attribute provides developers and themers with a more secure and explicit method to control which object methods can be called from Twig.

The Problem with Legacy Method Access

Before Drupal 11.3, Twig templates could automatically access certain methods of objects based on magic prefixes like get, is, and has. For example:

class Example {
  public function getTitle() {
    return "Hello Drupal!";
  }

  public function secret() {
    return "Do not expose!";
  }
}

In Twig:

{{ example.getTitle() }} {# Works #}
{{ example.secret() }}   {# Also works? Not necessarily, but legacy access rules can be tricky #}

While convenient, this approach had several downsides:

• Security risks: Any method with a recognized prefix could be accessed unintentionally.
• Lack of explicit control: Developers had no straightforward way to declare exactly which methods were safe for Twig.
• Legacy overrides: Access patterns could be customized via settings.php, which is discouraged.

Enter TwigAllowed

Drupal 11.3 introduces a PHP attribute #[\Drupal\Core\Template\Attribute\TwigAllowed] to explicitly allow a method for Twig access. Only methods marked with this attribute (or legacy get/is/has methods) are accessible.

Example Usage

namespace Drupal\my_module;

use Drupal\Core\Template\Attribute\TwigAllowed;

class TwigExample {

  #[TwigAllowed]
  public function allowed(): string {
    return __METHOD__;
  }

  public function notAllowed(): string {
    return __METHOD__;
  }

  // Still allowed due to legacy get-prefix, but deprecated.
  public function getLegacy(): string {
    return 'legacy';
  }
}

In Twig:

{% set obj = twig_example_instance %}

{# Allowed method #}
{{ obj.allowed() }}

{# Not allowed method - will trigger an error #}
{{ obj.notAllowed() }}

{# Legacy get-prefixed method #}
{{ obj.getLegacy() }}

Why TwigAllowed Matters

1. Security First
   Only explicitly marked methods are accessible, reducing the risk of exposing sensitive data.
2. Clarity for Developers
   Developers can now clearly document which methods are intended for template use.
3. Future Compatibility
   Legacy magic-prefix rules (get, is, has) still work but are deprecated. TwigAllowed is the future-proof method.

Migration Recommendations

For module developers:

• Review classes that are used in Twig templates.
• Add the #[TwigAllowed] attribute to methods that should be template-accessible.
• Avoid relying solely on legacy prefixes or settings.php overrides.

For themers:

• Be aware that calling non-allowed methods in Twig may now produce errors.
• Ensure templates are updated to reflect the new access rules.

Quick Comparison Table

Conclusion

Drupal 11.3’s TwigAllowed attribute is a small but powerful improvement for both security and developer clarity. By explicitly declaring which methods Twig can access, Drupal helps prevent accidental data exposure while making template behavior more predictable.