Filament Social Networks Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require happytodev/filament-social-networks
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Happytodev\FilamentSocialNetworks\FilamentSocialNetworksServiceProvider" --tag="config"
   

2. First Use Case Add the field to a Filament resource form:

   use Happytodev\FilamentSocialNetworks\Fields\SocialNetworksField;
   
   SocialNetworksField::make('social_links')
       ->required()
       ->columns(2) // Adjust layout
       ->help('Add your social media profiles.')
   

3. Where to Look First

   • Package GitHub (if available)
   • config/filament-social-networks.php for customization
   • app/Models/User.php to define the database column (e.g., social_links->json).

Implementation Patterns

Core Workflows

1. Resource Integration

   // In a Filament Resource
   public static function form(Form $form): Form
   {
       return $form
           ->schema([
               // ...
               SocialNetworksField::make('social_media')
                   ->label('Social Profiles')
                   ->columnSpanFull(),
           ]);
   }
   

2. Customizing Networks Extend the default list via config:

   // config/filament-social-networks.php
   'networks' => [
       'github' => [
           'label' => 'GitHub',
           'icon'  => 'heroicon-o-code-bracket',
           'url_pattern' => 'https://github.com/{username}',
       ],
       // Add custom networks here
   ],
   

3. Validation & Storage

   • Uses JSON storage by default (e.g., social_links column in DB).
   • Validate URLs with:

     SocialNetworksField::make('social_links')
         ->rules(['required', 'url'])
         ->validateUrls() // Built-in URL validation
     

4. Dynamic Data Handling

   // Retrieve data in a model
   $user->social_links['twitter'] ?? null;
   
   // Update via API
   $user->update(['social_links' => ['twitter' => 'https://twitter.com/user']]);
   

Integration Tips

• Filament Panels: Works seamlessly in both admin and tenant panels.
• Livewire Components: Use SocialNetworksField inside custom Livewire components.
• API Responses: Serialize the field in API resources:

  public function toArray($request)
  {
      return [
          'social_links' => $this->social_links,
      ];
  }
  

Gotchas and Tips

Common Pitfalls

1. Database Schema

   • Ensure the column type is json or text (not string).
   • Migration example:

     $table->json('social_links')->nullable();
     

2. URL Validation

   • Default validation may fail for non-standard URLs (e.g., LinkedIn profiles).
   • Override with custom rules:

     ->rules(['required', function ($attribute, $value, $fail) {
         if (!preg_match('/linkedin\.com\/in\/[a-zA-Z0-9_-]+/', $value)) {
             $fail('Invalid LinkedIn URL.');
         }
     }])
     

3. Icon Conflicts

   • If icons clash with your Filament theme, override them in the config or use a CDN-based solution:

     'icons' => [
         'github' => 'https://cdn.jsdelivr.net/gh/devicons/devicon/icons/github/github-original.svg',
     ],
     

Debugging

• Empty Data: Check if the JSON column is null or malformed. Use:

  $user->social_links = json_encode($user->social_links);
  

• Field Not Rendering: Verify the package is registered in AppServiceProvider:

  FilamentSocialNetworksServiceProvider::make();
  

Extension Points

1. Custom Networks Dynamically add networks via a callback:

   SocialNetworksField::make('social_links')
       ->getNetworksUsing(function () {
           return collect(config('filament-social-networks.networks'))
               ->merge(['custom' => ['label' => 'Custom', 'icon' => 'heroicon-o-globe-alt']]);
       })
   

2. Event Hooks Listen for social link updates (if the package emits events):

   // Example (hypothetical)
   event(new SocialLinksUpdated($user, $oldLinks, $newLinks));
   

3. Localization Translate labels/network names:

   ->label(__('Social Media'))
   ->networkLabels([
       'twitter' => __('Twitter'),
       'linkedin' => __('LinkedIn'),
   ])
   

Performance

• Large Datasets: Avoid loading social links eagerly in queries. Use with():

  User::with(['social_links' => function ($query) {
      $query->select('id', 'social_links');
  }])->get();
  

• Caching: Cache the networks config if extending dynamically:

  Cache::remember('filament-social-networks-networks', now()->addHours(1), function () {
      return config('filament-social-networks.networks');
  });