Social Buttons Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require chaplean/social-buttons-bundle
   

   Add to config/bundles.php:

   Chaplean\SocialButtonsBundle\ChapleanSocialButtonsBundle::class => ['all' => true],
   

2. Basic Configuration: Update config/packages/chaplean_social_buttons.yaml with your desired buttons (e.g., facebook, twitter) and their configurations (e.g., url, locale). Example:

   chaplean_social_buttons:
       buttons:
           twitter:
               url: "https://example.com/share"
               message: "Check this out!"
   

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

   {{ render(social_buttons('twitter')) }}
   

   Ensure required assets are loaded in your layout (see README for CSS/JS includes).

Implementation Patterns

Common Workflows

1. Dynamic URL Generation: Use Twig to pass dynamic URLs to buttons:

   {% set shareUrl = app.request.uri %}
   {{ render(social_buttons('facebook', {'url': shareUrl})) }}
   

2. Conditional Rendering: Hide/show buttons based on logic:

   {% if app.user.isPremium %}
       {{ render(social_buttons(['twitter', 'linkedin'])) }}
   {% endif %}
   

3. Custom Styling: Extend default classes via config:

   twitter:
       class_a: "btn-twitter-custom"
       class_i: "fa-twitter-square"
   

4. Integration with CMS: Use Twig functions in a CMS (e.g., Sylius, Sonata) to embed buttons in product pages or blog posts.

5. API-Driven Config: Fetch button configs from a database and merge them with default settings:

   // In a controller/service
   $config = $this->getButtonConfigFromDB();
   return $this->renderView('template.html.twig', [
       'socialButtons' => array_merge($defaultConfig, $config)
   ]);
   

Gotchas and Tips

Pitfalls

1. Asset Loading:

   • Forgetting to include bootstrap-social.css or font-awesome will break button rendering.
   • Fix: Always include the required assets in your base layout.

2. URL Validation:

   • Buttons with url: null will render but may fail silently. Validate URLs in config or runtime:

     {% if socialButton.url is not null %}
         {{ render(social_buttons(socialButton)) }}
     {% endif %}
     

3. Locale Quirks:

   • Some platforms (e.g., Twitter) may ignore or misinterpret non-standard locales (e.g., fr_FR vs. fr).
   • Tip: Test locales in a staging environment first.

4. Deprecated Dependencies:

   • The bundle relies on old versions of Bootstrap (3.x) and Font Awesome (4.x). Ensure compatibility with your project’s frontend stack.

5. Twig Function Scope:

   • The social_buttons Twig function is bundle-specific. Avoid naming conflicts with other extensions.

Debugging

• Inspect Rendered HTML: Use browser dev tools to verify button markup. Example output for Twitter:

  <a href="https://twitter.com/intent/tweet?text=Check%20this%20out%21&url=https%3A%2F%2Fexample.com%2Fshare&via=Chaplean"
     class="twitter btn btn-twitter" target="_blank">
     <i class="fa fa-twitter"></i> Tweet
  </a>
  

• Check Config Overrides: Use Symfony’s dump() to debug merged configs:

  $this->container->getParameter('chaplean_social_buttons.buttons');
  

Extension Points

1. Custom Button Types: Extend the bundle by creating a new button service. Example:

   # config/packages/chaplean_social_buttons.yaml
   buttons:
       custom:
           type: "custom"  # Requires custom implementation
           url: "https://example.com"
   

2. Override Twig Functions: Replace the default social_buttons function in your theme’s Twig environment:

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

3. Event Listeners: Listen for button rendering events (if the bundle exposes them) to modify behavior dynamically. Example:

   // src/EventListener/SocialButtonsListener.php
   public function onSocialButtonRender(SocialButtonEvent $event) {
       $event->setOption('class_a', 'my-custom-class');
   }