Deprecate the global ea variable in favor of a Twig function

javiereguiluz · javiereguiluz · commit 4a1afa96533f · 2025-06-20T21:01:50.000+02:00
diff --git a/UPGRADE.md b/UPGRADE.md
@@ -1,6 +1,19 @@
 Upgrade between EasyAdmin 4.x versions
 ======================================
 
+EasyAdmin 4.25.0
+----------------
+
+The global `ea` variable injected in all templates is deprecated.
+Use the equivalent `ea()` Twig function, which returns the current context
+of the EasyAdmin application.
+
+    // Before
+    {{ ea.i18n.translationDomain }}
+
+    // After
+    {{ ea().i18n.translationDomain }}
+
 EasyAdmin 4.22.0
 ----------------
 
diff --git a/src/Contracts/Provider/AdminContextProviderInterface.php b/src/Contracts/Provider/AdminContextProviderInterface.php
@@ -13,5 +13,6 @@ interface AdminContextProviderInterface extends AdminContextInterface
 {
     public function hasContext(): bool;
 
+    // the $throw parameter is deprecated and will be removed in 5.0
     public function getContext(bool $throw = false): ?AdminContextInterface;
 }
diff --git a/src/Provider/AdminContextProvider.php b/src/Provider/AdminContextProvider.php
diff --git a/src/Twig/EasyAdminTwigExtension.php b/src/Twig/EasyAdminTwigExtension.php
@@ -3,6 +3,7 @@
 namespace EasyCorp\Bundle\EasyAdminBundle\Twig;
 
 use EasyCorp\Bundle\EasyAdminBundle\Collection\FieldCollection;
+use EasyCorp\Bundle\EasyAdminBundle\Contracts\Context\AdminContextInterface;
 use EasyCorp\Bundle\EasyAdminBundle\Contracts\Provider\AdminContextProviderInterface;
 use EasyCorp\Bundle\EasyAdminBundle\Dto\FieldLayoutDto;
 use EasyCorp\Bundle\EasyAdminBundle\Factory\FormLayoutFactory;
