Site Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require atlantic18/coral-site-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Atlantic18\CoralSiteBundle\Atlantic18CoralSiteBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console coral:site:init
   

   Edit config/packages/coral_site.yaml to define:

   • Content storage (e.g., local, github, dropbox)
   • Route handling strategy (e.g., yaml, annotation, or php)

3. First Use Case: Rendering a Page Define a content file (e.g., content/home.yaml):

   title: "Welcome"
   content: "<h1>Hello, Coral!</h1>"
   

   Create a route in config/routes/coral.yaml:

   home:
       path: /
       defaults: { _controller: 'Atlantic18CoralSiteBundle:Page:render', content: 'home' }
   

   Run the dev server and visit /.

Implementation Patterns

Content Management Workflow

1. Storage Integration Use the CoralStorageInterface to integrate custom storage backends (e.g., S3, custom DB):

   // config/packages/coral_site.yaml
   coral_site:
       storage:
           driver: 'custom'
           options:
               connection: 's3://your-bucket'
   

   Implement Atlantic18\CoralSiteBundle\Storage\CoralStorageInterface for your driver.

2. Dynamic Routing Leverage the CoralRouter to handle routes dynamically:

   // src/Controller/CustomController.php
   use Atlantic18\CoralSiteBundle\Routing\CoralRouter;
   
   class CustomController extends AbstractController {
       public function __invoke(CoralRouter $router, string $contentId) {
           return $this->renderContent($contentId);
       }
   }
   

   Define routes in config/routes/coral.yaml:

   dynamic_route:
       path: /content/{id}
       defaults: { _controller: 'App\Controller\CustomController' }
   

3. Twig Integration Extend Twig templates with Coral-specific logic:

   {% extends 'base.html.twig' %}
   
   {% block content %}
       {{ coral_content('home').render() }}
       {# Render a specific content block #}
       {{ coral_content('home').getBlock('hero') }}
   {% endblock %}
   

   Register the Twig extension in config/packages/twig.yaml:

   twig:
       globals:
           coral_content: '@atlantic18_coral_site.twig.content_loader'
   

4. Content Branching Use GitHub/GitLab for content versioning:

   # coral_site.yaml
   coral_site:
       storage:
           driver: 'github'
           options:
               repo: 'your-org/your-repo'
               branch: 'main'
               token: '%env(GITHUB_TOKEN)%'
   

   Pull changes via:

   php bin/console coral:site:pull
   

Gotchas and Tips

Pitfalls

1. Caching Quirks Coral caches content aggressively. Clear caches after storage changes:

   php bin/console cache:clear
   php bin/console coral:site:clear-cache
   

   Override cache behavior in coral_site.yaml:

   coral_site:
       cache:
           enabled: false
           ttl: 3600
   

2. Route Precedence Coral routes take precedence over Symfony’s default router. Ensure no conflicts:

   # config/routes.yaml
   _coral:
       resource: "@Atlantic18CoralSiteBundle/Resources/config/routing.yaml"
       prefix: /
   

   Place Coral routes after other routes in routes.yaml.

3. Content Loading Order Content files are loaded alphabetically. Prefix files with numbers for ordering:

   content/01_home.yaml
   content/02_about.yaml
   

Debugging

1. Enable Debug Mode

   # coral_site.yaml
   coral_site:
       debug: true
   

   Logs detailed content loading events to var/log/coral_site.log.

2. Validate Content Structure Use the coral:site:validate command to check YAML syntax:

   php bin/console coral:site:validate
   

3. Storage Connection Issues For GitHub/Dropbox, ensure:

   • Tokens have repo/files permissions.
   • Webhooks are configured for real-time updates (if using webhook driver).

Extension Points

1. Custom Content Types Extend Atlantic18\CoralSiteBundle\Model\ContentInterface:

   class CustomContent implements ContentInterface {
       public function getCustomField() { /* ... */ }
   }
   

   Register the type in coral_site.yaml:

   coral_site:
       content_types:
           custom: 'App\Model\CustomContent'
   

2. Event Listeners Listen for content events (e.g., ContentLoadEvent):

   // src/EventListener/CoralListener.php
   use Atlantic18\CoralSiteBundle\Event\ContentLoadEvent;
   
   class CoralListener {
       public function onContentLoad(ContentLoadEvent $event) {
           if ($event->getContent()->getId() === 'home') {
               $event->setContent($this->modifyContent($event->getContent()));
           }
       }
   }
   

   Bind in services.yaml:

   services:
       App\EventListener\CoralListener:
           tags:
               - { name: 'kernel.event_listener', event: 'coral.content.load' }
   

3. Override Templates Override Coral’s default templates in templates/Atlantic18CoralSiteBundle/:

   templates/
       Atlantic18CoralSiteBundle/
           Page/
               render.html.twig  {# Override page rendering #}