Admin Laravel Package

Getting Started

Install

composer require vanilo/admin

In practice you rarely install this package directly — most projects pull it in transitively via vanilo/box or vanilo/framework. If you install it standalone, you also need the core vanilo/* packages (product, category, order, customer, channel, payment, shipment) and the AppShell stack it builds on (konekt/appshell, konekt/html, konekt/concord).

Prerequisites before /admin will load

1. An authenticated user class that satisfies AppShell. The admin is not a self-contained auth system. You either use the bundled Konekt\AppShell\Models\User, or make your App\Models\User compatible (implements Konekt\AppShell\Contracts\User, exposes a name/email, and has a concept of an admin role). Register it in config/appshell.php under the users.model key.
2. A role/permission layer that marks the user as admin. AppShell's gate checks rely on the user being recognized as an admin; without it every route 403s even when logged in.
3. Migrations run — the admin package itself ships no migrations, but the Vanilo core modules do. php artisan migrate after installing the framework is mandatory or every list page throws a "table not found" error.

Where to look first

• config/vanilo.php — feature toggles (channels, taxes, payment, shipping). If a menu item is missing, this is usually why.
• config/appshell.php — user model, route prefix, layout selection, dashboard widgets.
• The Vanilo\Admin\Providers\VaniloAdminServiceProvider — it's the map of registered resources, routes and view namespaces.

First use case

Log in, hit /admin. You'll land on the AppShell dashboard. To get a usable shop you must create, in order:

1. A Channel (Settings → Channels) — mark one as default.
2. At least one Taxon (category tree), a Taxonomy for it.
3. A Product, then attach it to the channel and a taxon.
4. A Payment Method and Shipping Method so checkout can complete.

Products without a channel and taxon fail validation — this trips up almost everyone on the first day.

Implementation Patterns

Registering a custom admin resource

Admin screens are AppShell UiResources: a class implementing Konekt\AppShell\Contracts\UiResource that declares a route group, a model, form fields, table columns and views. The idiomatic pattern is to subclass an existing Vanilo resource (e.g. Vanilo\Admin\Http\Resources\Product) and override fields(), table(), or getBreadcrumb() rather than building from scratch. Register your resource in a service provider:

app(\Konekt\AppShell\Contracts\UiResourceRegistry::class)
    ->register(new MyProductResource());

Extending a product form without forking

Publish the admin views once:

php artisan vendor:publish --tag=vanilo-admin-views

Then work in resources/views/vendor/vanilo/admin/.... Because the templates use konekt/html form builders, the cleanest extension is to add a field to the resource's fields() method and let the template render it — editing Blade directly is fragile on upgrades.

Dashboard widgets

AppShell renders the dashboard from a widget list. Add a KPI card by implementing Konekt\AppShell\Contracts\Widget and registering it in config/appshell.php under widgets. Vanilo ships widgets for orders, revenue, and new customers; copy one as a template (they're small and self-contained).

Menu customisation

Menu items come from appshell.menu in config plus whatever resources register themselves. For a quick "Reports" link or an external tool, append to the menu array; for conditional items, use the MenuBuilder service so you can gate on permissions.

Multi-channel behaviour

Most list screens (products, orders, customers) filter by channel implicitly. The admin determines the active channel from the session or a route parameter. If you're building cross-channel reporting, don't query the admin's repositories directly — use the Vanilo model queries with an explicit channel_id scope, otherwise you inherit whichever context the admin happens to be in.

Custom actions on list rows

AppShell's table row actions are declared in the resource's table() method. To add a "Duplicate" button, define an action that maps to a named route and returns a Konekt\AppShell\Actions\Action. Route it through a controller in your app, not the vendor controller, so upgrades don't stomp it.

Gotchas and Tips

The CSS will fight you. AppShell ships Bootstrap (with jQuery for some interactions). If your storefront uses Tailwind, Inertia, or Vite with a modern layout, keep the admin on its own layout and do not include your storefront CSS in the admin stack. The appshell.layout config key selects the base layout — point it at a minimal Blade layout, not your storefront's.

"Product could not be created" with no obvious reason. Almost always a missing channel, missing taxon, or a validation rule from vanilo/product that isn't surfaced cleanly. Check storage/logs/laravel.log and the channels table first — a default channel is required for the create form to even render meaningful options.

User model mismatch crashes with a type error. The most common install failure is a custom User model that doesn't implement AppShell's contract. Either implement the interface (it needs getName(), getEmail(), and role support) or set users.model in config/appshell.php to Konekt\AppShell\Models\User::class.

Views vs. config drift on upgrade. The admin is fast-moving and its Blade templates are not a stable API. Any view you publish is now your responsibility. Prefer adding fields via resource fields() and menu items via config; only override Blade for layout-level changes, and grep the diff between your published views and the vendor's on every update.

Routes 404 after installing. AppShell registers routes under a configurable prefix (default /admin) inside its service provider. If you see 404s, confirm the provider is auto-discovered (php artisan about) and that appshell.routes.prefix hasn't been overridden by an earlier config cache. php artisan route:list | grep admin is the fastest sanity check.

Cache clear is mandatory after config changes. Menu/widget/resource registrations are read from config at boot; php artisan config:clear and php artisan cache:clear after touching config/appshell.php or config/vanilo.php. Stale config cache is the #1 source of "my widget doesn't appear."

Order screens are read-only by design. You can view, annotate, and transition order status, but you cannot create an order from the admin. Orders originate from the checkout. If you need manual order entry (phone orders), that's a custom resource you build — don't try to repurpose the order resource.

Media/files need storage:link. Product image uploads go through Laravel's filesystem. The admin will happily accept an upload and then render a broken image if the symlink doesn't exist. Run php artisan storage:link as part of deployment, not just locally.

Extension points that survive upgrades, in order of stability:

1. Config (appshell.php, vanilo.php) — stable.
2. Your own service provider registering resources/widgets/menu — stable.
3. Subclassing Vanilo resource classes and overriding methods — mostly stable, watch for signature changes.
4. Published Blade views — unstable, treat as a fork.

Testing the admin. Browser-kit tests against /admin are painful because of the Bootstrap/JS stack. Test the underlying models and controllers directly; reserve Dusk/Pest browser tests for the couple of flows (product creation, order status change) you genuinely need to guard.

Small ecosystem reality check. With a handful of stars and no dependents, this package has a thin community. The Vanilo documentation site is the real reference; issues often get answered by the maintainer in the main vanilophp/framework repo rather than here. Budget time to read source when docs are thin — the resource classes are readable and self-documenting.