Social Buttons Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require ekyna/social-buttons-bundle
   

   Enable it in config/bundles.php:

   Ekyna\SocialButtonsBundle\EkynaSocialButtonsBundle::class => ['all' => true],
   

2. Basic Configuration Publish the default config (optional):

   php bin/console config:dump-reference EkynaSocialButtonsBundle
   

   Override defaults in config/packages/ekyna_social_buttons.yaml:

   ekyna_social_buttons:
       networks: ['facebook', 'twitter', 'linkedin'] # Enable required networks
       options: { /* Customize button styles, sizes, etc. */ }
   

3. First Use Case Render buttons in a Twig template:

   {{ render(social_buttons('share', {'url': app.request.uri})) }}
   

   Outputs a share button group for the current page URL.

Implementation Patterns

Common Workflows

1. Dynamic Network Selection Use Twig logic to conditionally render buttons:

   {% if app.user.isPremium %}
       {{ render(social_buttons('share', {'networks': ['pinterest', 'reddit']})) }}
   {% endif %}
   

2. Custom Button Styling Extend default options via config:

   ekyna_social_buttons:
       options:
           facebook:
               layout: 'box_count'  # Override default 'standard'
               size: 'large'
   

3. Integration with Forms Attach buttons to form actions (e.g., "Share this post"):

   <form method="post">
       {{ form_widget(form) }}
       {{ render(social_buttons('share', {'url': path('post_show', {'id': post.id})})) }}
   </form>
   

4. API-Driven Buttons Fetch dynamic URLs via controller:

   // src/Controller/SocialController.php
   public function share(Post $post): Response
   {
       return $this->render('post/share.html.twig', [
           'shareUrl' => $this->generateUrl('post_show', ['id' => $post->id]),
       ]);
   }
   

5. Localization Use Twig’s trans filter for network names:

   {% for network in social_buttons('share') %}
       <button>{{ trans('social.' ~ network) }}</button>
   {% endfor %}
   

Gotchas and Tips

Pitfalls

1. Network Availability

   • The bundle assumes networks are pre-configured. Unavailable networks (e.g., vk) will throw errors unless filtered in networks config.
   • Fix: Validate networks exist in Ekyna\SocialButtonsBundle\Network\NetworkManager.

2. Caching Issues

   • Buttons may not update if the options config is cached. Clear cache after changes:

     php bin/console cache:clear
     

3. Twig Template Overrides

   • Default Twig templates are in vendor/ekyna/social-buttons-bundle/Resources/views/. Override them in templates/bundles/ekynasocialbuttons/ to avoid updates overwriting changes.

4. CSRF on Forms

   • Buttons rendered inside forms may trigger CSRF errors. Use {{ form_csrf_token() }} or exclude buttons from form submission:

     <div class="social-buttons">
         {{ render(social_buttons('share')) }}
     </div>
     

Debugging Tips

1. Check Network URLs Dump generated URLs to verify configuration:

   {{ dump(social_buttons('share', {'url': 'https://example.com'}).urls) }}
   

2. Enable Dev Mode Set EKYNA_SOCIAL_BUTTONS_DEBUG=true in .env to log network errors.

3. Custom Networks Extend the NetworkInterface to add unsupported networks:

   // src/Network/CustomNetwork.php
   namespace App\Network;
   
   use Ekyna\SocialButtonsBundle\Network\NetworkInterface;
   
   class CustomNetwork implements NetworkInterface
   {
       public function getUrl(string $action, string $url): string
       {
           return "https://custom.com/share?url={$url}";
       }
   }
   

   Register it in services.yaml:

   services:
       App\Network\CustomNetwork:
           tags: [ekyna_social_buttons.network]
   

Extension Points

1. Event Listeners Hook into button rendering via ekyna_social_buttons.button_render event:

   // src/EventListener/SocialButtonListener.php
   public function onButtonRender(ButtonRenderEvent $event)
   {
       $event->getButtons()->addAttribute('data-custom', 'value');
   }
   

   Register in services.yaml:

   services:
       App\EventListener\SocialButtonListener:
           tags:
               - { name: kernel.event_listener, event: ekyna_social_buttons.button_render, method: onButtonRender }
   

2. Custom Actions Extend beyond share (e.g., like, follow) by creating new Twig functions or overriding the ActionManager.