You are browsing the documentation for version 1.x which is not maintained anymore.
If some of your projects are still using this version, consider upgrading.
Chapter 9. Creating Complex and Dynamic Backends
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):
- Override the default AdminController, which is easy to set up and best suited for simple backends.
- Define a different controller for some or all entities, which is also easy to set up and scales well for medium-sized backends.
- 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:
1 2 3 4 5 6 7 8 9 10 | // In Symfony 2 and 3: src/AppBundle/Controller/AdminController.php
// In Symfony 4: src/Controller/AdminController.php
namespace AppBundle\Controller;
use EasyCorp\Bundle\EasyAdminBundle\Controller\AdminController as BaseAdminController;
class AdminController extends BaseAdminController
{
// ...
}
|
Step 2. Open the routing file where the easy_admin_bundle
route is
defined and change the resource
option to point to your new controller:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | # In Symfony 2 and 3: app/config/routing.yml
easy_admin_bundle:
# this is just an example; update the value of 'resource' accordingly
resource: '@AppBundle/Controller/AdminController.php'
type: annotation
prefix: /admin
# In Symfony 4: 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 routing config in Symfony 4 loads the annotations of controllers
defined in src/Controller/
first. 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,
so you have access to all its shortcuts and utility methods:
1 2 3 4 5 6 7 | 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:
1 2 3 4 5 6 7 8 9 10 11 | 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.:
1 2 3 4 5 6 7 8 9 | 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:
1 2 3 4 5 | 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:
1 2 3 4 5 6 7 8 9 10 11 12 13 | 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:
1 2 3 4 5 6 7 8 9 10 11 | 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:
1 2 3 4 5 6 7 8 9 10 11 12 | 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);
// 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);
}
|
Delete action:
1 2 3 4 5 6 7 8 9 10 | 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);
}
|
New in version 1.17.8: The removeEntity()
method was added in EasyAdmin 1.17.8. Previously it
was called preRemoveEntity()
.
Edit action:
1 2 3 4 5 6 7 8 9 | 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 in version 1.17.8: The updateEntity()
method was added in EasyAdmin 1.17.8. Previously it
was called preUpdateEntity()
.
New action:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | 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)
}
|
New in version 1.17.8: The persistEntity()
method was added in EasyAdmin 1.17.8. Previously it
was called prePersistEntity()
.
Edit and New actions:
These methods are useful to make the same customizations for the edit
and
new
actions at the same time:
1 2 3 4 5 6 7 8 9 10 11 12 13 | 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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | // src/AppBundle/Controller/AdminController.php
namespace AppBundle\Controller;
use EasyCorp\Bundle\EasyAdminBundle\Controller\AdminController as BaseAdminController;
class AdminController extends BaseAdminController
{
// ...
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | // src/AppBundle/Controller/AdminController.php
namespace AppBundle\Controller;
use EasyCorp\Bundle\EasyAdminBundle\Controller\AdminController as BaseAdminController;
class AdminController extends BaseAdminController
{
// ...
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->get('app.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:
1 2 3 4 5 6 7 8 9 10 11 | 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:
1 2 3 4 5 6 7 8 9 10 11 12 13 | // src/AppBundle/Controller/AdminController.php
namespace AppBundle\Controller;
use EasyCorp\Bundle\EasyAdminBundle\Controller\AdminController as BaseAdminController;
class AdminController extends BaseAdminController
{
// Customizes the instantiation of entities only for the 'User' entity
public function createNewUserEntity()
{
return new User(array('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:
1 2 3 4 5 6 7 8 9 | // src/AppBundle/Controller/ProductController.php
namespace AppBundle\Controller;
use EasyCorp\Bundle\EasyAdminBundle\Controller\AdminController as BaseAdminController;
class ProductController extends BaseAdminController
{
// ...
}
|
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:
1 2 3 4 5 6 | easy_admin:
entities:
# ...
Product:
controller: AppBundle\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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | 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 defined by Symfony. The subject of the event depends on the current action:
show
,edit
andnew
actions receive the current$entity
object (this object is also available in the event arguments as$event['entity']
).list
andsearch
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 | namespace AppBundle\EventListener;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\EventDispatcher\GenericEvent;
use AppBundle\Entity\BlogPost;
class EasyAdminSubscriber implements EventSubscriberInterface
{
private $slugger;
public function __construct($slugger)
{
$this->slugger = $slugger;
}
public static function getSubscribedEvents()
{
return array(
'easy_admin.pre_persist' => array('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;
}
}
|
This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.