Filament Social Share Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require tapp/filament-social-share
   

   Ensure owenvoke/blade-fontawesome is installed (default dependency for icons):

   composer require owenvoke/blade-fontawesome
   

2. Publish Config (Optional):

   php artisan vendor:publish --provider="TappNetwork\FilamentSocialShare\FilamentSocialShareServiceProvider" --tag="config"
   

   Modify config/filament-social-share.php to customize platforms, icons, or default behavior.

3. First Use Case: Add the action to a Filament resource or page:

   use TappNetwork\FilamentSocialShare\Actions\SocialShareAction;
   
   protected static function getActions(): array
   {
       return [
           SocialShareAction::make(),
       ];
   }
   

   • Place the action in a resource's getActions() or a Filament page's getActions().
   • Defaults to sharing the current URL; override with url():

     SocialShareAction::make()->url(fn () => route('custom.route')),
     

Implementation Patterns

Core Workflows

1. Resource Integration: Attach to a Filament Resource or Page for contextual sharing (e.g., share a blog post URL):

   class PostResource extends Resource
   {
       public static function getActions(Post $record): array
       {
           return [
               SocialShareAction::make()
                   ->url(fn () => route('posts.show', $record))
                   ->label('Share Post'),
           ];
       }
   }
   

2. Dynamic URLs: Use closures to generate URLs dynamically:

   SocialShareAction::make()
       ->url(fn () => "https://example.com/posts/{$record->slug}")
   

3. Custom Platforms: Extend supported platforms (e.g., add WhatsApp):

   SocialShareAction::make()
       ->platforms([
           'whatsapp' => [
               'label' => 'WhatsApp',
               'icon' => 'fa-brands fa-whatsapp',
               'url' => fn (string $url) => "https://wa.me/?text=$url",
           ],
       ]),
   

4. Modal Customization: Override the modal view or template:

   SocialShareAction::make()
       ->modalView('custom::social-share-modal'),
   

5. Web Share API: Leverage native browser sharing (requires HTTPS):

   SocialShareAction::make()
       ->useWebShareApi(true),
   

Integration Tips

• Localization: Translate platform labels via Filament’s localization system.
• Permissions: Restrict access via Filament’s canAccessAction():

  SocialShareAction::make()->canAccessAction(fn () => auth()->user()->can('share-content')),
  

• Testing: Mock the action in tests:

  $this->get('/resource')
       ->assertSee('Share')
       ->assertDontSee('Web Share API'); // If not HTTPS
  

Gotchas and Tips

Pitfalls

1. HTTPS Requirement:

   • The Web Share API and clipboard copy fail on http://. Test locally with https:// or disable:

     SocialShareAction::make()->useWebShareApi(false),
     

2. Icon Dependencies:

   • Default icons rely on owenvoke/blade-fontawesome. If missing, icons won’t render. Fallback:

     SocialShareAction::make()->icon('fa-solid fa-share-nodes'),
     

3. URL Encoding:

   • Custom URLs must be URL-encoded. The package handles basic cases, but complex URLs (e.g., with ? or #) may need manual encoding:

     ->url(fn () => urlencode(route('route.with.query', ['param' => 'value'])))
     

4. Modal Z-Index:

   • If the modal appears behind other elements, override the CSS:

     SocialShareAction::make()->modalExtraAttributes(['style' => 'z-index: 9999;']),
     

Debugging

• Console Logs: Enable debug mode in config/filament-social-share.php:

  'debug' => env('APP_DEBUG', false),
  

  Logs URL generation and platform calls to storage/logs/laravel.log.

• Network Requests: Use browser dev tools to inspect failed social platform redirects (e.g., Twitter may block non-HTTPS URLs).

Extension Points

1. Custom Platforms: Add new platforms via the platforms() method or extend the Platform class:

   namespace App\Actions;
   
   use TappNetwork\FilamentSocialShare\Contracts\Platform;
   
   class CustomPlatform implements Platform
   {
       public function getLabel(): string { return 'Custom App'; }
       public function getIcon(): string { return 'fa-solid fa-rocket'; }
       public function getUrl(string $url): string { return "https://app.com/share?url=$url"; }
   }
   

   Register it:

   SocialShareAction::make()
       ->platforms(['custom' => new CustomPlatform()]),
   

2. Override Views: Publish and modify the modal/view:

   php artisan vendor:publish --tag="filament-social-share-views"
   

   Edit resources/views/vendor/filament-social-share/modal.blade.php.

3. Event Listeners: Listen for share events (e.g., log shares):

   use TappNetwork\FilamentSocialShare\Events\SocialShareRequested;
   
   SocialShareRequested::listen(function (SocialShareRequested $event) {
       \Log::info('Share attempted', ['platform' => $event->platform, 'url' => $event->url]);
   });
   

4. Configuration: Disable specific platforms globally in config/filament-social-share.php:

   'platforms' => [
       'twitter' => false, // Disable Twitter
       'linkedin' => true,
   ],