Slotbundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ais/slotbundle:dev-master
   

   Ensure your composer.json includes the required dependencies (e.g., fos/rest-bundle, nelmio/api-doc-bundle).

2. Register the Bundle: Add to app/AppKernel.php:

   new Ais\SlotBundle\AisSlotBundle(),
   

   Include required bundles (e.g., NelmioApiDocBundle, FOSRestBundle, JMSSerializerBundle).

3. Routing: Add to app/config/routing.yml:

   ais_slots:
     type: rest
     prefix: /api
     resource: "@AisSlotBundle/Resources/config/routes.yml"
   

4. First Use Case: Access the API docs at /api/doc (e.g., http://localhost/web/app_dev.php/api/doc) to explore available endpoints.

Implementation Patterns

Core Workflows

1. Slot Management:

   • Use RESTful endpoints (e.g., GET /api/slots, POST /api/slots) to create, read, update, or delete slots.
   • Leverage FOSRestBundle for standardized API responses (e.g., JSON, HTTP status codes).

2. Serialization:

   • Configure JMSSerializerBundle to handle slot entity serialization/deserialization. Example:

     # app/config/config.yml
     jms_serializer:
         metadata:
             directories:
                 AisSlotBundle:
                     namespace_prefix: "Ais\\SlotBundle\\Entity"
                     path: "@AisSlotBundle/Resources/config/serializer"
     

3. API Documentation:

   • NelmioApiDocBundle auto-generates Swagger docs. Annotate controllers with @SWG\* tags for clarity:

     use Nelmio\ApiDocBundle\Annotation\SWG;
     
     /**
      * @SWG\Get(
      *     path="/api/slots",
      *     summary="List all slots"
      * )
      */
     public function getSlotsAction()
     {
         // ...
     }
     

4. Dependency Injection:

   • Inject slot services into controllers:

     use Ais\SlotBundle\Service\SlotManager;
     
     class SlotController extends FOS\RestController
     {
         public function __construct(SlotManager $slotManager)
         {
             $this->slotManager = $slotManager;
         }
     }
     

Integration Tips

• Doctrine ORM: Extend Ais\SlotBundle\Entity\Slot for custom fields or behaviors.
• Validation: Use Symfony’s validators (e.g., @Assert\NotBlank) in slot entities.
• Testing: Utilize LiipFunctionalTestBundle for API endpoint testing:

  $client = static::createClient();
  $client->request('GET', '/api/slots');
  $this->assertEquals(200, $client->getResponse()->getStatusCode());
  

Gotchas and Tips

Pitfalls

1. Symfony Version Mismatch:

   • The bundle targets Symfony 2.7.4. Avoid mixing with newer Symfony 3.x/4.x features (e.g., dependency injection changes).
   • Fix: Use symfony/symfony:2.7.* in composer.json.

2. Missing Dependencies:

   • The bundle requires NelmioApiDocBundle, FOSRestBundle, and JMSSerializerBundle. Forgetting to register these will break routes/API docs.
   • Fix: Verify all dependencies are listed in AppKernel.php and composer.json.

3. Route Conflicts:

   • The ais_slots prefix (/api) may clash with existing routes. Customize in routing.yml if needed:

     ais_slots:
       prefix: /custom-prefix
     

4. Serialization Issues:

   • If slot entities aren’t serializing, check:
     • Metadata directories in jms_serializer config.
     • Entity annotations (e.g., @ORM\Entity, @Serializer\ExclusionPolicy).
   • Tip: Use php bin/console debug:serializer to validate mappings.

Debugging

• API Docs Not Loading:

  • Ensure NelmioApiDocBundle is registered after FOSRestBundle in AppKernel.php.
  • Clear cache:

    php bin/console cache:clear
    

• 404 Errors:

  • Verify routes are loaded:

    php bin/console debug:router | grep ais_slots
    

  • Check for typos in route names (e.g., ais_slots vs. ais_slot).

Extension Points

1. Custom Slot Types:

   • Extend Ais\SlotBundle\Entity\Slot and override methods (e.g., getTitle()).
   • Register new entities in Doctrine:

     # app/config/doctrine/orm.yml
     entity_managers:
         default:
             mappings:
                 AisSlotBundle: ~
                 AppBundle:  # Your custom entities
                     type: annotation
                     dir: "%kernel.root_dir%/../src/AppBundle/Entity"
                     prefix: "AppBundle\Entity"
                     alias: AppBundle
     

2. Event Listeners:

   • Subscribe to slot events (e.g., slot.create) via Symfony’s event dispatcher:

     services:
         app.slot_listener:
             class: AppBundle\EventListener\SlotListener
             tags:
                 - { name: kernel.event_listener, event: slot.create, method: onSlotCreate }
     

3. API Extensions:

   • Add custom actions to existing controllers by extending Ais\SlotBundle\Controller\SlotController.
   • Example:

     class CustomSlotController extends SlotController
     {
         public function customAction()
         {
             return $this->handleView($this->view(['data' => 'custom']));
         }
     }
     

     Register the new route in routing.yml:

     custom_slot:
         path: /api/slots/custom
         defaults: { _controller: AppBundle\Controller\CustomSlotController::customAction }
     

Configuration Quirks

• Parameter Handling:

  • Use incenteev/composer-parameter-handler to manage bundle parameters dynamically.
  • Example:

    php bin/console debug:config ais_slot
    

• Asset Management:

  • The bundle includes AsseticBundle for CSS/JS. Configure in config.yml:

    assetic:
        bundles: [AisSlotBundle]