Curl Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require carlescliment/curl
   

   Add the service provider to config/app.php under providers:

   CarlesCliment\Curl\CurlServiceProvider::class,
   

2. Basic Usage: The package provides a fluent interface for making HTTP requests. Start by resolving the Curl facade:

   use CarlesCliment\Curl\Facades\Curl;
   
   $response = Curl::to('https://api.example.com/data')
       ->get()
       ->send();
   

3. First Use Case: Fetch JSON data from an API:

   $data = Curl::to('https://api.example.com/users')
       ->withHeader('Accept', 'application/json')
       ->get()
       ->json();
   

Implementation Patterns

Common Workflows

1. Chaining Requests:

   $response = Curl::to('https://api.example.com')
       ->withHeader('Authorization', 'Bearer token')
       ->post()
       ->withData(['key' => 'value'])
       ->send();
   

2. Handling Responses:

   $response = Curl::to('https://api.example.com/data')->get()->send();
   
   if ($response->isOk()) {
       $body = $response->body();
       $json = $response->json();
   }
   

3. Error Handling:

   try {
       $response = Curl::to('https://api.example.com')->get()->send();
       $response->throwIfNotOk();
   } catch (\CarlesCliment\Curl\Exceptions\CurlException $e) {
       // Handle error
   }
   

4. Reusing Configurations:

   // In a service or helper
   function fetchWithAuth($url, $data) {
       return Curl::to($url)
           ->withHeader('Authorization', 'Bearer ' . auth()->token())
           ->post()
           ->withData($data)
           ->send();
   }
   

5. Integration with Laravel HTTP Client: For consistency, mirror Laravel's HTTP client patterns:

   $response = Curl::to('https://api.example.com')
       ->withOptions(['timeout' => 30])
       ->withHeader('X-Custom-Header', 'value')
       ->asJson()
       ->get();
   

Gotchas and Tips

Pitfalls

1. No Built-in Retry Mechanism: Unlike Laravel's HTTP client, this package lacks retry logic. Implement manually:

   $attempts = 3;
   while ($attempts--) {
       try {
           $response = Curl::to(url)->get()->send();
           break;
       } catch (\Exception $e) {
           if ($attempts === 0) throw $e;
           sleep(1);
       }
   }
   

2. No Automatic JSON Parsing: Always explicitly call ->json() to decode responses:

   // ❌ Won't work as expected
   $data = Curl::to(url)->get()->send()->json;
   
   // ✅ Correct
   $data = Curl::to(url)->get()->send()->json();
   

3. Curl Options Override: Custom CURLINFO_* options may not persist across requests. Reset them if needed:

   Curl::resetOptions();
   

Debugging Tips

1. Enable Verbose Output:

   Curl::to(url)->withOption(CURLOPT_VERBOSE, true)->get()->send();
   

   Logs will appear in stderr.

2. Inspect Headers:

   $headers = Curl::to(url)->get()->send()->headers();
   

3. Check Effective URL:

   $finalUrl = Curl::to(url)->get()->send()->effectiveUrl();
   

Extension Points

1. Custom Middleware: Attach middleware to modify requests/responses:

   Curl::to(url)->middleware(function ($request) {
       $request->withHeader('X-Middleware', 'enabled');
   })->get()->send();
   

2. Override Default Options: Configure defaults in config/curl.php:

   'defaults' => [
       CURLOPT_TIMEOUT => 30,
       CURLOPT_SSL_VERIFYPEER => false, // ⚠️ Disable only for testing!
   ],
   

3. Extend Response Class: Create a custom response handler by extending CarlesCliment\Curl\Response:

   class CustomResponse extends \CarlesCliment\Curl\Response {
       public function customMethod() {
           return $this->body() . ' (custom)';
       }
   }
   

   Bind it in the service provider’s boot method.

Performance

• Reuse Handles: For repeated requests to the same endpoint, reuse the Curl handle:

  $handle = Curl::create()->to(url);
  $handle->get()->send();
  $handle->post()->withData($data)->send();