Httpful Laravel Package

Getting Started

Install via Composer: composer require nategood/httpful. Begin with a simple GET request to fetch and parse JSON from an API:

$response = \Httpful\Request::get('https://api.example.com/users')
    ->expectsJson()
    ->send();

foreach ($response->body->users as $user) {
    echo $user->name . "\n";
}

Start here: the README includes basic examples; explore the examples/ directory if present in the repo for patterns like authentication or POSTing form data.

Implementation Patterns

• Fluent chaining for common HTTP verbs:

  \Httpful\Request::post('https://api.example.com/users')
      ->sendsJson()
      ->body(['name' => 'Bob'])
      ->addHeader('Authorization', "Bearer {$token}")
      ->timeout(15)
      ->send();
  

• Smart content negotiation: Use ->sendsJson(), ->sendsFormUrlEncoded(), and ->expectsJson() to auto-set headers and deserialize responses—no manual json_encode() or json_decode() needed.
• Response introspection: Access parsed JSON/XML via $response->body, raw string with $response->raw_body, HTTP status code via $response->code, and headers via $response->headers.
• Testability: Wrap Httpful\Request in a service class (e.g., UserService) and mock the client in tests:

  $mockResponse = Mockery::mock(\Httpful\Response::class);
  $mockResponse->shouldReceive('body')->andReturn((object)['id' => 123]);
  $client = Mockery::mock(\Httpful\Request::class);
  $client->shouldReceive('send')->andReturn($mockResponse);
  

• Custom handlers: Register fallback or logging handlers via Httpful\Client::registerHandler() for advanced protocol support (e.g., mocking in test environments).

Gotchas and Tips

• Inactive maintenance (last commit ~2017): Explicitly require a stable tag (^1.0) and verify PHP 8.x compatibility—some users report issues with strict error reporting or json_decode strictness.
• SSL/timeout edge cases: If encountering SSL: handshake timed out or silent failures, configure cURL options explicitly:

  ->options(['curl' => [
      CURLOPT_TIMEOUT => 10,
      CURLOPT_SSL_VERIFYPEER => true,
      CURLOPT_SSL_VERIFYHOST => 2
  ]])
  

• Parses JSON but not YAML/CSV: Use ->expects('application/json') to enforce JSON parsing or fallback to ->raw_body for non-standard formats. For XML, use ->expectsXml() and access via $response->body->xpath(...).
• No built-in retry logic: Implement retries in your application layer (e.g., try { ... } catch (\Exception $e) { retry(...) }), as the client offers no exponential backoff.
• Laravel note: Avoid in new code—use Laravel’s built-in Http:: client (Guzzle-based) instead. This package is best reserved for legacy integrations, CLI scripts, or where minimal dependencies are critical.