Easy Admin Commands Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require artgris/easy-admin-commands-bundle
   

2. Enable the bundle in config/bundles.php:

   return [
       // ...
       Artgris\EasyAdminCommandsBundle\ArtgrisEasyAdminCommandsBundle::class => ['all' => true],
   ];
   

3. Configure the bundle in config/packages/artgris_easy_admin_commands.yaml:

   artgris_easy_admin_commands:
       dir: '%kernel.project_dir%/config/packages/easy_admin/entities/'
       namespaces:
           - 'App\Entity'
   

4. Generate the first config:

   php bin/console artgris:easyadmin:export
   

   This creates a config/packages/easy_admin/entities/ directory and generates YAML files for all entities in the specified namespaces.

5. Import the generated configs in config/packages/easy_admin.yaml:

   imports:
       - { resource: easy_admin/entities/ }
   

First Use Case: Quick CRUD for a New Entity

After creating a new entity (e.g., App\Entity\Product), run:

php bin/console artgris:easyadmin:export App\Entity\Product

This generates a dedicated YAML config for Product in config/packages/easy_admin/entities/product.yaml, ready for EasyAdminBundle to use.

Implementation Patterns

Workflow for Entity Management

1. Add a new entity:

   • Create the entity class (e.g., App\Entity\BlogPost).
   • Run php bin/console artgris:easyadmin:export App\Entity\BlogPost to auto-generate the EasyAdmin config.
   • Customize the generated YAML (e.g., adjust field types, add validation, or reorder fields).

2. Bulk configuration:

   • Use the included/excluded lists in artgris_easy_admin_commands.yaml to control which entities are processed:

     artgris_easy_admin_commands:
         entities:
             included:
                 - 'App\Entity\Product'
                 - 'App\Entity\BlogPost'
             excluded:
                 - 'App\Entity\User'
     

   • Regenerate configs with:

     php bin/console artgris:easyadmin:export
     

3. Field-specific customization:

   • Override default field types using regex:

     regex:
         ^image_: image
         ^price_: money
     

   • Specify type options (e.g., for TinyMCE or Flatpickr):

     types:
         text:
             type_options:
                 attr: { class: 'tinymce' }
         date:
             type_options:
                 attr: { class: 'flatpickr', format: 'd/m/Y' }
     

4. List and form layout:

   • Control field order and visibility:

     list:
         position:
             - title
             - { property: 'createdAt', label: 'Published On' }
         excluded:
             - slug
     form:
         position:
             - title
             - content
             - { property: 'publishedAt', type: date }
     

5. Integration with EasyAdminBundle:

   • Ensure easy_admin.yaml imports the generated configs:

     imports:
         - { resource: easy_admin/entities/ }
     

   • Extend the generated configs in easy_admin.yaml for global overrides:

     easy_admin:
         design:
             menu:
                 - { label: 'Products', entity: 'App\Entity\Product', icon: 'tag' }
     

Gotchas and Tips

Pitfalls

1. Namespace Mismatches:

   • If entities aren’t generated, verify the namespaces in artgris_easy_admin_commands.yaml match your entity locations.
   • Example: Omitting App\Entity will miss all entities in that namespace.

2. Overwriting Configs:

   • Running php bin/console artgris:easyadmin:export without arguments regenerates all configs, overwriting manual edits.
   • Solution: Use php bin/console artgris:easyadmin:export App\Entity\SpecificEntity to target a single entity.

3. Type Conflicts:

   • Custom regex patterns may override default type mappings unintentionally.
   • Debug Tip: Check the generated YAML for unexpected field types after running the command.

4. EasyAdminBundle Version:

   • This bundle requires EasyAdminBundle ^2.0. Using an incompatible version (e.g., ^3.0) may cause errors.
   • Fix: Pin the dependency in composer.json:

     "require": {
         "easycorp/easyadmin-bundle": "~2.0"
     }
     

5. Circular Imports:

   • If easy_admin.yaml imports a non-existent file (e.g., due to a typo in dir), Symfony throws a FileNotFoundException.
   • Prevention: Validate the dir path exists and is writable.

Debugging Tips

1. Dry Run:

   • Inspect generated configs before applying them by checking the easy_admin/entities/ directory manually.

2. Command Arguments:

   • Use --help to see all options:

     php bin/console artgris:easyadmin:export --help
     

   • Example output includes entity-specific generation:

     php bin/console artgris:easyadmin:export App\Entity\Product --force
     

3. Logging:

   • Enable debug mode (APP_DEBUG=1) to see detailed output during config generation.

4. Validation:

   • After generation, validate YAML syntax using:

     php bin/console debug:container --parameters | grep app.path
     

     (Ensure paths like %app.path.product_images% are defined in parameters.yaml.)

Extension Points

1. Custom Field Types:

   • Extend the bundle by adding new type mappings in artgris_easy_admin_commands.yaml:

     types:
         json:
             type: json
             type_options:
                 attr: { class: 'json-editor' }
     

2. Post-Generation Hooks:

   • Use Symfony’s kernel.terminate event to process generated configs programmatically:

     // src/EventListener/PostEasyAdminGenerateListener.php
     namespace App\EventListener;
     
     use Symfony\Component\HttpKernel\Event\TerminateEvent;
     use Symfony\Component\HttpKernel\KernelEvents;
     
     class PostEasyAdminGenerateListener
     {
         public function onTerminate(TerminateEvent $event)
         {
             if ($event->isMainRequest()) {
                 $generatedConfigs = $this->findGeneratedConfigs();
                 // Custom logic (e.g., add translations, modify fields)
             }
         }
     }
     

     Register the listener in services.yaml:

     services:
         App\EventListener\PostEasyAdminGenerateListener:
             tags:
                 - { name: kernel.event_listener, event: kernel.terminate }
     

3. Dynamic Configs:

   • Combine with Symfony’s ParameterBag to generate configs dynamically based on environment variables:

     # artgris_easy_admin_commands.yaml
     types:
         image:
             base_path: '%env(APP_MEDIA_PATH)%'
     

4. Testing:

   • Mock the bundle in tests by overriding the ArtgrisEasyAdminCommandsBundle configuration:

     $container->get('artgris_easy_admin_commands.config')->setDir(sys_get_temp_dir() . '/easy_admin_test');