Admin Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require admin-platform/admin-bundle "dev-master"
   

   Note: Use "dev-master" only for testing; pin to a stable version in production.

2. Enable the Bundle Add to config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 3):

   return [
       // ...
       Platform\Bundle\AdminBundle\PlatformAdminBundle::class => ['all' => true],
   ];
   

3. First Use Case: CRUD for an Entity

   • Create a resource configuration (e.g., config/admin/resources/my_entity.yaml):

     resources:
         my_entity:
             driver: orm
             entity: App\Entity\MyEntity
             grid:
                 fields:
                     - { property: 'id', type: 'string' }
                     - { property: 'name', type: 'string' }
             form:
                 fields:
                     name: ~
     

   • Clear cache:

     php bin/console cache:clear
     

   • Access /admin/my_entity to see the auto-generated admin panel.

Where to Look First

• Documentation: Check the Sylius AdminBundle docs (since this bundle builds on Sylius components).
• Configuration: Focus on config/admin/resources/*.yaml for entity-specific admin panels.
• Templates: Override default templates in templates/admin/ (see Symfony templating).

Implementation Patterns

Core Workflows

1. Entity Admin Panels

   • Grid Configuration: Define columns, filters, and actions in YAML:

     grid:
         fields:
             - { property: 'createdAt', type: 'datetime', label: 'Created At' }
         filters:
             - { type: 'string', property: 'name', label: 'Name' }
         actions:
             - { type: 'edit' }
             - { type: 'delete' }
     

   • Form Fields: Customize forms with validation and field types:

     form:
         fields:
             name:
                 type: 'Symfony\Component\Form\Extension\Core\Type\TextType'
                 options:
                     attr:
                         placeholder: 'Enter name'
     

2. Reusing Components

   • Extend existing admin panels by merging configurations:

     imports:
         - { resource: '@PlatformAdminBundle/Resources/config/admin/resources/base_crud.yaml' }
     

3. Event Listeners

   • Hook into admin events (e.g., pre_update, post_create) via Symfony’s event system:

     // src/EventListener/MyEntityListener.php
     class MyEntityListener implements EventSubscriberInterface
     {
         public static function getSubscribedEvents()
         {
             return [
                 AdminEvents::PRE_UPDATE => 'onPreUpdate',
             ];
         }
     
         public function onPreUpdate(AdminUpdateEvent $event): void
         {
             $entity = $event->getSubject();
             // Modify entity before save
         }
     }
     

4. Custom Actions

   • Add custom buttons/links to grids:

     grid:
         actions:
             - { type: 'custom', label: 'Export', route: 'admin_my_entity_export', icon: 'download' }
     

Integration Tips

• Symfony Security: Use ROLE_ADMIN or custom roles to restrict access:

  # config/packages/security.yaml
  access_control:
      - { path: ^/admin, roles: ROLE_ADMIN }
  

• Translation: Override translations in translations/admin.en.yaml:

  admin:
      my_entity:
          name: 'Custom Name Field'
  

• Assets: Publish bundle assets for customization:

  php bin/console assets:install
  

  Override CSS/JS in web/bundles/platformadmin/.

Gotchas and Tips

Pitfalls

1. Cache Dependencies

   • Issue: Changes to YAML configs may not reflect immediately.
   • Fix: Clear cache after config changes:

     php bin/console cache:clear
     

   • Pro Tip: Use debug:config to verify loaded configs:

     php bin/console debug:config platform_admin
     

2. Entity Metadata Conflicts

   • Issue: If your entity uses #[ORM\Table(name: 'custom_table')], ensure the admin config matches the table name.
   • Fix: Explicitly set the table option in the resource config:

     resources:
         my_entity:
             driver: orm
             table: 'custom_table'
     

3. Sylius Component Quirks

   • Issue: Some Sylius components (e.g., sylius/resource) may conflict with Doctrine extensions.
   • Fix: Disable conflicting bundles in config/bundles.php or use override: false in config/packages/doctrine.yaml:

     doctrine:
         orm:
             mappings:
                 app: ~
             dql:
                 string_functions:
                     override: false
     

4. Translation Fallbacks

   • Issue: Missing translations may default to English or break.
   • Fix: Load default translations from the bundle:

     php bin/console debug:translation platform_admin
     

Debugging

1. Enable Debug Mode Set APP_DEBUG=true in .env to see detailed errors and logs.

2. Log Admin Events Enable event logging in config/packages/monolog.yaml:

   handlers:
       admin_events:
           type: stream
           path: "%kernel.logs_dir%/%kernel.environment%.admin.log"
           level: debug
           channels: ["platform_admin"]
   

3. Check Database Queries Use Symfony’s profiler (/_profiler) to inspect SQL queries for slow admin panels.

Extension Points

1. Custom Drivers

   • Extend the admin driver system to support non-ORM data sources (e.g., API-based):

     // src/Admin/Driver/CustomDriver.php
     class CustomDriver implements DriverInterface
     {
         public function load(): array { /* ... */ }
     }
     

   • Register the driver in services.yaml:

     services:
         Platform\Bundle\AdminBundle\Driver\CustomDriver:
             tags: [platform_admin.driver]
     

2. Dynamic Configs

   • Load admin configs dynamically (e.g., from a database):

     // src/Admin/ConfigLoader/DynamicLoader.php
     class DynamicLoader implements ConfigLoaderInterface
     {
         public function load(string $resourceName): array
         {
             return $this->fetchFromDatabase($resourceName);
         }
     }
     

3. API Integration

   • Use the admin panel as a backend for a React/Vue frontend by exposing endpoints:

     # config/routes.yaml
     admin_api:
         resource: "@PlatformAdminBundle/Resources/config/routing/api.yaml"
         prefix: /api/admin