Darvin Admin Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require darvinstudio/darvin-admin-bundle
   

   Enable the bundle in config/bundles.php:

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

2. First Admin Section Create a basic admin section by defining a YAML config file (e.g., config/admin/books.yml):

   darvin_admin:
       sections:
           books:
               label: Books
               entity: App\Entity\Book
               list:
                   fields: [id, title, author, createdAt]
   

   Clear cache:

   php bin/console cache:clear
   

3. First Use Case Access the admin panel at /admin (or your configured route). The bundle auto-generates CRUD interfaces for App\Entity\Book based on the YAML config.

Implementation Patterns

Workflows

1. Entity Management

   • List View: Customize columns via list.fields in YAML.

     list:
         fields: [id, title, {property: 'author.name', label: 'Author'}]
     

   • Edit Form: Use form.fields to include/exclude fields or add custom widgets.

     form:
         fields:
             - { property: 'title', type: 'text', options: { label: 'Book Title' } }
             - { property: 'coverImage', type: 'dropzone', options: { maxFiles: 1 } }
     

2. Dashboard Integration Add widgets to the dashboard via dashboard.widgets in config:

   dashboard:
       widgets:
           - { type: 'statistic', label: 'Total Books', value: 'entity(Book).count()' }
           - { type: 'chart', label: 'Books by Year', data: 'entity(Book).groupByYear()' }
   

3. Menu Customization Define menu items in YAML:

   menu:
       items:
           - { label: 'Books', route: 'admin_books_list' }
           - { label: 'Users', route: 'admin_users_list', icon: 'fas fa-user' }
   

4. CKEditor Integration Enable for a field in YAML:

   form:
       fields:
           - { property: 'description', type: 'ckeditor' }
   

5. Dropzone for File Uploads Configure in YAML:

   form:
       fields:
           - { property: 'coverImage', type: 'dropzone', options: { url: '/admin/upload', maxFilesize: 2 } }
   

   Handle uploads in a controller:

   #[Route('/admin/upload', name: 'admin_upload', methods: ['POST'])]
   public function upload(Request $request): JsonResponse
   {
       // Handle file upload logic
   }
   

Integration Tips

• Symfony Forms: Extend existing forms by overriding the entity class (see how-to-override-entity).
• Security: Use security.configurations to restrict access:

  security:
      roles:
          books:
              - ROLE_ADMIN
              - ROLE_EDITOR
  

• Translations: Localize labels and messages via Symfony’s translation system. Place translations in translations/admin.en.yml:

  books:
      list:
          title: 'Book Title'
          author: 'Author Name'
  

Gotchas and Tips

Pitfalls

1. Cache Dependencies

   • Issue: Changes to YAML configs may not reflect immediately.
   • Fix: Clear cache after config changes:

     php bin/console cache:clear
     

   • Pro Tip: Use debug:config darvin_admin to verify loaded configs.

2. Entity Overrides

   • Issue: Overriding entity classes requires proper namespace handling. Forgetting to extend the base entity class can break CRUD operations.
   • Fix: Follow the override guide and ensure your custom class extends DarvinStudio\AdminBundle\Form\Type\AdminEntityType.

3. Route Conflicts

   • Issue: Custom routes (e.g., for uploads) may conflict with bundle routes.
   • Fix: Prefix custom routes with _admin or use unique namespaces:

     # config/routes.yaml
     admin_upload:
         path: /admin/_upload
         controller: App\Controller\AdminUploadController::upload
     

4. Dropzone Configuration

   • Issue: Dropzone uploads may fail if the url option in YAML doesn’t match the controller route.
   • Fix: Ensure the url in YAML matches the exact route path (e.g., /admin/upload vs /admin/_upload).

5. CKEditor Assets

   • Issue: CKEditor assets (JS/CSS) may not load if not properly installed.
   • Fix: Run composer require ckeditor/ckeditor5 and ensure the bundle is enabled in config/bundles.php.

Debugging

• Log Level: Enable debug mode in config/packages/dev/darvin_admin.yaml:

  darvin_admin:
      debug: true
  

• Common Errors:
  • "Entity not found": Verify the entity path in YAML matches the fully qualified class name (e.g., App\Entity\Book).
  • "Field not found": Check for typos in list.fields or form.fields and ensure the property exists in the entity.

Extension Points

1. Custom Widgets Create reusable widgets by extending DarvinStudio\AdminBundle\Widget\AbstractWidget and register them in the bundle’s configuration.

2. Event Listeners Hook into lifecycle events (e.g., prePersist, postRemove) via Symfony’s event dispatcher. Example:

   // src/EventListener/AdminListener.php
   public static function getSubscribedEvents(): array
   {
       return [
           DarvinAdminEvents::PRE_PERSIST => 'onPrePersist',
       ];
   }
   
   public function onPrePersist(PrePersistEvent $event): void
   {
       $entity = $event->getEntity();
       if ($entity instanceof Book) {
           $entity->setUpdatedAt(new \DateTime());
       }
   }
   

3. Twig Extensions Extend Twig templates by creating custom templates in templates/admin/ and overriding bundle templates. Example:

   {# templates/admin/Book/list.html.twig #}
   <td>{{ book.author.name|default('N/A') }}</td>
   

4. API Integration Use the bundle’s underlying services to build custom API endpoints. Example:

   $adminSection = $this->container->get('darvin_admin.section.manager')->getSection('books');
   $repository = $adminSection->getEntityManager()->getRepository($adminSection->getEntityClass());
   $books = $repository->findAll();
   

Configuration Quirks

• YAML vs. PHP Config: While YAML is the primary config format, you can override settings in PHP by extending the bundle’s configuration class:

  // config/packages/darvin_admin.php
  $container->loadFromExtension('darvin_admin', [
      'debug' => true,
      'menu' => [
          'items' => [
              ['label' => 'Dashboard', 'route' => 'admin_dashboard'],
          ],
      ],
  ]);
  

• Dynamic Field Values: Use placeholders like entity(Book).count() in dashboard widgets. These are resolved at runtime.

Performance Tips

• Lazy-Loading: For large datasets, use pagination in list config:

  list:
      fields: [id, title]
      pagination: true
  

• Eager-Loading: Optimize queries by defining fetch plans in YAML:

  list:
      fields: [id, {property: 'author.name', label: 'Author'}]
      fetch_plan: ['author']