Core Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require atlantic18/coral-core-bundle
   

   Add to config/bundles.php:

   Atlantic18\CoralCoreBundle\Atlantic18CoralCoreBundle::class => ['all' => true],
   

2. First Use Case: Content Aggregation Coral excels at aggregating microservices. Start by defining a content type (e.g., Article) via YAML/JSON in config/coral/content_types/:

   # config/coral/content_types/article.yml
   Article:
     fields:
       title: { type: string }
       body:  { type: markdown }
   

   Register the type in services.yaml:

   coral.content_types:
     article: '@Atlantic18\CoralCoreBundle\ContentType\Article'
   

3. Fetching Content Use the ContentManager service to retrieve content:

   $content = $this->get('coral.content_manager')->get('article', 1);
   

Implementation Patterns

Workflow: Microservice Integration

1. Define API Endpoints Coral assumes microservices expose REST/GraphQL APIs. Configure connectors in config/coral/connectors/:

   # config/coral/connectors/user_service.yml
   user_service:
     endpoint: 'https://api.users.example.com'
     auth:   { type: 'bearer', token: '%env(USER_API_TOKEN)%' }
   

2. Aggregate Data Use the ConnectorManager to fetch remote data:

   $userData = $this->get('coral.connector_manager')->call('user_service', 'GET', '/users/1');
   

3. Compose Content Merge local and remote data into a unified content type:

   $content = $this->get('coral.content_composer')->compose([
       'local' => $localArticle,
       'remote' => $userData,
   ]);
   

Patterns for Developers

• Field Transformations Use field resolvers to transform data before rendering:

  // src/Resolver/MarkdownResolver.php
  class MarkdownResolver implements FieldResolverInterface {
      public function resolve($value) {
          return Markdown::parse($value);
      }
  }
  

  Register in services.yaml:

  coral.field_resolvers.markdown: '@App\Resolver\MarkdownResolver'
  

• Event-Driven Workflows Listen to content events (e.g., ContentUpdatedEvent) to trigger actions:

  // src/EventListener/ContentSyncListener.php
  class ContentSyncListener {
      public function onContentUpdated(ContentUpdatedEvent $event) {
          $this->get('coral.connector_manager')->call('sync_service', 'POST', '/sync', [
              'content_id' => $event->getId(),
          ]);
      }
  }
  

  Bind in services.yaml:

  coral.event_listener.content_sync: '@App\EventListener\ContentSyncListener'
  

• Custom Storage Backends Extend StorageInterface to support non-database storage (e.g., S3, Dropbox):

  class DropboxStorage implements StorageInterface {
      public function save($content) {
          // Use Dropbox SDK to upload
      }
  }
  

  Configure in config/coral/storage.yml:

  default: dropbox
  storages:
    dropbox: '@App\Storage\DropboxStorage'
  

Gotchas and Tips

Pitfalls

1. Connector Timeouts

   • Issue: Remote API calls may hang if microservices are slow/unavailable.
   • Fix: Configure timeouts in connector YAML:

     user_service:
       timeout: 5  # seconds
     

   • Debug: Use coral:debug:connectors to inspect active connections.

2. Content Type Caching

   • Issue: Changes to content_types/*.yml may not reflect immediately.
   • Fix: Clear the cache:

     php bin/console cache:clear
     

   • Tip: Use coral:dump:content-types to validate configurations.

3. Field Resolver Conflicts

   • Issue: Multiple resolvers for the same field type can cause ambiguity.
   • Fix: Prioritize resolvers by registering them in order (last registered wins).

4. Event Subscriber Overrides

   • Issue: Third-party bundles may override your event listeners.
   • Fix: Use tags with high priority:

     tags:
       - { name: kernel.event_listener, event: ContentUpdatedEvent, method: onContentUpdated, priority: 255 }
     

Debugging Tips

• Log Connector Calls Enable debug mode in config/coral/connectors.yml:

  debug: true
  

  Logs will appear in var/log/coral.log.

• Validate Content Structure Use the coral:validate:content command to check for missing fields or invalid types.

• Inspect Active Content Dump all loaded content types:

  php bin/console coral:dump:content-types
  

Extension Points

1. Custom Content Types Extend AbstractContentType to add business logic:

   class BlogPost extends AbstractContentType {
       public function isPublished() {
           return $this->get('status') === 'published';
       }
   }
   

2. Dynamic Field Resolution Use DynamicFieldResolver to resolve fields at runtime:

   $resolver = new DynamicFieldResolver([
       'author' => function($content) {
           return $this->get('coral.connector_manager')->call('user_service', 'GET', '/users/' . $content['user_id']);
       }
   ]);
   

3. Headless Mode Disable the Symfony framework entirely by configuring Coral as a standalone service:

   # config/packages/coral.yaml
   coral:
     framework: false
     storage: 'dropbox'
   

   Useful for CLI tools or serverless functions.

4. Webhook Triggers Expose Coral content via webhooks for real-time updates:

   // src/EventListener/WebhookListener.php
   class WebhookListener {
       public function onContentUpdated(ContentUpdatedEvent $event) {
           $this->sendWebhook($event->getContent());
       }
   
       private function sendWebhook($content) {
           // Use Guzzle or Symfony HttpClient
       }
   }