Generator Module Laravel Package

Getting Started

This package's views are the part you'll touch most days. Since v1.0.3 the published view stubs are sourced from the active theme rather than a single hard-coded stub directory — so the first thing to establish is which theme the stubs will be pulled from before you publish anything.

1. Install and publish, in this order: config → assets → views.

   composer require <vendor>/<package>
   php artisan vendor:publish --provider="<Vendor>\<Package>\<Package>ServiceProvider"
   

   Prefer publishing by tag (--tag=config, --tag=views) so you can re-run one stage without clobbering the others.
2. Look first at the package config file and the service provider's boot() method. The provider is where the view namespace is registered and where the theme is resolved — that ordering is what v1.0.3 changes. Confirm which directory it resolves to on your install (php artisan tinker and dump the resolved path, or check view()->getFinder()->getHints()).
3. First use case: set your theme, publish views, then change a single visible string in one published stub and reload the page. If your edit shows up, the theme path is wired correctly and you can start overriding for real. If it doesn't, you're editing a directory that isn't on the resolution path — that is the failure mode this release most directly affects.

Implementation Patterns

Treat published views as theme-owned, not vendor-owned. With theme-sourced stubs, keep customisations inside your theme's view directory and let the package supply the default. Never edit vendor/ — an upgrade will silently revert you.

Override, don't fork. Publish only the stubs you actually need to change. Each additional published file becomes a file you must diff against the vendor version on every upgrade. A minimal published set is a maintainable published set.

Resolve the theme explicitly in non-web contexts. Queue workers, console commands, and scheduled jobs don't get the same request lifecycle as HTTP. If your theme is chosen per-tenant or per-request, bind the theme resolver in a service provider or middleware and make sure it's set before any view is rendered — otherwise a queued mail or PDF export renders with the default theme.

Pin the theme before publishing in CI. Publish steps that run during deploy should run with the theme already configured (env var or config value), not with the resolver's fallback. Otherwise your build publishes stubs for the wrong theme and the error only surfaces at render time.

Verify view resolution in tests. A cheap feature test that renders the affected views catches namespace collisions and stale published stubs far earlier than manual QA:

$this->assertSame(
    resource_path('views/vendor/<package>/...'),
    view()->getFinder()->find('package::view')
);

Upgrade routine. After composer update, diff your published stubs against the new vendor stubs before clearing caches. v1.0.3 changed the stub source, so any stub you published under the old behaviour may now differ in content from what the package would generate today.

Gotchas and Tips

• View cache is the number one false alarm. Compiled views persist across stub edits. Run php artisan view:clear after publishing or editing stubs, and again after deploy.
• Already-published stubs are not retroactively theme-aware. This release changes where stubs come from at publish time. Files you published earlier stay exactly as they were. If your templates still look like the old defaults, re-publish the specific views (--force on those files only — not on the whole tag) or delete them and publish again.
• --force is destructive and untagged. There's no per-file confirmation. Copy your customisations out before forcing, or use version control and review the diff.
• Namespace shadowing. If you register your own view path under the same namespace, registration order determines the winner. prependNamespace beats loadViewsFrom; use it deliberately when you want theme views to win over package defaults.
• Config cache hides theme switches. php artisan config:cache freezes the theme value. If switching themes per environment or per tenant, drive it from something not cached (a DB lookup, request middleware, or an explicitly bound resolver) rather than a cached config key.
• Debugging a wrong view: php artisan view:clear, then temporarily add {{ __FILE__ }} or @dump(view()->getFinder()->find('package::name')) to confirm which file is actually rendering. Nine times out of ten it's a stale published stub, not a resolution bug.
• Extension point to prefer: if you need per-tenant theming at runtime, bind your own theme resolver in a service provider instead of copying stubs into multiple theme directories. Copying scales badly with the number of themes and turns every package upgrade into an N-way merge.
• Keep published views out of your build artefact if your deploy runs publish steps. Publishing at deploy time and committing published views are two different strategies — pick one. Mixing them means your committed files may be silently overwritten by a deploy-time publish.