Site Link Bundle Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation Add the bundle to your composer.json:

   composer require contextualcode/site-link-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       ContextualCode\SiteLinkBundle\SiteLinkBundle::class => ['all' => true],
   ];
   

2. Configuration Update config/packages/contextualcode_site_link.yaml to define your siteaccesses:

   site_link:
       siteaccesses:
           - site1
           - site2
       default_siteaccess: site1
   

3. First Use Case Generate a cross-siteaccess link for a content item:

   use ContextualCode\SiteLinkBundle\Generator\SiteLinkGenerator;
   
   $generator = $this->container->get(SiteLinkGenerator::class);
   $link = $generator->generate($content, 'site2');
   

   Outputs a URL like: https://site2.example.com/content/123.

Implementation Patterns

Common Workflows

1. Link Generation in Controllers Use dependency injection to generate links dynamically:

   public function showAction(Content $content, SiteLinkGenerator $generator)
   {
       $crossSiteLink = $generator->generate($content, 'mobile');
       return $this->render('content/show.html.twig', [
           'crossSiteLink' => $crossSiteLink,
       ]);
   }
   

2. Twig Integration Access the generator in templates:

   {{ app.service('contextualcode_site_link.generator').generate(content, 'admin') }}
   

3. Media Linking Handle media items (e.g., images) across siteaccesses:

   $mediaLink = $generator->generateMedia($media, 'site2');
   

4. Batch Processing Use the SiteLinkBatchGenerator for bulk operations (e.g., migrations):

   $batchGenerator = $this->container->get(SiteLinkBatchGenerator::class);
   $batchGenerator->process($contents, 'site2');
   

Integration Tips

• Symfony Event Listeners Trigger link updates on content publish/unpublish:

  use ContextualCode\SiteLinkBundle\Event\SiteLinkEvent;
  
  public function onContentPublish(SiteLinkEvent $event)
  {
      $event->getGenerator()->generate($event->getContent(), 'mobile');
  }
  

• Custom Link Types Extend the generator for non-standard routes:

  class CustomLinkGenerator extends SiteLinkGenerator
  {
      public function generateCustomRoute($content, $siteaccess)
      {
          return $this->router->generate('custom_route', [
              'id' => $content->id,
              '_siteaccess' => $siteaccess,
          ]);
      }
  }
  

• Cache Warmup Pre-generate links for critical paths:

  $generator->generate($content, 'site2'); // Forces cache population
  

Gotchas and Tips

Pitfalls

1. Siteaccess Mismatch

   • Issue: Links may break if default_siteaccess is misconfigured.
   • Fix: Explicitly pass the target siteaccess to generate().
   • Debug: Check ezplatform.siteaccess in the request context.

2. Circular Dependencies

   • Issue: Generating links for a content item that references itself (e.g., recursive blocks).
   • Fix: Use SiteLinkGenerator::generateSafe() to avoid infinite loops.

3. Media URL Overrides

   • Issue: Custom media URL resolvers may conflict with the bundle.
   • Fix: Ensure your resolver implements MediaUrlResolverInterface and is tagged correctly.

4. Route Not Found

   • Issue: generate() throws RouteNotFoundException for invalid routes.
   • Fix: Validate routes exist before generation or handle exceptions:

     try {
         $link = $generator->generate($content, 'site2');
     } catch (RouteNotFoundException $e) {
         $this->logger->error($e->getMessage());
         return null;
     }
     

Debugging Tips

• Enable Verbose Logging Add to config/packages/monolog.yaml:

  handlers:
      contextualcode:
          type: stream
          path: "%kernel.logs_dir%/site_link.log"
          level: debug
  

• Check Generated URLs Use debug:router to verify routes:

  php bin/console debug:router --siteaccess=site2
  

• Inspect Siteaccess Context Dump the current siteaccess in templates:

  {{ dump(app('ezpublish.siteaccess')|default('unknown')) }}
  

Extension Points

1. Custom Generators Create a service decorator:

   # config/services.yaml
   ContextualCode\SiteLinkBundle\Generator\SiteLinkGenerator:
       decorates: 'contextualcode_site_link.generator'
       arguments: ['@contextualcode_site_link.generator.inner']
   

2. Post-Install Hooks Use the SiteLinkEvents::POST_INSTALL event to update existing links:

   $event->getDispatcher()->addListener(
       SiteLinkEvents::POST_INSTALL,
       function (SiteLinkEvent $event) {
           $event->getGenerator()->regenerateAll('site2');
       }
   );
   

3. Dynamic Siteaccess Resolution Override SiteAccessResolverInterface for logic like:

   • User-agent-based siteaccess selection.
   • Geolocation routing.

4. Link Validation Add a validator to check links before rendering:

   use ContextualCode\SiteLinkBundle\Validator\SiteLinkValidator;
   
   $validator = new SiteLinkValidator($generator);
   if (!$validator->isValid($link, 'site2')) {
       throw new \RuntimeException('Invalid cross-siteaccess link');
   }