SonataAdminBundle

https://symfony.com/bundles/SonataAdminBundle/5.x/
Admin
SonataAdminBundle is a powerful Symfony bundle designed to easily generate and customize complete...
Tokens:64,538
Snippets:684
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Clear Cache and Install Assets

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/getting_started/installation.html

Perform post-installation environment cleanup and asset deployment.

```bash
bin/console cache:clear
bin/console assets:install
```

--------------------------------

### Install Symfony Maker Bundle

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/console.html

Installs the required dependency for the make:sonata:admin command.

```bash
composer require symfony/maker-bundle --dev
```

--------------------------------

### Setup Admin class ACL rules

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/security.html

Install or update the CRUD ACL rules for all registered Admin classes.

```bash
bin/console sonata:admin:setup-acl
Starting ACL AdminBundle configuration
> install ACL for sonata.media.admin.media
   - add role: ROLE_SONATA_MEDIA_ADMIN_MEDIA_GUEST, permissions: ["VIEW","LIST"]
   - add role: ROLE_SONATA_MEDIA_ADMIN_MEDIA_STAFF, permissions: ["EDIT","LIST","CREATE"]
   - add role: ROLE_SONATA_MEDIA_ADMIN_MEDIA_EDITOR, permissions: ["OPERATOR","EXPORT"]
   - add role: ROLE_SONATA_MEDIA_ADMIN_MEDIA_ADMIN, permissions: ["MASTER"]
... skipped ...
```

--------------------------------

### Complete ClientAdmin implementation

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/cookbook/recipe_sortable_listing.html

Full example of the Admin class including the trait and configured list fields.

```php
// src/Admin/ClientAdmin.php

namespace App\Admin;

use Runroom\SortableBehaviorBundle\Admin\SortableAdminTrait;
use Sonata\AdminBundle\Admin\AbstractAdmin;
use Sonata\AdminBundle\Datagrid\ListMapper;

final class ClientAdmin extends AbstractAdmin
{
    use SortableAdminTrait;

    protected function configureListFields(ListMapper $list): void
    {
        $list
            ->addIdentifier('name')
            ->add('enabled')
            ->add(ListMapper::NAME_ACTIONS, ListMapper::TYPE_ACTIONS, [
                'actions' => [
                    'move' => [
                        'template' => '@RunroomSortableBehavior/sort.html.twig'
                    ],
                ],
            ])
        ;
    }
}
```

--------------------------------

### Full Admin Class Implementation

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/cookbook/recipe_custom_action.html

Complete example of a CarAdmin class integrating custom routes and list actions.

```php
// src/Admin/CarAdmin.php

namespace App\Admin;

use Sonata\AdminBundle\Admin\AbstractAdmin;
use Sonata\AdminBundle\Datagrid\ListMapper;
use Sonata\AdminBundle\Route\RouteCollection;

final class CarAdmin extends AbstractAdmin
{
    protected function configureRoutes(RouteCollectionInterface $collection): void
    {
        $collection
            ->add('clone', $this->getRouterIdParameter().'/clone');
    }

    protected function configureListFields(ListMapper $list): void
    {
        $list
            ->addIdentifier('name')
            ->add('engine')
            ->add('rescueEngine')
            ->add('createdAt')
            ->add(ListMapper::NAME_ACTIONS, null, [
                'actions' => [
                    'show' => [],
                    'edit' => [],
                    'delete' => [],
                    'clone' => [
                        'template' => '@App/CRUD/list__action_clone.html.twig',
                    ]
                ]
            ]);
    }
}
```

--------------------------------

### Setup ACL definitions

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/console.html

Updates ACL definitions for all Admin classes registered in the pool.

```bash
bin/console sonata:admin:setup-acl
```

--------------------------------

### Configure Security Handler

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/configuration.html

Example of setting the security handler in the sonata_admin configuration file.

```yaml
# config/packages/sonata_admin.yaml

sonata_admin:
    security:

        # the default value
        handler: sonata.admin.security.handler.role

        # use this service if you want ACL
        handler: sonata.admin.security.handler.acl
```

--------------------------------

### Install Workflow Integration Bundle

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/cookbook/recipe_workflow_integration.html

Use Composer to add the third-party toolkit for Sonata and Workflow integration.

```bash
composer require yokai/sonata-workflow
```

--------------------------------

### Example numeric block

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/templates.html

A simple numeric sequence block.

```text
1
2
3
4
5
```

--------------------------------

### Dynamic Default Filters

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/action_list.html

Example of setting filters conditionally based on user roles or security context.

```php
class PostAdmin extends Sonata\UserBundle\Admin\Model\UserAdmin
{
    protected function configureDefaultFilterValues(array &$filterValues): void
    {
        // Assuming security context injected
        if (!$this->securityContext->isGranted('ROLE_ADMIN')) {
            $user = $this->securityContext->getToken()->getUser();

            $filterValues['author'] = [
                'type'  => EqualType::TYPE_IS_EQUAL,
                'value' => $user->getId()
            ];
        }
    }
}
```

--------------------------------

### Parent Admin Route Pattern Definition

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/routing.html

Example of a parent Admin class defining a base route pattern.

```php
// src/Admin/PostAdmin.php

// The parent admin class
final class PostAdmin extends AbstractAdmin
{
    protected function generateBaseRoutePattern(bool $isChildAdmin = false): string
    {
        return 'post';
    }
    // ...
}
```

--------------------------------

### Displaying Only Label Icon

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/action_list.html

Example of hiding the text label while displaying only the icon.

```php
->add('upvotes', null, [
    'label' => false,
    'label_icon' => 'fas fa-thumbs-up',
])
```

--------------------------------

### Defining a custom batch action

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/batch_actions.html