@@ -45,6 +46,7 @@ public function __construct(
     public function getFunctions(): array
     {
         return [
+            new TwigFunction('ea', [$this, 'ea']),
             new TwigFunction('ea_url', [$this, 'getAdminUrlGenerator']),
             new TwigFunction('ea_form_ealabel', null, ['node_class' => 'Symfony\Bridge\Twig\Node\SearchAndRenderBlockNode', 'is_safe' => ['html']]),
             // deprecated functions
@@ -69,10 +71,14 @@ public function getFilters(): array
 
     public function getGlobals(): array
     {
-        // this is needed to make the admin context available on any Twig template via the short named variable 'ea'
         return ['ea' => $this->adminContextProvider];
     }
 
+    public function ea(): ?AdminContextInterface
+    {
+        return $this->adminContextProvider->getContext();
+    }
+
     /**
      * Transforms ['a' => 'foo', 'b' => ['c' => ['d' => 7]]] into ['a' => 'foo', 'b[c][d]' => 7]
      * It's useful to submit nested arrays (e.g. query string parameters) as form fields.
diff --git a/templates/crud/detail.html.twig b/templates/crud/detail.html.twig
@@ -1,5 +1,6 @@
 {# @var ea \EasyCorp\Bundle\EasyAdminBundle\Context\AdminContext #}
 {# @var entity \EasyCorp\Bundle\EasyAdminBundle\Dto\EntityDto #}
+{% set ea = ea() %}
 {% extends ea.templatePath('layout') %}
 
 {% block body_id 'ea-detail-' ~ entity.name ~ '-' ~ entity.primaryKeyValue %}
diff --git a/templates/crud/edit.html.twig b/templates/crud/edit.html.twig
@@ -1,5 +1,6 @@
 {# @var ea \EasyCorp\Bundle\EasyAdminBundle\Context\AdminContext #}
 {# @var entity \EasyCorp\Bundle\EasyAdminBundle\Dto\EntityDto #}
+{% set ea = ea() %}
 {% extends ea.templatePath('layout') %}
 {% form_theme edit_form with ea.crud.formThemes only %}
 
diff --git a/templates/crud/field/array.html.twig b/templates/crud/field/array.html.twig
@@ -1,7 +1,7 @@
 {# @var ea \EasyCorp\Bundle\EasyAdminBundle\Context\AdminContext #}
 {# @var field \EasyCorp\Bundle\EasyAdminBundle\Dto\FieldDto #}
 {# @var entity \EasyCorp\Bundle\EasyAdminBundle\Dto\EntityDto #}
-{% if ea.crud.currentAction == 'detail' %}
+{% if ea().crud.currentAction == 'detail' %}
     <ul>
         {% for item in field.value %}
             <li>{{ item }}</li>
diff --git a/templates/crud/field/boolean.html.twig b/templates/crud/field/boolean.html.twig
@@ -1,6 +1,7 @@
 {# @var ea \EasyCorp\Bundle\EasyAdminBundle\Context\AdminContext #}
 {# @var field \EasyCorp\Bundle\EasyAdminBundle\Dto\FieldDto #}
 {# @var entity \EasyCorp\Bundle\EasyAdminBundle\Dto\EntityDto #}
+{% set ea = ea() %}
 {% trans_default_domain 'EasyAdminBundle' %}
 
 {% if ea.crud.currentAction == 'detail' or not field.customOptions.get('renderAsSwitch') %}
diff --git a/templates/crud/field/code_editor.html.twig b/templates/crud/field/code_editor.html.twig
@@ -1,7 +1,7 @@
 {# @var ea \EasyCorp\Bundle\EasyAdminBundle\Context\AdminContext #}
 {# @var field \EasyCorp\Bundle\EasyAdminBundle\Dto\FieldDto #}
 {# @var entity \EasyCorp\Bundle\EasyAdminBundle\Dto\EntityDto #}
-{% if ea.crud.currentAction == 'detail' %}
+{% if ea().crud.currentAction == 'detail' %}
     {{ _self.render_code_editor(field) }}
 {% else %}
     {% set html_id = 'ea-code-editor-' ~ field.uniqueId %}
diff --git a/templates/crud/field/text.html.twig b/templates/crud/field/text.html.twig
@@ -1,7 +1,7 @@
 {# @var ea \EasyCorp\Bundle\EasyAdminBundle\Context\AdminContext #}
 {# @var field \EasyCorp\Bundle\EasyAdminBundle\Dto\FieldDto #}
 {# @var entity \EasyCorp\Bundle\EasyAdminBundle\Dto\EntityDto #}
-{% if ea.crud.currentAction == 'detail' %}
+{% if ea().crud.currentAction == 'detail' %}
     <span title="{{ field.value }}">{{ field.formattedValue|raw|nl2br }}</span>
 {% else %}
     <span title="{{ field.value }}">{{ field.formattedValue|raw }}</span>
diff --git a/templates/crud/field/text_editor.html.twig b/templates/crud/field/text_editor.html.twig
@@ -1,7 +1,7 @@
 {# @var ea \EasyCorp\Bundle\EasyAdminBundle\Context\AdminContext #}
 {# @var field \EasyCorp\Bundle\EasyAdminBundle\Dto\FieldDto #}
 {# @var entity \EasyCorp\Bundle\EasyAdminBundle\Dto\EntityDto #}
-{% if ea.crud.currentAction == 'detail' %}
+{% if ea().crud.currentAction == 'detail' %}
     {{ field.formattedValue|nl2br }}
 {% else %}
     {% set html_id = 'ea-text-editor-' ~ field.uniqueId %}
diff --git a/templates/crud/field/textarea.html.twig b/templates/crud/field/textarea.html.twig
@@ -2,7 +2,7 @@
 {# @var field \EasyCorp\Bundle\EasyAdminBundle\Dto\FieldDto #}
 {# @var entity \EasyCorp\Bundle\EasyAdminBundle\Dto\EntityDto #}
 {% set render_as_html = field.customOptions.get('renderAsHtml') %}
-{% if ea.crud.currentAction == 'detail' %}
+{% if ea().crud.currentAction == 'detail' %}
     <span title="{{ field.value }}">
         {{ render_as_html ? field.formattedValue|raw|nl2br : field.formattedValue|nl2br }}
     </span>
diff --git a/templates/crud/field/url.html.twig b/templates/crud/field/url.html.twig
@@ -3,7 +3,7 @@
 {# @var entity \EasyCorp\Bundle\EasyAdminBundle\Dto\EntityDto #}
 {# NOTE: the rel="noopener" attr is needed to avoid performance and security issues
   (see https://web.dev/external-anchors-use-rel-noopener/) #}
-{% if ea.crud.currentAction == 'detail' %}
+{% if ea().crud.currentAction == 'detail' %}
     <a target="_blank" rel="noopener" href="{{ field.value }}">{{ field.value }}</a>
 {% else %}
     <a target="_blank" rel="noopener" href="{{ field.value }}">{{ field.formattedValue }}</a>
diff --git a/templates/crud/filters.html.twig b/templates/crud/filters.html.twig
@@ -1,6 +1,6 @@
 {# @var ea \EasyCorp\Bundle\EasyAdminBundle\Context\AdminContext #}
 {# @var filters_form \EasyCorp\Bundle\EasyAdminBundle\Form\Type\FiltersFormType #}
-{% form_theme filters_form with ea.crud.formThemes only %}
+{% form_theme filters_form with ea().crud.formThemes only %}
 
 {{ form_start(filters_form, { attr: {
     id: filters_form.vars.id,
diff --git a/templates/crud/form_theme.html.twig b/templates/crud/form_theme.html.twig
@@ -1,4 +1,5 @@
 {# @var ea \EasyCorp\Bundle\EasyAdminBundle\Context\AdminContext #}
+{% set ea = ea() %}
 {% use '@EasyAdmin/symfony-form-themes/bootstrap_5_layout.html.twig' %}
 
 {% block form_start %}
diff --git a/templates/crud/index.html.twig b/templates/crud/index.html.twig
@@ -1,6 +1,7 @@
 {# @var ea \EasyCorp\Bundle\EasyAdminBundle\Context\AdminContext #}
 {# @var entities \EasyCorp\Bundle\EasyAdminBundle\Collection\EntityCollection #}
 {# @var paginator \EasyCorp\Bundle\EasyAdminBundle\Orm\EntityPaginator #}
+{% set ea = ea() %}
 {% extends ea.templatePath('layout') %}
 {% trans_default_domain ea.i18n.translationDomain %}
 
diff --git a/templates/crud/new.html.twig b/templates/crud/new.html.twig
@@ -1,5 +1,6 @@
 {# @var ea \EasyCorp\Bundle\EasyAdminBundle\Context\AdminContext #}
 {# @var entity \EasyCorp\Bundle\EasyAdminBundle\Dto\EntityDto #}
+{% set ea = ea() %}
 {% extends ea.templatePath('layout') %}
 {% form_theme new_form with ea.crud.formThemes only %}
 
diff --git a/templates/crud/paginator.html.twig b/templates/crud/paginator.html.twig
@@ -1,5 +1,6 @@
 {# @var ea \EasyCorp\Bundle\EasyAdminBundle\Context\AdminContext #}
 {# @var paginator \EasyCorp\Bundle\EasyAdminBundle\Orm\EntityPaginator #}
+{% set ea = ea() %}
 {% trans_default_domain 'EasyAdminBundle' %}
 
 <div class="list-pagination">
diff --git a/templates/flash_messages.html.twig b/templates/flash_messages.html.twig
@@ -1,5 +1,6 @@
-{# @var ea \EasyCorp\Bundle\EasyAdminBundle\Provider\AdminContextProvider #}
-{% trans_default_domain ea.hasContext ? ea.i18n.translationDomain : (translation_domain is defined ? translation_domain ?? 'messages') %}
+{# @var ea \EasyCorp\Bundle\EasyAdminBundle\Provider\AdminContext #}
+{% set ea = ea() %}
+{% trans_default_domain null != ea ? ea.i18n.translationDomain : (translation_domain is defined ? translation_domain ?? 'messages') %}
 
 {% set flash_messages = app.flashes %}
 
diff --git a/templates/label/null.html.twig b/templates/label/null.html.twig
@@ -1,3 +1,3 @@
-{% if not (ea.crud.areNullValuesHidden ?? false) %}
+{% if not (ea().crud.areNullValuesHidden ?? false) %}
     <span class="badge badge-outline">{{ 'label.null'|trans(domain = 'EasyAdminBundle') }}</span>
 {% endif %}
diff --git a/templates/layout.html.twig b/templates/layout.html.twig
@@ -1,4 +1,5 @@
 {# @var ea \EasyCorp\Bundle\EasyAdminBundle\Context\AdminContext #}
+{% set ea = ea() %}
 {% trans_default_domain ea.i18n.translationDomain %}
 
 <!DOCTYPE html>
diff --git a/templates/menu.html.twig b/templates/menu.html.twig
@@ -4,7 +4,7 @@
 
     <ul class="menu">
         {% block main_menu %}
-            {% for menuItem in ea.mainMenu.items %}
+            {% for menuItem in ea().mainMenu.items %}
                 {% block menu_item %}
                     {% set is_submenu_item_with_no_items = menuItem.type == constant('EasyCorp\\Bundle\\EasyAdminBundle\\Dto\\MenuItemDto::TYPE_SUBMENU') and not menuItem.hasSubItems %}
                     {% if is_submenu_item_with_no_items %}
diff --git a/templates/page/content.html.twig b/templates/page/content.html.twig
@@ -1,6 +1,7 @@
 {# @var ea \EasyCorp\Bundle\EasyAdminBundle\Context\AdminContext #}
-{% extends ea.templatePath('layout') %}
-{% trans_default_domain ea.hasContext ? ea.i18n.translationDomain : (translation_domain is defined ? translation_domain ?? 'messages') %}
+{% set ea = ea() %}
+{% extends null != ea ? ea.templatePath('layout') : '@EasyAdmin/layout.html.twig' %}
+{% trans_default_domain null != ea ? ea.i18n.translationDomain : (translation_domain is defined ? translation_domain ?? 'messages') %}
 
 {% block body_class 'page-content' %}
 
diff --git a/templates/page/login.html.twig b/templates/page/login.html.twig
@@ -1,9 +1,10 @@
 {# @var ea \EasyCorp\Bundle\EasyAdminBundle\Provider\AdminContextProvider #}
-{% extends ea.hasContext ? ea.templatePath('layout') : '@EasyAdmin/page/login_minimal.html.twig' %}
-{% trans_default_domain ea.hasContext ? ea.i18n.translationDomain : (translation_domain is defined ? translation_domain ?? 'messages') %}
+{% set ea = ea() %}
+{% extends null != ea ? ea.templatePath('layout') : '@EasyAdmin/page/login_minimal.html.twig' %}
+{% trans_default_domain null != ea ? ea.i18n.translationDomain : (translation_domain is defined ? translation_domain ?? 'messages') %}
 
 {% block body_class 'page-login' %}
-{% block page_title %}{{ page_title is defined ? page_title|raw : (ea.hasContext ? ea.dashboardTitle|raw : '') }}{% endblock %}
+{% block page_title %}{{ page_title is defined ? page_title|raw : (null != ea ? ea.dashboardTitle|raw : '') }}{% endblock %}
 
 {% block head_favicon %}
     {% if favicon_path|default(false) %}
@@ -28,7 +29,7 @@
             <div id="header-logo">
                 {% block header_logo %}
                     {% if page_title %}
-                        {% if ea.hasContext %}
+                        {% if null != ea %}
                             <a class="logo {{ page_title|length > 14 ? 'logo-long' }}" title="{{ page_title|striptags }}" href="{{ path(ea.dashboardRouteName) }}">
                                 {{ page_title|raw }}
                             </a>
@@ -55,7 +56,7 @@
                     <input type="hidden" name="_csrf_token" value="{{ csrf_token(csrf_token_intention) }}">
                 {% endif %}
 
-                <input type="hidden" name="{{ target_path_parameter|default('_target_path') }}" value="{{ target_path|default(ea.hasContext ? path(ea.dashboardRouteName) : '/') }}" />
+                <input type="hidden" name="{{ target_path_parameter|default('_target_path') }}" value="{{ target_path|default(null != ea ? path(ea.dashboardRouteName) : '/') }}" />
 
                 {% block login_form_credentials_wrapper %}
                     <div class="form-group">

Original file line number	Diff line number	Diff line change
`@@ -13,5 +13,6 @@ interface AdminContextProviderInterface extends AdminContextInterface`
`13`	`13`	`{`
`14`	`14`	`public function hasContext(): bool;`
`15`	`15`
	`16`	`+ // the $throw parameter is deprecated and will be removed in 5.0`
`16`	`17`	`public function getContext(bool $throw = false): ?AdminContextInterface;`
`17`	`18`	`}`