Shariff Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require cedricziel/shariff-bundle
   

   Enable the bundle in config/bundles.php:

   CedricZiel\ShariffBundle\CedricZielShariffBundle::class => ['all' => true],
   

2. Routing Add to config/routes.yaml:

   cedricziel_shariff:
       resource: "@CedricZielShariffBundle/Resources/config/routing.xml"
       prefix: /_shariff
   

3. Basic Configuration Add to config/packages/cedricziel_shariff.yaml:

   cedricziel_shariff:
       domain: 'yourdomain.com'
       force_protocol: https  # or http
   

4. First Use Case Embed Shariff in a Twig template:

   {{ render(controller('CedricZielShariffBundle:Shariff:render', {
       'url': app.request.getUri(),
       'title': 'Your Page Title',
       'theme': 'heise'
   })) }}
   

Implementation Patterns

Common Workflows

1. Dynamic URL Sharing Pass dynamic URLs/titles from controllers:

   // src/Controller/ArticleController.php
   public function show(Article $article): Response
   {
       return $this->render('article/show.html.twig', [
           'shariff_data' => [
               'url' => $this->generateUrl('article_show', ['id' => $article->id]),
               'title' => $article->title,
           ],
       ]);
   }
   

   In Twig:

   {% if shariff_data %}
       {{ render(controller('CedricZielShariffBundle:Shariff:render', shariff_data)) }}
   {% endif %}
   

2. Theme Customization Override default themes by extending the bundle’s templates:

   templates/
   └── CedricZielShariffBundle/
       └── Shariff/
           └── render.html.twig  # Customize here
   

3. Caching Strategy Leverage Symfony’s cache for performance:

   cedricziel_shariff:
       cache:
           cacheDir: '%kernel.cache_dir%/shariff'
           lifetime: 3600  # 1 hour
   

4. Service Integration Use the ShariffService in services:

   // src/Service/MyService.php
   public function __construct(private ShariffService $shariff)
   {
   }
   
   public function generateShareCode(): string
   {
       return $this->shariff->render(
           url: '/current-url',
           title: 'Dynamic Title',
           theme: 'heise'
       );
   }
   

Gotchas and Tips

Pitfalls

1. Protocol Mismatch

   • If force_protocol is misconfigured, Shariff may fail to load due to mixed-content warnings.
   • Fix: Ensure force_protocol matches your site’s actual protocol (e.g., https for production).

2. Caching Issues

   • Stale cache can cause outdated share counts.
   • Fix: Clear cache after updates:

     php bin/console cache:clear
     

3. Domain Configuration

   • Shariff requires an exact domain match (e.g., yourdomain.com vs. www.yourdomain.com).
   • Fix: Use a wildcard (*.yourdomain.com) or configure multiple domains in domain:

     cedricziel_shariff:
         domain: ['yourdomain.com', 'www.yourdomain.com']
     

4. Twig Rendering Errors

   • If render() fails, check:
     • The route prefix (/_shariff) is accessible.
     • Required parameters (url, title) are passed.

Debugging Tips

• Inspect Generated HTML: View source to verify Shariff’s JavaScript/CSS is loaded.
• Check Network Requests: Ensure /_shariff/render returns a 200 status.
• Log Configuration: Add debug logs in config/packages/cedricziel_shariff.yaml:

  cedricziel_shariff:
      debug: true  # Logs configuration to Symfony's log channel
  

Extension Points

1. Custom Services Extend ShariffService to add logic:

   // src/Service/CustomShariffService.php
   class CustomShariffService extends ShariffService
   {
       public function renderWithAnalytics(array $options): string
       {
           $options['analytics'] = true;
           return parent::render($options);
       }
   }
   

   Register as a service override:

   services:
       CedricZiel\ShariffBundle\Service\ShariffService: '@app.custom_shariff_service'
   

2. Event Listeners Hook into Shariff events (e.g., shariff.render) to modify behavior:

   // src/EventListener/ShariffListener.php
   class ShariffListener implements EventSubscriberInterface
   {
       public static function getSubscribedEvents(): array
       {
           return [
               ShariffEvents::RENDER => 'onRender',
           ];
       }
   
       public function onRender(RenderEvent $event): void
       {
           $event->setTheme('custom-theme');
       }
   }
   

3. Theme Overrides Copy the default theme from:

   vendor/cedricziel/shariff-bundle/Resources/views/Shariff/
   

   To your project’s templates/CedricZielShariffBundle/Shariff/ and modify.