Http Client Implementation Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require --dev psr-mock/http-client-implementation:^1.0
   

   • Note: Requires PHP 8.1+ (updated in v1.0.1). Ensure your project meets this requirement.

2. First Use Case: Mocking HTTP Calls in Tests

   use Psr\Http\Message\RequestInterface;
   use Psr\Http\Client\ClientInterface;
   use PsrMock\Http\Client\MockClient;
   
   // In your test class:
   $mockClient = new MockClient();
   $mockClient->mockResponse('https://api.example.com/users', '{"id": 1, "name": "John"}');
   
   // Inject into your service under test:
   $service = new MyService($mockClient);
   

3. Where to Look First

   • README for updated setup notes.
   • src/PsrMock/Http/Client/MockClient.php for core functionality (PHP 8.1+ syntax).
   • tests/ directory for usage examples (verify compatibility with PHP 8.1).

Implementation Patterns

Workflows

1. Basic Mocking (PHP 8.1+)

   $mockClient = new MockClient();
   $mockClient->mockResponse('https://api.example.com/data', '{"key": "value"}');
   $response = $mockClient->sendRequest(new \GuzzleHttp\Psr7\Request('GET', 'https://api.example.com/data'));
   $this->assertEquals('{"key": "value"}', $response->getBody()->getContents());
   

2. Dynamic Responses (PHP 8.1+)

   $mockClient->mockResponse(
       'https://api.example.com/users',
       function (RequestInterface $request) {
           $query = $request->getUri()->getQuery();
           return new \GuzzleHttp\Psr7\Response(200, [], json_encode(['query' => $query]));
       }
   );
   

3. Exception Handling (PHP 8.1+)

   $mockClient->mockException('https://api.example.com/error', new \RuntimeException('API down'));
   

4. Integration with Laravel (PHP 8.1+)

   // In Laravel tests:
   $mockClient = new MockClient();
   $this->app->instance(ClientInterface::class, $mockClient);
   

5. Testing Middleware (PHP 8.1+)

   $mockClient = new MockClient();
   $stack = HandlerStack::create();
   $stack->push(Middleware::class);
   $mockClient->setHandler($stack);
   

Integration Tips

• Use with Laravel HTTP Client (PHP 8.1+)

  $httpClient = new \Illuminate\Http\Client\PendingRequest($mockClient);
  $response = $httpClient->get('https://api.example.com/users');
  

• Combine with Factories (PHP 8.1+)

  $mockClient = MockClient::withResponses([
      'https://api.example.com/users' => '{"id": 1}',
      'https://api.example.com/posts' => '{"title": "Test"}',
  ]);
  

Gotchas and Tips

Pitfalls

1. PHP Version Requirement

   • Breaking Change: Minimum PHP version is now 8.1. Projects using PHP < 8.1 will fail.
   • Fix: Update your project or use a lower package version (^0.9).

2. URL Matching Strictness

   • By default, the package uses exact URL matching. Use wildcards or regex for dynamic paths:

     $mockClient->mockResponse('/api/users/*', '{"id": 1}'); // Partial match
     

   • For regex:

     $mockClient->mockResponse('/api/users/[0-9]+', function () { ... });
     

3. Case Sensitivity

   • HTTP methods (GET, Post) are case-insensitive, but ensure consistency in tests.

4. Response Order

   • If multiple responses are mocked for the same URL, the last defined response wins.

5. Handler Overrides

   • If you set a custom handler (e.g., setHandler()), it replaces all mocked responses. Use cautiously.

Debugging

• Verify Mocked Responses

  $mockClient->getMockedResponses(); // Returns all mocked responses.
  

• Check Last Request

  $lastRequest = $mockClient->getLastRequest();
  $this->assertEquals('GET', $lastRequest->getMethod());
  

Config Quirks

• No Built-in Retry Logic
  • If your app uses retries (e.g., Guzzle middleware), mock responses must account for repeated calls.
• No PSR-7 Response Validation
  • Ensure mocked responses are valid PSR-7 responses (e.g., include headers, status code).

Extension Points

1. Custom Response Factories (PHP 8.1+)

   $mockClient->setResponseFactory(function ($url, $response) {
       return new CustomResponse($response);
   });
   

2. Middleware Support (PHP 8.1+)
   • Extend MockClient to support custom middleware in tests:

     class TestableClient extends MockClient {
         public function addTestMiddleware(callable $middleware) {
             $this->getHandler()->push($middleware);
         }
     }
     

3. Logging Requests (PHP 8.1+)

   $mockClient->enableRequestLogging();
   $logs = $mockClient->getRequestLogs();