Curl Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require dvelopment/curl
   

   Register the service provider in config/app.php under providers:

   Dvelopment\Curl\CurlServiceProvider::class,
   

2. First Use Case Make a simple GET request:

   use Dvelopment\Curl\Curl;
   
   $response = Curl::get('https://api.example.com/data');
   echo $response->body;
   

3. Where to Look First

   • Documentation: Check the package’s README.md for basic usage.
   • Facade: The Curl facade (Dvelopment\Curl\Facades\Curl) is the primary entry point.
   • Configuration: Publish the config file (if available) for customization:

     php artisan vendor:publish --provider="Dvelopment\Curl\CurlServiceProvider"
     

Implementation Patterns

Usage Patterns

1. Basic Requests Use fluent methods for common HTTP verbs:

   $response = Curl::post('https://api.example.com/submit', [
       'key' => 'value'
   ]);
   

2. Headers and Options Pass headers or cURL options as arrays:

   $response = Curl::withHeaders(['Authorization' => 'Bearer token'])
                   ->withOptions(['CURLOPT_TIMEOUT' => 30])
                   ->get('https://api.example.com/secure');
   

3. Authentication Handle basic auth or OAuth:

   $response = Curl::withAuth('username', 'password')
                   ->get('https://api.example.com/protected');
   

4. Response Handling Access response data via properties:

   $response = Curl::get('https://api.example.com/data');
   $status = $response->status; // HTTP status code
   $body = $response->body;     // Response body
   $headers = $response->headers; // Response headers
   

5. Error Handling Use exceptions or check the success property:

   try {
       $response = Curl::get('https://api.example.com/fail');
   } catch (\Dvelopment\Curl\Exceptions\CurlException $e) {
       // Handle error
   }
   

Workflows

1. API Integration

   • Use the package for Laravel API clients (e.g., Stripe, GitHub).
   • Example: Wrap API calls in a service class:

     class GitHubService {
         public function fetchUser($username) {
             return Curl::get("https://api.github.com/users/{$username}");
         }
     }
     

2. Background Jobs Offload cURL requests to queues (e.g., Laravel Queues):

   use Illuminate\Support\Facades\Queue;
   
   Queue::push(function () {
       Curl::post('https://api.example.com/async', ['data' => 'value']);
   });
   

3. Middleware Add request/response middleware for logging or transformations:

   Curl::addMiddleware(function ($request, $next) {
       $request->headers['X-Custom-Header'] = 'value';
       return $next($request);
   });
   

Integration Tips

• Laravel HTTP Client: Use alongside Laravel’s built-in Http client for hybrid workflows.
• Testing: Mock responses with Laravel’s HTTP tests or use Curl::fake() (if supported).
• Configuration: Override defaults (e.g., timeout, user agent) in config/curl.php.

Gotchas and Tips

Pitfalls

1. Resource Leaks

   • Ensure Curl instances are properly closed (the package likely handles this, but verify).
   • Avoid long-running requests without timeouts.

2. SSL/Warnings

   • Suppress cURL warnings if needed (e.g., for self-signed certs):

     Curl::withOptions(['CURLOPT_VERBOSE' => false, 'CURLOPT_SSL_VERIFYPEER' => false]);
     

   • Warning: Disabling SSL verification is insecure for production.

3. Header Conflicts

   • Headers like Content-Type or User-Agent may override defaults. Explicitly set them if needed:

     Curl::withHeaders(['Content-Type' => 'application/json']);
     

4. Large Responses

   • Stream large responses to avoid memory issues:

     $response = Curl::withOptions(['CURLOPT_WRITEFUNCTION' => function($ch, $data) {
         // Process data incrementally
     }])->get('https://api.example.com/large-data');
     

Debugging

1. Enable Verbose Output For debugging, enable cURL verbose mode:

   Curl::withOptions(['CURLOPT_VERBOSE' => true]);
   

   Check Laravel logs for output.

2. Check Response Codes Always inspect $response->status for non-200 responses.

3. Timeouts Set reasonable timeouts (default may be too low):

   Curl::withOptions(['CURLOPT_TIMEOUT' => 60]);
   

Config Quirks

• Default User Agent: Override in config/curl.php:

  'user_agent' => 'MyApp/1.0',
  

• Proxy Support: Configure via options:

  Curl::withOptions([
      'CURLOPT_PROXY' => 'http://proxy.example.com:8080',
  ]);
  

Extension Points

1. Custom Responses Extend the Dvelopment\Curl\Response class to add methods:

   class CustomResponse extends \Dvelopment\Curl\Response {
       public function parseJson() {
           return json_decode($this->body, true);
       }
   }
   

   Bind it in the service provider.

2. Hooks Use middleware or events (if the package supports them) to intercept requests/responses.

3. Low-Level Access For advanced use cases, access the underlying cURL handle:

   $handle = Curl::getHandle();
   // Manipulate handle directly (use with caution)