Social Links Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require astina/social-links-bundle:dev-master
   

   Add to AppKernel.php:

   new Astina\Bundle\SocialLinksBundle\AstinaSocialLinksBundle(),
   

2. First Use Case: Generate a Facebook share link in Twig:

   {{ social_link('facebook') }}
   

   Outputs a <a> tag with the current request URL pre-populated in Facebook’s share dialog.

Where to Look First

• Twig Extension: The core functionality is exposed via social_link() in Twig templates.
• Default Options: Check the README for default parameters (title, text, attributes, linkText).
• Supported Providers: Refer to oscarotero/social-links for available networks (e.g., twitter, linkedin).

Implementation Patterns

1. Dynamic URL Handling

• Current Request Fallback: Omit the URL parameter to auto-use the current request URI:

  {{ social_link('twitter') }}  {# Uses request.getUri() #}
  

• Explicit URL Override:

  {{ social_link('pinterest', 'https://example.com/product') }}
  

2. Customizing Link Appearance

• Attributes: Add classes, targets, or data attributes:

  {{ social_link('facebook', null, {'attributes': {'class': 'btn-share', 'data-tooltip': 'Share'}}) }}
  

• Link Text: Override the default provider name:

  {{ social_link('instagram', null, null, 'Share on IG') }}
  

3. Template Overrides

• Extend Default Rendering: Create app/Resources/AstinaSocialLinksBundle/views/SocialLinks/socialLink.html.twig to customize the <a> tag structure:

  <button class="share-btn" onclick="window.open('{{ link.href }}', '_blank')">
    {{ linkText|default(provider|title) }}
  </button>
  

4. Programmatic Usage

• Service Injection: Access the SocialLinks service in controllers:

  use Astina\Bundle\SocialLinksBundle\SocialLinks\SocialLinks;
  
  public function shareAction(SocialLinks $socialLinks)
  {
      $link = $socialLinks->getLink('linkedin', 'https://example.com');
      return new Response($link->getHtml());
  }
  

5. Batch Generation

• Loop Through Providers: Dynamically generate links for multiple networks:

  {% set providers = ['facebook', 'twitter', 'linkedin'] %}
  {% for provider in providers %}
      {{ social_link(provider) }}
  {% endfor %}
  

Gotchas and Tips

Pitfalls

1. Deprecated Bundle:

   • Last release was in 2017. Test thoroughly for compatibility with modern Symfony (e.g., Twig 3.x may break Twig 2.0-specific logic).
   • Workaround: Fork the repo and update dependencies (e.g., social-links/social-links:^2.0).

2. URL Encoding Issues:

   • URLs with special characters (e.g., ?, #) may not encode correctly. Manually encode URLs if needed:

     {{ social_link('twitter', 'https://example.com/page#section') }}
     {# May break; use urlencode_filter #}
     

3. Missing linkText:

   • If omitted, defaults to the provider name (e.g., Facebook). Override explicitly if needed:

     {{ social_link('facebook', null, null, 'Custom Text') }}
     

4. Twig Extension Caching:

   • Clear Twig cache (php bin/console cache:clear) if changes to the Twig extension aren’t reflected.

Debugging Tips

1. Inspect Generated HTML:

   • Use browser dev tools to verify the href attribute matches expectations. Example:

     <a href="https://www.facebook.com/sharer.php?u=https%3A%2F%2Fexample.com">
     

   • Mismatches often indicate URL encoding or provider-specific quirks.

2. Check Provider Support:

   • Not all providers work identically. Test with oscarotero/social-links’ demo.

3. Log SocialLinks Service:

   • Debug the underlying service in a controller:

     $this->get('social_links')->getLink('twitter', 'https://example.com')->getUrl();
     

Extension Points

1. Add Custom Providers:

   • Extend the underlying oscarotero/social-links by creating a custom provider class and registering it in the bundle’s configuration.

2. Override Default Options:

   • Modify the Twig extension’s default parameters in AstinaSocialLinksBundle/Twig/SocialLinksExtension.php:

     $options = array_merge([
         'attributes' => ['target' => '_blank', 'rel' => 'noopener noreferrer'],
     ], $options);
     

3. Integrate with Forms:

   • Use the bundle in Symfony Forms to attach share buttons to entities:

     $builder->add('share_link', HiddenType::class, [
         'mapped' => false,
         'data' => $this->get('social_links')->getLink('twitter', $entity->getUrl())->getHtml(),
     ]);
     

Configuration Quirks

1. No Config File:

   • The bundle has no config.yml; all behavior is driven by Twig extension parameters.

2. Request Context:

   • The URL defaults to request.getUri(). For non-web contexts (e.g., CLI), pass an explicit URL:

     {{ social_link('facebook', 'https://example.com') }}
     

3. Twig 3.x Compatibility:

   • If upgrading, replace {{ social_link(...) with {% set link = social_link(...) %}{{ link }} to avoid deprecated syntax.