Admin Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require eduandebruijne/admin-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       EDB\AdminBundle\EDBAdminBundle::class => ['all' => true],
   ];
   

2. Environment Configuration: Add to .env:

   EDB_ADMIN_PATH=admin
   EDB_ADMIN_TITLE=My Admin Panel
   

3. First Use Case:

   • Extend AbstractUser and AbstractMedia in src/Entity/ (as shown in README).
   • Run migrations:

     php bin/console doctrine:migrations:diff
     php bin/console doctrine:migrations:migrate
     

   • Access /admin/login (default credentials: admin/admin).

Where to Look First

• Bundle Configuration: config/packages/edb_admin.yaml (documented in the README snippet).
• Admin Routes: Check EDB\AdminBundle\Resources/config/routing.yaml for available routes.
• Templates: Override default templates in templates/edb_admin/ (see Symfony templating).
• Entities: Review EDB\AdminBundle\Entity\AbstractUser and AbstractMedia for required fields.

First CRUD Workflow

1. Create a Model Entity:

   // src/Entity/Post.php
   use EDB\AdminBundle\Entity\AbstractModel;
   
   #[Entity]
   class Post extends AbstractModel
   {
       #[Column(type: 'string', length: 255)]
       private string $title;
   
       #[Column(type: 'text')]
       private string $content;
   }
   

2. Register in Admin Config:

   # config/packages/edb_admin.yaml
   edb_admin:
       models:
           App\Entity\Post: ~
   

3. Access via Admin Panel: Navigate to /admin/models/post to manage Post records.

Implementation Patterns

Core Workflows

1. Model Management

• Automatic CRUD: Extend AbstractModel to auto-generate admin interfaces for entities.
• Field Customization:

  # config/packages/edb_admin.yaml
  edb_admin:
      models:
          App\Entity\Post:
              fields:
                  title: { label: "Post Title" }
                  content: { type: "textarea", rows: 10 }
  

• List Views:

  edb_admin:
      models:
          App\Entity\Post:
              list:
                  columns: [id, title, createdAt]
                  filters: [title]
  

2. Media Handling

• Use AbstractMedia for file uploads (images, documents).
• Configure allowed MIME types in edb_admin.yaml:

  edb_admin:
      media:
          allowed_mime_types: ['image/jpeg', 'image/png', 'application/pdf']
  

• Access uploaded files via Media entity (e.g., $media->getPath()).

3. User Management

• Extend AbstractUser for custom user fields (e.g., firstName, lastName).
• Override login/logout paths in security.yaml:

  firewalls:
      main:
          form_login:
              login_path: edb_admin_login  # Custom route
  

4. Routing and Access Control

• Dynamic Routes: All admin routes are prefixed with %env(EDB_ADMIN_PATH)% (e.g., /admin/models/post).
• Role-Based Access: Use ROLE_ADMIN for all admin routes (configurable in security.yaml).

Integration Tips

Doctrine Extensions

• Integrate with VichUploaderBundle for advanced media handling:

  # config/packages/vich_uploader.yaml
  vich_uploader:
      db_driver: orm
      storage: file_system
  

• Link Media entity to your models via @ManyToOne relationships.

Event Listeners

• Subscribe to admin events (e.g., edb_admin.model.create):

  // src/EventListener/AdminListener.php
  use EDB\AdminBundle\Event\AdminEvents;
  
  public function __construct()
  {
      $this->dispatcher->addListener(
          AdminEvents::MODEL_CREATE,
          [$this, 'onModelCreate']
      );
  }
  

Translation

• Override default translations in translations/messages.en.yaml:

  edb_admin:
      model:
          post:
              label: "Blog Post"
              plural_label: "Blog Posts"
  

API Integration

• Expose admin models via API using API Platform or [Symfony Serializer]:

  // src/Controller/Api/AdminController.php
  use EDB\AdminBundle\Repository\ModelRepository;
  
  #[Route('/api/admin/posts')]
  public function listPosts(ModelRepository $repository): JsonResponse
  {
      $posts = $repository->findAll();
      return $this->json($posts);
  }
  

Gotchas and Tips

Pitfalls

1. Entity Naming Conflicts:

   • Avoid naming custom entities User or Media to prevent collisions with the bundle’s abstract classes.
   • Fix: Use AdminUser or AppMedia instead.

2. Missing Migrations:

   • Always run doctrine:migrations:diff after adding new entities extending AbstractUser/AbstractMedia.
   • Fix: Manually create migrations if auto-generation fails.

3. CSRF Token Errors:

   • If forms fail with "CSRF token not found," ensure the csrf_token is included in templates or forms.
   • Fix: Add {{ csrf_token('edb_admin_form') }} to custom forms.

4. Permission Denied:

   • Double-check ROLE_ADMIN is assigned to users (e.g., via User entity’s roles field).
   • Fix: Use php bin/console edb:admin:user:create to add test admins.

5. Template Overrides:

   • Overriding templates in templates/edb_admin/ requires matching the exact directory structure (e.g., Block/admin_layout.html.twig).
   • Fix: Use {{ parent() }} to inherit parent template blocks.

Debugging

1. Enable Debug Mode:

   APP_DEBUG=1
   

   • Check logs in var/log/dev.log for errors.

2. Dump Admin Config:

   // src/Command/DumpAdminConfig.php
   use Symfony\Component\Console\Command\Command;
   use Symfony\Component\Console\Input\InputInterface;
   use Symfony\Component\Console\Output\OutputInterface;
   
   public function execute(InputInterface $input, OutputInterface $output): int
   {
       $config = $this->container->getParameter('edb_admin');
       $output->writeln(\print_r($config, true));
       return Command::SUCCESS;
   }
   

3. Database Issues:

   • Verify User and Media tables exist and have correct columns (e.g., username, password, roles for User).
   • Fix: Drop and recreate tables if corrupted.

Configuration Quirks

1. Dynamic Admin Path:

   • The admin path (%env(EDB_ADMIN_PATH)%) must be defined in .env and referenced in security.yaml.
   • Tip: Use a unique path (e.g., EDB_ADMIN_PATH=app_admin) to avoid conflicts.

2. Google Authenticator:

   • The GoogleAuthenticator requires the google/authenticator package:

     composer require google/authenticator
     

   • Tip: Disable it in security.yaml if unused:

     custom_authenticators: []
     

3. Model Field Types:

   • Unsupported Doctrine types (e.g., json) may not render in the admin panel.
   • Workaround: Use type: "text" and handle serialization manually.

Extension Points

1. Custom Admin Controllers:

   • Override default controllers by creating a custom bundle or using Symfony’s compiler passes.
   • Example: Extend EDB\AdminBundle\Controller\ModelController.

2. Add Custom Actions:

   • Extend the Action system by creating a custom service tagged as edb_admin.action:

     # config/services.yaml
     services:
         App\Admin\Action\ExportAction:
             tags: ['edb_admin.action']
     

3. Plugin System:

   • Design your app as a plugin system where each feature (e.g., "Blog", "Shop") is a standalone bundle with its own edb_admin.yaml.
   • Tip: Use Symfony’s autoloading to dynamically load plugin configs.

4. Event Dispatching:

   • Extend functionality by listening to events like