Override configureBatchActions in your Admin class to register new batch operations. This example checks for necessary routes and permissions before adding a merge action.

```php
protected function configureBatchActions(array $actions): array
{
    if (
      $this->hasRoute('edit') && $this->hasAccess('edit') &&
      $this->hasRoute('delete') && $this->hasAccess('delete')
    ) {
        $actions['merge'] = [
            'ask_confirmation' => true,
            'controller' => 'app.controller.merge::batchMergeAction',
            // Or 'App/Controller/MergeController::batchMergeAction' base on how you declare your controller service.
        ];
    }

    return $actions;
}
```

--------------------------------

### Child Admin Route Pattern Definition

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/routing.html

Example of a child Admin class inheriting and prefixing the parent route pattern.

```php
// src/Admin/CommentAdmin.php

// The child admin class
final class CommentAdmin extends AbstractAdmin
{
    protected function generateBaseRoutePattern(bool $isChildAdmin = false): string
    {
        return 'comment';
    }
    // ...
}
```

--------------------------------

### Parent Admin Route Name Definition

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/routing.html

Example of a parent Admin class defining a base route name.

```php
// src/Admin/PostAdmin.php

// The parent admin class
final class PostAdmin extends AbstractAdmin
{
    protected function generateBaseRouteName(bool $isChildAdmin = false): string
    {
        return 'sonata_post';
    }
}
```

--------------------------------

### Custom Preview Template Structure

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/preview_mode.html

Example of a custom Twig template for preview mode, extending a layout and overriding form actions.

```twig
{# '@App/CRUD/preview.html.twig #}

{% extends '@App/layout.html.twig' %}

{% use '@SonataAdmin/CRUD/base_edit_form.html.twig' with form as parentForm %}

{% import '@SonataAdmin/CRUD/base_edit_form_macro.html.twig' as form_helper %}

{# a block in '@App/layout.html.twig' expecting article #}
{% block templateContent %}
    {% set article = object %}

    {{ parent() }}

    <div class="sonata-preview-form-container">
        {{ block('parentForm') }}
    </div>
{% endblock %}

{% block formactions %}
    <button class="btn btn-success" type="submit" name="btn_preview_approve">
        <i class="fas fa-check"></i>
        {{ 'btn_preview_approve'|trans({}, 'SonataAdminBundle') }}
    </button>
    <button class="btn btn-danger" type="submit" name="btn_preview_decline">
        <i class="fas fa-times"></i>
        {{ 'btn_preview_decline'|trans({}, 'SonataAdminBundle') }}
    </button>
{% endblock %}
```

--------------------------------

### EqualType Constants

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/action_list.html

Example of defining integer constants for filter types.

```php
namespace Sonata\Form\Type;

final class EqualType extends AbstractType
{
    const TYPE_IS_EQUAL = 1;
    const TYPE_IS_NOT_EQUAL = 2;
}
```

--------------------------------

### Full Configuration Options

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/configuration.html

Comprehensive list of all available configuration options for the sonata_admin bundle.

```yaml
# Default configuration for extension with alias: "sonata_admin"
sonata_admin:
    security:
        handler: sonata.admin.security.handler.noop

        role_admin: ROLE_ADMIN
        role_super_admin: ROLE_SUPER_ADMIN

        information:

            # Prototype
            id: []
        admin_permissions:

            # Defaults:
            - CREATE
            - LIST
            - DELETE
            - UNDELETE
            - EXPORT
            - OPERATOR
            - MASTER
        object_permissions:

            # Defaults:
            - VIEW
            - EDIT
            - HISTORY
            - DELETE
            - UNDELETE
            - OPERATOR
            - MASTER
            - OWNER
        acl_user_manager: null
    title: 'Sonata Admin'
    title_logo: bundles/sonataadmin/images/logo_title.png
    search: true
    default_controller: 'sonata.admin.controller.crud'
    options:
        html5_validate: true

        # Auto order groups and admins by label or id
        sort_admins: false
        confirm_exit: true
        js_debug: false
        skin: 'skin-black'
        use_select2: true
        use_icheck: true
        use_bootlint: false
        use_stickyforms: true
        pager_links: null
        form_type: 'standard' # One of "standard"; "horizontal"
        default_admin_route: show
        default_group: default
        default_translation_domain: SonataAdminBundle
        default_icon: 'fas fa-folder'
        dropdown_number_groups_per_colums:  2
        logo_content: 'all' # One of "text"; "icon"; "all"
        list_action_button_content: 'all' # One of "text"; "icon"; "all"

        # Enable locking when editing an object, if the corresponding object manager supports it.
        lock_protection: false
    dashboard:
        groups:

            # Prototype
            id:
                label: ~
                translation_domain: ~
                icon: ~
                provider: ~
                items:
                    admin: ~
                    label: ~
                    route: ~
                    route_params: []
                roles: []
        blocks:
            type: ~
            roles: []
            settings:

                # Prototype
                id: ~
            position: right
            class: col-md-4

    default_admin_services:
        model_manager: null
        data_source: null
        form_contractor: null
        show_builder: null
        list_builder: null
        datagrid_builder: null
        translator: null
        configuration_pool: null
        route_generator: null
        validator: null
        security_handler: null
        label: null
        menu_factory: null
        route_builder: null
        label_translator_strategy: null
        pager_type: null
```

--------------------------------

### Explain admin model

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/console.html

Prints configuration details for a specific admin service ID.

```bash
bin/console sonata:admin:explain sonata.news.admin.post
```

--------------------------------

### Configure ExampleAdmin

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/cookbook/recipe_data_mapper.html

Register the custom DataMapper within the Admin class to handle form data processing.

