Chapter 9. Creating Complex and Dynamic Backends

In the previous chapters you’ve learned how to configure your backend using YAML configuration options and overriding Twig templates. This mechanism is enough for simple and medium-sized backends.

However, for more complex and dynamic backends you need to use the PHP-based customization mechanism provided by EasyAdmin. Depending on your needs you can choose any of these three customization options (or combine them, if your backend is very complex):

1. Override the default AdminController, which is easy to set up and best suited for simple backends.
2. Define a different controller for some or all entities, which is also easy to set up and scales well for medium-sized backends.
3. Define event listeners or subscribers that listen to the events triggered by EasyAdmin. This is harder to set up but allows you to define the customization code anywhere in your application.

Customization Based on Overriding the Default AdminController

This technique requires you to create a new controller in your Symfony application and make it extend from the default AdminController provided by EasyAdmin. Then you just add some methods in your controller to override the default ones.

Step 1. Create a new controller class anywhere in your Symfony application and make it extend from the default AdminController class:

// src/Controller/AdminController.php
namespace App\Controller;

use EasyCorp\Bundle\EasyAdminBundle\Controller\EasyAdminController;

class AdminController extends EasyAdminController
{
    // ...
}

Step 2. Open the EasyAdmin routing config file and change the resource option to point to your new controller:

# config/routes/easy_admin.yaml
easy_admin_bundle:
    # this is just an example; update the value of 'resource' accordingly
    resource: 'App\Controller\AdminController'
    type:     annotation
    prefix:   /admin

Save the changes and the backend will start using your own controller.

.. note::

The default Symfony routing config loads first the annotations of controllers
defined in `src/Controller/`. If you override the `AdminController`
in that directory, the routing config defined in `config/routes/easy_admin.yaml`
will be ignored. You can comment the contents of that file and use instead
the `@Route` annotation of `AdminController` to configure that route.

Step 3. You can now override in your own controller any of the methods executed in the default AdminController. The next sections explain all the available methods and show some practical examples.

AdminController Properties and Methods

