Curl Client Laravel Package

Technical Evaluation

Architecture Fit

• HTTP Client Abstraction: Continues to align with Laravel’s ecosystem as a lightweight, PSR-18-compliant HTTP client, ideal for API integrations, microservices, and background jobs. The cURL backend remains performant for simple requests while avoiding the overhead of Guzzle/Symfony HttpClient.
• Middleware Support: Retains full compatibility with Laravel’s middleware pipeline, enabling consistent request/response handling (e.g., authentication, logging, retries). No changes to this core functionality.
• Use Cases:
  • Symfony 8 Integration: Expanded compatibility with Symfony 8 broadens adoption in hybrid Laravel/Symfony stacks, enabling shared HTTP client instances across applications.
  • PHP 8.5 Features: Leverages modern PHP features (e.g., typed properties, enums, and first-class union types) for improved type safety and developer experience.
  • Performance: Continues to prioritize low-level cURL optimizations, making it suitable for high-throughput environments where simplicity and speed are critical.
• Trade-offs:
  • No Native Retry/Backoff Logic: Still requires middleware or external libraries (e.g., php-http/retry) for resilience patterns.
  • Limited Streaming: No native support for streaming responses (vs. Guzzle/Symfony), which may impact use cases like large file downloads or server-sent events.
  • Async Limitations: No built-in async support; requires integration with libraries like spatie/async-request or reactphp/curl.

Integration Feasibility

• Laravel Compatibility:
  • PSR-18 Adapter: Seamlessly integrates with Laravel’s Http facade via php-http/laravel or custom bindings. The package’s adherence to PSR-18 ensures interoperability with other PSR-compliant libraries.
  • Symfony Hybrid: Symfony 8 support enables shared HTTP clients in monorepos or microservice architectures where both Laravel and Symfony components are used.
• Dependency Graph:
  • PHP 8.1+ Only: Dropped support for PHP <8.1 simplifies dependency management by eliminating legacy polyfills and reducing attack surface. This aligns with Laravel 9+ requirements.
  • Lightweight: Minimal dependencies (php-http/message, php-http/client-common), ensuring low overhead and easy maintenance.
• Testing:
  • Mockability: Fully mockable via PSR-18 interfaces (e.g., php-http/mock-client), facilitating unit and integration testing.
  • HTTP Interceptors: Compatible with tools like WireMock or Laravel’s HTTP testing helpers.

Technical Risk

• Low Risk:
  • Backward Compatibility: No breaking changes to the core PSR-18 API, ensuring smooth adoption for existing users.
  • Active Maintenance: MIT-licensed with regular updates, including Symfony 8 and PHP 8.5 support.
• Mitigable Risks:
  • PHP 8.1+ Requirement: Critical for adoption; ensure all environments meet this threshold (Laravel 9+ typically supports PHP 8.1+). Use php-http/psr18-client-polyfill as a temporary workaround if needed.
  • Symfony 8 Dependency: Potential conflicts with Laravel’s Symfony bridge if both frameworks are tightly coupled. Validate integration in a staging environment.
  • Async/Streaming Gaps: May require additional libraries or custom implementations for advanced use cases.
  • cURL Extension Dependency: Critical for functionality; ensure the curl extension is enabled and properly configured (e.g., SSL, proxies).

Key Questions

1. PHP Version Alignment:
   • Are all Laravel environments upgraded to PHP 8.1+? If not, plan a phased migration or use a polyfill as an interim solution.
2. Symfony Hybrid Use Case:
   • Is Symfony 8 support necessary for shared HTTP clients in a Laravel/Symfony hybrid stack? If so, validate integration early to avoid conflicts.
3. Middleware Strategy:
   • How will retries, timeouts, and resilience patterns be implemented? Consider leveraging php-http/retry or custom Laravel middleware.
4. Performance Benchmarking:
   • Compare php-http/curl-client against Guzzle/Symfony HttpClient for critical paths (e.g., high-throughput APIs, large payloads) to justify the switch.
