Relay Base Publication Connector Pure Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Add the bundle via Composer:

   composer require dbp/relay-base-publication-connector-pure-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       DigitalBlueprint\RelayBasePublicationConnectorPureBundle\DigitalBlueprintRelayBasePublicationConnectorPureBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php artisan vendor:publish --tag=relay-connector-config
   

   Update config/relay_connector.php with your Relay API gateway credentials and endpoints.

3. First Use Case Publish a test resource via the connector:

   use DigitalBlueprint\RelayBasePublicationConnectorPureBundle\Service\PublicationService;
   
   $publicationService = app(PublicationService::class);
   $result = $publicationService->publish([
       'title' => 'Test Publication',
       'content' => 'Hello, Relay!',
       'type' => 'article',
   ]);
   

Where to Look First

• Documentation: Start with ./docs/README.md for setup and API reference.
• Config: Review config/relay_connector.php for endpoint and authentication settings.
• Service Container: Check src/Service/PublicationService.php for core methods like publish(), update(), and delete().

Implementation Patterns

Core Workflows

1. Publication Lifecycle

   • Create: Use PublicationService::publish() with a normalized array of data.

     $publication = $publicationService->publish($data);
     

   • Update: Fetch the publication first, modify, then update:

     $publication = $publicationService->get($id);
     $publication['title'] = 'Updated Title';
     $publicationService->update($id, $publication);
     

   • Delete: Soft or hard delete via delete():

     $publicationService->delete($id, ['force' => true]);
     

2. Event-Driven Integration Listen for publication events (e.g., PublicationCreated, PublicationUpdated) via Laravel’s event system:

   // In a service provider or listener
   Event::listen(PublicationCreated::class, function ($event) {
       // Trigger downstream actions (e.g., notifications, analytics)
   });
   

3. Batch Processing Use PublicationService::publishBatch() for bulk operations:

   $publicationService->publishBatch([
       ['title' => 'Post 1', 'content' => '...'],
       ['title' => 'Post 2', 'content' => '...'],
   ]);
   

Integration Tips

• Laravel Models: Attach the connector to Eloquent models via traits or observers:

  // In a model (e.g., Post.php)
  use DigitalBlueprint\RelayBasePublicationConnectorPureBundle\Traits\RelayPublishable;
  
  class Post extends Model
  {
      use RelayPublishable;
  
      public function publishToRelay()
      {
          return $this->relayPublish();
      }
  }
  

• API Resources: Transform Eloquent models to Relay-compatible arrays using Laravel’s Resource classes:

  use Illuminate\Http\Resources\Json\JsonResource;
  
  class PostResource extends JsonResource
  {
      public function toArray($request)
      {
          return [
              'title' => $this->title,
              'content' => $this->body,
              'type' => 'post',
              // Relay-specific fields
          ];
      }
  }
  

• Queue Jobs: Offload publication tasks to queues for async processing:

  // Dispatch a job
  PublishToRelay::dispatch($post);
  
  // Job class
  class PublishToRelay implements ShouldQueue
  {
      use Dispatchable, InteractsWithQueue;
  
      public function handle()
      {
          $post->publishToRelay();
      }
  }
  

Gotchas and Tips

Pitfalls

1. Authentication Failures

   • Issue: Relay API rejects requests due to invalid credentials or tokens.
   • Fix: Verify config/relay_connector.php for correct client_id, client_secret, and token_endpoint. Use php artisan relay:auth:test to validate.
   • Debug: Enable debug mode in config and check Laravel logs for GuzzleHttp errors.

2. Data Normalization Mismatches

   • Issue: Relay expects specific fields (e.g., slug, author_id), but your data lacks them.
   • Fix: Use the Normalizer class to pre-process data:

     $normalized = app(\DigitalBlueprint\RelayBasePublicationConnectorPureBundle\Service\Normalizer::class)
         ->normalize($rawData);
     

3. Rate Limiting

   • Issue: Relay throttles requests during batch operations.
   • Fix: Implement exponential backoff in your batch loop or use Laravel’s throttle middleware.

4. Webhook Verification

   • Issue: Relay’s webhook callbacks fail Laravel’s signature verification.
   • Fix: Configure the webhook_secret in the bundle’s config and use the provided RelayWebhookHandler middleware.

Debugging

• Log Responses: Enable debug: true in config to log raw Relay API responses to storage/logs/relay.log.
• HTTP Client: Use the underlying HttpClient directly for debugging:

  $client = app(\DigitalBlueprint\RelayBasePublicationConnectorPureBundle\Http\Client::class);
  $response = $client->get('/publications/1');
  

• Event Dumping: Temporarily dump events in listeners:

  Event::listen(PublicationCreated::class, function ($event) {
      \Log::debug('Relay Publication Event', ['event' => $event->toArray()]);
  });
  

Config Quirks

• Endpoint Overrides: Dynamically override endpoints per environment:

  // In a service provider
  $this->app->bind(\DigitalBlueprint\RelayBasePublicationConnectorPureBundle\Http\Client::class, function ($app) {
      $config = $app['config']['relay_connector'];
      $config['endpoint'] = env('RELAY_ENDPOINT_OVERRIDE', $config['endpoint']);
      return new Client($config);
  });
  

• Retry Logic: Customize retry behavior for transient failures:

  // In config/relay_connector.php
  'http' => [
      'timeout' => 30,
      'retries' => 3,
      'retry_delay' => 100, // ms
  ],
  

Extension Points

1. Custom Normalizers Extend the Normalizer class to handle domain-specific transformations:

   class CustomNormalizer extends \DigitalBlueprint\RelayBasePublicationConnectorPureBundle\Service\Normalizer
   {
       protected function normalizeAuthor($data)
       {
           return [
               'id' => $data['user_id'],
               'name' => $data['user']['name'],
           ];
       }
   }
   

   Register it in a service provider:

   $this->app->bind(
       \DigitalBlueprint\RelayBasePublicationConnectorPureBundle\Service\Normalizer::class,
       CustomNormalizer::class
   );
   

2. Webhook Handlers Extend the RelayWebhookHandler to process custom event types:

   class CustomWebhookHandler extends \DigitalBlueprint\RelayBasePublicationConnectorPureBundle\Event\RelayWebhookHandler
   {
       protected function handleCustomEvent($payload)
       {
           if ($payload['event'] === 'custom.event') {
               // Handle custom logic
           }
       }
   }
   

3. API Extensions Add custom endpoints to the HttpClient:

   // In a service provider
   $client = $this->app->make(\DigitalBlueprint\RelayBasePublicationConnectorPureBundle\Http\Client::class);
   $client->extend('custom', function ($client) {
       return new CustomRelayClient($client);
   });