Transkripbundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ais/transkripbundle:dev-master
   

   Ensure your composer.json includes the required dependencies (FOSRestBundle, JMSSerializerBundle, NelmioApiDocBundle).

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

   new Ais\TranskripBundle\AisTranskripBundle(),
   new Nelmio\ApiDocBundle\NelmioApiDocBundle(),
   new FOS\RestBundle\FOSRestBundle(),
   new JMS\SerializerBundle\JMSSerializerBundle(),
   

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

   ais_transkrips:
     type: rest
     prefix: /api
     resource: "@AisTranskripBundle/Resources/config/routes.yml"
   NelmioApiDocBundle:
     resource: "@NelmioApiDocBundle/Resources/config/routing.yml"
     prefix: /api/doc
   

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

Implementation Patterns

Core Workflows

1. RESTful API Development:

   • Leverage FOSRestBundle for standardized API responses (e.g., @Rest\View annotations).
   • Use NelmioApiDocBundle to auto-generate Swagger docs for client-side integration.

2. Entity Management:

   • TranskripBundle likely includes Doctrine entities (e.g., Transkrip). Extend or override them in src/Ais/TranskripBundle/Entity/:

     namespace AppBundle\Entity;
     use Ais\TranskripBundle\Entity\Transkrip as BaseTranskrip;
     
     class Transkrip extends BaseTranskrip { ... }
     

3. Serialization:

   • Customize serialization with JMSSerializerBundle via @Serializer\Annotation\Type or YAML configs in config/serializer/.

4. Form Handling:

   • Use Symfony forms with FOSRestBundle's FormHandler for API input validation.

Integration Tips

• Event Listeners: Hook into transkrip.* events (e.g., transkrip.pre_persist) via services.yml:

  services:
    app.transkrip_listener:
      class: AppBundle\EventListener\TranskripListener
      tags:
        - { name: kernel.event_listener, event: transkrip.pre_persist, method: onPrePersist }
  

• Custom Controllers: Extend bundle controllers (e.g., TranskripController) in your app:

  namespace AppBundle\Controller;
  use Ais\TranskripBundle\Controller\TranskripController as BaseController;
  
  class TranskripController extends BaseController { ... }
  

Gotchas and Tips

Pitfalls

1. Symfony Version Lock:

   • Bundle targets Symfony 2.7.4. Avoid mixing with newer Symfony versions (e.g., 3.x/4.x) without forks.

2. Missing Dependencies:

   • Ensure NelmioApiDocBundle, FOSRestBundle, and JMSSerializerBundle are installed. The bundle requires these.

3. Route Conflicts:

   • Prefix routes explicitly in routing.yml to avoid clashes with other bundles.

4. Dev-Master Instability:

   • Use dev-master cautiously; expect breaking changes. Consider forking for production.

Debugging

• API Docs Issues:

  • Clear cache (php app/console cache:clear) if docs fail to load.
  • Verify NelmioApiDocBundle is registered after FOSRestBundle.

• Serialization Errors:

  • Check config/serializer/Mapping/TranskripBundle.yaml for missing annotations or circular references.

Extension Points

1. Custom Fields: Add fields to Transkrip entity and update serialization config:

   Ais\TranskripBundle\Entity\Transkrip:
     exclusion_policy: ALL
     properties:
       customField:
         expose: true
   

2. Validation: Extend validation in config/validation/transkrip.yml:

   Ais\TranskripBundle\Entity\Transkrip:
     constraints:
       - Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity: { fields: ["slug"] }
   

3. API Extensions: Override routes in app/config/routing.yml:

   app_transkrip_custom:
     type: rest
     resource: "@AppBundle/Resources/config/routing.yml"