Filament Social Media Links Laravel Package

Getting Started

This release is a good first entry point: v2.2.0 contains no breaking changes, so the install path is the same as v2.1.x, with one improvement to structured-data output.

1. Install and publish assets:

   composer require wotzebra/filament-social-media-links
   php artisan vendor:publish --tag="filament-social-media-links-config"
   php artisan vendor:publish --tag="filament-social-media-links-migrations"
   php artisan migrate
   

2. Register the plugin on the panel(s) where editors should manage links:

   public function panel(Panel $panel): Panel
   {
       return $panel->plugin(SocialMediaLinksPlugin::make());
   }
   

3. Open the generated Filament page/resource, add your first platform entries (X, LinkedIn, GitHub, etc.), and save.
4. Render the links on the frontend (blade component or the package's view include) in your footer/header, and include the structured-data component in <head> if you want the JSON-LD Organization block.

Where to look first: the published config file (platform list, the model that supplies your logo/brand data, caching flags), the plugin class for panel/authorization options, the Blade views for frontend markup, and the structured-data generator if you plan to customise JSON-LD.

First use case: a settings-backed set of social profiles rendered as an icon row, plus an Organization JSON-LD block whose sameAs array is populated from those links.

Implementation Patterns

Config-driven platform set. Define the platforms you support in the config rather than hardcoding them in views; the Filament form builds its fields from that list, and the renderer iterates the same source. This keeps validation, icons, and output in sync.

Model-bound logo for structured data (new in v2.2.0). The JSON-LD logo is now resolved through the configured model instead of a static value. Point the config at the model that represents your organisation/site (whatever exposes the logo/URL), and the structured data picks it up automatically. This is the pattern to prefer over duplicating a logo URL in two places — one source of truth for both the UI and the schema block.

Programmatic seeding. For sites with a fixed, non-editable set of profiles, skip the UI and create the records in a seeder/migration. Keep the UI available only to admins via the plugin's authorization hooks.

Multi-panel / multi-tenant. Register the plugin per panel and scope records by tenant where applicable. If different panels need different platform subsets, drive the config per panel rather than sharing one global list.

Cache the rendered output. Social links change rarely but render on every request. Cache the rendered link array and the JSON-LD fragment (e.g. via Cache::remember keyed on locale/tenant), and bust the cache from the model's saved/deleted events or an observer. Filament saves don't automatically invalidate your frontend cache.

Frontend integration. Prefer the package's Blade component over hand-rolled loops so that icon sets, ordering, and rel/target attributes stay consistent. Override the view only when you need custom markup, and keep the override minimal.

Ordering and visibility. Treat sort order and an enabled/disabled flag as first-class fields — editors will want to hide a platform without deleting it.

Testing. Cover the Filament page with a Livewire test (create/edit/delete a link) and snapshot the rendered JSON-LD so schema regressions are caught when the package or your model changes.

Gotchas and Tips

• Upgrade check for the logo change. v2.2.0 resolves the structured-data logo through the configured model. If that model isn't configured, or its logo accessor returns null, the logo property may be omitted from the JSON-LD rather than falling back to a previous hardcoded value. After upgrading, validate your output with a schema validator or Rich Results Test.
• Clear caches after upgrading. If you cache the JSON-LD or rendered links, flush those keys; otherwise you'll keep serving the pre-upgrade logo behaviour and think the release did nothing.
• Run php artisan config:clear after any config edits — a cached config is the most common reason a platform or model change appears to be ignored.
• Non-breaking release. Everything else in v2.2.0 is Dependabot housekeeping (CI actions). No deprecations, no migrations, no signature changes — safe as a patch-level bump in composer.json if you pin minor versions.
• Re-publish views cautiously. If you override the package views, compare them against the shipped versions after each release; published views are not updated by Composer.
• Escape and validate. Editors control these URLs. Validate as URLs on save, and render with rel="noopener noreferrer" (and me if you're doing IndieAuth-style verification). Be deliberate about {!! !!} when outputting the JSON-LD block.
• Platform keys are load-bearing. An unrecognised platform key typically results in a missing icon rather than an error, which is easy to miss in review. Assert the key set in a test.
• Extension points. Custom platform definitions (config), model contract for logo/brand data, view overrides, and the plugin's authorization/canAccess hooks are the supported seams. Prefer them over forking the package.
• Debugging structured data. If the block renders but tools complain, dump the generated array before encoding — the usual culprits are an empty sameAs, a relative logo URL, or a trailing-slash mismatch against your canonical domain.