Core Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require contentful/core
   

   Note: This package is foundational—use it only with contentful/php or contentful-management.php.

2. First Use Case Initialize a Client (example for Delivery API):

   use Contentful\Client;
   use Contentful\Delivery\Client as DeliveryClient;
   
   $client = new Client([
       'space' => 'your-space-id',
       'accessToken' => 'your-access-token',
       'host' => 'cdn.contentful.com',
   ]);
   
   $deliveryClient = new DeliveryClient($client);
   

3. Key Classes to Explore

   • Contentful\Client: Base client for API calls.
   • Contentful\Delivery\Client: For content delivery operations.
   • Contentful\Management\Client: For managing spaces, content models, etc.
   • Contentful\Resource\ResourceCollection: Handles paginated responses.

Implementation Patterns

Core Workflows

1. Content Delivery Fetch entries, assets, or locales:

   $entries = $deliveryClient->getEntries(['content_type' => 'blogPost']);
   foreach ($entries as $entry) {
       echo $entry->getField('title');
   }
   

2. Management Operations Create/update content models or entries:

   $managementClient = new ManagementClient($client);
   $space = $managementClient->getSpace('your-space-id');
   $contentType = $space->getContentType('blogPost');
   $contentType->setField('title', ['name' => 'Title', 'validations' => []]);
   $contentType->save();
   

3. Pagination Handling Use ResourceCollection for iterating over large datasets:

   $collection = $deliveryClient->getEntries(['limit' => 100]);
   foreach ($collection as $entry) {
       // Process entry
   }
   // Auto-fetches next page if needed
   

4. Error Handling Wrap API calls in try-catch:

   try {
       $deliveryClient->getEntry('blogPost', '123');
   } catch (\Contentful\Exception\ContentfulException $e) {
       \Log::error($e->getMessage());
   }
   

Integration Tips

• Laravel Service Provider Bind clients to the container for dependency injection:

  $this->app->singleton(DeliveryClient::class, function ($app) {
      return new DeliveryClient(new Client(config('contentful.delivery')));
  });
  

• Caching Responses Cache ResourceCollection results for performance:

  $entries = Cache::remember('contentful_blog_posts', now()->addHours(1), function () {
      return $deliveryClient->getEntries(['content_type' => 'blogPost']);
  });
  

• Environment Configuration Store credentials in .env:

  CONTENTFUL_SPACE_ID=your-space-id
  CONTENTFUL_DELIVERY_TOKEN=your-token
  CONTENTFUL_MANAGEMENT_TOKEN=your-management-token
  

Gotchas and Tips

Pitfalls

1. Direct Usage Warning

   • This package is not meant for standalone use. Pair it with contentful/php or contentful-management.php for full functionality.

2. Rate Limiting

   • Contentful enforces rate limits. Handle 429 Too Many Requests gracefully:

     if ($e->getCode() === 429) {
         sleep($e->getRetryAfter());
         retry();
     }
     

3. Field Access

   • Fields are accessed via getField() or array notation:

     $title = $entry->getField('title'); // Preferred
     // or
     $title = $entry['fields']['title'];
     

4. Locale Handling

   • Always specify locales when fetching content:

     $deliveryClient->getEntries(['content_type' => 'blogPost', 'locale' => 'en-US']);
     

Debugging

• Enable Debug Mode

  $client = new Client([
      'debug' => true, // Logs HTTP requests/responses
      // ...
  ]);
  

• Common HTTP Errors

  • 401: Invalid token or space ID.
  • 404: Resource not found (e.g., entry/content type).
  • 403: Permission denied (check management token scopes).

Extension Points

1. Custom HTTP Client Override the default Guzzle client:

   use Contentful\Http\Client as HttpClient;
   use GuzzleHttp\Client as GuzzleClient;
   
   $httpClient = new HttpClient(new GuzzleClient([
       'timeout' => 30,
       'headers' => ['User-Agent' => 'MyApp/1.0'],
   ]));
   $client = new Client(['httpClient' => $httpClient]);
   

2. Middleware Add request/response middleware:

   $client->getHttpClient()->getEmitter()->addSubscriber(new class {
       public function process(\Psr\Http\Message\RequestInterface $request, callable $next) {
           $request = $request->withHeader('X-Custom-Header', 'value');
           return $next($request);
       }
   });
   

3. Event Listeners Listen for API events (e.g., Contentful\Events\RequestSent):

   $client->getHttpClient()->getEmitter()->addListener(
       'Contentful\Events\RequestSent',
       function ($event) {
           \Log::debug('Request sent to:', [$event->getRequest()->getUri()]);
       }
   );
   

Configuration Quirks

• Host Overrides Use host config to switch between environments (e.g., preview API):

  $client = new Client(['host' => 'preview.contentful.com']);
  

• SSL Verification Disable for self-signed certs (not recommended for production):

  $client = new Client(['verify' => false]);