Filament Tool Kit Laravel Package

Getting Started

akira/filament-tool-kit is a utility package for Filament admin panels that ships copy-and-compose building blocks (form components, table helpers, JSON field definitions) rather than drop-in screens. Adoption is low (single-digit stars, no dependents), but release cadence is high — 1.x reached 1.28.0 before the jump to 2.0.0 on 2025-09-30 — so treat it as actively maintained but not community-hardened. Expect to read src/ before relying on anything.

Install

composer require akira/filament-tool-kit:^2.0

If you are coming from 1.x, do not bump blind. The 2.0.0 notes are almost silent on breaking changes (the only listed feature is additive: bio and social media fields in form components and their JSON files), which is exactly the situation where a major bump hides a rename or a file-layout change. Diff before upgrading:

git diff --no-index vendor/akira/filament-tool-kit/src /tmp/ftk-1.28/src
# or, cleanly:
composer require akira/filament-tool-kit:1.28.0 --no-update && composer update akira/filament-tool-kit

Filament v3+ is an implied requirement — check the filament/filament constraint in the package's composer.json. A 2.0 major bump is a plausible moment for the package to have moved its own Filament floor, so verify rather than assume.

Publish config (if present)

php artisan vendor:publish --tag="filament-tool-kit-config"
php artisan vendor:publish --tag="filament-tool-kit-migrations"   # only if migrations ship

The 2.0.0 notes reference "JSON files" alongside form components, which means the package likely ships definition/preset JSON (probably under resources/ or config/). Check whether those are published or read directly from vendor/ — that distinction decides whether an upgrade silently changes your field definitions. If the publish step errors, run php artisan vendor:publish interactively and pick the provider from the list.

Where to look first

1. vendor/akira/filament-tool-kit/src/ — service provider, then Concerns/, Resources/, Widgets/, Commands/, Components/.
2. Any JSON the package ships (search for *.json under vendor/akira/filament-tool-kit/) — 2.0.0 changed these, so they are a primary surface now, not an afterthought.
3. config/ — the intended tuning surface.
4. CHANGELOG.md — compare the 1.28.0 → 2.0.0 entry against the actual diff; the published notes are thin.
5. README.md — likely still thin; do not expect recipes.

First use case

The realistic first win is composing the package's form components into a resource schema — most relevantly the newly added bio and social media fields if you are building profile/author/company forms. A minimal smoke test:

// app/Providers/Filament/AdminPanelProvider.php
public function panel(Panel $panel): Panel
{
    return $panel
        ->default()
        ->id('admin')
        ->path('admin')
        // any plugin/registration the package provides goes here
        ;
}

Then visit /admin and confirm no boot errors. If nothing visibly changes, the package is exposing classes/JSON you compose into resources rather than auto-registering UI — go to the patterns below.

Implementation Patterns

Day-to-day value comes from composing the package's components and JSON definitions into your own Filament resources. Standardize on the patterns below so an eventual 3.0 or an abandonment costs you one file, not every resource.

1. Wrap components behind app-level traits

namespace App\Filament\Concerns;

trait UsesToolKitForms
{
    protected static function toolKitForm(Schema $schema): Schema
    {
        return $schema->components([
            // call into akira/filament-tool-kit components here
        ]);
    }

    protected static function profileFields(): array
    {
        return [
            // bio + social media components introduced in 2.0.0
        ];
    }
}

Every resource that needs bio/social fields calls profileFields(); nothing outside this trait imports the package namespace. When 2.0 renamed something, you fix one file.

2. Treat shipped JSON as a copied asset, not a runtime read

2.0.0 explicitly changes the JSON files, so any workflow that reads them from vendor/ will shift under you on the next minor. Copy the definitions you need into resources/ or app/Filament/Support/presets/, commit them, and own them. Use the package copy only as a source of the initial shape — and again as a reference when you want to pull in new fields like the 2.0.0 bio/social additions.

3. Panel plugin registration

