Http Laravel Package

Product Decisions This Supports

• Standardization of HTTP Clients: Replace inconsistent cURL implementations across the codebase with a PSR-7/PSR-17-compliant client, ensuring interoperability with Laravel’s middleware, request/response handling, and third-party libraries.
• API-Centric Development: Accelerate integration with external APIs (e.g., payment gateways, SaaS platforms) by providing a consistent, type-safe interface for HTTP requests, reducing debugging time for API-related issues.
• Build vs. Buy Decision: Avoid over-engineering a custom HTTP client when a lightweight, standards-compliant alternative exists. Justify adoption by highlighting its dependency on Laminas Diactoros (a battle-tested PSR-7/17 implementation) and minimal overhead.
• Key Use Cases:
  • Legacy Code Modernization: Replace raw curl_exec() calls in legacy PHP/Laravel applications with a maintainable, standards-aligned client.
  • Middleware Integration: Leverage PSR-17 factories to dynamically construct requests/responses for middleware pipelines (e.g., authentication, logging).
  • Testing and Mocking: Simplify unit testing by mocking PSR-7 interfaces (e.g., RequestInterface, ResponseInterface) without coupling to cURL.
  • Event-Driven Workflows: Process webhooks or asynchronous HTTP callbacks using PSR-17 factories for request parsing and response generation.

When to Consider This Package

• Adopt if:

  • Your team prioritizes PSR compliance and minimalism over feature-rich HTTP clients (e.g., retries, middleware, async support).
  • You’re working in a Laravel-centric environment where PSR-7/17 interoperability is critical (e.g., integrating with Laravel’s middleware stack or existing PSR-17 factories).
  • Your use case requires fine-grained cURL control (e.g., SSL verification, custom headers, timeouts) without the complexity of Guzzle or Symfony’s HTTP client.
  • You need PSR-17 factory support for dynamic request/response construction (e.g., in middleware, testing, or event handlers).
  • Your project avoids Laravel-specific abstractions (e.g., HttpClient facade) and prefers standards-based solutions.

• Look elsewhere if:

  • You require built-in retry logic, HTTP/2 support, or advanced middleware (evaluate Guzzle or Symfony HTTP Client).
  • Your stack heavily relies on Laravel’s HttpClient facade or Eloquent/Queue integrations (this package lacks those).
  • You need asynchronous/non-blocking requests (this is synchronous and cURL-based).
  • Your team lacks familiarity with PSR-7/PSR-17 interfaces, as this package enforces strict compliance with those standards.
  • You’re building a microservice where async HTTP clients (e.g., ReactPHP) are preferred.

How to Pitch It (Stakeholders)

For Executives:

"This package provides a lean, standards-based HTTP client that replaces fragmented cURL code with a maintainable, scalable layer—reducing API integration risks and developer onboarding time. By adhering to PSR-7/PSR-17, we ensure compatibility with Laravel’s ecosystem while keeping the solution lightweight and future-proof. It’s ideal for API-heavy applications where simplicity and compliance matter more than advanced features like retries or async support. Adopting this client will reduce technical debt from ad-hoc HTTP implementations and align with modern PHP standards."

For Engineering:

• Pros:

  • PSR-7/PSR-17 Compliance: Seamlessly integrates with Laravel’s middleware, request/response handling, and PSR-17 factories (e.g., StreamFactory, UriFactory).
  • Laminas Diactoros Backing: Built on a mature, widely used PSR-7 implementation, ensuring stability and interoperability.
  • Explicit Control: Fine-tune cURL options (e.g., SSL, timeouts, custom headers) via constructor or configuration, without bloating the codebase.
  • Testability: Mock PSR-7 interfaces easily (e.g., for unit tests) by swapping the client with a test double.
  • Low Overhead: ~500 LOC vs. Guzzle’s 20K+, making it ideal for constrained environments or projects prioritizing simplicity.
  • Factory Support: PSR-17 factories enable dynamic request/response construction, useful for middleware, event handlers, or testing.

• Cons:

  • No Built-in Features: Lacks retries, middleware, or async support (requires custom implementation).
  • Laravel-Specific Gaps: Missing integrations with Laravel’s HttpClient facade, Eloquent, or Queue (use Laravel’s built-in client if those are critical).
  • Synchronous Only: Not suitable for high-concurrency or async workflows.

• Recommendation:

  • "Adopt for new API integrations where PSR compliance and minimalism are priorities. Pair with a lightweight middleware layer (e.g., php-http/message) if advanced features are needed later. Avoid for projects requiring async HTTP or deep Laravel integrations."

For Developers:

• Quick Wins:
  • Replace curl_exec() with a type-safe, PSR-compliant client in 10 minutes.
  • Use helper methods (get(), post(), etc.) for common HTTP verbs with minimal boilerplate.
  • Leverage PSR-17 factories to dynamically create requests/responses for middleware or testing.
• Migration Path:
  • Start with the client in new services/repositories before gradually replacing legacy cURL code.
  • Use dependency injection to swap the client for testing (e.g., mock Psr\Http\Message\RequestInterface).
• Example Workflow:

  // Before (Legacy)
  $ch = curl_init('https://api.example.com/data');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $response = curl_exec($ch);
  curl_close($ch);
  
  // After (pdeans/http)
  $client = new \pdeans\Http\Client();
  $response = $client->get('https://api.example.com/data', [
      'Authorization' => 'Bearer token123',
      'Accept' => 'application/json'
  ]);
  $data = json_decode((string) $response->getBody(), true);