Qcm Admin Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require avoo/qcm-admin-bundle:dev-master
   

   Ensure avoo/qcm-core-bundle is also installed (required dependency).

2. Register Bundles (AppKernel.php):

   new Qcm\Bundle\CoreBundle\QcmCoreBundle(),
   new Qcm\Bundle\AdminBundle\QcmAdminBundle(),
   

3. Configure Routing (config/routing.yml):

   qcm_admin:
       resource: "@QcmAdminBundle/Resources/config/routing.yml"
       prefix: /admin
   

4. Import Configs (config.yml):

   imports:
       - { resource: "@QcmCoreBundle/Resources/config/core.yml" }
       - { resource: "@QcmAdminBundle/Resources/config/core.yml" }
   

5. First Use Case:

   • Access /admin to see the default admin dashboard (if configured).
   • Use the bundle’s CRUD generators for managing entities (see QcmCoreBundle docs for entity setup).

Implementation Patterns

Core Workflows

1. Admin Panel Generation:

   • Decorate entities with @Qcm\Admin\Annotation\Admin to auto-generate admin interfaces.
   • Example:

     use Qcm\Admin\Annotation\Admin;
     
     /**
      * @Admin
      */
     class Product {}
     

   • The bundle renders a default admin UI for Product at /admin/product.

2. Customizing Admin Views:

   • Override templates in app/Resources/QcmAdminBundle/views/ to modify default layouts.
   • Extend controllers via event listeners (e.g., qcm.admin.pre_render).

3. Field Configuration:

   • Use @AdminField annotations to customize how entity properties are displayed/edited:

     /**
      * @AdminField(type="text", options={"label": "Product Name"})
      */
     private $name;
     

4. Permissions & Security:

   • Leverage Symfony’s security system to restrict admin access:

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

5. Integration with Forms:

   • The bundle integrates with Symfony’s FormBuilder. Extend forms via:

     $builder->addEventListener(FormEvents::PRE_SET_DATA, function (FormEvent $event) {
         // Custom logic
     });
     

Common Use Cases

• Quick CRUD: Auto-generate admin panels for Doctrine entities with minimal annotations.
• Multi-Tenant Admin: Use the bundle’s routing to scope admin panels by tenant (e.g., /admin/{tenant}/products).
• Audit Logs: Extend the bundle to log admin actions via qcm.admin.action events.

Gotchas and Tips

Pitfalls

1. Missing QcmCoreBundle:

   • The bundle requires avoo/qcm-core-bundle. Install it first or face routing/controller errors.
   • Error: Class 'Qcm\Bundle\CoreBundle\QcmCoreBundle' not found.

2. Annotation Overrides:

   • If annotations are ignored, clear the cache:

     php app/console cache:clear --env=prod
     

   • Ensure doctrine/annotations is installed and enabled in composer.json.

3. Routing Conflicts:

   • Prefix routes explicitly to avoid clashes with other bundles (e.g., /admin vs /app_dev.php/admin).

4. JavaScript Translations:

   • The bundle relies on BazingaJsTranslationBundle. If translations fail, verify:

     # config.yml
     bazinga_js_translation:
         default_locale: "%locale%"
     

Debugging Tips

1. Enable Debug Mode:

   • Add to config.yml:

     qcm_admin:
         debug: true  # Logs admin actions to Symfony's logger
     

2. Event Listeners:

   • Subscribe to events for custom logic:

     // src/QcmAdminBundle/EventListener/CustomListener.php
     public static function getSubscribedEvents()
     {
         return [
             'qcm.admin.pre_render' => 'onPreRender',
         ];
     }
     

3. Template Overrides:

   • Debug template paths by checking:

     php app/console debug:config qcm_admin
     

   • Look for template_path in the output.

Extension Points

1. Custom Admin Classes:

   • Override the default admin class for an entity:

     /**
      * @Admin(class="AppBundle\Admin\CustomProductAdmin")
      */
     class Product {}
     

2. Action Handlers:

   • Extend actions (e.g., create, edit) via services:

     services:
         app.custom_admin_action:
             class: AppBundle\Service\CustomAdminAction
             tags:
                 - { name: qcm.admin.action_handler, action: "custom_action" }
     

3. Asset Management:

   • Add custom CSS/JS to the admin panel:

     {# app/Resources/QcmAdminBundle/views/layout.html.twig #}
     {{ parent() }}
     {{ encore_entry_link_tags('admin-app') }}