Admin Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require aropixel/admin-bundle
   

   Register the bundle in config/bundles.php:

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

2. First Use Case: Generate a CRUD interface for an existing entity:

   php bin/console aropixel:make:crud
   

   Follow prompts to specify your entity and form type (e.g., App\Entity\Post, App\Form\PostType).

3. Access Admin Panel: Create an admin user:

   php bin/console aropixel:admin:create-user
   

   Log in at /admin (default route).

Implementation Patterns

Workflows

1. CRUD Generation:

   • Use make:crud to scaffold controllers, templates, and routes.
   • Customize generated files in src/Controller/Admin/ and templates/admin/[entity]/.
   • Extend templates by overriding blocks like datatable_body or formbody.

2. DataTables:

   • Configure columns in the controller:

     $dataTableFactory->create(Post::class)
         ->setColumns([
             ['label' => 'Title', 'orderBy' => 'title'],
             ['label' => 'Actions', 'orderBy' => '', 'class' => 'no-sort'],
         ]);
     

   • Use Twig macros for actions:

     {% import '@AropixelAdmin/Macro/actions.html.twig' as list %}
     {{ list.actions(item, path('admin_post_edit', {id: item.id}), path('admin_post_delete', {id: item.id})) }}
     

3. Forms:

   • Leverage custom form types (e.g., ImageType, EditorType):

     $builder->add('content', EditorType::class);
     $builder->add('thumbnail', ImageType::class, ['data_class' => PostImage::class]);
     

   • Organize fields with tabbed navigation:

     {% import '@AropixelAdmin/Macro/forms.html.twig' as forms %}
     {{ forms.tabs([
         { id: 'tab-content', label: 'Content' },
         { id: 'tab-media', label: 'Media' }
     ]) }}
     

4. Menu/Page Management:

   • Use PageBundle for hierarchical content:

     php bin/console aropixel:make:crud App\Entity\Page App\Form\PageType
     

   • Drag-and-drop sorting via JavaScript (included by default).

Integration Tips

• Symfony Security: Integrate with existing user providers or extend the AdminUser entity.
• Translation: Override translations in translations/messages.en.yaml:

  admin:
      post:
          title: 'Blog Post'
  

• Assets: Customize CSS/JS in assets/admin/ and import via Twig:

  {{ encore_entry_link_tags('admin') }}
  

Gotchas and Tips

Pitfalls

1. Entity Requirements:

   • Generated CRUDs assume entities have id, createdAt, and updatedAt fields. Add these if missing:

     #[ORM\GeneratedValue]
     #[ORM\Column]
     private ?int $id = null;
     
     #[ORM\Column(type: 'datetime_immutable')]
     private \DateTimeImmutable $createdAt;
     

2. FormType Mismatches:

   • Ensure the FormType class specified in make:crud matches the entity’s fields. Mismatches cause runtime errors.

3. Route Conflicts:

   • Default routes (e.g., /admin/posts) may clash with existing routes. Override in config/routes.yaml:

     aropixel_admin:
         resource: "@AropixelAdminBundle/Resources/config/routing.yaml"
         prefix: "/custom-admin"
     

4. LiipImagine Dependencies:

   • For ImageType, ensure liip/imagine-bundle is installed and filters are configured in config/packages/liip_imagine.yaml.

Debugging

• Template Overrides:

  • If macros (e.g., actions) don’t render, verify the Twig import path:

    {% import '@AropixelAdmin/Macro/actions.html.twig' as list %}
    

  • Check for typos in block names (e.g., datatable_body vs. datatableBody).

• DataTable Issues:

  • Clear cache after modifying columns:

    php bin/console cache:clear
    

  • Use browser dev tools to inspect AJAX requests for errors.

Extension Points

1. Custom Macros:

   • Add new macros in src/Resources/views/Macro/ and document them in macros.md.

2. Form Type Extensions:

   • Extend existing types (e.g., ImageType) by creating a custom class:

     class CustomImageType extends ImageType {
         public function configureOptions(OptionsResolver $resolver) {
             $resolver->setDefaults(['custom_option' => true]);
         }
     }
     

3. Admin Menu:

   • Customize the sidebar menu in templates/admin/base.html.twig:

   {% block admin_menu %}
       <li><a href="{{ path('admin_posts') }}">{{ 'admin.posts'|trans }}</a></li>
   {% endblock %}
   

4. Translation Keys:

   • Add new keys to translations/messages.en.yaml and reference them in templates:

     {{ 'admin.custom_label'|trans }}