Laravel Nomadic Laravel Package

Getting Started

v2.0.1 is a documentation and DX release on top of 2.0.0 — no breaking changes, no new runtime behaviour. If you are already on 2.0.0, upgrading is a safe patch bump; the value is in the docs and the newly documented extension points.

Minimal path to first value:

1. composer require <vendor>/<package> (^2.0).
2. Publish the config and stubs: php artisan vendor:publish --provider="<Vendor>\<Package>\<PackageServiceProvider>". Check the published config/<package>.php for the migration table key and the hooks/events block.
3. Run php artisan migrate before you touch the migration table name (see Gotchas).
4. Read the new docs in this order: the event/hook reference first, then the stubs section, then the migration table option. The hook reference is the part that changes how you build, so don't skip to the config.

First use case to try: instead of subclassing or forking the package's default behaviour, register a listener against one of its documented events in your own EventServiceProvider and mutate/augment the payload there. That is the intended 2.x extension model and the fastest way to confirm you understand the hook contract.

Implementation Patterns

Event-driven hooks as the primary extension mechanism. The documented pattern in 2.0.1 is to react to package events rather than override classes. Practical workflow:

• Register listeners in a dedicated PackageHooksServiceProvider (keeps them discoverable and easy to remove).
• Keep listeners thin — resolve an action class from the container so they stay testable in isolation.
• Use the event payload as the contract: assert on it in tests so a future package release that changes the payload fails loudly rather than silently.
• For anything slow (notifications, third-party calls), make the listener implement ShouldQueue. Hooks fired inline in a request cycle are the classic source of latency regressions.

Stubs for team conventions. Publishing and editing stubs is the low-effort way to make generated classes match your codebase — namespaces, base classes, declare(strict_types=1), constructor promotion, DTO style. Treat the published stub directory as a first-class artefact: commit it, and add a short note in your README on which stubs you have customised and why. When the package ships updated stubs, diff them against yours before blindly overwriting.

Customisable migration table. Useful when the default table name collides with an existing table, or when you want a naming convention shared across packages. Pattern: set the table name in config, ensure it's set consistently across every environment (config cache included), and only then run migrations. For multi-tenant setups, verify whether the table name is read at migrate time only or also at runtime — if runtime, it becomes a per-tenant concern and belongs in your tenancy bootstrap, not a static config value.

Typical integration flow: publish config + stubs → customise stubs → wire hooks in a service provider → adjust migration table if needed → migrate → add a feature test that exercises one hook end-to-end.

Gotchas and Tips

• Migration table rename is a one-way door for existing installs. Changing the config after migrations have run leaves data in the old table. Rename the table manually (or write a small migration) rather than expecting the package to migrate data for you. Decide the name before the first migrate in any environment.
• Config cache. php artisan config:cache in deploy scripts will pin the migration table and any hook toggles. If behaviour differs between local and staging, clear and rebuild the cache before debugging anything else.
• Stubs only affect future generation. Published stubs are copied at vendor:publish time and never auto-update. After a package upgrade, re-publish to a temp directory and diff.
• Hook ordering and duplication. If you register the same listener in more than one provider (a real risk when a package provider and your app provider both wire it), you get double execution. Use php artisan event:list to confirm exactly what is registered, and Event::fake() in tests to assert dispatch counts.
• Don't put business logic in listeners. Hooks are a seam, not a home. Delegate to an action/service; otherwise the logic becomes untestable without booting the full package.
• Debugging hooks: log inside the listener first to confirm it fires at all; a silent hook is usually a provider not registered, a config toggle off, or a cached config. Check bootstrap/providers.php / config/app.php registration before assuming a package bug.
• Docs-only release, but verify anyway. 2.0.1 changes no code paths, so any behaviour you observe is 2.0.0 behaviour. If the new docs describe a hook or config key you cannot find in the published config, you are likely on 2.0.0 with an older published config stub — re-publish and diff.
• Extension points worth knowing: published config, published stubs, and the documented events. Favour these three over subclassing; subclassing is the thing 2.x is steering you away from and it will break on minor releases.