Api2Symfony Bundle Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation:

   composer require creads/api2symfony-bundle 1.0.*@dev
   

   Register the bundle in AppKernel.php under dev/test environments only.

2. First Use Case: Generate a controller from a RAML file:

   php app/console api2symfony:generate:raml path/to/api.raml Acme\DemoBundle
   

   Output will be cached in app/cache/dev/api2symfony/.

3. Where to Look First:

   • Bundle Docs (limited, but covers core functionality).
   • Underlying Library (for deeper customization).
   • app/cache/dev/api2symfony/ (generated controllers).

Implementation Patterns

Workflows

1. RAML-to-Controller Generation:

   • Run the command with a RAML file path and target namespace.
   • Generated controllers are auto-placed in app/cache/dev/api2symfony/ with a versioned directory structure.
   • Example:

     php app/console api2symfony:generate:raml api/raml/posts.raml App\Controller\Api
     

     Outputs to:

     app/cache/dev/api2symfony/App/Controller/Api/1_0_1_alpha/PostsController.php
     

2. Integration with Symfony Workflow:

   • Dev/Test Only: Bundle is auto-registered only in dev/test environments (avoids runtime overhead).
   • Cache Awareness: Generated files are cached; clear cache (php bin/console cache:clear) to regenerate.
   • Versioning: RAML version (version field in spec) dictates the output directory. Update RAML to trigger regeneration.

3. Extending Functionality:

   • Override generated controllers by placing custom versions in src/ (Symfony’s autoloader priority).
   • Use traits or parent classes in custom controllers to reuse logic from generated ones.

Tips for Daily Use

• RAML Structure:

  • Ensure RAML files include:

    #%RAML 0.8
    title: YourAPI
    version: 1.0.0  # Critical for cache paths
    

  • Use /{id} for resource-specific routes (auto-generates getPost(), putPost(), etc.).

• Symfony Integration:

  • Annotate generated controllers with @Route or use routing.yml to expose endpoints.
  • Inject services (e.g., Doctrine repositories) via constructor injection in custom controllers.

• Testing:

  • Mock generated controllers in tests by extending them or using partial mocks.
  • Test RAML changes by clearing the cache and regenerating.

Gotchas and Tips

Pitfalls

1. Environment Restrictions:

   • Bundle only works in dev/test. Accidentally enabling it in prod will break routing (controllers won’t exist in src/).
   • Fix: Use a feature flag or environment check in AppKernel.php.

2. Cache Overwriting:

   • Regenerating RAML with the same version won’t overwrite cached files. Update the version field in RAML to force regeneration.
   • Debug Tip: Delete the cache directory manually if stuck:

     rm -rf app/cache/dev/api2symfony/
     

3. Limited Format Support:

   • Only RAML is fully supported. Blueprint/Swagger are "planned" but broken. Use RAML or pre-process other formats to RAML.
   • Workaround: Convert Swagger/Blueprint to RAML using tools like Swagger-to-RAML.

4. Generated Code Quality:

   • Output is basic CRUD scaffolding. Expect:
     • No validation (add Symfony Validators manually).
     • No authentication (integrate with Symfony’s security component).
     • Hardcoded JSON responses (customize via controller overrides).

5. Namespace Collisions:

   • Generated controllers use the target namespace exactly as provided. Typos (e.g., Acme\DemoBundl) will fail.
   • Fix: Verify namespace exists in composer.json or src/.

Debugging Tips

1. Command Errors:

   • Check RAML syntax with a validator like RAML Lint.
   • Enable debug mode (APP_DEBUG=1) for detailed command output.

2. Missing Controllers:

   • Confirm the cache directory exists and is writable:

     mkdir -p app/cache/dev/api2symfony/
     chmod -R 775 app/cache/dev/
     

   • Verify the RAML file path is correct (use absolute paths if needed).

3. Routing Issues:

   • Generated controllers lack @Route annotations. Add them manually or use Symfony’s routing.yml:

     api_posts:
         resource: "@Api2SymfonyBundle/Resources/config/routing.yml"
         prefix: /api
     

Extension Points

1. Custom Templates:

   • Override the Twig templates used for generation by copying files from vendor/creads/api2symfony-bundle/Resources/views/ to app/Resources/Api2SymfonyBundle/views/.

2. Post-Generation Hooks:

   • Use Symfony’s kernel.request event to modify generated controllers dynamically (e.g., inject services):

     // src/EventListener/ApiControllerListener.php
     public function onKernelRequest(GetResponseEvent $event) {
         if ($event->getRequest()->attributes->has('_controller') &&
             strpos($event->getRequest()->attributes->get('_controller'), 'Api2Symfony') !== false) {
             // Modify controller logic here
         }
     }
     

3. RAML Preprocessing:

   • Extend the bundle by adding a pre-generate hook to transform RAML (e.g., add auth headers):

     # app/config.yml
     api2symfony:
         preprocessors:
             - App\Preprocessor\AddAuthHeaders
     

Config Quirks

• No Config File: The bundle has no config.yml options. All behavior is driven by the api2symfony:generate:raml command.
• Version Field: The version in RAML must match the cache directory structure. Use semantic versioning (e.g., 1.0.0-alpha).