Cuzzle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require namshi/cuzzle
   

   Add to compser.json if using a monorepo or custom package manager.

2. Basic Usage

   use Namshi\Cuzzle\Cuzzle;
   use GuzzleHttp\Client;
   
   $client = new Client();
   $response = $client->request('GET', 'https://api.example.com/data');
   
   // Dump the request to cURL
   $curlCommand = Cuzzle::make($client->getLastRequest());
   echo $curlCommand;
   

3. First Use Case: Debugging API Calls

   • Use Cuzzle::make($request) to generate a cURL command from a Guzzle request.
   • Paste the output into a terminal or curl client to replicate the request.
   • Ideal for debugging failed API calls, verifying headers, or testing locally.

Implementation Patterns

Workflows

1. Debugging Middleware Create a middleware to log cURL commands for all requests:

   use Namshi\Cuzzle\Cuzzle;
   use Psr\Http\Message\RequestInterface;
   
   class LogCurlMiddleware
   {
       public function __invoke(RequestInterface $request, $next)
       {
           $response = $next($request);
           $curl = Cuzzle::make($request);
           \Log::debug('API Request:', ['curl' => $curl]);
           return $response;
       }
   }
   

   Register in app/Http/Kernel.php:

   protected $middleware = [
       \App\Http\Middleware\LogCurlMiddleware::class,
   ];
   

2. Testing API Responses Use cURL commands to test API endpoints locally:

   $request = $client->request('POST', '/api/users', ['json' => ['name' => 'John']]);
   $curl = Cuzzle::make($request);
   // Copy-paste $curl into terminal to test.
   

3. Generating Documentation Extract cURL examples from Guzzle requests for API docs:

   $curlExamples = collect($apiRequests)->map(fn($req) => Cuzzle::make($req));
   

Integration Tips

• Laravel HTTP Client: Works seamlessly with Laravel’s Http facade:

  $response = Http::get('https://api.example.com/data');
  $curl = Cuzzle::make($response->getRequest());
  

• Guzzle Events: Attach to request or complete events to log cURL commands:

  $client->on('request', function ($request) {
      \Log::debug('Request:', ['curl' => Cuzzle::make($request)]);
  });
  

• Custom Headers/Options: Ensure headers/options are included in the request before dumping:

  $request = $client->createRequest('GET', '/data', [
      'headers' => ['Authorization' => 'Bearer token'],
      'query' => ['page' => 1],
  ]);
  $curl = Cuzzle::make($request);
  

Gotchas and Tips

Pitfalls

1. Missing Request Data

   • If the request lacks a body (e.g., GET without query params), Cuzzle may omit it. Ensure you pass the full request object:

     $request = $client->getLastRequest(); // Use this instead of partial data.
     

   • For POST requests, verify the body is included in the cURL command. If not, check if the request was modified (e.g., by middleware).

2. Sensitive Data Exposure

   • Never log cURL commands in production with sensitive data (tokens, passwords). Use environment checks:

     if (app()->environment('local')) {
         \Log::debug('API Request:', ['curl' => Cuzzle::make($request)]);
     }
     

   • Strip sensitive headers/values before logging:

     $request = $request->withoutHeader('Authorization');
     $curl = Cuzzle::make($request);
     

3. Complex Requests

   • Multipart requests or custom stream handlers may not render correctly. Test edge cases like:

     $request = $client->createRequest('POST', '/upload', [
         'body' => new \CurlFile('/path/to/file.jpg'),
     ]);
     

   • Fallback: Manually construct the cURL command for unsupported cases.

4. Guzzle Version Compatibility

   • Older Guzzle versions (<6.0) may require adjustments. Test with:

     if (version_compare(\GuzzleHttp\version(), '6.0.0') < 0) {
         // Use alternative approach or update Guzzle.
     }
     

Debugging Tips

1. Verify Request Object Inspect the request object before passing it to Cuzzle:

   dd($request->getMethod(), $request->getUri(), $request->getHeaders());
   

2. Compare with curl Directly Run the generated cURL command manually to isolate issues:

   curl -v -X POST https://api.example.com/data -H "Authorization: Bearer token"
   

3. Check for Middleware Interference Disable middleware temporarily to rule out request modifications:

   $client = new Client(['handler' => HandlerStack::create()]);
   

Extension Points

1. Customize cURL Output Extend Cuzzle to modify the command (e.g., add proxies, verbose flags):

   class CustomCuzzle extends Cuzzle
   {
       protected function getCurlCommand(): string
       {
           $command = parent::getCurlCommand();
           return str_replace('--data', '--data --verbose', $command);
       }
   }
   

2. Add to Laravel Telescope Create a custom panel to display cURL commands:

   use Namshi\Cuzzle\Cuzzle;
   use Illuminate\Support\Facades\Http;
   
   Http::on(function ($request) {
       if (app()->environment('local')) {
           Telescope::log('API Request', [
               'curl' => Cuzzle::make($request),
           ]);
       }
   });
   

3. Support for Non-Guzzle Clients Adapt other HTTP clients (e.g., Symfony HTTP Client) by converting their requests to Guzzle-compatible objects.