5. Fallback Plan:
   • What is the backup strategy if the curl extension is disabled? Options include Symfony\Component\Panther\Client or file_get_contents (with caveats).
6. PHP 8.5 Features:
   • Are there plans to leverage PHP 8.5 features (e.g., enums, first-class union types) in custom middleware or request/response handling? If so, ensure all team members are aligned with the upgrade path.

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • PSR-18 Adapter: Use php-http/laravel to integrate with Laravel’s Http facade. Bind the client as a singleton in config/app.php:

    'http' => fn() => new \PhpHttp\Client\Curl\Client(),
    

  • Service Container: Register the client with optional middleware for auth, logging, or retries:

    $client = app(\PhpHttp\Client\Curl\Client::class);
    $client->addMiddleware(new \PhpHttp\Middleware\LoggerMiddleware());
    

  • Middleware Pipeline: Align with Laravel’s middleware stack for consistency.
• Symfony Hybrid:
  • Share the client across Laravel/Symfony applications via a shared vendor/ directory or a private Composer package. Ensure no conflicts with Laravel’s Symfony bridge.
• Alternatives:
  • Guzzle/Symfony HttpClient: Retain if advanced features (e.g., streaming, async) are critical. Use Symfony HttpClient if already embedded in a Symfony-heavy stack.
  • Symfony Panther: Fallback for headless browser scenarios (e.g., testing).

Migration Path

1. Phase 1: PHP 8.1+ Validation
   • Audit all environments for PHP 8.1+ compatibility. Update composer.json to enforce the minimum version:

     "require": {
         "php": "^8.1",
         "php-http/curl-client": "^2.4"
     }
     

   • For environments stuck on PHP <8.1, use php-http/psr18-client-polyfill as a temporary solution.
2. Phase 2: Pilot Integration
   • Replace a non-critical API client (e.g., a 3rd-party service) with php-http/curl-client.
   • Use a PSR-18 adapter (e.g., php-http/laravel) to maintain compatibility with Laravel’s Http facade.
   • Example adapter setup:

     use PhpHttp\Laravel\LaravelHttpClient;
     $client = new LaravelHttpClient(new \PhpHttp\Client\Curl\Client());
     

3. Phase 3: Middleware Refactoring
   • Migrate auth, retries, and logging from Guzzle plugins to Laravel middleware or php-http middleware.
   • Example retry middleware:

     use PhpHttp\Middleware\RetryMiddleware;
     $client->addMiddleware(new RetryMiddleware(3, 100));
     

4. Phase 4: Full Replacement
   • Update all GuzzleHttp\Client instances to use php-http/curl-client.
   • Deprecate old clients via feature flags or environment-based routing.
   • Remove redundant dependencies (e.g., Guzzle) post-migration.

Compatibility

• Laravel Versions:
  • Compatible with Laravel 9+ (PHP 8.1+). For Laravel 8, use php-http/psr18-client-polyfill or upgrade PHP.
• PHP Versions:
  • Minimum: PHP 8.1 (dropped support for <8.1).
  • Recommended: PHP 8.2+ for full feature parity (e.g., enums, typed properties, first-class union types).
• Symfony 8:
  • Validated compatibility; no conflicts expected with Laravel’s Symfony bridge. Test in a staging environment if using both frameworks.
• cURL Requirements:
  • Verify the curl extension is enabled (php -m | grep curl).
  • Configure via middleware for edge cases (e.g., proxies, SSL, custom headers):

    $client->addMiddleware(new \PhpHttp\Middleware\CurlOptionsMiddleware([
        CURLOPT_PROXY => 'http://proxy.example.com',
        CURLOPT_SSL_VERIFYPEER => false, // Temporary workaround; avoid in production
    ]));
    

Sequencing

1. Dependency Update:
   • Add php-http/curl-client:^2.4 to composer.json and run composer update.
   • Remove redundant clients (e.g., Guzzle) after full migration.
2. Testing:
   • Unit Tests: Mock the client with php-http/mock-client:

     $mock =