Shariff Bundle Laravel Package

## Getting Started

### Minimal Setup
1. **Install via Composer**:
   ```bash
   composer require nucleos/shariff-bundle

2. Enable the Bundle in config/bundles.php:

   return [
       // ...
       Nucleos\ShariffBundle\NucleosShariffBundle::class => ['all' => true],
   ];
   

3. Configure the Bundle in config/packages/nucleos_shariff.yaml:

   nucleos_shariff:
       services: ['facebook', 'twitter', 'xing']  # Default services
       theme: 'dark'                              # 'light' or 'dark'
       url: 'https://your-site.com'              # Base URL for shariff
   

4. Add Twig Extension to your templates:

   {{ render(controller('NucleosShariffBundle:Shariff:render', {'services': ['facebook', 'twitter']})) }}
   

   • First Use Case: Integrate shariff buttons into a SonataAdmin list action or a custom page template.

Implementation Patterns

Common Workflows

1. Dynamic Service Rendering:

   • Use Twig to conditionally render shariff buttons based on user roles or content type:

     {% if app.user.hasRole('ROLE_PREMIUM') %}
         {{ render(controller('NucleosShariffBundle:Shariff:render', {
             'services': ['facebook', 'linkedin'],
             'theme': 'light'
         })) }}
     {% endif %}
     

   • Laravel Twig Bridge: If using Laravel, ensure the Twig bundle is configured to resolve Symfony controllers (e.g., via Twig\Environment extensions).

2. SonataAdmin Integration:

   • Override the default list action in SonataAdmin to include shariff buttons:

     // src/Admin/YourAdmin.php
     protected function configureListFields(ListMapper $listMapper)
     {
         $listMapper
             ->add('title')
             ->add('_action', 'actions', [
                 'actions' => [
                     'share' => [
                         'template' => '@NucleosShariff/share_button.html.twig',
                         'services' => ['twitter', 'facebook']
                     ]
                 ]
             ]);
     }
     

   • Create a custom template (templates/admin/YourAdmin/share_button.html.twig) to render shariff buttons.

3. API-Driven Configuration:

   • Fetch shariff service configurations dynamically from a database or API:

     // src/Service/ShariffConfigService.php
     public function getShariffConfig(): array
     {
         return [
             'services' => $this->configRepository->getEnabledServices(),
             'theme' => $this->userPreferences->getTheme(),
         ];
     }
     

   • Pass the dynamic config to the Twig render:

     {{ render(controller('NucleosShariffBundle:Shariff:render', app.shariffConfig)) }}
     

4. Event-Driven Extensions:

   • Listen to the nucleos_shariff.build_config event to modify shariff configurations globally:

     // src/EventListener/ShariffConfigListener.php
     public function onBuildConfig(ShariffConfigEvent $event)
     {
         $event->setTheme('dark');
         $event->addService('mastodon');
     }
     

   • Register the listener in services.yaml:

     services:
         App\EventListener\ShariffConfigListener:
             tags:
                 - { name: kernel.event_listener, event: nucleos_shariff.build_config }
     

Gotchas and Tips

Pitfalls

1. Controller Resolution in Laravel:

   • The bundle assumes Symfony’s controller resolution. In Laravel, you may need to:
     • Use a Twig extension to proxy the call:

       // src/Twig/AppExtension.php
       public function getShariffButtons(array $services, string $theme = 'dark'): string
       {
           $html = file_get_contents('https://your-site.com/shariff?' . http_build_query([
               'services' => implode(',', $services),
               'theme' => $theme,
           ]));
           return new \Twig\Markup($html, 'UTF-8');
       }
       

     • Register the extension in config/services.php:

       Twig::getInstance()->addExtension(new \App\Twig\AppExtension());
       

2. Caching Static Assets:

   • Shariff buttons are static HTML/JS. Ensure your CDN or cache (e.g., Laravel’s config('cache.default')) does not aggressively cache the dynamic query strings (e.g., ?services=facebook,twitter). Use cache tags or versioned URLs:

     {{ render(controller('NucleosShariffBundle:Shariff:render', {
         'services': ['facebook'],
         'cacheKey': 'shariff_facebook_v1'
     })) }}
     

3. Archived Package Risks:

   • The package is archived (no updates since 2021). Verify compatibility with:
     • Your Symfony/Laravel version (e.g., test with symfony/http-foundation:^5.4).
     • Modern shariff.js versions (e.g., dxng/shariff).
   • Mitigation: Fork the repo and update dependencies if critical features are missing.

4. Theme Inconsistencies:

   • The theme option (light/dark) may not propagate correctly if shariff.js is loaded from a CDN. Override the CSS in your assets:

     /* resources/assets/css/shariff-overrides.css */
     .shariff-dark { --shariff-bg: #1a1a1a; } /* Customize dark theme */
     

Debugging Tips

1. Inspect Rendered HTML:

   • Check the output of {{ render(controller(...)) }} in Twig. If empty, verify:
     • The controller path is correct (NucleosShariffBundle:Shariff:render).
     • No Symfony kernel exceptions (enable debug mode: APP_DEBUG=true).

2. Service-Specific Issues:

   • If a service (e.g., xing) fails to load, check:
     • The service’s shariff.js configuration (e.g., dxng/shariff#services).
     • Network requests in DevTools for blocked resources (e.g., CORS errors).

3. Laravel-Specific Debugging:

   • Use Laravel’s dd() or dump() to inspect the bundle’s config:

     dd(\Nucleos\ShariffBundle\DependencyInjection\Configuration::getConfigTreeBuilder());
     

Extension Points

1. Custom Services:

   • Extend the bundle by creating a custom service provider:

     // src/Service/ExtendedShariffService.php
     public function renderExtended(array $services): string
     {
         $services[] = 'custom_service';
         return $this->render($services);
     }
     

   • Override the Twig render call:

     {{ app.extended_shariff.renderExtended(['facebook']) }}
     

2. Twig Filters:

   • Add a Twig filter to sanitize service names:

     // src/Twig/AppExtension.php
     public function getFilters()
     {
         return [
             new \Twig\TwigFilter('shariff_services', [$this, 'sanitizeServices']),
         ];
     }
     

     {{ ['facebook', 'twitter|']|shariff_services }}
     

3. Laravel Mix/Webpack:

   • Bundle shariff.js with your assets to avoid CDN dependencies:

     // webpack.mix.js
     mix.js('resources/js/shariff.js', 'public/js')
         .copy('node_modules/shariff/dist/shariff.min.js', 'public/js/shariff.min.js');
     

   • Load it in your layout:

     <script src="{{ asset('js/shariff.min.js') }}"></script>
     

```markdown
## Additional Notes for Laravel Developers
- **Service Provider**: Register the bundle in `config/app.php` under `providers` (if not auto-discovered):
  ```php
  Nucleos\ShariffBundle\NucleosShariffBundle::class,

• Route Prefix: If using Laravel’s routing, prefix the shariff route in routes/web.php:

  Route::prefix('shariff')->group(function () {
      // Proxy the Symfony controller or use the Twig extension
  });
  

• Blade Integration: For Blade templates, use the Twig extension via a helper:

  // app/Helpers/ShariffHelper.php
  function shariffButtons(array $services): string
  {
      return app('twig')->render('shariff_