Admin Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require elao/admin-bundle
   

   Register the bundle in AppKernel.php and import routing in routing.yml as shown in the README.

2. Define a Model: Ensure your model (e.g., User) is a Doctrine entity with proper annotations/repositories.

3. Configure an Admin: Create a YAML configuration file (e.g., app/config/admin.yml) to define actions for your model:

   elao_admin:
       models:
           App\Entity\User:
               actions:
                   list: ~
                   create: ~
                   edit: { route_parameters: { id: id } }
                   delete: ~
   

4. First Use Case: Access /users (or your prefixed route) to see a generated list of users. The bundle auto-registers routes like /users, /users/create, /users/{id}/edit, etc.

Implementation Patterns

Core Workflow

1. Action Definition: Define actions (e.g., list, create, edit, delete) in admin.yml for each model. Use built-in actions or extend them:

   actions:
       custom_action:
           class: App\Admin\Action\CustomAction
           arguments: [@service_id]
   

2. Template Overrides: Override default templates by placing them in templates/ElaoAdminBundle/[ActionName]/[template].html.twig. Example:

   templates/ElaoAdminBundle/List/list.html.twig
   

3. Dynamic Routing: Leverage the bundle’s auto-routing. For a model App\Entity\Post, routes like /posts/{id}/publish are auto-generated if publish is defined in actions.

4. Service Integration: Inject services into actions via arguments in YAML or constructor binding:

   actions:
       export:
           class: App\Admin\Action\ExportAction
           arguments: [@doctrine.orm.entity_manager, @some_service]
   

5. Batch Actions: Use the batch action for bulk operations (e.g., delete, export):

   actions:
       batch_delete: ~
   

Integration Tips

• Doctrine Integration: The bundle assumes Doctrine ORM. Ensure your entities have proper id fields and repositories.
• Security: Use Symfony’s security voters or override isGranted() in custom actions:

  public function isGranted($attribute, $object = null)
  {
      return $this->security->isGranted('ROLE_ADMIN');
  }
  

• Event Listeners: Attach listeners to actions for pre/post hooks:

  actions:
      create:
          listeners:
              - App\EventListener\UserCreateListener
  

• Form Types: Extend Elao\Bundle\AdminBundle\Form\Type\AdminType for custom forms:

  class UserType extends AdminType
  {
      public function buildForm(FormBuilderInterface $builder, array $options)
      {
          $builder->add('name');
      }
  }
  

  Configure in YAML:

  actions:
      edit:
          form_type: App\Form\Type\UserType
  

Gotchas and Tips

Pitfalls

1. Outdated Package: The bundle is archived (last release: 2017). Test thoroughly in your environment, especially with newer Symfony/Laravel versions (though this is Symfony-specific). Consider forking if critical bugs arise.

2. Routing Conflicts: Prefix routes in routing.yml to avoid clashes with other bundles:

   prefix: /admin
   

   Otherwise, /users may conflict with FOSUserBundle or other routes.

3. Action Configuration Overrides: YAML configuration is merged, so later definitions override earlier ones. Order matters:

   # app/config/admin.yml
   models:
       App\Entity\User:
           actions:
               list: { template: "custom_list.html.twig" }
   

4. Template Inheritance: Overriding templates requires exact directory structure. Misplaced templates (e.g., templates/ElaoAdminBundle/List/list.html.twig vs. templates/bundles/elaoadmin/list.html.twig) will fail silently.

5. Doctrine Proxy Issues: If using proxies, ensure your actions handle lazy-loading properly. Example:

   public function preExecute()
   {
       $this->getObject()->load(); // Force load if needed
   }
   

Debugging

1. Route Debugging: Use Symfony’s debug:router command to verify auto-generated routes:

   php bin/console debug:router | grep elao_admin
   

2. Action Debugging: Enable debug mode (APP_DEBUG=true) to see action instantiation errors. Check var/log/dev.log for YAML parsing issues.

3. Event Listener Debugging: Add logging in listeners to trace execution:

   public function onPreAction()
   {
       $this->logger->debug('Action executed for object:', ['id' => $this->getObject()->getId()]);
   }
   

Extension Points

1. Custom Actions: Extend Elao\Bundle\AdminBundle\Action\AbstractAction for reusable logic:

   class ExportAction extends AbstractAction
   {
       protected function execute()
       {
           // Custom logic
       }
   }
   

2. Dynamic Action Configuration: Use PHP callbacks in YAML for dynamic action setup:

   actions:
       custom:
           class: App\Admin\Action\DynamicAction
           arguments: ["%kernel.root_dir%/config/dynamic_actions.php"]
   

3. Model-Specific Logic: Override getModelClass() in custom actions to support polymorphic behavior:

   public function getModelClass()
   {
       return $this->getRequest()->attributes->get('model_class');
   }
   

4. Asset Management: Override CSS/JS by extending the bundle’s assets:

   {% block elao_admin_stylesheets %}
       {{ parent() }}
       <link rel="stylesheet" href="{{ asset('bundles/elaoadmin/custom.css') }}">
   {% endblock %}
   

Configuration Quirks

• Empty Actions: Omitting an action (e.g., delete: ~) disables it entirely. Explicitly define all actions you need.
• Route Parameters: Use route_parameters to customize route paths:

  actions:
      edit: { route_parameters: { _route: 'app_user_edit' } }
  

• Translation Domains: Actions use ElaoAdminBundle as the default translation domain. Override in YAML:

  actions:
      list: { translation_domain: 'messages' }