Curl Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require lib/curl:0.2
   

   Add to composer.json under require:

   "lib/curl": "0.2"
   

2. First Use Case: Fetch a simple API endpoint or external resource:

   use Curl\Request;
   
   $curl = new Request();
   $curl->url = 'https://api.example.com/data';
   $curl->get(); // For GET requests (default)
   $response = $curl->execute();
   
   return $response;
   

3. Key Files:

   • vendor/lib/curl/src/Curl/Request.php (main class)
   • Check tests/ for usage examples (if available).

Implementation Patterns

Core Workflows

1. Basic Requests:

   $curl = new Request();
   $curl->url = 'https://api.example.com/users';
   $curl->get(); // Explicit GET (optional)
   $response = $curl->execute();
   

2. POST/PUT with Data:

   $curl->post = ['key' => 'value']; // or $curl->put()
   $curl->execute();
   

3. Headers and Auth:

   $curl->headers = [
       'Authorization: Bearer token123',
       'Content-Type: application/json'
   ];
   $curl->execute();
   

4. Timeouts and Retries:

   $curl->timeout = 30; // seconds
   $curl->maxRedirects = 5;
   

Laravel Integration

1. Service Provider: Register the wrapper globally for easy access:

   // app/Providers/AppServiceProvider.php
   public function register()
   {
       $this->app->singleton('curl', function () {
           return new \Curl\Request();
       });
   }
   

2. Facade (Optional): Create a facade for cleaner syntax:

   // app/Facades/Curl.php
   namespace App\Facades;
   
   use Illuminate\Support\Facades\Facade;
   
   class Curl extends Facade
   {
       protected static function getFacadeAccessor() { return 'curl'; }
   }
   

   Usage:

   $response = Curl::url('https://api.example.com')->get()->execute();
   

3. HTTP Client Wrapper: Chain with Laravel’s HTTP client for consistency:

   $response = Http::withOptions(['curl' => $curl->getOptions()])
       ->get('https://api.example.com');
   

4. Job Queues: Offload long-running requests:

   // app/Jobs/FetchExternalData.php
   public function handle()
   {
       $curl = new \Curl\Request();
       $curl->url = 'https://slow-api.example.com';
       $curl->timeout = 600;
       $result = $curl->execute();
       // Store result...
   }
   

Gotchas and Tips

Pitfalls

1. No Modern PHP Support:

   • Last release in 2014 (PHP 5.x). May break on PHP 8+ due to:
     • Deprecated functions (e.g., create_function).
     • Missing type hints or strict standards.
   • Workaround: Use a polyfill or fork the package.

2. Error Handling:

   • Errors are basic (e.g., curl_errno()). Extend the class to log errors:

     $curl->onError(function ($error) {
         Log::error("cURL Error: " . $error);
     });
     

3. No SSL Pinning:

   • Vulnerable to MITM attacks. Use Laravel’s Http client with SSL options instead.

4. No Async Support:

   • Blocking calls only. For async, pair with ReactPHP or Laravel Queues.

5. Deprecated Methods:

   • Avoid addPost()/addGet() in favor of $curl->post = [...].

Debugging Tips

1. Enable Verbose Output:

   $curl->verbose = true;
   $curl->execute();
   

   Check logs for raw cURL commands.

2. Test Locally First: Use curl --trace-ascii debug.txt http://example.com to compare.

3. Fallback to Native cURL: If the wrapper fails, debug with raw cURL:

   $ch = curl_init($curl->url);
   curl_setopt_array($ch, $curl->getOptions());
   $result = curl_exec($ch);
   

Extension Points

1. Add Middleware: Extend the Request class to support middleware:

   class ExtendedRequest extends \Curl\Request
   {
       protected $middleware = [];
   
       public function addMiddleware(callable $middleware)
       {
           $this->middleware[] = $middleware;
       }
   
       public function execute()
       {
           foreach ($this->middleware as $middleware) {
               $this = $middleware($this);
           }
           return parent::execute();
       }
   }
   

2. Custom Response Handling: Override execute() to parse JSON/XML:

   public function execute()
   {
       $result = parent::execute();
       return json_decode($result, true);
   }
   

3. Retry Logic: Add exponential backoff:

   public function execute()
   {
       $attempts = 0;
       $maxAttempts = 3;
       $delay = 100; // ms
   
       while ($attempts < $maxAttempts) {
           try {
               return parent::execute();
           } catch (\Exception $e) {
               if ($attempts === $maxAttempts - 1) throw $e;
               usleep($delay);
               $delay *= 2;
               $attempts++;
           }
       }
   }
   

4. Proxy Support: Add proxy configuration:

   $curl->proxy = [
       'host' => 'proxy.example.com',
       'port' => 8080,
       'user' => 'user',
       'pass' => 'pass'
   ];
   

   Then extend getOptions() to include proxy settings.

Configuration Quirks

1. Default Timeout: Set globally in a config file:

   // config/curl.php
   return [
       'default_timeout' => 30,
   ];
   

   Then inject into the Request class constructor.

2. User-Agent: Override the default user-agent:

   $curl->headers['User-Agent'] = 'MyApp/1.0';