Sharebuttons Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Run composer require c975L/sharebuttons-bundle in your Laravel project (note: this bundle is Symfony-based, but can be adapted via Laravel's bridge or standalone usage).

2. Publish Assets Since the bundle relies on Bootstrap and FontAwesome, ensure these are already included in your project. If not, install them via:

   npm install bootstrap @fortawesome/fontawesome-free
   

   Then compile assets (Laravel Mix/Vite).

3. First Use Case Add the share buttons to a Twig template (or Laravel Blade via Twig integration):

   {{ share_buttons({
       'url': 'https://example.com/current-page',
       'title': 'Share this page',
       'theme': 'light'  // or 'dark'
   }) }}
   

   For Laravel Blade, use @twig directive or embed Twig directly.

Implementation Patterns

Core Workflows

1. Dynamic URL Handling Pass dynamic URLs (e.g., from Laravel routes) to the bundle:

   {{ share_buttons({
       'url': path('article.show', {'slug': article.slug}),
       'title': article.title
   }) }}
   

2. Custom Styling Override the default template (app/Resources/c975LShareButtonsBundle/views/layout.html.twig) to match your theme:

   {% extends 'base.html.twig' %}
   {% block share_buttons %}
       <div class="custom-share-container">
           {{ parent() }}
       </div>
   {% endblock %}
   

3. Conditional Rendering Use Twig conditionals to show/hide buttons based on context:

   {% if is_mobile() %}
       {{ share_buttons({ 'theme': 'dark', 'compact': true }) }}
   {% else %}
       {{ share_buttons({ 'theme': 'light' }) }}
   {% endif %}
   

4. Laravel Integration

   • Service Provider: Register the bundle in config/app.php (if using Symfony-style bundles in Laravel).
   • Blade Directives: Create a custom Blade directive to wrap Twig calls:

     // app/Providers/BladeServiceProvider.php
     Blade::directive('shareButtons', function ($expression) {
         return "<?php echo \$this->twig->render('@c975LShareButtons/layout.html.twig', ['buttons' => $expression]); ?>";
     });
     

     Usage:

     @shareButtons(['url' => route('post.show'), 'title' => 'Post Title'])
     

5. API-Driven Buttons Fetch share links dynamically via a Laravel controller:

   public function getShareLinks(Request $request) {
       $url = $request->url;
       return ShareButtons::getLinks($url); // Hypothetical method
   }
   

   Render in Twig:

   {% for link in shareLinks %}
       <a href="{{ link.url }}">{{ link.icon }}</a>
   {% endfor %}
   

Gotchas and Tips

Pitfalls

1. Bootstrap/FontAwesome Dependency

   • The bundle assumes Bootstrap 4/5 and FontAwesome are loaded. If missing, buttons will break.
   • Fix: Ensure your resources/views/layouts/app.blade.php includes:

     <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet">
     <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/all.min.css">
     

2. Twig in Laravel

   • The bundle uses Twig templates. For pure Laravel projects:
     • Use TwigBridge (composer require twig/twig) or manually convert Twig to Blade.
     • Tip: Cache compiled Twig templates to avoid runtime overhead.

3. Route Conflicts

   • The bundle registers routes under /. In Laravel, this may conflict with existing routes.
   • Fix: Override the prefix in routes.yaml or use a subpath (e.g., /share).

4. Localization Issues

   • Share button labels (e.g., "Twitter", "Facebook") are hardcoded. For multilingual sites:
     • Override the template and replace text with Laravel’s __() or Symfony’s trans filter.
     • Example:

       <a href="{{ link.url }}"><i class="fab fa-twitter"></i> {{ 'Share on Twitter'|trans }}</a>
       

5. CORS for Dynamic URLs

   • If sharing URLs from APIs, ensure CORS headers allow cross-origin requests.
   • Fix: Add to Laravel’s HandleCors middleware:

     'paths' => ['api/share-buttons/*'],
     'allowed_methods' => ['GET'],
     

Debugging Tips

1. Inspect Rendered HTML Use browser dev tools to verify the bundle’s output. Missing styles? Check if Bootstrap/FontAwesome paths are correct.

2. Check Twig Environment If Twig templates fail to render:

   • Ensure the bundle’s templates are published:

     php artisan vendor:publish --tag=c975l-sharebuttons-views
     

   • Verify Twig is initialized in Laravel’s AppServiceProvider:

     $this->app->make('twig')->addPath(__DIR__.'/../resources/views', 'app');
     

3. Log Share Button Data Debug dynamic URLs by logging them in a Twig extension:

   // app/Extensions/ShareButtonsExtension.php
   public function getShareData($url, $title) {
       \Log::debug("Share URL: $url, Title: $title");
       return [...];
   }
   

Extension Points

1. Add Custom Share Services Extend the bundle by adding new share platforms (e.g., LinkedIn, Pinterest):

   • Override the ShareButtonsService (if exposed) or create a new Twig function.
   • Example Twig extension:

     $twig->addFunction(new \Twig\TwigFunction('customShareButton', [$this, 'renderCustomButton']));
     

2. Analytics Tracking Wrap share buttons in tracking code:

   <a href="{{ link.url }}" onclick="trackEvent('share', '{{ link.platform }}')">
       {{ link.icon }}
   </a>
   

3. Conditional Button Visibility Use Twig filters to show buttons only for specific content types:

   {% if article->isShareable %}
       {{ share_buttons({...}) }}
   {% endif %}
   

4. Lazy-Loading Defer non-critical share buttons to improve performance:

   <div class="lazy-share" data-url="{{ article.url }}">
       {{ share_buttons({...}) }}
   </div>
   

   Add JavaScript to load on scroll/interaction.