Request Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require cmrweb/request-bundle
   

   For non-Flex projects, add Cmrweb\RequestBundle\RequestBundle::class to config/bundles.php.

2. Configure Environment: Add to .env:

   API_ROOT_URL="https://api.example.com/"
   API_KEY="your_api_key_here"
   

3. First Use Case: Extend AbstractApiRequest in a service:

   use Cmrweb\RequestBundle\AbstractApiRequest;
   
   class MyRequestService extends AbstractApiRequest
   {
       protected $endpoint = 'users';
   
       public function fetchUsers()
       {
           return $this->get();
       }
   }
   

   Inject the service and call fetchUsers().

Implementation Patterns

Core Workflows

1. API Request Abstraction: Extend AbstractApiRequest to define endpoints and methods:

   class UserService extends AbstractApiRequest
   {
       protected $endpoint = 'users';
   
       public function create(array $data)
       {
           return $this->post($data);
       }
   }
   

2. Configuration Management: Use services.yaml to centralize API settings:

   services:
       App\Service\UserService:
           arguments:
               $url: '%cmrweb.api.url%'
               $apiKey: '%cmrweb.api.key%'
   

3. Request Customization: Override getHeaders() or getOptions() for per-request tweaks:

   protected function getHeaders()
   {
       return array_merge(parent::getHeaders(), [
           'X-Custom-Header' => 'value',
       ]);
   }
   

4. Error Handling: Implement handleResponse() to customize error responses:

   protected function handleResponse($response)
   {
       if ($response->getStatusCode() === 404) {
           throw new UserNotFoundException();
       }
       return parent::handleResponse($response);
   }
   

5. Dependency Injection: Inject the service into controllers:

   public function __construct(private UserService $userService) {}
   
   public function index()
   {
       $users = $this->userService->fetchUsers();
       // ...
   }
   

Gotchas and Tips

Common Pitfalls

1. Missing Configuration: Ensure .env variables (API_ROOT_URL, API_KEY) are set. Validate via:

   php bin/console debug:config cmrweb
   

2. Endpoint Mismatches: Double-check $endpoint in extended classes. Use absolute paths (e.g., /api/v1/users) if needed.

3. CORS/Headers: If API requires custom headers, override getHeaders() in your service class.

4. Rate Limiting: The bundle doesn’t handle retries by default. Use a middleware or decorator pattern for exponential backoff.

5. Symfony Flex Compatibility: If using Symfony 5.4+, ensure config/bundles.php is auto-generated. Manually add the bundle if missing.

Debugging Tips

• Log Requests: Override logRequest() in your service to dump payloads:

  protected function logRequest($method, $url, $data)
  {
      $this->logger->debug(sprintf(
          'Request: %s %s | Data: %s',
          $method,
          $url,
          json_encode($data)
      ));
  }
  

• Response Inspection: Use var_dump($this->getResponse()) in handleResponse() to debug raw responses.

Extension Points

1. Custom HTTP Clients: Override createClient() to use Guzzle with custom plugins:

   protected function createClient()
   {
       $client = parent::createClient();
       $client->getConfig()['debug'] = true; // Enable debug
       return $client;
   }
   

2. Authentication: Extend getAuthHeaders() for token-based auth:

   protected function getAuthHeaders()
   {
       return [
           'Authorization' => 'Bearer ' . $this->getApiKey(),
       ];
   }
   

3. Middleware: Add request/response middleware via services.yaml:

   services:
       App\Middleware\ApiLoggingMiddleware:
           tags:
               - { name: kernel.event_listener, event: kernel.request, method: onKernelRequest }