Generic Admin Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require eduardoledo/generic-admin-bundle
   php composer.phar update eduardoledo/generic-admin-bundle
   

   Ensure FOSUserBundle, PagerBundle, and TinymceBundle are installed (automatically handled by the package).

2. Enable the Bundle: Add to AppKernel.php:

   new Lomaswifi\AdminBundle\LomaswifiAdminBundle(),
   

3. First Use Case: Create a basic CRUD controller for an entity (e.g., Post):

   php app/console lomaswifi:admin:generate --entity=Post --bundle=AppBundle
   

   This generates a controller, routes, and admin configuration.

4. Configuration: Edit app/config/config.yml to include:

   lomaswifi_admin:
       bundles:
           - AppBundle
       default_per_page: 20
   

5. Routing: Import routes in app/config/routing.yml:

   lomaswifi_admin:
       resource: "@LomaswifiAdminBundle/Resources/config/routing.yml"
       prefix:   /admin
   

Implementation Patterns

Workflows

1. Entity-Based CRUD:

   • Generate admin panels for any Doctrine entity with:

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

   • Customize fields via YAML configuration (e.g., app/config/admin.yml):

     lomaswifi_admin:
         entities:
             AppBundle\Entity\User:
                 fields:
                     - { name: username, type: text }
                     - { name: email, type: email }
     

2. Field Types: Leverage built-in types (text, email, textarea, tinymce, date, etc.) or extend with custom types:

   fields:
       - { name: content, type: tinymce }
       - { name: publishedAt, type: date }
   

3. Permissions: Restrict access via FOSUserBundle roles (e.g., ROLE_ADMIN):

   entities:
       AppBundle\Entity\Post:
           access_control: ROLE_ADMIN
   

4. Pagination: Configure per-page limits globally or per-entity:

   lomaswifi_admin:
       default_per_page: 10
   

5. Reusable Admin Panels: Share configurations across entities using inheritance:

   entities:
       AppBundle\Entity\BaseEntity:
           fields:
               - { name: createdAt, type: date, readonly: true }
       AppBundle\Entity\Post:
           extends: AppBundle\Entity\BaseEntity
   

Integration Tips

1. Doctrine Events: Hook into prePersist/preUpdate for validation or logic:

   // In your entity
   public function prePersist()
   {
       $this->setSlug(Str::slug($this->title));
   }
   

2. Custom Actions: Add buttons/actions (e.g., "Publish") in admin.yml:

   entities:
       AppBundle\Entity\Post:
           actions:
               - { name: publish, route: app_post_publish, icon: fa-check }
   

3. Form Extensions: Extend forms via event listeners (e.g., add a published checkbox):

   // src/AppBundle/EventListener/AdminFormListener.php
   public function onBuildForm(FormEvent $event)
   {
       $form = $event->getForm();
       $form->add('published', CheckboxType::class);
   }
   

4. API Integration: Use the generated CRUD as a backend for frontend frameworks (e.g., React/Vue) by exposing routes:

   # app/config/routing.yml
   app_admin_api:
       resource: "@LomaswifiAdminBundle/Resources/config/routing.yml"
       prefix: /api/admin
       defaults: { _format: json }
   

5. Asset Management: Override templates (e.g., edit.html.twig) in AppBundle/Resources/LomaswifiAdminBundle/views/.

Gotchas and Tips

Pitfalls

1. Bundle Naming: The bundle uses LomaswifiAdminBundle in code but is named GenericAdminBundle in the package. Ensure consistency in AppKernel.php and commands.

2. FOSUserBundle Dependency:

   • If not installed, the package attempts auto-installation but may fail silently. Verify dependencies manually:

     composer require friendsofsymfony/user-bundle makerlabs/pager-bundle stfalcon/tinymce-bundle
     

3. TinymceBundle Conflicts:

   • The package auto-configures TinymceBundle but may clash with existing configs. Override in config.yml:

     stfalcon_tinymce:
         selector: "textarea.tinymce"
         plugins: ["advlist autolink lists link charmap print preview anchor"]
     

4. Entity Generation Issues:

   • The generate command may fail if the entity lacks a id field or has complex relationships. Manually define fields in admin.yml if needed.

5. Routing Conflicts:

   • Prefix routes explicitly to avoid clashes with other bundles:

     lomaswifi_admin:
         prefix: /admin
     

Debugging

1. Command Errors:

   • Check generated files in src/AppBundle/Controller/Admin/ and app/config/admin.yml for typos.
   • Run with -v for verbose output:

     php app/console lomaswifi:admin:generate -v --entity=Post
     

2. Template Overrides:

   • Clear cache after overriding templates:

     php app/console cache:clear
     

3. Permission Denied:

   • Ensure FOSUserBundle roles are correctly assigned (e.g., ROLE_ADMIN). Test with:

     php app/console fos:user:create admin admin@example.com --super-admin
     

4. Field Validation:

   • Validate fields in admin.yml match the entity’s properties. Use doctrine:schema:validate to check:

     php app/console doctrine:schema:validate
     

Extension Points

1. Custom Field Types: Create a service for new field types (e.g., select2):

   # services.yml
   services:
       app.admin.field.select2:
           class: AppBundle\Form\Type\Select2Type
           tags:
               - { name: lomaswifi_admin.field_type, alias: select2 }
   

2. Event Listeners: Subscribe to admin events (e.g., AdminEntityEvent):

   // src/AppBundle/EventListener/AdminListener.php
   public function onPreSave(AdminEntityEvent $event)
   {
       $entity = $event->getEntity();
       $entity->setUpdatedAt(new \DateTime());
   }
   

   Register in services.yml:

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

3. Dynamic Field Mapping: Use callbacks in admin.yml for dynamic values:

   fields:
       - { name: status, type: text, callback: getStatusLabel }
   

   Implement the callback in your entity or service.

4. Bulk Actions: Extend bulk operations via custom routes and controllers:

   # routing.yml
   app_admin_bulk:
       path: /admin/{entity}/bulk
       defaults: { _controller: AppBundle:Admin\BulkController::index }
   

5. Internationalization: Translate field labels/placeholders using Symfony’s translation system:

   # app/config/admin.yml
   entities:
       AppBundle\Entity\Post:
           fields:
               - { name: title, label: "admin.post.title" }
   

   Add translations in translations/messages.en.yml:

   admin:
       post:
           title: "Post Title"