```php
// src/Admin/ExampleAdmin.php

namespace App\Admin;

use Sonata\AdminBundle\Admin\AbstractAdmin;
use Sonata\AdminBundle\Form\FormMapper;
use App\Form\DataMapper\ExampleDataMapper;

final class ExampleAdmin extends AbstractAdmin
{
    protected function configureFormFields(FormMapper $form): void
    {
        $form
            ->add('name', null)
            ->add('description', null);
        ;

        $builder = $form->getFormBuilder();
        $builder->setDataMapper(new ExampleDataMapper());
    }

    // ...
```

--------------------------------

### Create a custom Admin Extension

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/extensions.html

Implement AbstractAdminExtension and use the AutoconfigureTag attribute to target a specific admin service.

```php
namespace App\Admin\Extension;

use Sonata\AdminBundle\Admin\AbstractAdminExtension;
use Sonata\AdminBundle\Form\FormMapper;
use Symfony\Component\DependencyInjection\Attribute\AutoconfigureTag;

#[AutoconfigureTag(name: 'sonata.admin.extension', attributes: ['target' => 'sonata.page.admin.page'])]
final class PositionAdminExtension extends AbstractAdminExtension
{
    public function configureFormFields(FormMapper $form): void
    {
        $form->add('position');
    }
}
```

--------------------------------

### Configure List View Fields

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/action_list.html

Demonstrates how to apply visual configuration options like header styles, row alignment, and field collapsing within the configureListFields method.

```php
protected function configureListFields(ListMapper $list): void
{
    $list
        ->add('id', null, [
            'header_style' => 'width: 5%; text-align: center',
            'row_align' => 'center'
        ])
        ->add('name', FieldDescriptionInterface::TYPE_STRING, [
            'header_style' => 'width: 35%'
        ])
        ->add('description', FieldDescriptionInterface::TYPE_STRING, [
            'header_style' => 'width: 35%',
            'collapse' => true
        ])
        ->add('upvotes', null, [
            'label_icon' => 'fas fa-thumbs-up'
        ])
        ->add('actions', null, [
            'header_class' => 'customActions',
            'row_align' => 'right'
        ])
    ;
}
```

--------------------------------

### Global Admin Settings

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/configuration.html

Configure persistence, search, and breadcrumb behavior.

```yaml
persist_filters: false
filter_persister: sonata.admin.filter_persister.session
show_mosaic_button: true

global_search:
    empty_boxes: show
    admin_route: show

breadcrumbs:
    child_admin_route: show
```

--------------------------------

### Define Example Entity

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/cookbook/recipe_data_mapper.html

An entity class that uses a constructor and domain methods instead of standard setters.

```php
// src/Entity/Example.php

namespace App\Entity;

final class Example
{
    private string $name;

    private string $description;

    public function __construct(string $name, string $description)
    {
        $this->name = $name;
        $this->description = $description;
    }

    public function update(string $description)
    {
        $this->description = $description
    }

    // rest of the code goes here
}
```

--------------------------------

### Enable Bootlint in SonataAdminBundle

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/cookbook/recipe_bootlint.html

Configure the bundle to enable Bootlint by setting the use_bootlint option to true in your YAML configuration file.

```yaml
# config/packages/sonata_admin.yaml

sonata_admin:
    options:
        use_bootlint: true # enable Bootlint
```

--------------------------------

### Rendering Custom Controller Action

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/cookbook/recipe_custom_action.html

Example of rendering a custom controller action in Twig, requiring the _sonata_admin attribute.

```twig
{{ render(controller('App\\Controller\\XxxxCRUDController::comment', {'_sonata_admin': 'sonata.admin.xxxx' })) }}
```

--------------------------------

### Create a Custom Controller for Menu Items

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/cookbook/recipe_knp_menu.html

Define a controller with routes that will be referenced in the admin menu configuration.

```php
use Symfony\Component\HttpFoundation\Response;

final class BlogController
{
    /**
     * @Route("/blog", name="blog_home")
     */
    public function blogAction(): Response
    {
        // ...
    }

    /**
     * @Route("/blog/article/{articleId}", name="blog_article")
     */
    public function ArticleAction(string $articleId): Response
    {
        // ...
    }
}
```

--------------------------------

### Create Database Schema

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/getting_started/creating_an_admin.html

Executes the console command to generate the database schema based on the defined entities.

```bash
bin/console doctrine:schema:create
```

--------------------------------

### Child Admin Route Name Definition

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/routing.html

Example of a child Admin class inheriting and prefixing the parent route name.

```php
// src/Admin/CommentAdmin.php

// The child admin class
final class CommentAdmin extends AbstractAdmin
{
    protected function generateBaseRouteName(bool $isChildAdmin = false): string
    {
        return 'comment';
    }
    // will result in routes named :
    //   sonata_post_comment_list
    //   sonata_post_comment_create
    //   etc..

    // ...
}
```

--------------------------------

### Configure Security Firewalls and Access Control

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/security.html

Set up the security provider, firewall, and access control rules in security.yaml to secure the admin area.

