Admin Bundle Laravel Package

Getting Started

Minimal Steps

1. Install Dependencies Run composer require culabs/admin-bundle:2.6.*@dev and update vendors:

   composer update --prefer-dist
   

2. Register Bundles Add the required bundles to app/AppKernel.php:

   new CULabs\AdminBundle\CULabsAdminBundle(),
   new Knp\Bundle\PaginatorBundle\KnpPaginatorBundle(),
   new Lexik\Bundle\FormFilterBundle\LexikFormFilterBundle(),
   new Knp\Bundle\MenuBundle\KnpMenuBundle(),
   

3. Configure Twig Set the default form theme in config.yml:

   twig:
       form:
           resources:
             - bootstrap_3_horizontal_layout.html.twig
   

4. Generate a CRUD Controller Use the bundle’s command to scaffold a CRUD interface:

   php app/console culabs:admin:generate:crud --entity=YourEntity --bundle=YourBundle
   

5. Define Backend Menu Create app/config/menu.yml to structure your admin navigation:

   menu.backend:
       items:
           your_entity:
               label: Your Entity
               uri: path/to/your_entity
   

6. Import Menu Config Add to config.yml:

   imports:
       - { resource: menu.yml }
   

7. Clear Cache Run:

   php app/console cache:clear
   

First Use Case

Generate a CRUD for a User entity:

php app/console culabs:admin:generate:crud --entity=User --bundle=AppBundle

This creates:

• A controller (UserAdminController) with index, create, edit, and delete actions.
• Filterable forms (via LexikFormFilterBundle).
• Paginated listings (via KnpPaginatorBundle).
• Menu integration (via KnpMenuBundle).

Implementation Patterns

Workflows

1. CRUD Generation

   • Use culabs:admin:generate:crud for rapid scaffolding.
   • Customize generated templates in Resources/views/ of your bundle.
   • Override controller methods (e.g., configure()) to add logic:

     public function configure()
     {
         parent::configure();
         $this->add('custom_field', 'text');
     }
     

2. Form Customization

   • Extend form types by creating custom form classes and referencing them in the generated controller:

     $this->add('custom_field', 'AppBundle\Form\Type\CustomFieldType');
     

   • Leverage LexikFormFilterBundle for dynamic filtering:

     # config.yml
     lexik_form_filter:
         form_types:
             - AppBundle\Form\Type\YourEntityFilterType
     

3. Menu Management

   • Dynamically build menus in menu.yml:

     menu.backend:
         items:
             dashboard:
                 label: Dashboard
                 uri: '#'
                 children:
                     users:
                         label: Users
                         uri: path/to/users
     

   • Access the menu in Twig:

     {{ knp_menu_render('menu.backend', { 'depth': 2 }) }}
     

4. Pagination

   • Use KnpPaginatorBundle for pagination in listings:

     $paginator = $this->get('knp_paginator');
     $results = $paginator->paginate(
         $this->getDoctrine()->getRepository('AppBundle:User')->findAll(),
         $this->get('request')->query->get('page', 1),
         10
     );
     return $this->render('AppBundle:UserAdmin:index.html.twig', ['results' => $results]);
     

5. Entity-Specific Logic

   • Override actions in the generated controller:

     public function preUpdateAction($id)
     {
         // Custom logic before update
     }
     

Integration Tips

• Doctrine Integration Ensure your entity is properly mapped with Doctrine and has a repository class.

• Security Protect admin routes in security.yml:

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

• Asset Management Use Symfony’s asset system for CSS/JS:

  {% block stylesheets %}
      {{ parent() }}
      {{ asset('bundles/culabsadmin/css/admin.css') }}
  {% endblock %}
  

• Translation Extend translations in translations/messages.en.yml:

  'Your Entity': 'Your Entity Label'
  

Gotchas and Tips

Pitfalls

1. Bundle Compatibility

   • The bundle is archived and may not support Symfony 4/5+. Test thoroughly.
   • Dependencies (LexikFormFilterBundle, KnpPaginatorBundle) must be compatible with your Symfony version.

2. Menu Configuration

   • Forgetting to import menu.yml in config.yml will break navigation.
   • Typos in menu.yml keys (e.g., items) will cause silent failures.

3. Form Theme Overrides

   • If bootstrap_3_horizontal_layout.html.twig is missing, forms will render without styling.
   • Ensure the theme file exists in vendor/culabs/admin-bundle/Resources/views/Form/ or override it in your bundle.

4. Command Output

   • The generate:crud command may overwrite existing files. Backup your Resources/ directory first.

5. Pagination Issues

   • If pagination doesn’t work, verify KnpPaginatorBundle is registered before CULabsAdminBundle in AppKernel.php.

Debugging

1. Check Generated Files

   • After running generate:crud, inspect:
     • src/YourBundle/Controller/YourEntityAdminController.php
     • Resources/views/YourEntityAdmin/
     • Resources/config/routing.yml

2. Symfony Debug Toolbar

   • Use the profiler to check:
     • Twig template rendering errors.
     • Doctrine queries (ensure entities are loaded correctly).
     • Form data binding issues.

3. Log Errors

   • Enable debug mode in app/config/config_dev.yml:

     framework:
         router:
             resource: "%kernel.root_dir%/config/routing_dev.yml"
             strict_requirements: true
         profiler: { only_exceptions: false }
     

Tips

1. Customize Templates Override bundle templates by creating a CULabsAdminBundle directory in your bundle’s Resources/:

   YourBundle/
       Resources/
           CULabsAdminBundle/
               views/
                   YourEntityAdmin/
                       index.html.twig
   

2. Add Custom Actions Extend the controller to add actions (e.g., bulk delete):

   public function bulkDeleteAction()
   {
       $ids = $this->get('request')->request->get('ids');
       // Logic to delete entities
       return $this->redirect($this->generateUrl('admin_users'));
   }
   

3. Use Events Listen to bundle events (e.g., culabs.admin.entity.pre_save) for pre/post-processing:

   services:
       app.admin.listener:
           class: AppBundle\EventListener\AdminListener
           tags:
               - { name: kernel.event_listener, event: culabs.admin.entity.pre_save, method: onPreSave }
   

4. Performance

   • Add @ORM\Cache(usage="READ_WRITE") to entities for heavy CRUD operations.
   • Use ->select() in repository queries to limit loaded fields.

5. Testing

   • Test CRUD actions with:

     php app/console culabs:admin:generate:crud --entity=TestEntity --bundle=AppBundle --test
     

   • Mock dependencies in functional tests:

     $this->container->set('culabs_admin.templating.helper', $this->createMock('CULabs\AdminBundle\Templating\Helper\AdminHelper'));