EasyAdmin Extension provides some useful extensions to EasyAdmin admin generator for Symfony.
-
Branch
3.x
of this bundle requires at least PHP 7.1 and Symfony 4.2 components or stack and is suitable for EasyAdmin^2.2.2
(Versions v2.2.0 and v2.2.1 are not allowed as they don't have native menu permissions). It allows installation of EasyAdmin2.2.0
or upper and Symfony 5 as well. Extension bundle implementation of list filters is NOT COMPATIBLE with EasyAdmin dynamic list filters ! That's why we introduced the following change :โ BC BREAK list filters implemented by this extension bundle now use
ext_filters
query/form parameter, asfilters
is now used by native EasyAdmin for its own implementation of dynamic list filters. -
Branch
2.x
of this bundle requires at least PHP 7.1 and Symfony 4.1 components or stack and is suitable for EasyAdmin2.0.x
and2.1.x
. It does not allow installation of EasyAdmin2.2.0
or upper ! -
Branch
1.x
of this bundle requires at least PHP 7.0 and Symfony 3.0 components or stack and is suitable for EasyAdmin1.x
.
Features
- List filters form
- Register its own form types and aliases
- Embed lists in EDIT and SHOW views
- Autocomplete option to create related entity
- Role based access permissions
- Confirmation modal for custom POST actions (without form)
- Form fields by exclusion
- Vertical theme for SHOW view
$ composer require alterphp/easyadmin-extension-bundle
This command requires you to have Composer installed globally, as explained in the Composer documentation.
<?php
// app/AppKernel.php
// ...
class AppKernel extends Kernel
{
public function registerBundles()
{
$bundles = array(
// ...
new AlterPHP\EasyAdminExtensionBundle\EasyAdminExtensionBundle(),
);
}
// ...
}
Instead of loading routes from EasyAdminBundle EasyAdminController, load them from EasyAdminExtensionBundle EasyAdminController.
# config/routes/easy_admin.yaml
easy_admin_bundle:
resource: '@EasyAdminExtensionBundle/Controller/EasyAdminController.php'
type: annotation
prefix: /admin
# ...
If you have defined your own admin controllers, make them extend EasyAdminExtensionBundle EasyAdminController.
Add filters on list views by configuration.
Consider following Animation entity using such ValueListTrait :
class Animation
{
use ValueListTrait;
/**
* @var string
*
* @ORM\Id
* @ORM\Column(type="guid")
*/
private $id;
/**
* @var bool
*
* @ORM\Column(type="boolean", nullable=false)
*/
private $enabled;
/**
* @var string
*
* @ORM\Column(type="string", length=31)
*/
protected $status;
/**
* @var string
*
* @ORM\Column(type="string", length=31, nullable=false)
*/
private $type;
/**
* @var int
*
* @ORM\Column(type="integer", nullable=false)
*/
private $maxSubscriptions;
/**
* @var Organization
*
* @ORM\ManyToOne(targetEntity="App\Entity\Organization", inversedBy="animations")
* @ORM\JoinColumn(nullable=false)
*/
private $organization;
const STATUS_DRAFT = 'draft';
const STATUS_PUBLISHED = 'published';
const STATUS_OPEN = 'open';
const STATUS_ACTIVE = 'active';
const STATUS_CLOSED = 'closed';
const STATUS_ARCHIVED = 'archived';
}
Define your filters under list
.form_filters
entity configuration
easy_admin:
design:
assets:
css:
- 'bundles/easyadmin/bootstrap-all.css'
js:
# By default, EasyAdminBundle embeds a limited version of Bootstrap JS.
# For collapsible form filters to work, a full version should be added:
- 'bundles/easyadmin/bootstrap-all.js'
entities:
Animation:
class: App\Entity\Animation
list:
form_filters:
- enabled
- { property: type, type_options: { choices: { Challenge: challenge, Event: event } } }
- { property: status, type_options: { choices_static_callback: [getValuesList, [status, true]] } }
- organization
Let's see the result !
Guesser for list form filters are based on mapped entity property :
- boolean: guessed filter is a choice list (null, Yes, No)
- string: guessed filter is multiple choice list that requires either
choices
(value/label array) orchoices_static_callback
(static callback from entity class returning a value/label array) intype_options
. - integer, smallint, bigint: guessed filter is an integer input
- decimal, float: guessed filter is a number input
- *-to-one-relation: guessed filter is a multiple autocomplete of relation target entity.
Filters form's method is GET and submitted through form_filter
parameter. It is transmitted to the referer used for post update/delete/create redirection AND for search !
By default, list filter use equals
operator or in
for multiple value filters.
But you can use more operators with the operator
attribute :
entities:
Animation:
class: App\Entity\Animation
list:
form_filters:
- { name: maxSubscriptionGTE, property: maxSubscriptions, label: 'Max subscriptions >=', operator: gte }
- { name: maxSubscriptionLTE, property: maxSubscriptions, label: 'Max subscriptions <=', operator: lte }
Available built-in operators are listed in AlterPHP\EasyAdminExtensionBundle\Model\ListFilter
class, as constant OPERATOR_*
:
- equals: Is equal to
- not: Is different of
- in: Is in (
array
or DoctrineCollection
expected) - notin: Is not in (
array
or DoctrineCollection
expected) - gt: Is greater than
- gte: Is greater than or equal to
- lt: Is lower than
- lte: Is lower than or equal to
- like: Is LIKE %filterValue%
- EasyAdmin allows filtering list with
dql_filter
configuration entry. But this is not dynamic and must be configured as an apart list ineasy_admin
configuration.*
This extension allows to dynamically filter lists by adding ext_filters
parameter in the URL parameters. Having a list of books at URL <url-to-admin>?action=list&entity=Book
with a releaseYear field, you can filter on books releasd in 2016 by requesting <url-to-admin>?action=list&entity=Book&ext_filters[entity.releaseDate]=2016
. It only matches exact values, but you can chain them. To request books released in 2015 and 2016, you must request <url-to-admin>?action=list&entity=Book&ext_filters[entity.releaseDate][]=2015&ext_filters[entity.releaseDate][]=2016
.
This ext_filters
parameter is transmitted to the referer used for post update/delete/create redirection AND for search !
You have custom form types that you want to use in the EasyAdmin configuration. You can already register them with FQCN ... but it's quite boring and makes the admin massively enlarged. This feature allows you to define your own form types with short names, by configuration.
Let's see how to register them with those 2 examples (enum and statusable) :
easy_admin_extension:
custom_form_types:
enum: Admin\Form\Type\EnumType
statusable: Admin\Form\Type\StatusableType
Embedded lists are useful to show relations to en entity in its NEW/EDIT/FORM or SHOW view. It relies on the LIST view of the related entities you want to embed in the parent EDIT/SHOW view. Options must be defined in type_options
key for a NEW/EDIT/FORM view, or in template_options
for a SHOW view.
Available options are :
entity
: Entity config name (key under the EasyAdminentities
config)ext_filters
: Request filters to apply on the listhidden_fields
: List of fields (columns) to hide from list fields configmax_results
: Number of items par page (list.max_results config is used if not defined)sort
: Sort to applyparent_entity_fqcn
: Parent entity FQCN in order to guess default filters (only when embedded in SHOW view, almost never required)parent_entity_property
: Matching property name on parent entity FQCN (only when embedded in SHOW view, ifproperty
is not an ORM field)entity_fqcn
: Listed entities FQCN in order to guess default filters (only when embedded in SHOW view, almost never required)
Service EmbeddedListHelper is intended to guess entity
entry for embedded_list. It's reads ORM metadata, based on parent entity (the one that embeds the list) and property name.
It also guess default filter (relation between the parent and embedded list) for most of cases.
Use pre-configured type embedded_list
in the form definition :
easy_admin:
entities:
Event:
class: App\Entity\Event
Promoter:
class: App\Entity\Promoter
form:
fields:
# ...
- { type: group, label: Events, css_class: 'col-sm-12', icon: calendar }
- { property: events, label: '', type: embedded_list, type_options: { entity: Event, ext_filters: { 'entity.promoter': 'form:parent.data.id' } } }
But in many cases, the EmbeddedListHelper guesses type_options for you, and you just have to write :
easy_admin:
entities:
Event:
class: App\Entity\Event
Promoter:
class: App\Entity\Promoter
form:
fields:
# ...
- { type: group, label: Events, css_class: 'col-sm-12', icon: calendar }
- { property: events, label: '', type: embedded_list }
Let's see the result !
Using guesser for classic *ToMany relations :
easy_admin:
entities:
Event:
class: App\Entity\Event
Promoter:
class: App\Entity\Promoter
show:
fields:
# ...
- { property: events, label: '', type: embedded_list }
Use following template_options to pass options.
easy_admin:
entities:
Promoter:
class: App\Entity\Promoter
Event:
class: App\Entity\Event
form:
fields:
# ...
- { property: 'promoter', type: 'easyadmin_autocomplete', type_options: { attr: { create: true } } }
You can define a minimum role to access the EasyAdmin controller (any action handled by the controller) :
easy_admin_extension:
minimum_role: ROLE_ADMIN
This is just a global restriction, that should live with a security firewall as described in Symfony documentation.
You can also define role permissions per entity action :
easy_admin:
entities:
Product:
class: App\Entity\Product
list:
role: ROLE_ADMIN_PRODUCT_LIST
search:
role: ROLE_ADMIN_PRODUCT_SEARCH
new:
role: ROLE_ADMIN_PRODUCT_NEW
edit:
role: ROLE_ADMIN_PRODUCT_EDIT
show:
role: ROLE_ADMIN_PRODUCT_SHOW
delete:
role: ROLE_ADMIN_PRODUCT_DELETE
Above configuration define a required role per action for Product entity. This is too verbose, isn't it ? Let's sum up as following :
easy_admin:
entities:
Product:
class: App\Entity\Product
role_prefix: ROLE_ADMIN_PRODUCT
Entity role_prefix defines all actions required roles by appending the action name to the prefix.
You can also define role permissions per entity field in a form:
easy_admin:
entities:
Product:
class: App\Entity\Product
form:
fields:
- { property: enabled, role: ROLE_ADMIN }
If user do not hold the required role, the form field will be disabled.
A generic confirmation modal asks for confirmation (or any custom message) for links with data-confirm
attribute (that may contain the custom message) and URL in data-href
attribute.
Easy configurable with custom list actions by adding a confirm
key :
easyadmin:
entities:
User:
list:
actions:
- { name: disable, icon: ban, title: Disable user, label: false, target: _blank, confirm: User will lose any access to the platform ! }
easyadmin:
entities:
User:
form:
exclude_fields: ['references']
In such entity:
<?php
class User
{
public $name;
public $title;
public $references;
}
It will show all fields but those mentioned in exclude_fields
, equivalent to the following configuration:
easyadmin:
entities:
User:
form:
fields: ['name', 'title']
Design EasyAdmin configuration:
easy_admin:
design:
templates:
show: '@EasyAdminExtension/default/show_vertical.html.twig'
Run following command :
$ ./vendor/phpunit/phpunit/phpunit
OR using Docker and Docker Compose :
$ docker-compose run --rm phpunit
Locally with Docker :
docker-compose run --rm php /app/vendor/bin/php-cs-fixer fix --config=/app/.php_cs /app/src
Locally with Docker :
docker-compose run --rm php /app/vendor/bin/phpstan analyse -c /app/phpstan.neon --level=5 /app/src
This software is published under the MIT License