Crud Event Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require beefeater/crud-event-bundle
   

   Enable in config/bundles.php:

   return [
       // ...
       Beefeater\CrudEventBundle\BeefeaterCrudEventBundle::class => ['all' => true],
   ];
   

2. Define a CRUD Configuration Create a YAML file (e.g., config/crud/v1/posts.yaml):

   resources:
       App\Entity\Post:
           operations:
               list: ~
               create: ~
               read: ~
               update: ~
               delete: ~
   

3. Register Routes Add to config/routes.yaml:

   crud_api_v1:
       resource: '%kernel.project_dir%/config/crud/v1/*.yaml'
       type: crud
   

4. First Use Case Trigger a GET /api/v1/posts request to list posts with auto-pagination/sorting/filtering.

Implementation Patterns

Core Workflow

1. Configuration-Driven Define CRUD operations in YAML (e.g., config/crud/v1/posts.yaml):

   resources:
       App\Entity\Post:
           operations:
               list:
                   pagination: { items_per_page: 20 }
                   sorting: [ { field: 'createdAt', direction: 'desc' } ]
               create:
                   validation_groups: [ 'Default', 'Create' ]
   

2. Event-Driven Extensibility Listen to events in Symfony’s EventDispatcher:

   // src/EventListener/PostCreateListener.php
   use Beefeater\CrudEventBundle\Event\CrudEvent;
   
   class PostCreateListener {
       public function onPostCreate(CrudEvent $event): void {
           $post = $event->getEntity();
           $post->setSlug(Str::slug($post->getTitle()));
       }
   }
   

   Register in services.yaml:

   services:
       App\EventListener\PostCreateListener:
           tags:
               - { name: 'kernel.event_listener', event: 'beefeater.crud.post.create' }
   

3. Custom Controllers Override default controllers by specifying a controller in YAML:

   resources:
       App\Entity\Post:
           operations:
               create:
                   controller: App\Controller\CustomPostController::createAction
   

4. Pagination/Sorting/Filtering Use query parameters:

   GET /api/v1/posts?page=2&sort=-createdAt&filter[status]=published
   

Integration Tips

• Doctrine Integration: Auto-generates Repository calls; extend via custom DQL.
• Validation: Use Symfony’s Validation component with validation_groups.
• Security: Define per-operation roles in YAML:

  operations:
      delete:
          security: ROLE_ADMIN
  

• Excel Export: Enable via config:

  resources:
      App\Entity\Post:
          operations:
              list:
                  excel_export: true
  

Gotchas and Tips

Pitfalls

1. Route Naming Conflicts

   • Default routes use beefeater_crud_<resource>_<operation>. Override via route_name in YAML:

     operations:
         list:
             route_name: 'api_v1_posts_list'
     

2. Event Dispatching Order

   • Events fire in this order: pre_<operation>, post_<operation>. Avoid side effects in pre_ events if post_ listeners depend on them.

3. Pagination Edge Cases

   • Default pagination uses items_per_page: 15. Override globally in config/packages/beefeater_crud.yaml:

     beefeater_crud:
         default_pagination: { items_per_page: 50 }
     

4. UUID Route Parameters

   • Ensure param_converter is configured for UUIDs in Symfony (e.g., NelmioApiDocBundle or api_platform).

Debugging

• Enable Logging Configure in config/packages/beefeater_crud.yaml:

  beefeater_crud:
      logging: true
  

  Logs appear in var/log/beefeater_crud.log.

• Validate YAML Use Symfony’s debug:config to validate config:

  php bin/console debug:config beefeater_crud
  

Extension Points

1. Custom Event Subscribers Extend core events (e.g., CrudEvent) to add domain logic:

   class CustomSubscriber implements EventSubscriberInterface {
       public static function getSubscribedEvents(): array {
           return [
               'beefeater.crud.post.pre_create' => 'onPreCreate',
           ];
       }
   }
   

2. Dynamic Configuration Load YAML configs dynamically via CrudConfigLoader service:

   $loader = $container->get('beefeater_crud.config_loader');
   $config = $loader->load('v1/posts.yaml');
   

3. Override Templates Customize response templates by extending the bundle’s Twig templates (located in vendor/beefeater/crud-event-bundle/templates).

4. Add New Operations Extend the CrudOperation class to support custom actions (e.g., publish). Register via YAML:

   operations:
       publish:
           method: POST
           path: /publish
           controller: App\Controller\PostController::publishAction