Admin Bundle Laravel Package

Getting Started

Minimal Steps to Begin

1. Manual Installation

   • Clone the repository directly into your Symfony project:

     git clone https://github.com/charlar/symfony-admin.git AdminBundle
     

   • Place the AdminBundle folder in either:
     • /Symfony/src/ (if using Symfony 2.3+ with autoloading)
     • /Symfony/vendor/bundles/ (legacy Symfony 2.x)
   • Register the bundle in AppKernel.php:

     $bundles[] = new CRL\AdminBundle\CRLAdminBundle();
     

2. Route Configuration Add the admin route in app/config/routing.yml (or routing_dev.yml):

   _admin:
       resource: "@CRLAdminBundle/Controller/AdminController.php"
       type:     annotation
       prefix:   /admin
   

3. First Use Case

   • Visit /admin in your browser.
   • The bundle auto-detects Doctrine ORM entities and generates a CRUD interface for each.
   • Click on an entity to browse, edit, or create records.

Implementation Patterns

Workflow Integration

1. Entity-Based CRUD

   • The bundle dynamically generates admin interfaces for all Doctrine entities in your project.
   • No manual controller/route setup required for basic CRUD operations.

2. Customization via Annotations

   • Use annotations on entities to override default behavior (e.g., @Admin\Title, @Admin\List).
   • Example:

     use CRL\AdminBundle\Annotation as Admin;
     
     /**
      * @Admin\Title("Custom Title")
      * @Admin\List(columns={"id", "name"})
      */
     class Product {}
     

3. Form Customization

   • Extend the default form types by overriding the bundle’s form templates.
   • Override CRLAdminBundle:Admin:form.html.twig in your theme.

4. Security Integration

   • Secure admin routes using Symfony’s security system (e.g., ROLE_ADMIN).
   • Example in security.yml:

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

5. Event Listeners

   • Hook into lifecycle events (e.g., prePersist, postUpdate) via Symfony’s event dispatcher.
   • Example:

     $dispatcher->addListener('admin.pre_save', function ($event) {
         $entity = $event->getEntity();
         // Custom logic before save
     });
     

Gotchas and Tips

Pitfalls

1. Manual Installation Quirks

   • Ensure the AdminBundle directory is named exactly AdminBundle (case-sensitive).
   • If using Symfony 2.3+, manually update composer.json autoload:

     "autoload": {
         "psr-4": { "CRL\\AdminBundle\\": "src/" }
     }
     

     Then run composer dump-autoload.

2. Entity Detection Issues

   • The bundle only auto-detects entities in the Entity namespace by default.
   • To include custom namespaces, configure in config.yml:

     crl_admin:
         entity_namespaces: ["AppBundle\Entity", "Vendor\\Bundle\\Entity"]
     

3. Form Field Mapping

   • Complex Doctrine types (e.g., ArrayCollection) may not render correctly out-of-the-box.
   • Override the form type for such fields in services.yml:

     services:
         app.form.type.my_collection:
             class: AppBundle\Form\Type\MyCollectionType
             tags: { name: form.type, alias: my_collection }
     

4. Routing Conflicts

   • Avoid naming custom routes _admin to prevent conflicts with the bundle’s route.

Debugging Tips

1. Check Entity Annotations

   • Use the doctrine:schema:validate command to ensure entities are properly annotated:

     php app/console doctrine:schema:validate
     

2. Enable Debug Mode

   • Set APP_DEBUG=true in .env to see detailed errors in the admin interface.

3. Clear Cache

   • After manual changes, clear the cache:

     php app/console cache:clear
     

Extension Points

1. Custom Templates

   • Override templates in app/Resources/CRLAdminBundle/views/ to modify UI.
   • Example: Copy AdminBundle:Admin:list.html.twig to your theme.

2. Add Custom Actions

   • Extend the AdminController to add bulk actions or custom buttons.
   • Example:

     // In a custom controller extending AdminController
     public function bulkDeleteAction() {
         // Logic for bulk delete
     }
     

3. Localization

   • Translate labels/buttons by overriding the bundle’s translation files in translations/:

     # app/Resources/translations/messages.en.yml
     crl_admin:
         add: "Create New"
         edit: "Modify"