Guzzle Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require aadrian-alexandru/guzzle-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       AadrianAlexandru\GuzzleBundle\CsaGuzzleBundle::class => ['all' => true],
   ];
   

2. Configure a Client Define a client in config/packages/csa_guzzle.yaml:

   csa_guzzle:
       clients:
           api:
               base_url: 'https://api.example.com'
               timeout: 30
               options:
                   headers:
                       'Accept': 'application/json'
   

3. First Use Case: HTTP Request Inject the client into a service/controller:

   use AadrianAlexandru\GuzzleBundle\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

Workflows

1. Dynamic Client Configuration Override client settings per environment (e.g., dev vs. prod):

   # config/packages/csa_guzzle.yaml
   csa_guzzle:
       clients:
           api:
               base_url: '%env(API_URL)%'
               middleware:
                   - 'csa_guzzle.middleware.profiler'
                   - 'csa_guzzle.middleware.logger'
   

2. Middleware Stack Attach middleware globally or per-client:

   csa_guzzle:
       clients:
           api:
               middleware:
                   - '@App\Middleware\AuthMiddleware'  # Custom middleware
                   - 'csa_guzzle.middleware.cache'    # Built-in cache
   

3. Dependency Injection Tag clients for autowiring (Symfony 4.3+):

   services:
       App\Service\MyService:
           arguments:
               $client: '@csa_guzzle.client.api'
   

4. Async Requests Use Symfony’s HttpClient integration for async tasks:

   $this->apiClient->getAsync('endpoint')->then(
       function (ResponseInterface $response) { /* ... */ }
   );
   

Integration Tips

• Symfony Messenger: Combine with symfony/messenger for async HTTP calls.
• API Platform: Use the bundle’s profiler integration to debug API Platform clients.
• Doctrine Cache: Leverage csa_guzzle.middleware.cache with Doctrine cache adapters.

Gotchas and Tips

Pitfalls

1. Middleware Order Matters Middleware executes in the order defined. Place logger after profiler to avoid duplicate logs:

   middleware:
       - 'csa_guzzle.middleware.profiler'
       - 'csa_guzzle.middleware.logger'
   

2. Debug Toolbar Visibility Ensure APP_DEBUG=true in .env to see Guzzle requests in the toolbar. Profiler data may not appear in production.

3. Deprecated Features Avoid service_descriptions (deprecated in 1.3+). Use Symfony’s native HttpClient for service metadata.

4. PHP 8.0+ Compatibility While the fork supports PHP 8.0, test with guzzlehttp/guzzle:^7.0 for edge cases (e.g., named arguments in middleware).

Debugging

• Enable Verbose Logging Add to config/packages/monolog.yaml:

  handlers:
      guzzle:
          type: stream
          path: '%kernel.logs_dir%/guzzle.log'
          level: debug
  

  Then configure the client to use the logger middleware.

• Timeline Profiler Check the Symfony profiler’s "Timeline" tab for request duration breakdowns.

Extension Points

1. Custom Middleware Implement GuzzleMiddlewareInterface:

   use AadrianAlexandru\GuzzleBundle\Client\Middleware\GuzzleMiddlewareInterface;
   
   class MyMiddleware implements GuzzleMiddlewareInterface {
       public function handle(RequestInterface $request, callable $next) {
           // Modify request/response
           return $next($request);
       }
   }
   

   Register in services.yaml:

   services:
       App\Middleware\MyMiddleware:
           tags: ['csa_guzzle.middleware']
   

2. Override Client Factory Extend ClientFactory to customize client creation:

   use AadrianAlexandru\GuzzleBundle\Client\ClientFactory;
   
   class CustomClientFactory extends ClientFactory {
       protected function createClient(array $config) {
           $client = parent::createClient($config);
           // Add custom logic (e.g., default headers)
           return $client;
       }
   }
   

   Bind in services.yaml:

   AadrianAlexandru\GuzzleBundle\Client\ClientFactory: '@App\CustomClientFactory'
   

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

   use AadrianAlexandru\GuzzleBundle\Event\GuzzleEvents;
   
   class GuzzleSubscriber implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [
               GuzzleEvents::REQUEST => 'onRequest',
           ];
       }
   }