Social Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require c975l/social-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       C975L\SocialBundle\C975LSocialBundle::class => ['all' => true],
   ];
   

2. Database Migration Run migrations to create the social_links table (if using Doctrine):

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

3. First Use Case Display the social links block in a Twig template:

   {{ render_block('social_links') }}
   

   Or use the share buttons:

   {{ share_buttons() }}
   

Implementation Patterns

Core Workflows

1. Managing Social Links

• Admin CRUD: Access via EasyAdmin (/admin/social_links). No need to integrate into existing block collections.
• Dynamic Rendering: Use the social_links_display block in any page’s block flow:

  {{ render_block('social_links_display') }}
  

2. Share Buttons Integration

• Global Configuration: Enable share buttons site-wide via config/packages/c975l_social.yaml:

  c975l_social:
      enable_share_buttons: true
      networks: [twitter, facebook, linkedin]  # Customize networks
      style: flat  # Options: flat, badge, monochrome
  

• Twig Usage:

  {# Auto-render on all pages if enabled #}
  {{ include('C975LSocialBundle:share_buttons.html.twig') }}
  
  {# Manual override with custom URL #}
  {{ share_buttons('https://example.com/my-page') }}
  

3. Extending Social Networks

• Custom Networks: Override the networks config or extend the SocialNetwork enum (if available) in your bundle.
• Dynamic Icons: Use the icon key in the social_links table to reference custom SVG/FontAwesome icons.

4. Scheduled Posting (Future-Proofing)

• Hook into Events: Listen for C975LSocialBundleEvents::POST_SCHEDULED to integrate with third-party APIs (e.g., Buffer, Hootsuite) when the feature is added.

Integration Tips

Laravel-Specific Adaptations

1. Service Registration: Register the bundle’s services in config/services.php or use Laravel’s package auto-discovery:

   composer require laravel/package-autoload
   

2. Twig Integration: Ensure Twig is configured to auto-reload templates:

   // config/view.php
   'compiled' => env('APP_DEBUG') ? false : true,
   

3. EasyAdmin Compatibility: If using EasyAdmin, ensure your EasyAdminBundle config includes:

   easy_admin:
       entities:
           C975L\SocialBundle\Entity\SocialLink:
               class: C975L\SocialBundle\Entity\SocialLink
               label: 'Social Links'
   

4. Block System Integration: For Laravel’s block systems (e.g., spatie/laravel-blocks), map the social_links_display block to your block registry:

   // AppServiceProvider@boot
   Block::macro('socialLinks', function () {
       return Block::create('social_links_display')
           ->setTemplate('C975LSocialBundle::blocks/social_links_display');
   });
   

Gotchas and Tips

Pitfalls

1. Database Schema Assumptions:

   • The bundle expects a social_links table. If using Laravel’s migrations, manually create it or extend the bundle’s migrations.
   • Fix: Override the migration path in config/packages/c975l_social.yaml:

     c975l_social:
         migration_path: 'vendor/c975l/social-bundle/migrations'
     

2. EasyAdmin Dependency:

   • The admin CRUD relies on EasyAdmin. If not installed, the /admin/social_links route will 404.
   • Fix: Install EasyAdmin or disable the route via config:

     c975l_social:
         enable_admin: false
     

3. Twig Function Conflicts:

   • The share_buttons() function may conflict with existing Twig extensions.
   • Fix: Rename the function in your template or override the Twig environment:

     // config/services.php
     Twig\Environment::class => fn($container) => $container->get('twig')->addFunction(
         new \Twig\TwigFunction('custom_share_buttons', [$container->get('c975l_social.share_button_service'), 'render'])
     );
     

4. Caching Issues:

   • Social links or share buttons may not update immediately due to caching.
   • Fix: Clear the cache after changes:

     php artisan cache:clear
     php artisan view:clear
     

Debugging Tips

1. Log Social Link Queries: Enable Doctrine logging to debug social_links queries:

   # config/packages/dev/doctrine.yaml
   doctrine:
       dbal:
           logging: true
           profiling: true
   

2. Check Block Rendering: Verify the block is registered in your block system:

   php artisan block:list
   

3. Network-Specific Errors:

   • If share buttons fail silently, check the networks config for typos or unsupported networks.
   • Debug: Add a dd() in the ShareButtonService (if extendable) to inspect the networks array.

Extension Points

1. Custom Social Networks: Extend the SocialNetwork enum (if available) or override the getNetworks() method in the service:

   // src/Service/CustomSocialService.php
   use C975L\SocialBundle\Service\ShareButtonService;
   
   class CustomSocialService extends ShareButtonService
   {
       public function getNetworks(): array
       {
           return array_merge(parent::getNetworks(), ['custom_network']);
       }
   }
   

   Register the service in config/services.php:

   services:
       C975L\SocialBundle\Service\ShareButtonService:
           alias: App\Service\CustomSocialService
   

2. Block Template Overrides: Override Twig templates in resources/views/override/C975LSocialBundle/:

   resources/
       views/
           override/
               C975LSocialBundle/
                   blocks/
                       social_links.html.twig
   

3. Scheduled Posting Hooks: Listen for future events (once implemented):

   // EventSubscriber
   public static function getSubscribedEvents()
   {
       return [
           C975LSocialBundleEvents::POST_SCHEDULED => 'onPostScheduled',
       ];
   }
   
   public function onPostScheduled(PostScheduledEvent $event)
   {
       // Integrate with your API (e.g., Buffer)
   }
   

4. Icon Customization: Add custom icons by extending the SocialLink entity or using CSS:

   /* resources/css/app.css */
   .social-link-icon.custom-network::before {
       content: "\f123"; /* FontAwesome icon */
   }