Curl Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer:

   composer require anchovy/curl-bundle
   

2. Enable the Bundle in config/bundles.php:

   return [
       // ...
       Iman\AnchovyCURLBundle\ImanAnchovyCURLBundle::class => ['all' => true],
   ];
   

3. Autowire the Service in your controller/service:

   use Iman\AnchovyCURLBundle\Service\CurlService;
   
   public function __construct(private CurlService $curlService) {}
   

First Use Case: Simple GET Request

// In a controller or service
$response = $this->curlService->get('https://api.example.com/data');
$body = $response->getBody();
$status = $response->getStatusCode();

Implementation Patterns

Core Workflows

1. Request/Response Pattern:

   // GET
   $response = $this->curlService->get($url, $options);
   
   // POST
   $response = $this->curlService->post($url, $data, $headers);
   
   // PUT/DELETE/PATCH
   $response = $this->curlService->put($url, $data);
   

2. Custom Headers & Authentication:

   $headers = [
       'Authorization' => 'Bearer token123',
       'X-Custom-Header' => 'value'
   ];
   $response = $this->curlService->get($url, ['headers' => $headers]);
   

3. Handling Responses:

   $response = $this->curlService->get($url);
   $json = $response->getJson(); // Auto-decodes JSON
   $status = $response->getStatusCode();
   $headers = $response->getHeaders();
   

Integration Tips

• Dependency Injection: Prefer injecting CurlService over instantiating it directly.
• Configuration: Override default options via config/packages/anchovy_curl.yaml:

  anchovy_curl:
      default_options:
          timeout: 30
          ssl_verifypeer: false
  

• Middleware: Extend the bundle’s CurlResponse class to add custom logic:

  // src/Service/CustomCurlResponse.php
  class CustomCurlResponse extends \Iman\AnchovyCURLBundle\Response\CurlResponse {
      public function getCustomData() { ... }
  }
  

  Then bind it in services.yaml:

  services:
      Iman\AnchovyCURLBundle\Response\CurlResponse: '@App\Service\CustomCurlResponse'
  

Gotchas and Tips

Pitfalls

1. Symfony 2.x Legacy: The bundle is designed for Symfony 2.x. For Symfony 4/5/6, use a modern alternative like guzzlehttp/guzzle or symfony/http-client.
2. Error Handling: The bundle throws exceptions on failure. Catch them explicitly:

   try {
       $response = $this->curlService->get($url);
   } catch (\Iman\AnchovyCURLBundle\Exception\CurlException $e) {
       // Handle error (e.g., log, retry, or return fallback)
   }
   

3. SSL Verification: Disabling SSL verification (ssl_verifypeer: false) is insecure. Use it only for testing or trusted internal APIs.

Debugging

• Enable Verbose Output: Pass CURLOPT_VERBOSE via options:

  $response = $this->curlService->get($url, [
      'options' => [
          CURLOPT_VERBOSE => true,
          CURLOPT_STDERR => fopen('php://temp', 'w+')
      ]
  ]);
  

• Check Underlying cURL Errors:

  $response = $this->curlService->get($url);
  if ($response->getError()) {
      $error = $response->getError();
      // Log or handle $error
  }
  

Extension Points

1. Custom Request Factories: Override the default CurlRequestFactory to modify request behavior:

   // src/Service/CustomRequestFactory.php
   class CustomRequestFactory extends \Iman\AnchovyCURLBundle\Factory\CurlRequestFactory {
       public function createRequest($method, $url, array $options = []) {
           // Add custom logic (e.g., default headers)
           return parent::createRequest($method, $url, $options);
       }
   }
   

   Bind it in services.yaml:

   services:
       Iman\AnchovyCURLBundle\Factory\CurlRequestFactory: '@App\Service\CustomRequestFactory'
   

2. Response Transformers: Extend CurlResponse to add custom parsing logic (e.g., XML, custom APIs):

   class CustomResponse extends \Iman\AnchovyCURLBundle\Response\CurlResponse {
       public function getParsedData() {
           return json_decode($this->getBody(), true);
       }
   }
   

Performance Tips

• Reuse Handles: For repeated requests to the same host, configure CURLOPT_FORBID_REUSE and CURLOPT_FRESH_CONNECT in default options.
• Connection Pooling: Use CURLOPT_SHARE to share connections across requests (advanced use case).