```yaml
# config/packages/security.yaml

security:
    providers:
        sonata_user_bundle:
            id: sonata.user.security.user_provider

    firewalls:
        admin:
            pattern:      .*
            form-login:
                provider:       sonata_user_bundle
                login_path:     /login
                use_forward:    false
                check_path:     /login_check
                failure_path:   null
            logout:       true
            anonymous:    true

    access_control:

        # The WDT has to be allowed to anonymous users to avoid requiring the login with the AJAX request
        - { path: ^/wdt/, role: IS_AUTHENTICATED_ANONYMOUSLY }
        - { path: ^/profiler/, role: IS_AUTHENTICATED_ANONYMOUSLY }

        # AsseticBundle paths used when using the controller for assets
        - { path: ^/js/, role: IS_AUTHENTICATED_ANONYMOUSLY }
        - { path: ^/css/, role: IS_AUTHENTICATED_ANONYMOUSLY }

        # URL of SonataUserBundle which need to be available to anonymous users
        - { path: ^/login$, role: IS_AUTHENTICATED_ANONYMOUSLY }
        - { path: ^/login_check$, role: IS_AUTHENTICATED_ANONYMOUSLY } # for the case of a failed login
        - { path: ^/user/new$, role: IS_AUTHENTICATED_ANONYMOUSLY }
        - { path: ^/user/check-confirmation-email$, role: IS_AUTHENTICATED_ANONYMOUSLY }
        - { path: ^/user/confirm/, role: IS_AUTHENTICATED_ANONYMOUSLY }
        - { path: ^/user/confirmed$, role: IS_AUTHENTICATED_ANONYMOUSLY }
        - { path: ^/user/request-reset-password$, role: IS_AUTHENTICATED_ANONYMOUSLY }
        - { path: ^/user/send-resetting-email$, role: IS_AUTHENTICATED_ANONYMOUSLY }
        - { path: ^/user/check-resetting-email$, role: IS_AUTHENTICATED_ANONYMOUSLY }
        - { path: ^/user/reset-password/, role: IS_AUTHENTICATED_ANONYMOUSLY }

        # Secured part of the site
        # This config requires being logged for the whole site and having the admin role for the admin part.
        # Change these rules to adapt them to your needs
        - { path: ^/admin/, role: ROLE_ADMIN }
        - { path: ^/.*, role: IS_AUTHENTICATED_ANONYMOUSLY }

    # Sonata "special" roles (ROLE_SONATA_ADMIN and ROLE_SUPER_ADMIN) are configurable
    role_hierarchy:
        ROLE_ADMIN:       [ROLE_USER, ROLE_SONATA_ADMIN]
        ROLE_SUPER_ADMIN: [ROLE_ADMIN, ROLE_ALLOWED_TO_SWITCH]

    acl:
        connection: default
```

--------------------------------

### Implement ExampleDataMapper

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/cookbook/recipe_data_mapper.html

A custom DataMapper implementation to handle mapping form data to the entity and vice versa.

```php
// src/Form/DataMapper/ExampleDataMapper.php

namespace App\Form\DataMapper;

use Symfony\Component\Form\DataMapperInterface;
use App\Entity\Example;

final class ExampleDataMapper implements DataMapperInterface
{
    /**
     * @param Example $data
     * @param FormInterface[]|\Traversable $forms
     */
    public function mapDataToForms($data, $forms)
    {
        if (null !== $data) {
            $forms = iterator_to_array($forms);
            $forms['name']->setData($data->getName());
            $forms['description']->setData($data->getDescription());
        }
    }

    /**
     * @param FormInterface[]|\Traversable $forms
     * @param Example $data
     */
    public function mapFormsToData($forms, &$data)
    {
        $forms = iterator_to_array($forms);

        if (null === $data->getId()) {
            $name = $forms['name']->getData();
            $description = $forms['description']->getData();

            // New entity is created
            $data = new Example(
                $name,
                $description
            );
        } else {
            $data->update(
                $forms['description']->getData()
            );
        }
    }
}
```

--------------------------------

### Register Bundles in bundles.php

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/getting_started/installation.html

Enable the SonataAdminBundle and its dependencies in the project's configuration file.

```php
// config/bundles.php

return [
    // ...
    Symfony\Bundle\SecurityBundle\SecurityBundle::class => ['all' => true],
    Sonata\BlockBundle\SonataBlockBundle::class => ['all' => true],
    Knp\Bundle\MenuBundle\KnpMenuBundle::class => ['all' => true],
    Sonata\AdminBundle\SonataAdminBundle::class => ['all' => true],
    Sonata\Doctrine\Bridge\Symfony\SonataDoctrineBundle::class => ['all' => true],
    Sonata\Form\Bridge\Symfony\SonataFormBundle::class => ['all' => true],
    Sonata\Twig\Bridge\Symfony\SonataTwigBundle::class => ['all' => true],
    Symfony\UX\StimulusBundle\StimulusBundle::class => ['all' => true],
];
```

--------------------------------

### Create a super-admin user

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/security.html

Use this command to create a new user with super-admin privileges via the console.

```bash
bin/console sonata:user:create --super-admin
    Please choose a username:root
    Please choose an email:root@domain.com
    Please choose a password:root
    Created user root
```

--------------------------------

### Inspect Admin Routes via Console

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/routing.html

Use the console command to list all routes defined for a specific Admin service.

```bash
bin/console sonata:admin:explain <<admin.service.name>>
```

```bash
bin/console sonata:admin:explain app.admin.foo
```

--------------------------------

### Download SonataAdminBundle

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/getting_started/installation.html

Use Composer to add the SonataAdminBundle to your project dependencies.

```bash
composer require sonata-project/admin-bundle
```

--------------------------------

### Configure Admin Extensions

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/configuration.html

Define extension prototypes for global or specific admin services.

```yaml
extensions:

    # Prototype
    id:
        global: false
        admins: []
        excludes: []
        implements: []
        extends: []
        instanceof: []
        uses: []
        admin_implements: []
        admin_extends: []
        admin_instanceof: []
        admin_uses: []
```

--------------------------------

### Organize Show Fields with Groups and Tabs

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/getting_started/the_show_view.html

Uses tab and with methods to organize fields into visual groups and tabs within the show view.

```php
// src/Admin/BlogPostAdmin.php

protected function configureShowFields(ShowMapper $show): void
{
    $show
        ->tab('Post')
            ->with('Content', ['class' => 'col-md-9'])
                // ...
            ->end()
            ->with('Meta data', ['class' => 'col-md-3'])
                // ...
            ->end()
        ->end()

        ->tab('Publish Options')
            // ...
        ->end()
    ;
}
```

