Cloudflareapi Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require akyos/cloudflareapi-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Akyos\CloudflareApiBundle\AkyosCloudflareApiBundle::class => ['all' => true],
   ];
   

2. Configure API Credentials Publish the default config:

   php bin/console config:dump-reference AkyosCloudflareApiBundle
   

   Update config/packages/akyos_cloudflare_api.yaml:

   akyos_cloudflare_api:
       api_token: '%env(CLOUDFLARE_API_TOKEN)%'
       account_id: '%env(CLOUDFLARE_ACCOUNT_ID)%'
   

3. First Use Case: Fetch Zones Inject the client in a controller/service:

   use Akyos\CloudflareApiBundle\Client\CloudflareClient;
   
   public function __construct(private CloudflareClient $cloudflare)
   {
   }
   
   public function listZones()
   {
       $zones = $this->cloudflare->getZones();
       return $this->json($zones);
   }
   

Implementation Patterns

Common Workflows

1. Zone Management

   // Fetch a single zone
   $zone = $this->cloudflare->getZone('your-zone-id');
   
   // Create a DNS record
   $this->cloudflare->createDnsRecord('zone-id', [
       'type' => 'A',
       'name' => 'example.com',
       'content' => '192.0.2.1',
   ]);
   

2. Purge Cache

   $this->cloudflare->purgeCache('zone-id', ['url' => 'https://example.com']);
   

3. Worker Scripts

   $this->cloudflare->createWorkerScript('script-id', [
       'script' => file_get_contents('script.js'),
   ]);
   

Integration Tips

• Symfony Dependency Injection: Prefer injecting CloudflareClient over instantiating directly.
• Error Handling: Wrap API calls in try-catch:

  try {
      $this->cloudflare->getZone('invalid-id');
  } catch (\Akyos\CloudflareApiBundle\Exception\CloudflareException $e) {
      $this->addFlash('error', $e->getMessage());
  }
  

• Async Operations: Use queue for long-running tasks (e.g., purges):

  $this->cloudflare->purgeCacheAsync('zone-id', ['url' => '...']);
  

Gotchas and Tips

Pitfalls

1. Token Permissions: Ensure your API token has the correct scopes (e.g., Zones:Read, DNS:Edit).

   • Debug: Check CloudflareException messages for missing permissions.

2. Rate Limiting: Cloudflare enforces rate limits (~1200 requests/minute). Cache responses aggressively:

   $this->cloudflare->getZones(['cache' => ['ttl' => 300]]);
   

3. Zone ID vs. Domain: The API uses zone_id, not domain names. Cache mappings:

   $zoneId = $this->cloudflare->getZoneIdByName('example.com');
   

Debugging

• Enable API Logging: Set in config:

  akyos_cloudflare_api:
      debug: true
  

  Logs appear in var/log/dev.log.

• HTTP Client: Under the hood, it uses GuzzleHttp. Override the client for custom middleware:

  akyos_cloudflare_api:
      http_client:
          middleware: ['custom.middleware']
  

Extension Points

1. Custom Endpoints: Extend the client via traits or decorators:

   use Akyos\CloudflareApiBundle\Client\CloudflareClientInterface;
   
   class CustomCloudflareClient implements CloudflareClientInterface {
       use \Akyos\CloudflareApiBundle\Client\Traits\CloudflareClientTrait;
   
       public function customEndpoint() {
           return $this->request('GET', '/custom/path');
       }
   }
   

2. Response Transformers: Override default responses (e.g., for pagination):

   $this->cloudflare->setResponseTransformer(function ($response) {
       return $response->getData()['result'];
   });
   

3. Event Listeners: Subscribe to API events (e.g., cloudflare.api.response):

   // config/services.yaml
   services:
       App\EventListener\CloudflareListener:
           tags:
               - { name: kernel.event_listener, event: cloudflare.api.response, method: onResponse }