Webapi Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require adrotec/webapi-bundle:dev-master symfony/validator:dev-master
   

   Ensure you’re using Symfony 2.x (this bundle is unmaintained and tied to it).

2. Enable the Bundle: Add to AppKernel.php before JMSSerializerBundle (order matters):

   new Adrotec\WebApiBundle\AdrotecWebApiBundle(),
   new JMS\SerializerBundle\JMSSerializerBundle(),
   

3. Configure Routing: Define a route with {resource} parameter (e.g., /api/users):

   # src/Acme/Bundle/Resources/config/routing.yml
   api:
       path:     /api/{resource}
       defaults: { _controller: AcmeBundle:Api:api }
   

4. Create a Resource Class: Define a class (e.g., User) with properties and validation rules (e.g., @Assert\NotBlank).

5. First API Call: Access /api/users with HTTP methods (GET, POST, etc.) to test CRUD operations. The bundle auto-generates JSON responses for Breeze.js or similar clients.

Implementation Patterns

Core Workflows

1. Resource-Based Routing:

   • Use {resource} in routes to dynamically map to classes (e.g., User, Product).
   • Example: /api/users → User class, /api/products → Product class.

2. Controller-Free API:

   • The bundle’s ApiController handles all CRUD logic. No need to manually define actions like index(), store(), etc.

3. Validation Integration:

   • Use Symfony’s Assert constraints (e.g., @Assert\Email) in your resource classes. The bundle validates requests automatically.

4. Serialization:

   • Leverages JMSSerializerBundle for JSON output. Customize serialization via annotations (e.g., @SerializedName).

5. Breeze.js Compatibility:

   • Designed for Breeze.js clients. Returns responses in Breeze’s expected format (e.g., { data: [...], meta: {...} }).

Integration Tips

• Custom Responses: Override AdrotecWebApiBundle:Api:api in your routing to extend behavior (e.g., add authentication middleware).

  api_custom:
      path:     /api/{resource}
      defaults: { _controller: AcmeBundle:Api:customApi }
  

• Nested Resources: Use dot notation in routes (e.g., /api/users/{user}/posts) and define relationships in your resource classes.

• Pagination: The bundle supports pagination via query parameters (e.g., ?page=1&limit=10). Customize in config.yml:

  adrotec_webapi:
      pagination:
          default_limit: 20
  

• Authentication: Integrate with Symfony’s security system by extending the ApiController or using event listeners (e.g., kernel.request).

Gotchas and Tips

Pitfalls

1. Symfony 2.x Only:

   • Not compatible with Symfony 3+ or Laravel. Avoid migration attempts.

2. JMSSerializerBundle Conflicts:

   • The bundle overrides JMSSerializerBundle behaviors (e.g., naming strategy). If you need custom serialization, extend the bundle’s services or use a separate serializer.

3. Unmaintained:

   • No updates since 2015. Use at your own risk. Fork if critical fixes are needed.

4. Validation Quirks:

   • Ensure symfony/validator is installed (required for Breeze validation). Custom validators may need manual registration.

5. Route Overrides:

   • If you override the api controller, ensure you replicate all bundle logic (e.g., resource resolution, HTTP method handling).

Debugging

• 404 Errors: Verify the {resource} parameter matches a valid class name (case-sensitive). Check routing cache (app/cache).

• Validation Failures: Enable Symfony’s profiler to inspect validation errors. Example response:

  {
      "errors": {
          "email": ["This value should not be blank."]
      }
  }
  

• Serialization Issues: Clear the cache (php app/console cache:clear) after adding/removing @SerializedName annotations.

Extension Points

1. Custom Response Format: Extend the bundle’s ResponseBuilder service to modify JSON structure:

   # config.yml
   adrotec_webapi:
       response_builder: AcmeBundle\Service\CustomResponseBuilder
   

2. Add Middleware: Use Symfony’s event system (e.g., kernel.request) to inject logic before API processing.

3. Custom Actions: Create a separate controller extending ApiController and override methods like handleGet() or handlePost().

4. Database Abstraction: The bundle assumes Doctrine ORM. For custom data sources, override the ResourceManager service.

Tips

• Testing: Use PHPUnit with Symfony’s WebTestCase to test API endpoints. Example:

  $client->request('GET', '/api/users');
  $this->assertJson($client->getResponse()->getContent());
  

• Documentation: Refer to breeze.server.php for client-side integration details.

• Fallback for Laravel: For Laravel projects, consider alternatives like:

  • laravel/api-resources (for API resources).
  • fideloper/proxy + custom controllers (for Breeze.js compatibility).