--------------------------------

### Manage Embedded Image Admin Lifecycles

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/cookbook/recipe_file_uploads.html

Implement prePersist and preUpdate in the parent Admin to manually trigger file management logic for embedded Image entities.

```php
// src/Admin/PostAdmin.php

final class PostAdmin extends AbstractAdmin
{
    public function prePersist(object $page): void
    {
        $this->manageEmbeddedImageAdmins($page);
    }

    public function preUpdate(object $page): void
    {
        $this->manageEmbeddedImageAdmins($page);
    }

    private function manageEmbeddedImageAdmins(object $page): void
    {
        // Cycle through each field
        foreach ($this->getFormFieldDescriptions() as $fieldName => $fieldDescription) {
            // detect embedded Admins that manage Images
            if ($fieldDescription->getType() === 'sonata_type_admin' &&
                ($associationMapping = $fieldDescription->getAssociationMapping()) &&
                $associationMapping['targetEntity'] === 'App\Entity\Image'
            ) {
                $getter = 'get'.$fieldName;
                $setter = 'set'.$fieldName;

                /** @var Image $image */
                $image = $page->$getter();

                if ($image) {
                    if ($image->getFile()) {
                        // update the Image to trigger file management
                        $image->refreshUpdated();
                    } elseif (!$image->getFile() && !$image->getFilename()) {
                        // prevent Sf/Sonata trying to create and persist an empty Image
                        $page->$setter(null);
                    }
                }
            }
        }
    }
}
```

--------------------------------

### Extend Admin Menu for Child Admins

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/child_admin.html

Implement the configureTabMenu method in the parent admin class to display links to child admin actions.

```php
namespace App\Admin;

use Knp\Menu\ItemInterface as MenuItemInterface;
use Sonata\AdminBundle\Admin\AbstractAdmin;
use Sonata\AdminBundle\Admin\AdminInterface;

final class PlaylistAdmin extends AbstractAdmin
{
    protected function configureTabMenu(MenuItemInterface $menu, string $action, ?AdminInterface $childAdmin = null): void
    {
        if (!$childAdmin && !in_array($action, ['edit', 'show'])) {
            return;
        }

        $admin = $this->isChild() ? $this->getParent() : $this;
        $id = $admin->getRequest()->get('id');

        $menu->addChild('View Playlist', $admin->generateMenuUrl('show', ['id' => $id]));

        if ($this->isGranted('EDIT')) {
            $menu->addChild('Edit Playlist', $admin->generateMenuUrl('edit', ['id' => $id]));
        }

        if ($this->isGranted('LIST')) {
            $menu->addChild('Manage Videos', $admin->generateMenuUrl('App\Admin\VideoAdmin.list', ['id' => $id]));
        }
    }
}
```

--------------------------------

### Implement the UserProvider

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/cookbook/recipe_sonata_admin_without_user_bundle.html

Create a custom UserProvider to load users from the database using Doctrine.

```php
namespace App\Security;

use App\Entity\User;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Component\Security\Core\User\UserInterface;
use Symfony\Component\Security\Core\User\UserProviderInterface;
use Symfony\Component\Security\Core\Exception\UsernameNotFoundException;

final class UserProvider implements UserProviderInterface
{
    private EntityManagerInterface $entityManager;

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

    public function loadUserByUsername($email): User
    {
        $user = $this->findOneUserBy(['email' => $email]);

        if (!$user) {
            throw new UsernameNotFoundException(
                sprintf(
                    'User with "%s" email does not exist.',
                    $email
                )
            );
        }

        return $user;
    }

    private function findOneUserBy(array $options): ?User
    {
        return $this->entityManager
            ->getRepository(User::class)
            ->findOneBy($options);
    }

    public function refreshUser(UserInterface $user): User
    {
        assert($user instanceof User);

        if (null === $reloadedUser = $this->findOneUserBy(['id' => $user->getId()])) {
            throw new UsernameNotFoundException(sprintf(
                'User with ID "%s" could not be reloaded.',
                $user->getId()
            ));
        }

        return $reloadedUser;
    }

    public function supportsClass($class): bool
    {
        return $class === User::class;
    }
}
```

--------------------------------

### Configure Global Preview Template

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/preview_mode.html

Override the default preview template globally using the sonata_admin configuration.

```yaml
# config/packages/sonata_admin.yaml

sonata_admin:
    templates:
        preview: '@App/CRUD/preview.html.twig'
```

--------------------------------

### Define a Batch Action Controller

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/batch_actions.html

Implement a custom batch action by creating a controller that accepts ProxyQueryInterface and AdminInterface. Ensure the controller is configured as a service with the controller.service_arguments tag.

```php
// src/Controller/MergeController.php

namespace App\Controller;

use Sonata\AdminBundle\Admin\AdminInterface;
use Sonata\AdminBundle\Datagrid\ProxyQueryInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpFoundation\Request;

class MergeController extends AbstractController
{
    public function batchMergeAction(ProxyQueryInterface $query, AdminInterface $admin): RedirectResponse
    {
        $admin->checkAccess('edit');
        $admin->checkAccess('delete');

        $modelManager = $admin->getModelManager();

        $target = $modelManager->find($admin->getClass(), $request->get('targetId'));

        if ($target === null) {
            $this->addFlash('sonata_flash_info', 'flash_batch_merge_no_target');

            return new RedirectResponse(
                $admin->generateUrl('list', [
                    'filter' => $admin->getFilterParameters()
                ])
            );
        }

        $selectedModels = $query->execute();

        // do the merge work here

        try {
            foreach ($selectedModels as $selectedModel) {
                $modelManager->delete($selectedModel);
            }

            $this->addFlash('sonata_flash_success', 'flash_batch_merge_success');
        } catch (\Exception $e) {
            $this->addFlash('sonata_flash_error', 'flash_batch_merge_error');
        } finally {
            return new RedirectResponse(
                $admin->generateUrl('list', [
                    'filter' => $admin->getFilterParameters()
                ])
            );
        }
    }

    // ...
}
```

