Getting Started

Minimal Setup

Installation Add the bundle to composer.json:

composer require misd/guzzle-bundle

Enable in config/bundles.php:

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

Basic Configuration Define a client in config/packages/misd_guzzle.yaml:

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

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

use Misd\GuzzleBundle\Client\ClientInterface;

class MyController
{
    public function __construct(private ClientInterface $client)
    {
    }

    public function fetchData()
    {
        $response = $this->client->get('endpoint');
        $data = json_decode($response->getBody(), true);
        return $this->render('template.html.twig', ['data' => $data]);
    }
}

Implementation Patterns

Common Workflows

1. Service-Based API Clients

Create dedicated services for API interactions:

// src/Service/ExternalApiService.php
namespace App\Service;

use Misd\GuzzleBundle\Client\ClientInterface;

class ExternalApiService
{
    public function __construct(private ClientInterface $client)
    {
    }

    public function getUserData(int $id): array
    {
        $response = $this->client->get("/users/{$id}");
        return json_decode($response->getBody(), true);
    }
}

2. ParamConverter Integration

Use with SensioFrameworkExtraBundle for automatic request handling:

# config/packages/misd_guzzle.yaml
misd_guzzle:
    param_converter:
        enabled: true
        clients:
            - default

Annotate controller actions:

use Sensio\Bundle\FrameworkExtraBundle\Configuration\ParamConverter;

class UserController
{
    /**
     * @ParamConverter("user", converter="misd_guzzle.param_converter")
     */
    public function show(User $user)
    {
        // $user is automatically fetched via API
    }
}

3. JMS Serializer Integration

Enable serialization/deserialization:

# config/packages/misd_guzzle.yaml
misd_guzzle:
    clients:
        default:
            serializer:
                enabled: true
                options:
                    groups: ['api']

Use in services:

$user = $this->client->get('/users/1', User::class);

4. Middleware Stack

Extend the client with middleware (e.g., logging, retries):

# config/packages/misd_guzzle.yaml
misd_guzzle:
    clients:
        default:
            middleware:
                - Misd\GuzzleBundle\Middleware\LoggingMiddleware
                - Misd\GuzzleBundle\Middleware\RetryMiddleware

5. Async Requests

Use Guzzle’s async capabilities:

$promises = [];
$promises[] = $this->client->getAsync('endpoint1');
$promises[] = $this->client->postAsync('endpoint2', ['data' => []]);

$results = \Guzzle\Promise\Utils::settle($promises)->wait();

Integration Tips

Symfony Profiler

Requests are automatically logged in the Symfony Profiler under the "Guzzle" tab. Useful for debugging:

Response times
Headers
Payloads

Dependency Injection

Prefer type-hinting ClientInterface over concrete implementations for flexibility:

public function __construct(private ClientInterface $client)

Configuration Overrides

Override client configurations per environment (e.g., config/packages/dev/misd_guzzle.yaml):

misd_guzzle:
    clients:
        default:
            base_url: 'https://dev-api.example.com'
            timeout: 60

Testing

Mock the ClientInterface in tests:

$mockClient = $this->createMock(ClientInterface::class);
$mockClient->method('get')->willReturn(new Response(200, [], '{}'));

$service = new ExternalApiService($mockClient);

Gotchas and Tips

Pitfalls

1. Outdated Guzzle Version

The bundle targets Guzzle 3, which is deprecated (EOL 2016). Avoid for new projects.
Workaround: Use php-http/guzzle6-adapter or migrate to a modern bundle like nelmio/api-client-bundle.

2. SensioFrameworkExtraBundle Dependency

The ParamConverter requires SensioFrameworkExtraBundle. If missing, disable it in config:
```
misd_guzzle:
    param_converter:
        enabled: false
```

3. JMS Serializer Conflicts

Ensure JMSSerializerBundle is installed and configured before enabling serialization:
```
composer require jms/serializer-bundle
```

Debug serialization errors with:

php bin/console debug:container misd_guzzle.client.default

4. Profiler Overhead

Disabling the profiler in production reduces memory usage:
```
misd_guzzle:
    profiler:
        enabled: false
```

5. Timeout Handling

Default timeout is 30 seconds. Increase for slow APIs:

misd_guzzle:
    clients:
        default:
            timeout: 120

Debugging Tips

1. Enable Debug Mode

Add to config/packages/dev/misd_guzzle.yaml:

misd_guzzle:
    debug: true

Triggers Guzzle deprecation warnings in Symfony debug toolbar.

2. Log Raw Requests/Responses

Use the LoggingMiddleware:

misd_guzzle:
    clients:
        default:
            middleware:
                - Misd\GuzzleBundle\Middleware\LoggingMiddleware
            options:
                logging: true

Logs appear in var/log/dev.log.

3. Validate Config

Check for syntax errors:

php bin/console debug:config misd_guzzle

4. Handle Exceptions

Catch Misd\GuzzleBundle\Exception\ClientException and Misd\GuzzleBundle\Exception\ServerException:

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

Extension Points

1. Custom Middleware

Create middleware classes (e.g., for auth):

// src/Middleware/CustomAuthMiddleware.php
namespace App\Middleware;

use Guzzle\Common\Event;
use Guzzle\Common\Middleware;

class CustomAuthMiddleware implements Middleware
{
    public function __invoke(Event $event)
    {
        $event['request']->setHeader('X-Auth-Token', 'your_token');
    }
}

misd_guzzle:
    clients:
        default:
            middleware:
                - App\Middleware\CustomAuthMiddleware

2. Custom ParamConverter

Extend the base converter for custom logic:

// src/ParamConverter/CustomApiConverter.php
namespace App\ParamConverter;

use Misd\GuzzleBundle\ParamConverter\ApiConverter;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\ParamConverter;

class CustomApiConverter extends ApiConverter
{
    protected function getApiUrl($name, array $options)
    {
        return 'custom/' . parent::getApiUrl($name, $options);
    }
}

services:
    app.param_converter.custom:
        class: App\ParamConverter\CustomApiConverter
        tags:
            - { name: 'misd_guzzle.param_converter', alias: 'custom' }

3. Event Subscribers

Listen to Guzzle events (e.g., for analytics):

// src/EventSubscriber/GuzzleSubscriber.php
namespace App\EventSubscriber;

use Guzzle\Common\Event;
use Guzzle\Common

Guzzle Bundle Laravel Package