Voyager Hooks Laravel Package

Getting Started

Start from a working Voyager 1.x admin panel and confirm the Laravel/PHP versions in composer.lock; this package’s last release was 2020, so compatibility is the first thing to verify.

1. Install with Composer:

   composer require larapack/voyager-hooks
   

2. If package discovery is unavailable or the provider is not auto-registered, add the package service provider in config/app.php.
3. Publish any package config/migrations/views if the README instructs it, then run:

   php artisan config:clear
   php artisan view:clear
   

4. Look first at the package README’s hook-name table and at vendor/larapack/voyager-hooks/src for doAction / applyFilters calls. The actual hook names in your installed Voyager version are the source of truth.
5. Register a first hook in a dedicated service provider rather than routes/web.php, for example an admin-only dashboard notice or an extra menu link. Confirm it fires in the Voyager admin, then remove it or gate it by role.

The first practical use case is usually presentation-level: inject a banner, script, menu item, or small widget into Voyager admin screens without overriding Voyager views.

Implementation Patterns

• Use a dedicated provider. Put all Voyager hook registrations in something like app/Providers/VoyagerHooksServiceProvider.php and keep boot() declarative. This makes admin hooks easy to disable, test, and audit.
• Actions vs. filters. Treat actions as side-effect/append points and filters as value transformers. Always return the filtered value; never rely on mutation alone.
• Target admin surface areas first. Menu, dashboard, BREAD form, and BREAD lifecycle hooks are the natural day-to-day leverage points. Use them to add admin UI, normalize BREAD input before save, or log/audit changes without forking Voyager.
• Keep callbacks thin. Delegate to invokable classes or small services:

  Hook::addAction('voyager.dashboard', DashboardNotice::class);
  Hook::addFilter('voyager.bread.before_save', NormalizeBreadData::class);
  

  Replace hook names with the ones exposed by your installed package version.
• Gate by admin context. Check the Voyager admin guard, route, or role before rendering or executing. Hooks can run on admin requests you did not anticipate.
• Use hooks for cross-cutting admin concerns. Business logic still belongs in model events, jobs, or services. Hooks are best for UI injection, admin-side validation/normalization, audit logging, and small integrations.
• Compose with Voyager’s own extension points. If Voyager already provides widgets, form fields, or actions, prefer those for structural changes; use hooks for the gaps.
• Test callbacks directly. Invoke the action/filter in isolation and assert behavior; then smoke-test in the admin panel because hook wiring can fail silently.

Gotchas and Tips

• Staleness is the main risk. Last release in 2020, tied to legacy Voyager and older Laravel/PHP stacks. Pin versions, test upgrades explicitly, and avoid introducing it into a new project.
• Provider order matters. Register your hook provider after Voyager’s provider so Voyager is booted before you attach hooks.
• Typos fail silently. Hook names are plain strings. Search vendor/ for the exact doAction/applyFilters call, or centralize names as constants. Add temporary logging inside callbacks when a hook “doesn’t fire.”
• Filters must return. A missing return in a filter callback can break admin pages in confusing ways.
• Clear caches aggressively. config:clear, view:clear, and route cache clears solve many “my hook disappeared” reports.
• Watch performance. Dashboard/menu hooks run on every admin request. Avoid heavy queries, external HTTP calls, or large view renders in those paths.
• Secure any admin-managed hooks. If your install exposes hook editing through the Voyager UI, restrict it to trusted super admins. Executable/admin-editable hook code is a high-risk extension point.
• Never edit vendor files. Publish config/views where supported and keep customizations in app code.
• Confirm the hook exists in your Voyager version. A package hook name from the README may not be present in the Voyager release you run. Inspect the vendor source before debugging your own callback.