Ssi Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require crunch/ssi-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Crunch\SsiBundle\CrunchSsiBundle::class => ['all' => true],
   ];
   

2. Basic Configuration Edit config/packages/crunch_ssi.yaml:

   crunch_ssi:
       enabled: true
       cache_dir: '%kernel.cache_dir%/ssi'
       default_fragment_ttl: 3600  # 1 hour in seconds
   

3. First Use Case Create a fragment template at templates/partials/_header.html.twig:

   {# templates/partials/_header.html.twig #}
   <header>
       <h1>Welcome, {{ app.user.name }}</h1>
   </header>
   

   Render it in a layout:

   {# templates/base.html.twig #}
   {% ssi include '_header' %}
   

Implementation Patterns

Fragment Caching & Reusability

• Named Fragments: Use named fragments for reusable components:

  {% ssi include '_sidebar' with {'items': sidebarItems} %}
  

• Dynamic Parameters: Pass variables to fragments:

  {% ssi include '_product_card' with {
      product: product,
      price: product.price - product.discount
  } %}
  

Integration with Symfony Components

• Twig Extensions: Extend Twig with custom logic:

  // src/Twig/AppExtension.php
  class AppExtension extends \Twig\Extension\AbstractExtension
  {
      public function getFunctions()
      {
          return [
              new \Twig\TwigFunction('get_ssi_cache_key', [$this, 'getCacheKey']),
          ];
      }
  
      public function getCacheKey($fragmentName, $params)
      {
          return \Crunch\SsiBundle\SsiRenderer::generateCacheKey($fragmentName, $params);
      }
  }
  

• Event Listeners: Hook into fragment rendering lifecycle:

  // src/EventListener/SsiListener.php
  class SsiListener implements EventSubscriberInterface
  {
      public static function getSubscribedEvents()
      {
          return [
              SsiEvents::PRE_RENDER => 'onPreRender',
          ];
      }
  
      public function onPreRender(PreRenderEvent $event)
      {
          $fragment = $event->getFragment();
          if ($fragment->getName() === 'analytics') {
              $event->setContent('<!-- Analytics snippet -->');
          }
      }
  }
  

Performance Optimization

• Cache Invalidation: Manually invalidate fragments:

  $this->get('crunch_ssi.renderer')->invalidateFragment('header');
  

• Conditional Rendering: Use Twig’s if with SSI:

  {% if app.user.isAdmin %}
      {% ssi include '_admin_tools' %}
  {% endif %}
  

Gotchas and Tips

Common Pitfalls

• Cache Directory Permissions: Ensure cache_dir is writable:

  chmod -R 775 %kernel.cache_dir%/ssi
  

• Fragment Naming Conflicts: Avoid duplicate fragment names across bundles.
• Circular Dependencies: SSI fragments cannot include themselves directly.

Debugging

• Disable Caching Temporarily:

  crunch_ssi:
      enabled: true
      cache_dir: null  # Disables caching
  

• Log Fragment Rendering:

  crunch_ssi:
      debug: true
  

  Check logs for rendered fragments and cache hits/misses.

Extension Points

• Custom Renderers: Implement Crunch\SsiBundle\Renderer\RendererInterface for non-Twig templates (e.g., PHP).
• Pre/Post-Processors: Use SsiEvents::PRE_RENDER and SsiEvents::POST_RENDER to modify fragment content dynamically.
• Template Paths: Override default paths via configuration:

  crunch_ssi:
      template_paths:
          - '@App/partials'
          - '@VendorBundle/partials'
  

Pro Tips

• Fragment Versioning: Append version hashes to fragment names for cache busting:

  {% ssi include '_header_v2' %}
  

• Edge Cases: Handle empty fragments gracefully:

  {% ssi include '_optional_feature' ignore_missing=true %}
  

• Security: Sanitize fragment names to prevent path traversal:

  $fragmentName = preg_replace('/[^a-zA-Z0-9_]/', '', $fragmentName);