Sonata Admin Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation via Symlink (as per README):

   mkdir -p src/Awaresoft
   git clone https://github.com/awaresoft/SonataAdminBundle.git src/Awaresoft/SonataAdminBundle
   

   Ensure composer.json excludes the package from vendor installation (remove from require/require-dev).

2. Enable Bundle in config/bundles.php:

   return [
       // ...
       Awaresoft\SonataAdminBundle\SonataAdminBundle::class => ['all' => true],
   ];
   

3. Configure Database (if using Doctrine):

   php bin/console doctrine:database:create
   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

4. First Admin CRUD:

   php bin/console sonata:admin:generate:crud --entity=App\Entity\YourEntity --format=yml --dest=config/sonata_admin
   

   Register the admin in config/packages/sonata_admin.yaml:

   sonata_admin:
       options:
           models_namespace: App\Entity
           admin_code_generator_template: 'twig:SonataAdminBundle:CRUD:base_admin_class.html.twig'
       managers:
           app:
               class: SonataAdminBundle\Admin\ORM\SonataAdminORMManager
               entity_directories: [App\Entity]
   

5. Clear Cache:

   php bin/console cache:clear
   

First Use Case: Quick Admin Panel

• Goal: Create a dashboard for managing User entities.
• Steps:
  1. Generate CRUD:

     php bin/console sonata:admin:generate:crud --entity=App\Entity\User --format=yml
     

  2. Customize the YAML (e.g., config/sonata_admin/user_admin.yml):

     sonata_admin:
         app.admin.user:
             class: App\Admin\UserAdmin
             arguments:
                 - ~
                 - App\Entity\User
                 - SonataAdminBundle:CRUD
             tags:
                 - { name: sonata.admin, manager_type: orm, group: Users, label: User }
     

  3. Extend the admin class (src/Admin/UserAdmin.php):

     namespace App\Admin;
     use Sonata\AdminBundle\Admin\AbstractAdmin;
     use Sonata\AdminBundle\Datagrid\DatagridMapper;
     use Sonata\AdminBundle\Form\FormMapper;
     
     class UserAdmin extends AbstractAdmin {
         protected function configureDatagridFilters(DatagridMapper $filter) {
             $filter->add('name');
         }
         protected function configureFormFields(FormMapper $form) {
             $form->add('name');
         }
     }
     

  4. Access /admin/app_user in your browser.

Implementation Patterns

Core Workflows

1. Admin Generation:

   • Use sonata:admin:generate:crud for boilerplate (avoid manual CRUD creation).
   • Customize via YAML or PHP admin classes (prefer PHP for complex logic).

2. Entity Integration:

   • Step 1: Ensure your entity has:
     • id (primary key).
     • createdAt/updatedAt (if using timestamps).
     • Getters/setters for all fields.
   • Step 2: Generate admin:

     php bin/console sonata:admin:generate:crud --entity=App\Entity\Product --format=php
     

   • Step 3: Override methods in the generated admin class (e.g., prePersist(), postUpdate()).

3. Grouping Admins:

   • Organize admins into logical groups in YAML:

     sonata_admin:
         managers:
             app:
                 group: [Users, Products, Settings]
     

4. Field Customization:

   • Use configureFormFields() for form layout:

     $form->add('name', TextType::class, ['label' => 'Full Name']);
     $form->add('isActive', CheckboxType::class, ['required' => false]);
     

   • Use configureListFields() for list views:

     $list->add('name', 'string', ['template' => 'SonataAdminBundle:CRUD:base_list_field.html.twig']);
     

5. Permissions:

   • Secure routes via security.yaml:

     access_control:
         - { path: ^/admin/, roles: ROLE_ADMIN }
     

   • Use isGranted() in admin classes:

     public function isAccessible() {
         return $this->getConfigurationPool()->getContainer()->get('security.authorization_checker')->isGranted('ROLE_ADMIN');
     }
     

Integration Tips

1. Doctrine Extensions:

   • Enable stof/doctrine-extensions-bundle for soft deletes, timestamps, etc.:

     # config/packages/doctrine.yaml
     doctrine:
         orm:
             filters:
                 softdeleteable:
                     class: Gedmo\SoftDeleteable\Filter\SoftDeleteableFilter
                     enabled: true
     

2. Twig Templates:

   • Override default templates in templates/SonataAdminBundle/:

     {# templates/SonataAdminBundle/CRUD/base_list_field.html.twig #}
     {% extends 'SonataAdminBundle:CRUD:base_list_field.html.twig' %}
     {% block field %}{{ value|upper }}{% endblock %}
     

3. API Integration:

   • Use sonata-project/google-maps-bundle for maps or sonata-project/easy-extends-bundle for dynamic fields.

4. Event Listeners:

   • Attach listeners to admin events (e.g., sonata.admin.post_persist):

     // src/EventListener/AdminListener.php
     namespace App\EventListener;
     use Sonata\AdminBundle\Event\ConfigureEvent;
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
     
     class AdminListener implements EventSubscriberInterface {
         public static function getSubscribedEvents() {
             return [
                 'sonata.admin.configure', // Fires before admin config
             ];
         }
         public function onConfigure(ConfigureEvent $event) {
             $event->getAdmin()->setTemplate('edit', 'AppBundle:Admin:edit.html.twig');
         }
     }
     

5. Batch Actions:

   • Enable in YAML:

     sonata_admin:
         app.admin.product:
             batch_actions: ['delete']
     

   • Customize in PHP:

     protected function configureBatchActions(DatagridMapper $datagrid) {
         $datagrid->add('delete', null, ['label' => 'Delete']);
     }
     

Gotchas and Tips

Pitfalls

1. Symlink Issues:

   • Problem: Forgetting to remove the package from vendor/ or update autoload_psr4.php.
   • Fix: Run composer dump-autoload after symlinking.

2. Cache Dependencies:

   • Problem: Changes to admin classes/templates not reflecting.
   • Fix: Clear cache and debug cache:

     php bin/console cache:clear
     php bin/console debug:cache:clear
     

3. Doctrine Migrations:

   • Problem: Sonata’s default migrations may conflict with custom entities.
   • Fix: Disable Sonata migrations and manage schema manually:

     # config/packages/doctrine.yaml
     doctrine:
         orm:
             auto_generate_proxy_classes: false
     

4. Permission Denied:

   • Problem: Admins not accessible despite ROLE_ADMIN.
   • Fix: Ensure:
     • User has ROLE_ADMIN in security.yaml.
     • sonata.admin.security.handler is configured:

       sonata_admin:
           security:
               handler: sonata.admin.security.handler.role
       

5. YAML vs. PHP Conflicts:

   • Problem: YAML and PHP admin configurations override each other unpredictably.
   • Fix: Prefer PHP for complex logic; use YAML for simple overrides.

Debugging

1. Enable Debug Mode:

   # config/packages/dev/sonata_admin.yaml
   sonata_admin:
       debug: true
   

2. Log Admin Events:

   • Use sonata.admin.event in monolog config:

     monolog:
         handlers:
             sonata_admin:
                 type: stream
                 path: "%kernel.logs_dir%/sonata_admin.log"
                 level: debug
                 channels: ["sonata_admin"]
     

3. Check SQL Queries:

   • Enable Doctrine profiling:

     php bin/console debug:container sonata.admin.orm.profiler
     

Extension Points

1. Custom Admin Services:
   • Register a custom admin service: