Pando Base Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require blackboxcode/pando-base-bundle
   

   Add to config/bundles.php:

   BlackBoxCode\PandoBaseBundle\PandoBaseBundle::class => ['all' => true],
   

2. First Use Case: Base Controller Extend PandoBaseBundle\Controller\BaseController for CRUD operations:

   use BlackBoxCode\PandoBaseBundle\Controller\BaseController;
   
   class ProductController extends BaseController
   {
       protected $entityClass = Product::class;
       protected $serializerGroups = ['default', 'api'];
   }
   

   • Auto-generates RESTful endpoints (index, store, show, update, destroy).
   • Uses Symfony’s Serializer for JSON responses.

3. Key Files to Explore

   • src/Controller/BaseController.php: Core logic for CRUD.
   • config/packages/pando_base.yaml: Default configuration.
   • Resources/config/routing.yaml: Default routes (extendable).

Implementation Patterns

1. CRUD Workflow

• Automatic Endpoints: Inherit BaseController to get pre-built routes.

  # config/routes.yaml
  pando_base:
      resource: "@PandoBaseBundle/Resources/config/routing.yaml"
      prefix: /api
  

• Customize Actions: Override methods like createEntity() or updateEntity():

  protected function createEntity(Request $request): Product
  {
      $data = $request->request->all();
      $data['slug'] = Str::slug($data['name']); // Custom logic
      return parent::createEntity($request);
  }
  

2. Serialization

• Define groups in your entity’s Serialize annotations:

  /**
   * @ORM\Entity
   * @ApiResource(
   *     normalizationContext={"groups": {"default"}},
   *     itemOperations={...}
   * )
   */
  class Product {}
  

• Override getSerializerGroups() in your controller for dynamic groups.

3. Validation

• Use Symfony’s Validator with constraints:

  use Symfony\Component\Validator\Constraints as Assert;
  
  /**
   * @Assert\NotBlank
   * @Assert\Length(min=3)
   */
  private $name;
  

• Handle validation errors in BaseController via handleValidationErrors().

4. Event Integration

• Dispatch events for lifecycle hooks (e.g., prePersist, postRemove):

  use BlackBoxCode\PandoBaseBundle\Event\BaseEntityEvent;
  
  public function prePersist(BaseEntityEvent $event): void
  {
      $event->getEntity()->setCreatedAt(new \DateTime());
  }
  

• Listen in your bundle’s services:

  # config/services.yaml
  BlackBoxCode\PandoBaseBundle\EventListener\YourListener:
      tags:
          - { name: kernel.event_listener, event: pando_base.pre_persist, method: onPrePersist }
  

5. API Platform Integration

• If using API Platform, merge configurations:

  # config/api_platform.yaml
  resources:
      App\Entity\Product:
          collectionOperations:
              - GET
              - POST
          itemOperations:
              - GET
              - PUT
              - DELETE
          normalization_context:
              groups: [default, 'api']
  

Gotchas and Tips

Pitfalls

1. Route Conflicts

   • Default routes may clash with existing ones. Prefix routes explicitly:

     pando_base_product:
         resource: "@PandoBaseBundle/Resources/config/routing.yaml"
         prefix: /api/v1/products
     

2. Serialization Groups

   • Forgetting to define groups in entities causes empty responses. Always include:

     @ApiResource(normalizationContext={"groups": {"default"}})
     

3. Event Priority

   • Events like prePersist run before Doctrine’s lifecycle callbacks. Use postPersist for post-save logic.

4. Doctrine vs. API Platform

   • If using API Platform, avoid duplicating ApiResource annotations in the bundle’s base controller.

Debugging Tips

• Enable Debug Mode: Add to config/packages/dev/pando_base.yaml:

  debug: true
  

  Logs SQL queries and event dispatches.

• Check Events: Dump dispatched events in a listener:

  public function onPrePersist(BaseEntityEvent $event): void
  {
      \dump($event->getEntity());
  }
  

Extension Points

1. Custom Controllers

   • Extend BaseController for domain-specific logic:

     class AdminProductController extends BaseController
     {
         protected $entityClass = Product::class;
         protected $permission = 'ROLE_ADMIN';
     }
     

2. Dynamic Routes

   • Override getRoutePrefix() for dynamic segments:

     protected function getRoutePrefix(): string
     {
         return '/api/v1/' . $this->getEntityName();
     }
     

3. Custom Serializers

   • Register a custom serializer in services.yaml:

     App\Serializer\CustomProductSerializer:
         tags: [serializer.normalizer]
         arguments:
             - '@doctrine.orm.entity_manager'
     

4. Bulk Operations

   • Use BaseController::bulkAction() for batch updates/deletes:

     public function bulkDelete(Request $request)
     {
         $this->bulkAction($request, 'DELETE');
     }