If a plugin class ships, register it once in AdminPanelProvider and gate it by environment:

->plugins(array_filter([
    app()->environment('local') ? ToolKitPlugin::make() : null,
]))

Filament plugins are never auto-registered, so "features don't appear" usually means this step was skipped.

4. Widgets and dashboard composition

Register package widgets on the panel or a custom Dashboard page rather than scattering them:

->widgets([
    \Akira\FilamentToolKit\Widgets\StatsOverview::class,
])

Keep anything that runs its own queries behind a feature flag — tool-kit widgets rarely ship with pagination or caching, and a full-table stat widget on a large dashboard is an easy outage.

5. Commands as a build step

If artisan generators are included, wire them into composer run setup or onboarding docs so environments scaffold identically. Never run generators ad hoc against a real database; run them on a fresh branch and diff the output.

6. Upgrade 1.x → 2.x deliberately

Because the release notes list one additive feature against a major version number, assume the diff contains more than the notes say. Suggested sequence: branch, bump constraint, php artisan optimize:clear plus filament:optimize-clear, diff src/ and the JSON files against 1.28.0, re-run your panel boot test, and eyeball every resource using the wrapped trait. Only then merge.

7. Compose, then copy

For anything non-trivial, copy the class into app/Filament/Support/, adjust namespaces, and own it. Keep the composer dependency only for pieces you genuinely use at runtime. This is the highest-leverage pattern for a low-adoption package.

Gotchas and Tips

The major bump is under-documented. 2.0.0 lists "add bio and social media fields to form components and JSON files" — an additive feature — as the sole change over 1.28.0. Either the version number is semver-loose, or breaking changes are unlisted. Both cases argue for diffing the tags before upgrading and for pinning.

Pin, don't float. Use an exact tag or a tight constraint ("akira/filament-tool-kit": "2.0.0" or ~2.0.0), not ^2.0. With no dependents there is no downstream pressure to keep BC between minors, and this release proves the project will bump majors for what looks like a feature.

Version drift with Filament is the standing risk. Filament v3 → v4 changed schemas, actions, and panel config substantially. Confirm the package's filament/filament constraint against your installed version before adopting, and after every upgrade. A CI test that boots the panel is the cheapest guard.

Auto-discovery vs manual registration. Laravel discovers the service provider; Filament plugins are not auto-registered. Verify with:

php artisan about                 # confirm the provider is loaded
php artisan filament:optimize

Clear caches after install or upgrade. Filament caches components and panel config; stale caches produce "class not found" or "component not registered" errors, particularly after a schema-affecting upgrade:

php artisan optimize:clear
php artisan filament:optimize-clear   # command name is version-dependent

Config and JSON publishing is one-way. vendor:publish will not overwrite an existing file without --force. After upgrading to 2.0.0, diff the shipped config and shipped JSON against your published copies — new keys and renamed field definitions silently default to null, which is the usual source of "it worked before the update" bugs. This is the single most likely failure mode of this specific release.

Asset handling. If the package registers CSS/JS via FilamentAsset, run php artisan filament:assets (or filament:upgrade) after install and after upgrades. Missing assets show as unstyled widgets with no PHP error — check the browser console first.

Testing. Add a boot test so a broken upgrade fails CI, not production:

test('admin panel boots', function () {
    $this->actingAs(User::factory()->create())
        ->get('/admin')
        ->assertSuccessful();
});

Add a second test that resolves each package component you use, so a renamed class in 2.x fails loudly.

Extension points to prefer. Favor config, macros (Filament::macro), and plugin ->configureUsing() hooks over subclassing internals. Internal classes in low-star packages change without notice; config and macros are the intended surfaces. After 2.0.0, JSON definitions are a third surface — but copy them rather than reading them in place.

Dependency hygiene. No dependents means no community pressure for backward compatibility. Review the changelog and the commit list before bumping, and keep the trait/JSON-wrapper patterns above so you can drop the package in a single PR if maintenance stops or a 3.0 arrives without notes.