Filament Clicktrail Laravel Package

Getting Started

This release is a compatibility/security bump rather than a feature release: it tightens the Composer constraints to Filament ^3.3.55 and Laravel 12.60+ / 13.10+, and refreshes the package's localized requirement strings. Practically, that means the first thing to check before writing any code is whether your app already satisfies those floors.

composer require <vendor>/<package>   # will hard-fail on older Filament/Laravel
php artisan about                    # confirm framework + Filament versions

If composer update refuses to resolve, you are on a Filament build older than 3.3.55 or a Laravel patch below the new minimum — upgrade those first, since the constraint is a hard requirement, not a suggestion. Older Filament versions are explicitly excluded because of a security fix upstream, so don't try to --ignore-platform-reqs your way around it.

Once installed:

1. Publish assets/config: php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" (check the README for the exact tags — config and lang files are usually separate tags and you rarely need both).
2. Register the plugin in your panel provider (->plugin(PackagePlugin::make())) if it ships a Filament plugin class.
3. Clear caches: php artisan filament:optimize-clear && php artisan optimize:clear. Stale cached panel manifests are the single most common "it installed but nothing shows up" cause.
4. Open the panel and confirm the feature renders in the default locale before you touch translations.

Your first realistic use case is the happy path on a single panel with the default locale, then a second locale — localization is the area this release touched, so validate it early rather than at the end of integration.

Implementation Patterns

Pin and lockstep your dependency floors. Because the package now requires a specific Filament patch, treat Filament/Laravel upgrades as coupled. In CI, run composer update --prefer-lowest on at least one job — that is the only way you'll catch a regression where you silently drift below the floor on a fresh clone.

Config-first integration. Publish the config file into config/ and commit it. Reading defaults from the vendor directory makes behaviour invisible in code review and breaks when the package changes defaults in a patch release.

Locale resolution belongs in middleware, not in the plugin. If the package surfaces localized strings, drive the active locale from your own SetLocale middleware (user preference → session → app()->getLocale()), and let the package only render. Coupling locale switching to the package makes it painful to reuse the same locale logic on non-Filament routes.

Panel-scoped registration. For multi-panel apps, register the plugin only on the panels that need it. Pattern:

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(PackagePlugin::make())
        // ->plugin(PackagePlugin::make()->someOption(...))
        ;
}

Keep per-panel configuration in dedicated config keys rather than branching inside the provider — multi-tenant panel setups get unreadable fast otherwise.

Testing pattern. Use Filament's testing helpers plus a locale matrix. A cheap, high-value test is a Pest dataset over your supported locales that renders the component/page and asserts no missing-translation markers (__('...') keys leaking through as raw strings, or package::key appearing verbatim in output). This release changed localized requirements, so a locale-matrix smoke test is exactly the regression net you want.

Upgrade workflow. In a branch: bump the package, run composer update <vendor>/<package> -W, run your test suite, then diff the published lang files (git diff lang/vendor/<package>) to see which strings the release changed. Reviewing that diff is faster than re-reading release notes and tells you precisely which UI copy moved.

Gotchas and Tips

• The constraint is the feature. If you're seeing resolution conflicts, read them as an upgrade instruction, not a bug. The most common failure is a transitive package pinning filament/filament to 3.3.x below the patch floor; composer why-not filament/filament 3.3.55 identifies the culprit immediately.
• Laravel 12.60+ / 13.10+ is narrower than it looks. Apps on an early 12.x patch will fail to install even though "Laravel 12" sounds fine. Check composer show laravel/framework before assuming compatibility.
• Cached translations mask the change. Filament caches panel components and Laravel caches compiled views; after upgrading, php artisan optimize:clear and php artisan filament:optimize-clear before concluding the localized strings didn't update. In production, make sure your deploy script clears both.
• Published lang files override vendor updates. If you published translations in an earlier version, the release's updated requirement strings will not reach you — your published copy wins. Either re-publish (and re-apply your customizations, ideally via a dedicated override file rather than editing vendor-published copies), or diff manually.
• Don't hand-edit vendor/ lang files. Override at the app level or via a custom translation namespace; vendor edits vanish on the next composer install and are a recurring source of "works on my machine".
• Debugging missing strings: php artisan lang:publish won't help for vendor namespaces — check that the namespace matches the one the package registers, and that the locale actually exists under the package's resources/lang (a missing locale silently falls back to fallback_locale, which looks like a translation bug but isn't).
• Extension points to prefer: the plugin class (for panel config) and the published config file (for behaviour). Avoid subclassing package internals — patch releases like this one are exactly when internal signatures drift, and there's no BC promise in a 0.x line.
• Versioning signal: still on 0.1.x, so treat every minor bump as potentially breaking regardless of what the notes say. Pin an exact constraint ("<vendor>/<package>": "0.1.1") and upgrade deliberately rather than floating on ^0.1.