Guzzle Client Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require devmachine/guzzle-client-bundle
   

   Add the bundle to config/bundles.php:

   Devmachine\GuzzleClientBundle\DevmachineGuzzleClientBundle::class => ['all' => true],
   

2. Configuration: Define clients in config/packages/devmachine_guzzle_client.yaml:

   devmachine_guzzle_client:
       clients:
           api_client:
               base_uri: 'https://api.example.com'
               timeout: 30
               headers:
                   Accept: 'application/json'
               options:
                   verify: false # Disable SSL verification (for testing only)
   

3. First Use Case: Inject the client into a service and make a request:

   use Devmachine\GuzzleClientBundle\Client\ClientInterface;
   
   class MyService
   {
       public function __construct(private ClientInterface $apiClient) {}
   
       public function fetchData()
       {
           $response = $this->apiClient->get('endpoint');
           return json_decode($response->getBody(), true);
       }
   }
   

Implementation Patterns

Dependency Injection

• Service Integration: Use the bundle’s ClientInterface in services to abstract HTTP calls:

  public function __construct(private ClientInterface $client) {}
  

  Autowire works seamlessly with Symfony’s DI container.

• Named Clients: Reference clients by name (e.g., api_client) in services:

  services:
      App\Service\MyService:
          arguments:
              $client: '@devmachine_guzzle_client.api_client'
  

Request Customization

• Dynamic Headers/Options: Override defaults per request:

  $response = $this->client->request('GET', 'endpoint', [
      'headers' => ['Authorization' => 'Bearer token'],
      'query' => ['param' => 'value']
  ]);
  

• Middleware: Attach middleware to clients via config:

  clients:
      api_client:
          middleware: ['Devmachine\GuzzleClientBundle\Middleware\LoggingMiddleware']
  

Workflows

• API Abstraction: Create a facade or repository layer to encapsulate API logic:

  class UserApiRepository
  {
      public function __construct(private ClientInterface $client) {}
  
      public function getUser(int $id): array
      {
          return $this->client->get("/users/{$id}")->json();
      }
  }
  

• Retry Logic: Use Guzzle’s retry middleware (included by default) for transient failures.

Gotchas and Tips

Configuration Quirks

• Base URI Handling: Ensure base_uri in config ends with / if your endpoints are path-based (e.g., https://api.example.com/). Relative paths (e.g., /users) will append correctly.

• SSL Verification: Disable verify: false only in development. Use proper certificates in production.

Debugging

• Logging: Enable Guzzle’s logging middleware for request/response inspection:

  clients:
      api_client:
          middleware: ['Devmachine\GuzzleClientBundle\Middleware\LoggingMiddleware']
  

  Logs appear in Symfony’s monolog channel.

• Error Handling: Catch GuzzleException for HTTP errors:

  try {
      $response = $this->client->get('endpoint');
  } catch (GuzzleException $e) {
      // Handle 4xx/5xx responses
  }
  

Extension Points

• Custom Clients: Extend Devmachine\GuzzleClientBundle\Client\Client to add domain-specific logic:

  class CustomClient extends Client
  {
      public function customMethod()
      {
          return $this->post('/custom', ['data' => 'value']);
      }
  }
  

• Middleware: Create custom middleware by implementing GuzzleHttp\Middleware and register it in config.

• Event Listeners: Subscribe to Guzzle events (e.g., request or response) via Symfony’s event dispatcher.