Tesla Client Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Add the bundle to composer.json:

   "require": {
       "24hoursmedia/tesla-client-bundle": "master-dev"
   }
   

   Run composer update and register the bundle in AppKernel.php:

   new Tesla\Bundle\ClientBundle\TeslaClientBundle(),
   

2. First Use Case Fetch a URL using the HTTP client factory:

   $factory = $this->get('tesla_client.http_client_factory');
   $httpClient = $factory->get('https://api.example.com');
   $request = $httpClient->createRequest('https://api.example.com/data');
   $response = $httpClient->execute($request);
   $content = $response->getContent(); // Process response
   

3. Where to Look First

   • Service Configuration: Check Resources/config/services.yml for default configurations.
   • Client Factory: Explore HttpClientFactory for creating clients with custom base URLs.
   • Request/Response Classes: Review TeslaRequest and TeslaResponse for request/response manipulation.

Implementation Patterns

Core Workflows

1. Client Creation Use the factory to instantiate clients with different base URLs or configurations:

   $client = $factory->get('https://api.example.com', ['timeout' => 30]);
   

2. Request Customization Extend TeslaRequest to add headers, query params, or auth:

   $request = $client->createRequest('https://api.example.com/endpoint');
   $request->setHeader('Authorization', 'Bearer token');
   $request->setQuery(['param' => 'value']);
   

3. Response Handling Parse responses with built-in methods:

   $response = $client->execute($request);
   $data = json_decode($response->getContent(), true);
   $status = $response->getStatusCode();
   

4. Caching Integration Leverage the bundled caching layer for repeated requests:

   $cachedClient = $factory->get('https://api.example.com', ['cache' => true]);
   

5. Proxy Support Configure proxies via DI or factory options:

   $proxyClient = $factory->get('https://api.example.com', [
       'proxy' => ['http' => 'tcp://proxy.example.com:8080']
   ]);
   

Integration Tips

• Dependency Injection: Inject HttpClientInterface directly into services for cleaner code.
• Configuration: Override default settings via config.yml or environment variables.
• Error Handling: Extend TeslaResponse to add custom exception handling for HTTP errors.

Gotchas and Tips

Pitfalls

1. Deprecated Symfony 2 The bundle is designed for Symfony 2, which may cause compatibility issues with newer Symfony versions (e.g., DI changes, HTTP client updates).

   • Workaround: Use a wrapper or fork for Symfony 3+/4+/5+.

2. Limited Documentation The README is sparse; explore the source (src/Tesla/Bundle/ClientBundle/) for undocumented features.

   • Tip: Check HttpClientFactory and TeslaRequest for hidden methods.

3. Caching Quirks The caching layer may not support all HTTP methods or edge cases (e.g., conditional requests).

   • Tip: Test caching thoroughly with ETag/Last-Modified headers.

4. Proxy Configuration Proxy settings are passed as raw curl options, which may not align with modern PHP HTTP clients (e.g., Guzzle).

   • Tip: Validate proxy URLs/ports before use.

5. No Built-in Retries The bundle lacks retry logic for transient failures (e.g., 503 errors).

   • Tip: Implement middleware or wrap the client in a retry decorator.

Debugging

• Enable Verbose Logging Add CURLOPT_VERBOSE to curl options to debug requests:

  $client = $factory->get('https://api.example.com', [
      'curl_options' => [CURLOPT_VERBOSE => true]
  ]);
  

  Log output to a file with CURLOPT_STDERR.

• Check Response Headers Use getHeaders() on TeslaResponse to inspect raw headers for clues:

  $headers = $response->getHeaders();
  

Extension Points

1. Custom Request Classes Extend TeslaRequest to add domain-specific logic:

   class ApiRequest extends TeslaRequest {
       public function setAuthToken($token) {
           $this->setHeader('X-Auth-Token', $token);
       }
   }
   

2. Response Transformers Override TeslaResponse to auto-transform JSON/XML:

   class JsonResponse extends TeslaResponse {
       public function getData() {
           return json_decode($this->getContent(), true);
       }
   }
   

3. Middleware Support Use Symfony’s event system to intercept requests/responses:

   # config.yml
   tesla_client:
       listeners:
           request: ['App\EventListener\AddAuthHeaderListener']
   

4. Testing Mock HttpClientInterface in tests to avoid real HTTP calls:

   $mockClient = $this->createMock(HttpClientInterface::class);
   $mockClient->method('execute')->willReturn($mockResponse);
   $this->container->set('tesla_client.http_client', $mockClient);