Http Client Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require dormilich/http-client-bundle
   

   Ensure your project uses symfony/http-client (PSR-18) and a PSR-17 implementation (e.g., symfony/http-foundation).

2. Basic Setup: The bundle auto-configures with default JSON and URL transformers. No additional steps are required unless customization is needed.

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

   use Dormilich\HttpClientBundle\Client\ClientInterface;
   use Psr\Http\Message\RequestInterface;
   
   class MyService
   {
       public function __construct(private ClientInterface $client) {}
   
       public function fetchData(): array
       {
           $request = $this->client->createRequest('GET', 'https://api.example.com/data');
           $response = $this->client->sendRequest($request);
           return json_decode($response->getBody(), true);
       }
   }
   

Implementation Patterns

Core Workflows

1. Request Creation: Use the client to create requests with headers, body, and query parameters:

   $request = $this->client->createRequest('POST', '/endpoint');
   $request = $request
       ->withHeader('Content-Type', 'application/json')
       ->withBody($this->client->getEncoder()->encode(json_encode(['key' => 'value'])));
   

2. Response Handling: Decode responses using built-in transformers:

   $response = $this->client->sendRequest($request);
   $data = $this->client->getDecoder()->decode($response->getBody());
   

3. Tagging Clients: Configure multiple clients in services.yaml for different environments or use cases:

   services:
       App\Service\ApiClient:
           arguments:
               $client: '@dormilich_http_client.api'
   tags:
       - { name: dormilich_http_client.client, alias: 'api' }
   

4. Custom Transformers: Extend or replace transformers (e.g., for XML or custom formats):

   $encoder = new \Dormilich\HttpClient\Encoder\JsonEncoder(JSON_THROW_ON_ERROR);
   $this->client->setEncoder($encoder);
   

Integration Tips

• Symfony Forms: Use URL transformers to handle form data submission.
• API Clients: Abstract API logic into services for reusability.
• Middleware: Chain middleware (e.g., auth, logging) via PSR-18 client decorators.

Gotchas and Tips

Pitfalls

1. PSR Compliance: Ensure your PSR-17/18 implementations are compatible. symfony/http-client is recommended but not mandatory.

   • Debugging: Check for Psr\NotSupportedException if unsupported features are used.

2. JSON Configuration: Incorrect JSON_* constants (e.g., JSON_OBJECT_AS_ARRAY) may cause silent failures.

   • Fix: Validate constants with json_encode([], JSON_OBJECT_AS_ARRAY).

3. URL Encoding: The php strategy relies on PHP’s native parsing, which may not handle edge cases (e.g., Unicode).

   • Tip: Use nvp for strict name=value pairs.

4. Service Tagging: Misconfigured tags (e.g., typos in alias) will silently ignore the client.

   • Debugging: Verify tags with debug:container or dump(container.get('dormilich_http_client.api')).

Tips

1. Configuration Overrides: Override defaults in config/packages/dormilich_http_client.yaml:

   dormilich_http_client:
       encoder:
           json: !php/const JSON_THROW_ON_ERROR
           url: nvp
   

2. Testing: Mock the client interface for unit tests:

   $this->client = $this->createMock(ClientInterface::class);
   $this->client->method('sendRequest')->willReturn(new Response(200, [], file_get_contents('fixture.json')));
   

3. Performance: Reuse request objects and clients where possible to avoid overhead.

4. Extending: Create custom transformers by implementing Dormilich\HttpClient\Encoder\EncoderInterface or DecoderInterface.

5. Debugging: Enable Symfony’s profiler to inspect requests/responses in the HTTP client panel.