Filament Plugin Cli Laravel Package

Getting Started

• Install as a dev-only dependency — this is a scaffolding tool, not runtime code:

  composer require --dev asciito/filament-plugin-cli
  

  Pin it while on 0.0.x (see Gotchas) and never ship it in require.

• Find the entry point before reading docs: composer.json in the package declares a bin, so the executable lands in vendor/bin. Locate it with:

  ls vendor/bin | grep -i filament
  vendor/bin/<binary> --help
  

  If a Laravel service provider is registered, the same commands are usually reachable through php artisan.

• Look at the published config and stub files first. The v0.0.19 changelog mentions tag removal via regex and configuration messaging, which means the CLI renders and rewrites stub content — the config file and stubs/ directory are where behaviour actually lives, not the command classes.

• First use case: scaffold a single plugin skeleton end-to-end, inspect every generated file, then delete it. Do this once on a throwaway branch before you build real plugins on top of the generator. You want to see what the generator produces before you have code that depends on its naming conventions.

• Verify the generated plugin actually boots: register it in your PanelProvider (->plugin(MyPlugin::make())), then load the panel. A skeleton that generates but doesn't register is the most common first-run surprise.

Implementation Patterns

Throwaway scaffold, then promote. The most reliable workflow is: generate into the app (app/Filament/Plugins/... or the package's default path), confirm it works, then move it to packages/<vendor>/<name> and wire it up as a path repository once the shape is settled. Generating directly into a path-repo package on the first attempt means a bad skeleton leaves you with a broken composer.json that you have to hand-fix.

One plugin per invocation. Treat the command as idempotent-per-plugin, not as a batch tool. Scripting multiple generations in a loop is fine, but each invocation should target a distinct, validated name — the v0.0.18/0.0.19 fixes were both in tag-removal regex handling, i.e. the string surgery applied to generated files, and string surgery is exactly what breaks when you feed it unusual input.

Commit the skeleton separately from your edits. Generate, commit the raw output, then build on top. When a later version changes the stubs you can diff generated-vs-your-code and see precisely what the generator now does differently, instead of guessing which lines were yours.

Re-publish rather than hand-patch config. The v0.0.19 "improve configuration message" change is cosmetic, but it signals the config/publish surface is still moving. Keep your published config thin — override only what you must — so re-publishing after an upgrade is cheap.

Non-interactive flags for CI. For repo bootstrap scripts, prefer explicit flags over prompt-driven input so the command doesn't hang in CI. Check --help for --no-interaction support inherited from Symfony Console; -n almost always works.

Pair with your own Pint/PHPStan setup. Generated code is a starting point, not a standard. Run your formatter and static analysis over the output as part of the same commit so generated skeletons match the rest of the codebase from day one.

Gotchas and Tips

• 0.0.x is not semver-stable. Composer treats ^0.0.19 as >=0.0.19 <0.0.20, which is fine, but ^0.0 is not. Pin explicitly ("asciito/filament-plugin-cli": "0.0.19") and upgrade deliberately — v0.0.18 and v0.0.19 were back-to-back regex fixes to the same code path, which tells you the string-manipulation layer is still settling.

• The tag-removal regex is the fragile part. Two consecutive releases fixing it means the generator strips tag markers from stub content, and that stripping previously misfired. If you generated anything on v0.0.17, diff your generated files against a fresh v0.0.19 scaffold — you may be carrying leftover marker comments or, worse, content that was removed when it shouldn't have been. Regenerate rather than hand-clean.

• Validate names before generating. Regex-driven substitution breaks on names containing spaces, leading digits, mixed case, or non-ASCII. Confirm the plugin name is a clean StudlyCase identifier before running the command; fixing a half-rewritten namespace across a dozen files afterwards is far more work than retyping a name.

• Config cache. After publishing or editing the package config, run php artisan config:clear (and config:cache in production-like environments). A stale cached config silently ignores your changes and makes the CLI look broken when it isn't.

• Line endings and path separators. If you develop on Windows and CI runs Linux, stub rewriting can introduce CRLF or backslash noise into generated composer.json and namespaces. Add an .gitattributes normalisation pass, or run generation inside the same container as CI.

• Debug with verbosity. When generation fails silently, re-run with -v / -vvv to get the underlying exception and the file path being processed. The failure is nearly always either a name validation issue or a stub that doesn't exist at the expected path.

• Extension point: publish and override stubs. Rather than forking the package, publish its stubs (check --help and the service provider's publishes calls) and edit your local copies. This is the cleanest way to enforce house style — namespace conventions, licence headers, declare(strict_types=1) — without diverging from upstream.

• Don't depend on it at runtime. Nothing in src/ should be referenced from application code. If you find yourself importing a class from this package outside of a generator script, you've coupled your plugin to a 0.0.x dev tool and every patch release becomes a risk.

• Watch the repo, not just the changelog. Release notes here are one-line summaries. Subscribe to the GitHub releases feed for asciito/filament-plugin-cli; at this version cadence, the compare links are more informative than the bullet points.