Filament Form Builder Laravel Package

Getting Started

• Install with composer require <vendor>/<package>; the service provider is auto-discovered, so there is nothing to add to config/app.php.

• Publish only the tags the package actually documents (php artisan vendor:publish --tag=<package>-config, --tag=<package>-views, --tag=<package>-migrations). Publishing a tag whose source directory is missing is silently a no-op in most Laravel versions — always confirm files landed.

• Smoke-test the install immediately with the command chain that broke in 5.0.0:

  php artisan view:cache && php artisan optimize
  

  This is the fastest way to prove the provider's registered paths (loadViewsFrom, publishes) point at directories that exist in the installed dist.

• First real use case: publish the views tag and override a template under resources/views/vendor/<package>/…. That override path only works if the package registers a view namespace, which is exactly the registration that regressed in 5.0.0.

Implementation Patterns

• Override, never edit. loadViewsFrom() gives host overrides in resources/views/vendor/<package> precedence over the package copy. Publish once, commit the overrides, and re-check them on every major bump.
• Namespace hygiene. If the package registers a view namespace but ships no views (the 5.0.0 situation), don't publish and don't rely on the namespace. Register your own with View::addNamespace('<package>', resource_path('views/vendor/<package>')) in an app service provider, or expose a Blade component instead.
• Registration guards. Use $this->app->runningInConsole() only for console-only wiring (commands, migrations). Never wrap loadViewsFrom() or publishes() in it — deferred/conditional registration makes view:cache behave differently between local and CI, which is how path bugs slip through.
• Defensive forks. If you maintain a fork or wrapper provider, guard the call: is_dir($path) && $this->loadViewsFrom($path, '<package>'). Cheap and immune to this class of bug.
• Deploy pipeline. composer install --no-dev && php artisan optimize is a standard last step. Pin ^5.0.1 so the pipeline isn't broken by the provider's dead view path.
• CI guard. Add php artisan view:cache (exit-code checked) as a job step. It compiles every registered hint path and therefore catches missing-directory regressions from any installed package, not just this one.

Gotchas and Tips

• The 5.0.0 defect. The service provider registered (and offered to publish) a resources/views directory the package does not ship. view:cache enumerates the view finder's namespace hints and throws when a hinted directory is absent, so php artisan optimize failed in every host app — including apps that never touched the package's views. Fixed in 5.0.1; there is no reason to stay on 5.0.0.
• Debugging the symptom. You'll see a DirectoryNotFoundException (or a Symfony Finder "directory does not exist" error) during optimize/view:cache. php artisan view:clear does not help — nothing was cached. Run php artisan about, then grep vendor/<vendor>/<package>/src for loadViewsFrom and publishes to find the dead path.
• Root cause is usually packaging, not code. Either the folder never existed (boilerplate provider copied from a package that does ship views) or it was excluded from the dist tarball via .gitattributes export-ignore. Check vendor/ rather than the Git repo — a path that exists in Git can still be missing from the installed package.
• Clean up after 5.0.0. If you ran vendor:publish on 5.0.0 you may have an empty resources/views/vendor/<package> tree. It's harmless but misleading for the next developer; prune it and re-run view:cache to confirm.
• Extension points that avoid the provider entirely: View::composer(), Blade::directive(), Blade::component(), or a small app-level provider registered after the package's. Keeping overrides out of the vendor provider means a patch release like 5.0.1 can't collide with your customisations.
• Treat "no views shipped" as a signal. A package that publishes views but ships none usually renders nothing of its own — read the README before assuming the view tag is part of the setup, and skip it if the templates are meant to come from your app.