First, the default `AdminController` extends from [the base Symfony controller](https://symfony.com/doc/current/book/controller.html#the-base-controller-class),
so you have access to all its shortcuts and utility methods:

``` php
// src/Controller/AdminController.php
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
// ...

class AdminController extends Controller
{
    // ...
}
```

In addition, the default `AdminController` defines some *properties* which
are commonly used in the rest of the methods:

``` php
// src/Controller/AdminController.php
class AdminController extends Controller
{
    /** @var array The full configuration of the entire backend */
    protected $config;
    /** @var array The full configuration of the current entity */
    protected $entity;
    /** @var Request The instance of the current Symfony request */
    protected $request;
    /** @var EntityManager The Doctrine entity manager for the current entity */
    protected $em;
}
```

Finally, the default `AdminController` defines lots of *methods* which you
can override in your own backends.

The `indexAction()` method is the only "real controller" because it's the only
method associated with a route (all the pages created with EasyAdmin use a
single route called `easyadmin`). It makes some checks and then it redirects to
the actual executed method, such as `listAction()`, `showAction()`, etc.:

``` php
// src/Controller/AdminController.php
class AdminController extends Controller
{
    /** @Route("/", name="easyadmin") */
    public function indexAction(Request $request)
    {
        // you can override this method to perform additional checks and to
        // perform more complex logic before redirecting to the other methods
    }
}
```

The `initialize()` method is called by `indexAction()` and it initializes
the values of the ``$config``, ``$entity``, ``$request`` and ``$em`` properties
shown above:

``` php
// src/Controller/AdminController.php
class AdminController extends Controller
{
    // override this method to initialize your custom properties
    protected function initialize(Request $request);
}
```

Then, the `AdminController` defines a method to handle each view. These
methods are complex because they need to perform lots of checks:

``` php
// src/Controller/AdminController.php
class AdminController extends Controller
{
    protected function listAction();
    protected function showAction();
    protected function editAction();
    protected function newAction();
    protected function searchAction();
    protected function deleteAction();
    // special Ajax-based action used to get the results for the autocomplete form field
    protected function autocompleteAction();
    // useful to add/modify/remove the parameters passed to the Twig template
    protected function renderTemplate();
}
```

The rest of the available methods are specific for each action:

*List* action:

``` php
// src/Controller/AdminController.php
class AdminController extends Controller
{
    // Creates the Doctrine query builder used to get all the items. Override it
    // to filter the elements displayed in the listing
    protected function createListQueryBuilder($entityClass, $sortDirection, $sortField = null, $dqlFilter = null);

    // Performs the actual database query to get all the items (using the query
    // builder created with the previous method). You can override this method
    // to filter the results before sending them to the template
    protected function findAll($entityClass, $page = 1, $maxPerPage = 15, $sortField = null, $sortDirection = null, $dqlFilter = null);
}
```

*Search* action:

``` php
// src/Controller/AdminController.php
class AdminController extends Controller
{
    // Creates the Doctrine query builder used to look for items according to the
    // user's query. Override it to filter the elements displayed in the search listing
    protected function createSearchQueryBuilder($entityClass, $searchQuery, array $searchableFields, $sortField = null, $sortDirection = null, $dqlFilter = null);

    // Performs the actual database query to look for the items according to the
    // user's query (using the query builder created with the previous method).
    // You can override this method to filter the results before sending them to
    // the template
    protected function findBy($entityClass, $searchQuery, array $searchableFields, $page = 1, $maxPerPage = 15, $sortField = null, $sortDirection = null, $dqlFilter = null);
}
```

*Delete* action:

``` php
// src/Controller/AdminController.php
class AdminController extends Controller
{
    // Creates the form used to delete an entity item (a form is required because
    // items are deleted using the 'DELETE' HTTP method)
    protected function createDeleteForm($entityName, $entityId);

    // It deletes the given Doctrine entity. You can override this method to prevent
    // entity removal when certain conditions met (e.g. don't delete user if username == 'admin').
    protected function removeEntity($entity);
}
```

*Edit* action:

``` php
// src/Controller/AdminController.php
class AdminController extends Controller
{
    // Creates the form used to edit an entity item
    protected function createEditForm($entity, array $entityProperties);

    // It flushes the given Doctrine entity to save its changes. It allows to modify
    // the entity before it's saved in the database.
    protected function updateEntity($entity)
}
```

*New* action:

``` php
// src/Controller/AdminController.php
class AdminController extends Controller
{
    // Creates a new instance of the entity being created. This instance is passed
    // to the form created with the 'createNewForm()' method. Override this method
    // if your entity has a constructor that expects some arguments to be passed
    protected function createNewEntity()

    // Creates the form used to create a new entity item
    protected function createNewForm($entity, array $entityProperties)

    // It persists and flushes the given Doctrine entity. It allows to modify the entity
    // before/after being saved in the database (e.g. to transform a DTO into a Doctrine entity)
    protected function persistEntity($entity)
}
```

*Edit* and *New* actions:

These methods are useful to make the same customizations for the `edit` and
`new` actions at the same time:

``` php
// src/Controller/AdminController.php
class AdminController extends Controller
{
    // Creates the form builder used to create the form rendered in the
    // create and edit actions
    protected function createEntityFormBuilder($entity, $view);

    // Returns the list of form options used by 'createEntityFormBuilder()'
    protected function getEntityFormOptions($entity, $view);

    // Creates the form object passed to the 'edit' and 'new' templates (using the
    // form builder created by 'createEntityFormBuilder()')
    protected function createEntityForm($entity, array $entityProperties, $view);
}
```

Overriding the Default AdminController in Practice

Update Some Properties for All Entities …

Imagine that some or all of your entities define a property called updatedAt. Instead of editing this value using the backend interface or relying on Doctrine extensions, you can make use of the updateEntity() method, which is called to save the changes made on an existing entity:

// src/Controller/AdminController.php
namespace App\Controller;

use EasyCorp\Bundle\EasyAdminBundle\Controller\EasyAdminController;

class AdminController extends EasyAdminController
{
    // ...

    public function updateEntity($entity)
    {
        if (method_exists($entity, 'setUpdatedAt')) {
            $entity->setUpdatedAt(new \DateTime());
        }

        parent::updateEntity($entity);
    }
}

This other example shows how to automatically set the slug of the entities when creating (persistEntity()) or editing (updateEntity()) them:

// src/Controller/AdminController.php
namespace App\Controller;

use EasyCorp\Bundle\EasyAdminBundle\Controller\EasyAdminController;

class AdminController extends EasyAdminController
{
    // ...

    public function persistEntity($entity)
    {
        $this->updateSlug($entity);
        parent::persistEntity($entity);
    }

    public function updateEntity($entity)
    {
        $this->updateSlug($entity);
        parent::updateEntity($entity);
    }

    private function updateSlug($entity)
    {
        if (method_exists($entity, 'setSlug') and method_exists($entity, 'getTitle')) {
            $entity->setSlug($this->slugger->slugify($entity->getTitle()));
        }
    }
}

Override the AdminController Methods per Entity

Before executing the methods showed above (`listAction()`, `showAction()`,
etc.), the controller looks for the existence of methods created specifically
for the current entity. These specific methods are called like the regular
methods, but they include the entity name as part of their names:

``` php
protected function list<EntityName>Action();
protected function search<EntityName>Action();
protected function show<EntityName>Action();
// ...
protected function render<EntityName>Template();
// ...
protected function createNew<EntityName>Entity();
// ...
protected function persist<EntityName>Entity();
protected function update<EntityName>Entity();
// ...
```

.. tip::

    Given the syntax of method names, it's recommended to use CamelCase notation
    to set the entity names.

Suppose that you have a `User` entity which requires to pass the roles of the
new user to its constructor. If you try to create new users with EasyAdmin,
you'll see an error because the entity constructor is missing a required
argument.

Instead of overriding the `createNewEntity()` method and check for the
`User` entity, you can just define the following method:

``` php
// src/Controller/AdminController.php
namespace App\Controller;

use EasyCorp\Bundle\EasyAdminBundle\Controller\EasyAdminController;

class AdminController extends EasyAdminController
{
    // Customizes the instantiation of entities only for the 'User' entity
    public function createNewUserEntity()
    {
        return new User(['ROLE_USER']);
    }
}
```

## Customization Based on Entity Controllers

If your backend is medium-sized, the previous overriding mechanism doesn't scale
well because it requires you to put all the custom code in the same AdminController.
In those cases, you can make each entity to use a different controller.

**Step 1.** Create a new controller class (for example `ProductController`)
anywhere in your Symfony application and make it extend from the default
`AdminController` class:

``` php
// src/Controller/ProductController.php
namespace App\Controller;

use EasyCorp\Bundle\EasyAdminBundle\Controller\EasyAdminController;

class ProductController extends EasyAdminController
{
    // ...
}
```

**Step 2.** Define the `controller` configuration option for the entity that
will use that controller and set the fully qualified class name as its value:

``` yaml
# config/packages/easy_admin.yaml
easy_admin:
    entities:
        # ...
        Product:
            controller: App\Controller\ProductController
            # ...
```

**Step 3.** You can now override any of the default `AdminController` methods
and they will be executed only for the `Product` entity. Repeat these steps for
the other backend entities that you want to customize.

.. note::

    It's not mandatory that your custom controllers extend from the default
    `AdminController` class, but doing that will simplify the code of your
    controllers.

.. note::

    In addition to the custom controller fully qualified class name, the
    `controller` option also works for controllers defined as services. Just
    set the name of the service as the value of the `controller` option.

## Customization Based on Symfony Events

During the execution of the backend actions, lots of events are triggered. Using
Symfony's event listeners or event subscribers you can hook to these events and
modify the behavior of your backend.

EasyAdmin events are defined in the ``EasyCorp\Bundle\EasyAdminBundle\Event\EasyAdminEvents`` class.
They are triggered before and after important operations and their names follow
the ``PRE_*`` and ``POST_*`` pattern:

``` php
final class EasyAdminEvents
{
    // Events related to initialize()
    const PRE_INITIALIZE;
    const POST_INITIALIZE;

    // Events related to the main actions
    const PRE_DELETE;
    const POST_DELETE;
    const PRE_EDIT;
    const POST_EDIT;
    const PRE_LIST;
    const POST_LIST;
    const PRE_NEW;
    const POST_NEW;
    const PRE_SEARCH;
    const POST_SEARCH;
    const PRE_SHOW;
    const POST_SHOW;

    // Events related to Doctrine entities
    const PRE_PERSIST;
    const POST_PERSIST;
    const PRE_UPDATE;
    const POST_UPDATE;
    const PRE_REMOVE;
    const POST_REMOVE;

    // Events related to the Doctrine Query builders
    const POST_LIST_QUERY_BUILDER;
    const POST_SEARCH_QUERY_BUILDER;
}
```

The Event Object
~~~~~~~~~~~~~~~~

Event listeners and subscribers receive an event object based on the
[GenericEvent class](https://symfony.com/doc/current/components/event_dispatcher/generic_event.html) defined by Symfony. The subject of the event depends
on the current action:

- `show`, `edit` and `new` actions receive the current ``$entity`` object
  (this object is also available in the event arguments as ``$event['entity']``).
- `list` and `search` actions receive the ``$paginator`` object which contains
  the collection of entities that meet the criteria of the current listing
  (this object is also available in the event arguments as
  ``$event['paginator']``).

In addition, the event arguments contain all the AdminController properties
(``$config``, ``$entity``, ``$request`` and ``$em``). You can access to them
through the `getArgument()` method or via the array access provided by the
`GenericEvent` class.

Event Subscriber Example
~~~~~~~~~~~~~~~~~~~~~~~~

The following example shows how to use an event subscriber to set the `slug`
property of the `BlogPost` entity before persisting it:

``` php
# src/EventSubscriber/EasyAdminSubscriber.php
namespace App\EventSubscriber;

use App\Entity\BlogPost;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\EventDispatcher\GenericEvent;

class EasyAdminSubscriber implements EventSubscriberInterface
{
    private $slugger;

    public function __construct($slugger)
    {
        $this->slugger = $slugger;
    }

    public static function getSubscribedEvents()
    {
        return [
            'easy_admin.pre_persist' => ['setBlogPostSlug'],
        ];
    }

    public function setBlogPostSlug(GenericEvent $event)
    {
        $entity = $event->getSubject();

        if (!($entity instanceof BlogPost)) {
            return;
        }

        $slug = $this->slugger->slugify($entity->getTitle());
        $entity->setSlug($slug);

        $event['entity'] = $entity;
    }
}
```

## Page Templates for Custom Backends

EasyAdmin provides several page templates which are useful when you are
customizing your backends.

Login Form Template
~~~~~~~~~~~~~~~~~~~

Twig Template Path: `@EasyAdmin/page/login.html.twig`

It displays a simple username + password login form that matches the style of
the rest of the backend. The template defines lots of config options, but most
applications can rely on its default values:

``` php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;
use Symfony\Component\Security\Http\Authentication\AuthenticationUtils;

class SecurityController extends AbstractController
{
    /**
     * @Route("/login", name="login")
     */
    public function login(AuthenticationUtils $authenticationUtils): Response
    {
        $error = $authenticationUtils->getLastAuthenticationError();
        $lastUsername = $authenticationUtils->getLastUsername();

        return $this->render('@EasyAdmin/page/login.html.twig', [
            // parameters usually defined in Symfony login forms
            'error' => $error,
            'last_username' => $lastUsername,

            // OPTIONAL parameters to customize the login form:

            // the string used to generate the CSRF token. If you don't define
            // this parameter, the login form won't include a CSRF token
            'csrf_token_intention' => 'authenticate',
            // the URL users are redirected to after the login (default: path('easyadmin'))
            'target_path' => $this->generateUrl('admin_dashboard'),
            // the label displayed for the username form field (the |trans filter is applied to it)
            'username_label' => 'Your username',
            // the label displayed for the password form field (the |trans filter is applied to it)
            'password_label' => 'Your password',
            // the label displayed for the Sign In form button (the |trans filter is applied to it)
            'sign_in_label' => 'Log in',
            // the 'name' HTML attribute of the <input> used for the username field (default: '_username')
            'username_parameter' => 'my_custom_username_field',
            // the 'name' HTML attribute of the <input> used for the password field (default: '_password')
            'password_parameter' => 'my_custom_password_field',
        ]);
    }
}
```

Content Page Template
~~~~~~~~~~~~~~~~~~~~~

Twig Template Path: `@EasyAdmin/page/content.html.twig`

It displays a simple page similar to the list/show/edit/new pages, with the
main header, the sidebar menu and the central content section. The only
difference is that the content section is completely empty, so it's useful to
display your own text contents, custom forms, etc.

Blank Page Template
~~~~~~~~~~~~~~~~~~~

Twig Template Path: `@EasyAdmin/page/blank.html.twig`

It displays a page with the same header and sidebar menu as the
list/show/edit/new pages, but without the central content section. It's useful
to define completely custom page, such as a complex dashboard.