Voyager Frontend Laravel Package

Getting Started

1. Confirm the stack before you install. This package is archived and its last release is January 2020; it targets Voyager 1.x on Laravel 5.8–7.x and PHP 7.2–7.4. Check composer.json constraints and pin laravel/framework and tcg/voyager accordingly. On Laravel 8+ / PHP 8 you will hit removed helpers (str_slug, array_get), replaced contracts, and Blade changes — expect to fork rather than composer require cleanly.
2. Install both packages.

   composer require tcg/voyager pvtl/voyager-frontend
   php artisan voyager:install --with-dummy   # or your existing Voyager install
   php artisan voyager-frontend:install       # publishes config, views, assets
   

   Run php artisan list | grep voyager to confirm the exact command signature in the release you pulled.
3. Look here first, in this order:
   • config/voyager-frontend.php — theme, route prefix/middleware, view namespaces, image sizes, blocks.
   • resources/views/vendor/voyager-frontend/ — the published Blade theme; this is what you actually edit.
   • vendor/pvtl/voyager-frontend/src/Http/Controllers/ — PageController, PostController, etc., to see how models are resolved from slugs.
   • Voyager's admin BREAD screen — the package does nothing without matching BREAD types.
4. Create the BREADs it expects in the Voyager admin: pages, posts (and categories if you want archives). Set each BREAD's type column correctly (page, post) — the package keys off the BREAD model lookup, not the table name alone.
5. First use case: seed a Page with slug about, visit /about, and confirm the package route renders your published theme's page view. That single loop — Voyager record → route → theme view — is the whole mental model. Everything else is repetition.

Implementation Patterns

• Slug-driven routing. Pages and posts resolve via route-model binding on slug. Treat Voyager slugs as public API: renaming one is a breaking URL change unless you add redirects. For hierarchical pages, use parent_id and build URLs like /parent/child; verify the package's controller honors nesting in your version, or override it.
• Theme override, not theme edit. Keep a thin resources/views/vendor/voyager-frontend/ layer that @extends the package layout and overrides only the sections you need (content, head, scripts). This survives partial re-publishes and keeps diffs small.
• Blocks for reusable content. Blocks are the package's answer to "our marketing team needs to edit the footer banner." Define a block key, render it in a Blade partial, and let editors manage copy in Voyager. Use blocks for content regions, not for layout structure — editors will delete structural markup.
• Menus via Voyager's menu builder. menu('main') renders the admin-managed tree; wrap it in your own partial so you can add classes, active-state logic, and aria-current without patching the package.
• Separate frontend routes from app routes. Put your own routes (search, contact form, auth) before the package's catch-all in route registration order, or constrain the slug pattern. Otherwise /{slug} shadows anything you add later.
• Custom BREAD types get custom controllers. For a team_member or event BREAD, don't hack the Page controller — bind your own controller/route and reuse the published views. The package is a template, not a framework.
• Cache at the view layer. Since it's query-per-request with no built-in caching, wrap expensive regions (Cache::remember around block/menu queries) and use php artisan view:cache in production. This is often the single biggest win.
• Compose with Voyager hooks (Voyager::addAction, model events) for admin-side enhancements rather than forking the package's service provider.

Gotchas and Tips

• It is archived — plan for stewardship. No security patches, no Laravel upgrades. If you adopt it today, budget for a fork. For new projects, treat it as a reference implementation for a Voyager frontend rather than a dependency.
• Published views are frozen. voyager-frontend:install copies views into your app; composer update will not refresh them. Track upstream changes manually.
• Route cache collisions. Config edits (prefix, middleware, route list) require php artisan config:clear && php artisan route:clear. A stale config cache is the #1 cause of "my changes do nothing."
• Config cache in production. If the package reads config at boot, always run config:cache after deploys; verify the frontend prefix and middleware survive it.
• Image resizing needs intervention/image + GD/Imagick and a storage symlink. Broken images are almost always a missing symlink or an unpublished image_sizes entry rather than a code bug.
• BREAD type mismatch is silent. If a Page returns 404, first check Voyager::model('Page') resolves and the BREAD row has the expected type. Dump the resolved model in the controller before assuming routing broke.
• The catch-all slug route shadows new routes. Use php artisan route:list --path=your-prefix to confirm order; register specific routes earlier or add a where('slug', ...) constraint.
• Slug uniqueness. Voyager doesn't enforce globally unique slugs across BREADs. Add a DB unique index or a validation rule if two BREADs share a namespace.
• Minimal i18n. The package's localization is shallow; for multilingual sites use Laravel's own locale middleware plus per-locale slugs, or a maintained forked branch. Don't expect Voyager's translation UI to wire through automatically.
• Debugging flow: route:list → resolved controller → dd($bread) → view name from config('voyager-frontend.views'). Nine times out of ten the failure is config, not code.
• Extension points that hold up: overriding published views, binding your own controllers, Voyager model events, and Blade view composers. Patching vendor/ does not.