Admin Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require ekyna/admin-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Ekyna\AdminBundle\EkynaAdminBundle::class => ['all' => true],
   ];
   

2. Basic Configuration Define a minimal config/packages/ekyna_admin.yaml:

   ekyna_admin:
       menu:
           - { label: 'Dashboard', route: 'dashboard' }
       resources:
           App\Entity\User:
               controller: 'Ekyna\AdminBundle\Controller\AdminController::indexAction'
               template: '@EkynaAdmin/CRUD/index.html.twig'
   

3. First Use Case Create a simple admin route in routes.yaml:

   ekyna_admin:
       resource: '@EkynaAdminBundle/Resources/config/routing.yml'
       prefix: /admin
   

   Access /admin to see the generated menu and resource listing.

Implementation Patterns

Core Workflows

1. Resource Management

   • Define entities in ekyna_admin.resources config:

     resources:
         App\Entity\Product:
             controller: 'App\Controller\Admin\ProductController'
             template: 'admin/product/index.html.twig'
             actions:
                 - { name: 'index', label: 'List' }
                 - { name: 'new', label: 'Create' }
     

   • Extend Ekyna\AdminBundle\Controller\AdminController for custom logic.

2. Menu Customization

   • Group routes hierarchically:

     menu:
         - { label: 'Products', route: 'ekyna_admin_product_index' }
           children:
               - { label: 'Categories', route: 'ekyna_admin_category_index' }
     

   • Dynamically hide entries via isGranted() checks in Twig:

     {% if is_granted('ROLE_ADMIN') %}
         {{ render(ekyna_admin.menu_item('ekyna_admin_product_index')) }}
     {% endif %}
     

3. Template Overrides

   • Override default templates in templates/admin/:

     resources:
         App\Entity\User:
             template: 'admin/user/custom_index.html.twig'
     

4. Form Handling

   • Use Ekyna\AdminBundle\Form\Type\AdminType for entity forms:

     $builder->add('name', TextType::class, ['label' => 'Product Name']);
     

Integration Tips

• Symfony Security: Leverage VOTER for granular permissions:

  security:
      access_control:
          - { path: ^/admin/product, roles: ROLE_PRODUCT_MANAGER }
  

• Doctrine: Ensure entities are mapped and use Ekyna\AdminBundle\Repository\AdminRepository for queries.
• Translation: Use ekyna_admin.translation_domain in config for i18n support.

Gotchas and Tips

Pitfalls

1. Deprecated Practices

   • The bundle lacks modern Symfony (5.4+) compatibility. Expect deprecation warnings for:
     • Symfony\Component\HttpFoundation\Request (use Symfony\Component\HttpFoundation\RequestStack).
     • Legacy Twig extensions (migrate to Twig\Extension).

2. Configuration Overrides

   • Null Config: The bundle does not handle null values gracefully. Always provide defaults:

     resources:
         App\Entity\Post:
             template: ~  # Explicitly set to null if unused
     

   • Menu Group References: Hardcoded group names (e.g., main) may break if not defined. Use absolute routes instead.

3. Class Existence Checks

   • Pool Configurations: Verify Ekyna\AdminBundle\Pool\AdminPool classes exist before use. Override via:

     ekyna_admin:
           pool:
               class: 'App\Admin\CustomAdminPool'
     

4. Resource Context

   • Request Scope: The bundle lacks built-in request scoping. Manually inject RequestStack:

     public function __construct(RequestStack $requestStack) {
         $this->request = $requestStack->getCurrentRequest();
     }
     

5. Error Handling

   • Resource Not Found: Customize Ekyna\AdminBundle\Exception\ResourceNotFoundException in a global exception handler:

     public function onKernelException(GetResponseForExceptionEvent $event) {
         $exception = $event->getThrowable();
         if ($exception instanceof ResourceNotFoundException) {
             return new Response('Custom 404', 404);
         }
     }
     

6. Frontend Quirks

   • No Script Alerts: The bundle disables JavaScript alerts by default. Use addFlash() for notifications:

     $this->addFlash('success', 'Product saved!');
     

Debugging Tips

• Enable Debug Mode: Set EKYNA_ADMIN_DEBUG: true in .env for detailed logs.
• Dump Config: Use Symfony’s container.getParameter('ekyna_admin') to inspect loaded config.
• Twig Debugging: Extend Ekyna\AdminBundle\Twig\AdminExtension for custom helpers:

  {{ dump(ekyna_admin.getResourceConfig('App\Entity\User')) }}
  

Extension Points

1. Custom Controllers Extend Ekyna\AdminBundle\Controller\AdminController and override methods like configure():

   public function configure() {
       $this->menu->addChild('custom', ['route' => 'custom_route']);
   }
   

2. Event Listeners Subscribe to ekyna_admin.resource.load events:

   public function onResourceLoad(ResourceLoadEvent $event) {
       $event->setTemplate('custom/template.html.twig');
   }
   

3. Form Type Extensions Override field types in config/packages/ekyna_admin.yaml:

   ekyna_admin:
       form_types:
           App\Entity\User:
               - { name: 'email', type: 'Symfony\Component\Form\Extension\Core\Type\EmailType' }