Service Client Bundle Laravel Package

Getting Started

First Steps

1. Installation Add the bundle via Composer:

   composer require deeep/service-client-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       Deeep\ServiceClientBundle\DeeepServiceClientBundle::class => ['all' => true],
   ];
   

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

   clients:
       my_api:
           url: "https://api.example.com"
           retry:
               max_attempts: 3
               delay: 100
           circuit_breaker:
               enabled: true
               failure_threshold: 5
               reset_timeout: 60
   

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

   use Deeep\ServiceClientBundle\Client\ClientInterface;
   
   class MyService
   {
       public function __construct(private ClientInterface $client) {}
   
       public function fetchData()
       {
           return $this->client->get('my_api', '/data');
       }
   }
   

Implementation Patterns

Core Workflows

1. Multi-Host Routing Dynamically switch endpoints per request:

   clients:
       dynamic_api:
           hosts:
               prod: "https://api.prod.example.com"
               staging: "https://api.staging.example.com"
   

   Use in code:

   $this->client->get('dynamic_api', '/data', ['host' => 'staging']);
   

2. Retry Logic Configure per-client or globally:

   retry:
       default:
           max_attempts: 5
           delay: 200
           backoff: 2.0  # Exponential backoff
   

3. Circuit Breaker Enable for fault tolerance:

   circuit_breaker:
       enabled: true
       failure_threshold: 3
       reset_timeout: 30
   

4. Async Requests (Fibers) Use async() for non-blocking calls:

   $fiber = $this->client->async('my_api', 'GET', '/data');
   $result = $fiber->start();
   

Integration Tips

• Dependency Injection: Prefer constructor injection for clients.
• Middleware: Extend with custom middleware via client.middleware config.
• Testing: Mock ClientInterface for unit tests:

  $this->mock(ClientInterface::class)->shouldReceive('get')->andReturn(['data' => 'test']);
  

Gotchas and Tips

Pitfalls

1. Fiber Compatibility Ensure your PHP version supports Fibers (8.1+). Async calls may fail on older versions. Debug: Check for FiberError exceptions.

2. Circuit Breaker State The breaker state is not persisted across requests by default. Use a shared cache (e.g., Redis) for distributed systems:

   circuit_breaker:
       storage: 'redis://localhost'
   

3. Host Overrides Hardcoding host overrides in requests bypasses routing logic. Prefer config-based host switching.

4. Retry Delays Delays are non-blocking in async mode. Use sleep() in sync mode if needed.

Debugging

• Logs: Enable debug mode in config:

  debug: true
  

• HTTP Traces: Use client.logger to log raw requests/responses.

Extension Points

1. Custom Middleware Implement Deeep\ServiceClientBundle\Client\Middleware\MiddlewareInterface:

   class MyMiddleware implements MiddlewareInterface
   {
       public function handle(Request $request, callable $next)
       {
           // Pre-processing
           $response = $next($request);
           // Post-processing
           return $response;
       }
   }
   

   Register in config:

   client:
       middleware:
           - MyMiddleware
   

2. Response Transformers Override default JSON/XML parsing via client.response_transformer.

3. Event Listeners Subscribe to client.request and client.response events for observability.