Filament Plugin Tools Laravel Package

Getting Started

Before you install, answer the version question. This package ships two lines (2.x and 3.x) whose relationship to Filament majors is undocumented, and the 2.0.5 changelog compares 3.0.0...2.0.5 — a 2.0.5 tag against a 3.0.0 baseline. Do not composer require with a floating constraint. Install it explicitly against the Filament major in your panel and record why:

# check what your panel actually runs first
composer show filament/filament | grep versions
composer show lara-zeus/filament-plugin-tools --all

# then install pinned, as a dev dependency
composer require --dev lara-zeus/filament-plugin-tools:^2.0 --with-all-dependencies

If the two lines map to Filament v3 vs v4 and your panel is on v3, take the 2.x line; if you can't get a clear answer from the maintainer or the tags, treat that as a blocker on standardizing and fall back to a template repo. The package is small; the switching cost is a day.

Verify the dependency graph on a clean tree, not on your existing lock file. Release 2.0.5 dropped illuminate/contracts:

composer why illuminate/contracts

Filament almost certainly supplies Contracts transitively, so nothing breaks — but if any in-house plugin was relying on this package to drag Contracts into the graph, you now get a Class not found at the worst possible time. Two minutes here saves an afternoon later.

Where to look first. In order:

1. vendor/lara-zeus/filament-plugin-tools/composer.json — read require vs require-dev. You want to know whether the tooling leaks dev-only packages into the graph you'd inherit when generating a plugin.
2. vendor/lara-zeus/filament-plugin-tools/src/ — the command classes are the real documentation. This package is a generator; the commands are the API surface.
3. The stubs/ directory — this is what you'll actually be editing long-term. Skim it before you generate anything, because it determines the shape of every plugin you ship.
4. php artisan list | grep -i zeus — enumerate the available commands rather than guessing names from the README.

First use case: scaffold one real plugin, not a hello-world. The whole value proposition is setup-time savings on realistic surface area. Point the generator at a packages/ directory wired through a Composer path repository, generate a plugin that mirrors an existing internal admin resource, and time it against your manual baseline. A toy plugin proves only that the generator runs.

// root composer.json
"repositories": [{ "type": "path", "url": "packages/*" }]

A path repository keeps the feedback loop fast and defers release engineering until the pattern has proven itself — exactly right for a pilot.

Implementation Patterns

Keep the tooling in require-dev and out of the generated plugin's runtime. This is the pattern that matters most and the one most likely to be violated by generated output. When the generator writes a composer.json for your new plugin, audit it: the plugin should depend on filament/filament and Laravel — not on lara-zeus/filament-plugin-tools. The tooling is a factory, not a component. If generated plugins inherit the tooling as a runtime require, you've made every plugin you ship carry a 4-star, single-maintainer dependency into production for no reason.

Treat generated output as application code you own. The adoption doc should say this out loud. Generated service providers, config files, and stubs are yours to edit freely — commit them, review them, refactor them. The upgrade path is not composer update plus regeneration; it's "the maintainer changed a stub, and we decide whether to adopt the change manually across our plugins." Set that expectation early or every Filament bump becomes a merge exercise across every plugin you've ever generated.

Wire the plugin the way Filament expects, and let the generator handle the boilerplate. A Filament plugin is a class implementing Filament\Contracts\Plugin with getId(), register(Panel $panel), and boot(Panel $panel), backed by a service provider. The scaffolding's job is to get that skeleton right so you're not hand-typing loadViewsFrom / loadMigrationsFrom / mergeConfigFrom for the fifth time. Use the generated provider as the seam for asset registration (Filament's asset registration in the panel's boot), config merging, and migration loading — then leave it alone.

Publish and customize stubs for house style. The leverage comes from consistency, and consistency comes from the stubs matching your conventions, not the maintainer's. Publish them, then adjust:

• Namespace and vendor prefix conventions
• Whether the skeleton includes a test harness (pest/phpunit bootstrap, a Filament panel test case) — if generated plugins ship without tests by default, add them to the stub, because "we'll add tests later" never happens
• composer.json metadata: license, authors, require/require-dev split, PHP constraint matching your fleet
• Config file shape and env var names

Once stubs are published and customized, they belong to you and they drift. Note in the README that a tooling upgrade means re-diffing stubs, not blindly republishing.

Use a path repository for the pilot, tags for the steady state. During the spike, packages/* path repos let you change the generated plugin and the consuming app in the same commit. Once the pattern is proven, promote to tagged releases per plugin. Don't skip the path-repo phase — tagging releases during discovery is how you burn a week on version bumps for a plugin you might delete.

Add a generator smoke test to CI. A single job that runs the scaffolding commands into a temp directory and asserts the output compiles (php -l, or a composer install + php artisan about) catches the failure mode this class of package is most prone to: a stub that passes on the maintainer's machine and breaks on yours after a patch release. Cheap, and it makes upgrades a green/red decision instead of an investigation.

Gotchas and Tips

The 2.0.5 / 3.0.0 version tangle is a gate, not a footnote. Whatever you pin, pin it exactly and write down which Filament major it targets. A ^ constraint on a package whose major-line relationship is undocumented means an unreviewed major jump can land in a routine composer update — and unlike a runtime dependency, you won't find out from an error page. You'll find out when a generator produces a skeleton that doesn't match your panel version.

illuminate/contracts removal is the classic "works on my machine" change. The 2.0.5 substance is dropping a transitive dependency. Impact is probably nil because Filament supplies it — but "probably" is exactly the confidence level that produces a Class not found in someone else's branch three weeks later. Run composer why illuminate/contracts on a scratch install as a checklist item, not an investigation. Also worth asking the maintainer whether the removal was hygiene or conflict-avoidance; the latter means it may regress.

Don't let it creep into the request path. No generated plugin should require this package. No production service provider should reference it. The failure mode with small dev tooling is quiet promotion: someone adds it to require "just to reuse a helper," and now a single-maintainer package with no SLA is load-bearing in production. State the boundary in the adoption doc and enforce it in review.

Four stars and zero dependents means you are the QA. Not disqualifying for dev tooling — blast radius is a developer's branch — but it means the pilot must exercise real surface area. Expect to read src/ rather than documentation, and budget for the possibility that you file the first bug report. The mitigation to record is a fork plan with a named owner: the package is small enough that forking is genuinely low-cost, and it's better to name that option before you need it than to negotiate it during a crisis.

Debugging generator output. When a generated plugin doesn't behave, check in this order: (1) is the plugin class registered on the panel (->plugin(MyPlugin::make()) in the PanelProvider), (2) did the service provider get autoloaded (check composer dump-autoload and bootstrap/providers.php for Laravel 11+), (3) are config/views/migrations actually being loaded (php artisan config:clear, then php artisan about and php artisan route:list for panel routes), (4) is a stale published stub shadowing the vendor one — vendor:publish --force will silently overwrite your customizations if you're not careful about tags.

Clear caches after every scaffolding run. php artisan optimize:clear — generated config and view paths won't register reliably behind a cached config, and the resulting "it works after I restart" confusion burns more time than the cache clear ever did.

Extension points, ranked by durability. Stubs first (yours, version them, expect drift on upgrade). Config publishing second. Everything else — command internals, traits — is vendor code you shouldn't patch; if you need behavior the package won't give you, fork it or write the ten lines yourself. At this size, the second option is usually cheaper than tracking a fork.