Voyager Extension Laravel Package

Getting Started

Version alignment is the first thing to check. This release targets Laravel 10 and Voyager 1.7. That combination implies PHP 8.1+ and a Voyager install that has itself been upgraded to 1.7 — the package assumes the 1.7 hooks/registry. If you are still on Voyager 1.6 / Laravel 9, pin an older package release rather than mixing.

1. composer require <vendor>/<package>:"^0.95" — let Composer resolve against your existing laravel/framework and tcg/voyager constraints. Run composer why-not <vendor>/<package> 0.95.84 if it refuses to install; that tells you which of the two is blocking.
2. If the package ships a service provider that is not auto-discovered (Laravel 10 still honours extra.laravel.providers), register it in config/app.php after TCG\Voyager\VoyagerServiceProvider — anything touching BREAD, form fields, or widgets needs Voyager's bindings to exist first.
3. Publish and review config before touching the admin UI:

   php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"
   php artisan migrate   # only if the package ships migrations
   

4. Open the package's config/ file and its src/ service provider first — that is where the extension points (form fields, widgets, hooks, data types) are registered. Then navigate to /admin and confirm the package's menu entries or field types appear.

First use case: attach whatever the package provides to a single BREAD (a custom form field on one Add/Edit form, or one widget on the dashboard) rather than retrofitting every BREAD at once. That gives you a one-model smoke test that the Laravel 10 boot path and Voyager 1.7 asset pipeline are actually wired up.

Implementation Patterns

Register through hooks, not by editing package or Voyager files. Voyager's Voyager::hooks() / event system is the sanctioned seam for injecting behaviour into the admin. Editing published views or vendor code means every composer update reverts your work — and this release is precisely the kind of upgrade that will re-publish assets.

Custom form fields / BREAD types. The usual pattern is: define the field class, register it in the package's (or Voyager's) field registry from a service provider's boot(), then select it by key inside BREAD → Add/Edit. Keep the field's Blade view in resources/views/vendor/<package>/ so it overrides the package copy without a fork.

Config-driven behaviour. Prefer the published config over constructor arguments — it survives container rebuilds and is cache-safe with php artisan config:cache. If you need per-environment differences, use env() only inside the config file, never at runtime.

Compose with your own service providers. Wrap package calls in a thin application-level service (App\Support\...) so your controllers and BREAD callbacks depend on your API, not the package's. When the next minor release renames something, you patch one class.

Testing. Voyager-dependent code is easiest to test with RefreshDatabase plus a seeded admin user; assert on the rendered admin response and on the database effect rather than on package internals. For asset/field registration, a container assertion (app()->bound(...) or the registry resolving the key) is faster than a full HTTP test.

Upgrade workflow. On a release like this: bump the constraint on a branch, run composer update <vendor>/<package> tcg/voyager --with-dependencies, re-publish assets with --force, clear caches, then click through every BREAD that uses the package. Automated tests rarely cover the admin UI, so the manual pass is the real regression suite.

Gotchas and Tips

• Stale published assets are the #1 post-upgrade bug. vendor:publish --force plus a hard browser refresh; Voyager caches compiled views and its own BREAD cache, so also run php artisan view:clear and, if menus/permissions look wrong, php artisan cache:clear.
• Config cache hides new keys. After upgrading, php artisan config:clear before assuming a new option is missing — a cached config.php will silently drop keys added in v0.95.x.
• Laravel 10 removals bite indirectly. If the package touches Eloquent models, watch for $dates (removed — use $casts), dynamic-property deprecations under PHP 8.2, and doctrine/dbal 3.x behaviour on change() migrations. Run the suite on the exact PHP version your production box uses, not just the CI default.
• Voyager 1.7 is the constraint that fails first. If Composer resolves the package but the admin 500s, check composer show tcg/voyager — a 1.6 install left in place will load the old provider and the package's 1.7 assumptions break at boot.
• Order of service providers matters. A "class not found" or "target not instantiable" during php artisan boot almost always means the package provider registered before Voyager's. Fix the order in config/app.php or bootstrap/providers.php rather than lazily resolving.
• Extension points to prefer: published config → package hooks/events → view overrides → (last resort) vendor patch. Keep a short list of which seam you used for each customisation; it is the difference between a 10-minute upgrade and a day-long one.
• Debugging the admin: APP_DEBUG=true plus storage/logs/laravel.log is usually enough, but Voyager swallows some exceptions into flash messages. Temporarily remove the package's try/catch (or set a breakpoint in the field/widget renderer) when a form field silently renders blank — a blank field is nearly always a failed registry lookup or a missing view, not a data problem.