mortalkiller/filament-package-standard
A standardized foundation for building Filament packages, bundling conventions, tooling, and base structure so you can scaffold, develop, and ship consistent plugins faster with less boilerplate.
Standard v2 is a development-time package, not a runtime dependency. You add it to a package repository's require-dev and it shapes scaffolding, static analysis, tests, and CI — it doesn't ship code to your consumers.
composer require --dev mortalkiller/filament-package-standard:^2.0
First steps after requiring it:
plugin → filament/filament (integrates with a panel)theme → filament/filamentforms → filament/formstables → filament/tableslibrary → filament/support
Choose the narrowest one that matches actual behavior — a forms-only package should not drag in filament/filament.CHANGELOG.md plus the dedicated guide) even for new packages; it doubles as the map of what v2 expects to exist in the repo.developing-filament-packages Boost skill. It's distributed through the Laravel Boost third-party skill convention and now includes dedicated scaffolding and migration guidance — the fastest way to get correct, current scaffolding instructions in an AI-assisted workflow..editorconfig, the Larastan config at level 6+, the PHPUnit/Pest config with the new strict flags, and the GitHub Actions workflows (including the Zizmor audit).First practical use case: scaffold a fresh forms package, run the standard's analysis and test setup, and push it through CI — that exercises every v2 default (profile, opt-ins, Larastan, strict PHPUnit, Zizmor) in one pass before you touch a real package.
Profile-first scaffolding. Treat the profile as a contract. It decides your minimum Filament runtime dependency and which stubs and opt-ins make sense. When in doubt, pick the narrower profile; widening later is a deliberate decision, narrowing later is a breaking change for consumers.
Opt-in capabilities, not a monolith. v2 formalizes opt-ins for config, migrations, views, translations, stubs, assets, Workbench, browser tests, and Rector. Enable only what the package actually uses. A package with no publishable views shouldn't carry view stubs or asset build steps — this keeps CI fast and the diff surface small.
Panel plugins only when there's a panel. Only add a Filament Plugin class if the package genuinely integrates with a panel. A forms/tables/library package that registers a plugin is signaling an integration it doesn't have.
Prefer spatie/laravel-package-tools for new runtime packages. It standardizes service provider wiring, config publishing, migrations, and view/translation loading. Existing packages are explicitly exempt — do not churn a working provider just to adopt it.
Adopt v2 tooling on your current major. This is the key workflow pattern: upgrading the standard is not a package release. Package SemVer is driven by consumer-visible API, behavior, and compatibility — not by the standard's version. A typical adoption PR is docs + CI + config changes, with no CHANGELOG "breaking" entry and no new major tag.
CI as the enforcement layer. Wire the generated workflows so that Larastan level 6+, the strict PHPUnit/Pest settings, and Zizmor all run on PRs. Reviewers then argue about design, not about whether analysis was run. Add a Windows job for anything cross-platform-sensitive (path handling in asset/stub tooling, shell invocations, line endings).
Laravel Boost skill in the loop. Keep the developing-filament-packages skill available to the team so scaffolding and v1→v2 migration requests produce v2-shaped answers instead of v1-shaped ones. It's the cheapest way to keep a growing team consistent.
Incremental migration for existing packages. Order of operations that keeps PRs reviewable: (1) .editorconfig + Rector, (2) Larastan to level 6+, (3) PHPUnit/Pest strictness flags, (4) Zizmor + workflow updates, (5) opt-in capabilities you were missing, (6) profile alignment / dependency narrowing last, since that's the only step that can change the runtime dependency graph.
The standard's major version is not your package's major version. The single most likely mistake is bumping your package to a new major because the standard went to v2. v2 states this explicitly: no automatic major. If runtime behavior is unchanged, ship it as a minor or patch.
PHP 8.2 is now the floor for the standard itself. Verified on 8.2, 8.3, 8.4, and 8.5. If your own package still supports 7.x-era PHP, the standard's tooling may run on a newer PHP than your runtime matrix claims — keep those two matrices deliberate and separate. Run CI across the whole PHP range you advertise, not just the standard's.
Over-broad profile = over-broad dependency. Choosing plugin for something that only provides form fields silently adds filament/filament to every consumer's install. Verify composer.json after scaffolding; this is easy to miss and hard to unwind without a breaking change.
Strict PHPUnit/Pest settings surface old sloppiness. Warnings, risky tests, empty suites, and randomized execution turning on will fail suites that previously passed. Expect a cleanup pass: remove empty test classes, fix tests with no assertions, and chase order-dependence bugs that randomized execution exposes. Do this in its own commit — don't bury it in a feature PR.
Randomized execution reveals hidden state. Tests that depend on insertion order or shared static state will fail intermittently. The fix is test isolation, not disabling randomization — but if you must, disable it temporarily and file the cleanup.
Larastan level 6+ is a real jump. Budget time for generics, array shape, and nullability fixes. Suppress narrowly with @phpstan-ignore and a reason; don't lower the level or blanket-ignore whole directories. Level 6 is the documented baseline, so lowering it is a visible deviation.
Zizmor findings are about workflow security, not your PHP. Pin actions, scope permissions, and remove untrusted-input interpolation in run: blocks. These are quick wins but unfamiliar to most PHP devs — route them to whoever owns CI.
Windows CI failures are usually paths and line endings. If you add the Windows job, expect the first run to fail on separators, executable bits, or shell-specific commands. .editorconfig plus consistent PHP_EOL handling heads off most of it. Also avoid hardcoding / in test fixtures and stub paths.
Opt-ins are additive but not free. Enabling Workbench or browser tests adds runtime and CI minutes; enabling assets implies a build step. Add each one with a reason in the PR description, or they'll accumulate as dead config.
Don't refactor a working provider. Existing packages are explicitly allowed to keep hand-written service providers. Migrating to spatie/laravel-package-tools mid-life buys nothing for consumers and risks subtle changes to publish tags and merge config — do it only if you're already touching that code for another reason.
Extension points to lean on: profiles (change once, propagate), per-capability opt-ins (compose the feature set you need), the generated CI workflows (add jobs rather than editing generated steps, so upstream updates stay mergeable), and the Boost skill (keeps humans and agents on the same v2 conventions).
How can I help you explore Laravel packages today?