--------------------------------

### Configure Form Group Options

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/action_create_edit.html

Demonstrates how to apply custom CSS classes and descriptions to a form group within the configureFormFields method.

```php
// src/Admin/PersonAdmin.php

final class PersonAdmin extends AbstractAdmin
{
    protected function configureFormFields(FormMapper $form): void
    {
        $form
            ->tab('General') // the tab call is optional
                ->with('Addresses', [
                    'class'       => 'col-md-8',
                    'box_class'   => 'box box-solid box-danger',
                    'description' => 'Lorem ipsum',
                    // ...
                ])
                    ->add('title')
                    // ...
                ->end()
            ->end()
        ;
    }
}
```

--------------------------------

### Configure Image Preview in Single-Layer Admin

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/cookbook/recipe_image_previews.html

Use this approach when working directly with an Admin class. It retrieves the subject via getSubject() and injects an HTML img tag into the field's help option.

```php
final class ImageAdmin extends AbstractAdmin
{
    protected function configureFormFields(FormMapper $form): void
    {
        // get the current Image instance
        $image = $this->getSubject();

        // use $fileFormOptions so we can add other options to the field
        $fileFormOptions = ['required' => false];
        if ($image && ($webPath = $image->getWebPath())) {
            // get the request so the full path to the image can be set
            $request = $this->getRequest();
            $fullPath = $request->getBasePath().'/'.$webPath;

            // add a 'help' option containing the preview's img tag
            $fileFormOptions['help'] = '<img src="'.$fullPath.'" class="admin-preview"/>';
            $fileFormOptions['help_html'] = true;
        }

        $form
            ->add('file', 'file', $fileFormOptions)
        ;
    }
}
```

--------------------------------

### Using AdminInterface for reusable actions

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/cookbook/recipe_decouple_crud_controller.html

Type-hint AdminInterface to create controller actions that are reusable across different Admin classes.

```php
// src/Controller/CarAdminController.php

namespace App\Controller;

use Sonata\AdminBundle\Admin\AdminInterface;
use Symfony\Component\HttpFoundation\RedirectResponse;

final class CloneAdminController
{
    public function clone(AdminInterface $admin, Request $request)
    {
        $object = $admin->getSubject();

        // ...

        $request->getSession()->getFlashBag()->add('sonata_flash_success', 'Cloned successfully');

        return new RedirectResponse($admin->generateUrl('list'));
    }
}
```

--------------------------------

### Enable Translator Service

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/getting_started/installation.html

Configure the framework translator service required for proper label display.

```yaml
# config/packages/framework.yaml

framework:
    translator: { fallbacks: ['%locale%'] }
```

--------------------------------

### Enable sortable feature in StofDoctrineExtensionsBundle

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/cookbook/recipe_sortable_listing.html

Alternative configuration for projects using the StofDoctrineExtensionsBundle.

```yaml
# config/packages/stof_doctrine_extensions.yaml

stof_doctrine_extensions:
    orm:
        default:
            sortable: true
```

--------------------------------

### Customizing Collapse Option

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/action_list.html

Shows how to provide an array to the collapse option to override default height and link text parameters.

```php
->add('description', TextType::class, [
    'header_style' => 'width: 35%',
    'collapse' => [
        // height in px
        'height' => 40,

        // content of the "read more" link
        'more' => 'I want to see the full description',

         // content of the "read less" link
        'less' => 'This text is too long, reduce the size',
    ]
])
```

--------------------------------

### Import and Initialize jQuery UI Plugins

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/cookbook/recipe_jquery_ui.html

Import the specific jQuery UI widgets needed and initialize them on your DOM elements.

```javascript
// assets/js/sonata.js

import $ from 'jquery';

import 'jquery-ui/ui/widget';
import 'jquery-ui/ui/widgets/draggable';

$('.foo').draggable(); // The new UI plugin can be used.
$('.bar').sortable(); // The already loaded by sonata plugin can be used too.
```

--------------------------------

### Configure show group options

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/action_show.html

Specify layout and display options for groups within the show page using the ShowMapper.

```php
// src/Admin/PersonAdmin.php

use Sonata\AdminBundle\Admin\AbstractAdmin;
use Sonata\AdminBundle\Show\ShowMapper;

final class PersonAdmin extends AbstractAdmin
{
    protected function configureShowFields(ShowMapper $show): void
    {
        $show
            ->tab('General') // the tab call is optional
                ->with('Addresses', [
                    'class'       => 'col-md-8',
                    'box_class'   => 'box box-solid box-danger',
                    'description' => 'Lorem ipsum',
                ])
                    ->add('title')
                    // ...
                ->end()
            ->end()
        ;
    }
}
```

--------------------------------

### Configure Show Fields in Admin Class

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/action_show.html

Defines the fields to be displayed in the show view using the ShowMapper.

```php
// src/Admin/PostAdmin.php

use Sonata\AdminBundle\Show\ShowMapper;

final class ClientAdmin extends AbstractAdmin
{
    protected function configureShowFields(ShowMapper $show): void
    {
        // here we set the fields of the ShowMapper variable,
        // $show (but this can be called anything)
        $show

             // The default option is to display the value
             // as text (for boolean this will be 1 or 0)
            ->add('name')
            ->add('phone')
            ->add('email')

             // The boolean option is actually very cool
             // true   shows a check mark and the 'yes' label
             // false  shows a check mark and the 'no' label
            ->add('dateCafe', FieldDescriptionInterface::TYPE_BOOLEAN)
            ->add('datePub', FieldDescriptionInterface::TYPE_BOOLEAN)
            ->add('dateClub', FieldDescriptionInterface::TYPE_BOOLEAN)
        ;

    }
}
```

