Curl Builder Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require alexkart/curl-builder

Add to composer.json if not using Composer directly.

2. First Use Case: Generate a basic GET request:

   use Alexkart\CurlBuilder\CurlBuilder;
   
   $curl = CurlBuilder::get('https://api.example.com/users')
       ->withHeader('Accept', 'application/json')
       ->build();
   
   echo $curl; // Outputs the full cURL command
   

3. Where to Look First:

   • Source Code (if available) for advanced usage.
   • CurlBuilder class methods (e.g., get(), post(), withHeader(), withData()).
   • build() method to generate the final command.
   • New: Check the updated changelog for fixes in option handling and PHP 8.4 compatibility.

Implementation Patterns

Common Workflows

1. API Requests:

   $curl = CurlBuilder::post('https://api.example.com/users')
       ->withHeader('Authorization', 'Bearer token123')
       ->withData(['name' => 'John', 'email' => 'john@example.com'])
       ->withOption(CURLOPT_RETURNTRANSFER, true)
       ->build();
   

   Note: Duplicate options are now handled gracefully (fixed in 1.1.0).

2. Authentication:

   $curl = CurlBuilder::get('https://api.example.com/protected')
       ->withBasicAuth('username', 'password')
       ->build();
   

3. File Uploads:

   $curl = CurlBuilder::post('https://api.example.com/upload')
       ->withFile('file.txt', '/path/to/file.txt')
       ->build();
   

4. Integration with Laravel HTTP Client:

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

Best Practices

• Reuse Builders: Store configurations in a service class for repeated requests.

  class ApiClient {
      public static function getUsers() {
          return CurlBuilder::get('https://api.example.com/users')
              ->withHeader('Accept', 'application/json');
      }
  }
  

• Debugging: Use ->debug() to inspect intermediate steps.

  $curl = CurlBuilder::get('https://api.example.com/data')->debug();
  

• PHP 8.4 Compatibility: Tested in CI matrix (1.1.0). Ensure your project aligns with PHP 8.4 features if upgrading.

Gotchas and Tips

Pitfalls

1. Option Conflicts:

   • Fixed in 1.1.0: Duplicate options are now handled without silent failures.
   • Avoid overriding built-in options (e.g., CURLOPT_URL) manually after setting the URL.
   • Use withOption() for custom options, but ensure they don’t clash with defaults.

2. File Paths:

   • Absolute paths are required for withFile(). Relative paths may fail silently.

3. Encoding Issues:

   • Special characters in URLs or data may require manual URL encoding:

     $url = urlencode('https://api.example.com/search?q=hello world');
     

Debugging Tips

• Inspect Raw Command:

  $curl = CurlBuilder::get('https://api.example.com/data')->build();
  echo $curl; // Paste into terminal to test manually.
  

• Check for Typos:
  • Method names like withHeader (not withHeaders).
  • Option constants (e.g., CURLOPT_RETURNTRANSFER, not CURLOPT_RETURN_TRANSFER).

Extension Points

1. Custom Options: Add frequently used options as methods:

   $curl->withFollowRedirects(true); // Alias for CURLOPT_FOLLOWLOCATION
   

   Extend the CurlBuilder class or create a trait.

2. Middleware: Chain middleware for pre-processing requests:

   $curl = CurlBuilder::get('https://api.example.com/data')
       ->pipe(function ($builder) {
           $builder->withHeader('X-Custom-Header', 'value');
       });
   

3. Testing: Mock the builder in unit tests:

   $mockBuilder = Mockery::mock(CurlBuilder::class);
   $mockBuilder->shouldReceive('build')->andReturn('mocked_curl_command');
   

   Note: Test coverage has been improved in 1.1.0, making edge cases easier to validate.

4. PHP 8.4 Features:

   • Leverage named arguments or attributes if extending the package.
   • Example: Use #[Attribute] for metadata in custom builders.

NO_UPDATE_NEEDED would **not** apply here—this assessment has been updated to reflect the new release's fixes and improvements.