--------------------------------

### Configure List Fields and Actions

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/action_list.html

Define columns, field types, editable properties, and custom actions within the configureListFields method.

```php
// ...

protected function configureListFields(ListMapper $list): void
{
    $list
        // addIdentifier allows to specify that this column
        // will provide a link to the entity
        // (edit or show route, depends on your access rights)
        ->addIdentifier('name')

        // you may specify the field type directly as the
        // second argument instead of in the options
        ->add('isVariation', FieldDescriptionInterface::TYPE_BOOLEAN)

        // if null, the type will be guessed
        ->add('enabled', null, [
            'editable' => true
        ])

        // editable association field
        ->add('status', FieldDescriptionInterface::TYPE_CHOICE, [
            'editable' => true,
            'class' => 'Vendor\ExampleBundle\Entity\ExampleStatus',
            'choices' => [
                1 => 'Active',
                2 => 'Inactive',
                3 => 'Draft',
            ],
        ])

        // editable multiple field
        ->add('winner', FieldDescriptionInterface::TYPE_CHOICE, [
            'editable' => true,
            'multiple' => true,
            'choices' => [
                'jury' => 'Jury',
                'voting' => 'Voting',
                'encouraging' => 'Encouraging',
            ],
        ])

        // we can add options to the field depending on the type
        ->add('price', FieldDescriptionInterface::TYPE_CURRENCY, [
            'currency' => $this->currencyDetector->getCurrency()->getLabel()
        ])

        // Here we specify which property is used to render the label of each entity in the list
        ->add('productCategories', null, [
            'associated_property' => 'name'
            // By default, sorting will be done on the associated property.
            // To sort on another property, add the following:
            'sort_field_mapping' => [
                'fieldName' => 'weight',
            ],
        ])

        // you may also use dotted-notation to access
        // specific properties of a relation to the entity
        ->add('image.name')

        // you may also use a custom accessor
        ->add('description1', null, [
            'accessor' => 'description'
        ])
        ->add('description2', null, [
            'accessor' => function ($subject) {
                return $this->customService->formatDescription($subject);
            }
        ])

        // You may also specify the actions you want to be displayed in the list
        ->add(ListMapper::NAME_ACTIONS, null, [
            'actions' => [
                'show' => [],
                'edit' => [
                    // You may add custom link parameters used to generate the action url
                    'link_parameters' => [
                        'full' => true,
                    ]
                ],
                'delete' => [],
            ]
        ])

    ;
}
```

--------------------------------

### Implement Dynamic Filtering with callback

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/form_types.html

Implement a prefix-based filtering system within the callback to allow users to specify the property to filter on dynamically.

```php
$form
    ->add('category', ModelAutocompleteType::class, [
        'property' => 'title',
        'callback' => static function (AdminInterface $admin, string $property, string $value): void {
            $datagrid = $admin->getDatagrid();

            $valueParts = explode(':', $value);
            if (count($valueParts) === 2 && in_array($valueParts[0], ['id', 'email', 'username'])) {
                [$property, $value] = $valueParts;
            }

            $datagrid->setValue($datagrid->getFilter($property)->getFormName(), null, $value);
        },
    ])
;
```

--------------------------------

### Enable Preview Mode in Admin Class

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/preview_mode.html

Set the $supportsPreviewMode property to true within your Admin class to enable the preview button.

```php
// src/AdminPostAdmin.php

final class PostAdmin extends AbstractAdmin
{
    public $supportsPreviewMode = true;
}
```

--------------------------------

### Create a Menu Listener

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/cookbook/recipe_knp_menu.html

Implement an event listener to add custom items to the sidebar menu via the sonata.admin.event.configure.menu.sidebar event.

```php
// src/EventListener/MenuBuilderListener.php

namespace App\EventListener;

use Sonata\AdminBundle\Event\ConfigureMenuEvent;

final class MenuBuilderListener
{
    public function addMenuItems(ConfigureMenuEvent $event): void
    {
        $menu = $event->getMenu();

        $child = $menu->addChild('reports', [
            'label' => 'Daily and monthly reports',
            'route' => 'app_reports_index',
        ])->setExtras([
            'icon' => 'fas fa-bar-chart', // html is also supported
        ]);
    }
}
```

--------------------------------

### Simulating multi-field sorting

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/action_list.html

Combine configureDefaultSortValues with multiple addOrderBy calls in configureQuery to simulate sorting by multiple fields.

```php
// src/Admin/PostAdmin.php

use Sonata\AdminBundle\Admin\AbstractAdmin;
use Sonata\AdminBundle\Datagrid\DatagridInterface;

final class PostAdmin extends AbstractAdmin
{
    // ...

    protected function configureDefaultSortValues(array &$sortValues): void
    {
        // display the first page (default = 1)
        $sortValues[DatagridInterface::PAGE] = 1;

        // reverse order (default = 'ASC')
        $sortValues[DatagridInterface::SORT_ORDER] = 'DESC';

        // name of the ordered field (default = the model's id field, if any)
        $sortValues[DatagridInterface::SORT_BY] = 'updatedAt';
    }

    protected function configureQuery(ProxyQueryInterface $query): ProxyQueryInterface
    {
        $rootAlias = current($query->getRootAliases());

        $query->addOrderBy($rootAlias.'.author', 'ASC');
        $query->addOrderBy($rootAlias.'.createdAt', 'ASC');

        return $query;
    }

    // ...
}
```

--------------------------------

### Configure Admin Service with Custom Label Strategy

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/architecture.html

Demonstrates overriding the default label translator strategy for an Admin service using setter injection.

```yaml
services:
    app.admin.post:
        class: App\Admin\PostAdmin
        calls:
            - [setLabelTranslatorStrategy, ['@sonata.admin.label.strategy.underscore']]
        tags:
            - { name: sonata.admin, model_class: App\Entity\Post, manager_type: orm, group: 'Content', label: 'Post' }
```

--------------------------------

### Implement Custom SecurityHandler

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/advanced_configuration.html

Create a custom security handler by implementing the SecurityHandlerInterface to define bespoke access logic.

```php
// src/Security/Handler/CustomSecurityHandler.php

use Sonata\AdminBundle\Security\Handler\SecurityHandlerInterface;

final class CustomSecurityHandler implements SecurityHandlerInterface
{
    public function isGranted(AdminInterface $admin, $attributes, ?object $object = null): bool
    {
        return $this->customAccessLogic();
    }

    public function getBaseRole(AdminInterface $admin): string
    {
        return '';
    }

    public function buildSecurityInformation(AdminInterface $admin): array
    {
        return [];
    }

    public function createObjectSecurity(AdminInterface $admin, object $object): void
    {
    }

    public function deleteObjectSecurity(AdminInterface $admin, object $object): void
    {
    }
}
```

--------------------------------

### List available admin services

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/console.html

Displays all registered admin service IDs from the sonata.admin.pool.

```bash
bin/console sonata:admin:list
```

--------------------------------

### Configure Symfony Workflow

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/cookbook/recipe_workflow_integration.html

Define the state machine workflow for the BlogPost entity in the framework configuration.

```yaml
# config/packages/workflow.yaml

framework:
    workflows:
        blog_post:
            type: state_machine
            marking_store:
                type: single_state
                arguments:
                    - status
            supports:
                - App\Entity\BlogPost
            places:
                - draft
                - pending_review
                - pending_update
                - published
            initial_place: draft
            transitions:
                start_review:
                    from: draft
                    to:   pending_review
                interrupt_review:
                    from: pending_review
                    to:   pending_update
                restart_review:
                    from: pending_update
                    to:   pending_review
                publish:
                    from: pending_review
                    to:   published
```

--------------------------------

### Define Admin Service Dependencies via Method Call

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/advanced_configuration.html

Use the method call approach for a more explicit configuration of Admin service dependencies.

```yaml
# config/services.yaml

app.admin.project:
    class: App\Admin\ProjectAdmin
    calls:
        - [setLabelTranslatorStrategy, ['@sonata.admin.label.strategy.native']]
        - [setRouteBuilder, ['@sonata.admin.route.path_info']]
    tags:
        - { name: sonata.admin, model_class: App\Entity\Project, manager_type: orm, group: 'Project', label: 'Project' }
```

--------------------------------

### Configure label strategy in services.xml

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/reference/translation.html

Configures the label translator strategy for an Admin service registration.

```xml
<!-- config/services.xml -->

<service id="app.admin.project" class="App\Admin\ProjectAdmin">
    <tag
        name="sonata.admin"
        model_class="App\Entity\Project"
        manager_type="orm"
        group="Project"
        label="Project"
        label_translator_strategy="sonata.admin.label.strategy.native"
        />
</service>
```

--------------------------------

### Register Admin class as a service

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/getting_started/creating_an_admin.html

Define the Admin class as a service in your configuration file and apply the sonata.admin tag to register it with the bundle.

```yaml
# config/services.yaml

services:
    # ...
    admin.category:
        class: App\Admin\CategoryAdmin
        tags:
            - { name: sonata.admin, model_class: App\Entity\Category, manager_type: orm, label: Category }
```

--------------------------------

### Register a menu provider as a service

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/cookbook/recipe_knp_menu.html

Define a custom menu provider as a service with the knp_menu.menu tag to use it in the configuration.

```xml
<service id="my_menu_provider" class="MyBundle/MyDirectory/MyMenuProvider">
    <tag name="knp_menu.menu" alias="my_menu_alias"/>
</service>
```

--------------------------------

### Configure the Admin service

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/getting_started/the_form_view.html

Service definition for registering the BlogPostAdmin class with the required sonata.admin tag.

```yaml
# config/services.yaml

services:
    admin.blog_post:
        class: App\Admin\BlogPostAdmin
        tags:
            - { name: sonata.admin, model_class: App\Entity\BlogPost, manager_type: orm, label: 'Blog post' }
```

--------------------------------

### Configure Image Preview in Embedded Admin

Source: https://symfony.com/bundles/SonataAdminBundle/5.x/cookbook/recipe_image_previews.html

Use this approach when the Admin is embedded within another Admin. It detects the parent field description to retrieve the correct image instance.

```php
final class ImageAdmin extends AbstractAdmin
{
    protected function configureFormFields(FormMapper $form): void
    {
        if($this->hasParentFieldDescription()) { // this Admin is embedded
            // $getter will be something like 'getlogoImage'
            $getter = 'get' . $this->getParentFieldDescription()->getFieldName();

            // get hold of the parent object
            $parent = $this->getParentFieldDescription()->getAdmin()->getSubject();
            if ($parent) {
                $image = $parent->$getter();
            } else {
                $image = null;
            }
        } else {
            $image = $this->getSubject();
        }

        // use $fileFormOptions so we can add other options to the field
        $fileFormOptions = ['required' => false];
        if ($image && ($webPath = $image->getWebPath())) {
            // add a 'help' option containing the preview's img tag
            $fileFormOptions['help'] = '<img src="'.$webPath.'" class="admin-preview"/>';
            $fileFormOptions['help_html'] = true;
        }

        $form
            ->add('file', 'file', $fileFormOptions)
        ;
    }
}
```
Tokens:
Raw