Admin Menu, Breadcrumbs and Dashboard Widgets

Make your feature reachable from the admin sidebar, give it breadcrumbs, and put summary cards on the dashboard — or take core items away.

The sidebar (MenuManager)

The admin sidebar is a collection of App\Services\Menu\MenuItems held by the MenuManager singleton (facade App\Facades\MenuManager). It is filled on every admin request: first by AdminAsideMenu (core), then by every AdminBooting listener (plugins). Register inside an AdminBooting listener, never in boot() (the signed-in user is not known yet there).

A top-level entry with sub-entries

simplified from Modules/Testimonials/app/Helpers/TestimonialsMenu.php

use App\Facades\MenuManager;
use App\Services\Menu\MenuItems;

MenuManager::make('testimonials', function (MenuItems $menu): void {
    $menu->label('testimonials::testimonials.menu')   // translation key, resolved when rendered
        ->menuType(MenuItems::ADMIN)                  // required: ADMIN or FRONT
        ->icon('nav-icon ph ph-quotes')              // Phosphor icon class
        ->route('admin.testimonials.index');         // named route (type becomes "route")
}, 36);                                                // priority: lower = higher in the sidebar

MenuManager::get('testimonials')->subMenu('create', function (MenuItems $menu): void {
    $menu->key('create')
        ->label('testimonials::testimonials.create')
        ->menuType(MenuItems::ADMIN)
        ->icon('nav-icon ph ph-caret-right')
        ->route('admin.testimonials.create');
});

MenuItems API

MenuManager API

Core keys you can get(), modify or remove(): dashboard, pages, posts, appearance, users, advertisements, settings, support-tickets, languages, patches. Because your AdminBooting listener runs after the core registered them, you may add a child to an existing group (MenuManager::get('appearance')?->subMenu(...)) or hide one:

Event::listen(AdminBooting::class, function (): void {
    MenuManager::remove('advertisements');   // the entry disappears for every admin user
});

Conventions copied from the bundled modules

• Gate the whole group with access {alias} and each child with its own permission (TruCommerceMenu::register()).
• Build the child list as an array of [key, label, icon, route, permission] tuples and loop — it keeps long menus (Booking's two groups hold 21 children) readable.
• Pick the group's own route from the first child the user may open, so a limited user still gets a working link.
• Use consistent priorities: Booking 5/30/31, TruCommerce 8/32/33/34, Payments next to them; reserve single digits for dashboards.

Breadcrumbs

The admin layout prints Breadcrumbs::render() and builds the browser title from Breadcrumbs::current(). Register one per page route in a file your provider requires:

Modules/Testimonials/routes/breadcrumbs.php

use Diglactic\Breadcrumbs\Breadcrumbs;
use Diglactic\Breadcrumbs\Generator as BreadcrumbTrail;

Breadcrumbs::for('admin.testimonials.index', function (BreadcrumbTrail $trail): void {
    $trail->parent('admin.dashboard');      // defined by the core
    $trail->push(__('testimonials::testimonials.menu'), route('admin.testimonials.index'));
});

Breadcrumbs::for('admin.testimonials.edit', function (BreadcrumbTrail $trail, Testimonial $testimonial): void {
    $trail->parent('admin.testimonials.index');
    $trail->push($testimonial->author_name, route('admin.testimonials.edit', $testimonial));
});

Route-model-bound parameters are passed to the callback in the order of the route's parameters. A page route with no definition throws; a route that only redirects needs none. The front end has its own breadcrumb names (front, pages.show, blog routes) rendered by <x-application-breadcrumbs />.

The dashboard (Dashboard registry)

A dashboard is a named list of rows; a row holds items. The view calls @dashboard('name'). Facade App\Facades\Dashboard:

Default rows you can place around or remove

Writing a dashboard widget

Modules/Testimonials/app/Widgets/Admin/TestimonialsCounterWidget.php

use Arrilot\Widgets\AbstractWidget;

class TestimonialsCounterWidget extends AbstractWidget
{
    protected array $config = [];                  // typed: Arrilot declares it as array

    // public int|float|bool $cacheTime = 60;      // minutes; false disables widget caching
    // public int|float|bool $reloadTimeout = 60;  // seconds; auto-reload for async widgets

    public function run(): View
    {
        return view('testimonials::widgets.admin.counter', [
            'total' => Testimonial::query()->count(),
            'published' => Testimonial::query()->published()->count(),
        ]);
    }
}

• Widgets in the dashboard receive $params as their config array (params: ['limit' => 5]).
• For heavy widgets use async: true and a lightweight placeholder(); the core's graph widget is an example. Async widgets are fetched after page load through the package's own route (arrilot/load-widget), a separate request.
• All four core admin widgets (CountersWidget, GraphWidget, …) call Theme::set('admin') in their constructor because an async request does not pass through AdminTheme. If your widget renders theme views asynchronously, do the same.
• The visitor dashboard (Dashboard::user()) renders in the front theme: write markup for Echo, not CoreUI.

A dashboard of your own

// Provider boot()
Dashboard::for('shop.dashboard')
    ->row('counters', order: 10, class: 'row g-4')
    ->widget(id: 'shop.counters', widget: ShopCountersWidget::class, async: false, class: 'col-12');

// resources/views/admin/dashboard.blade.php
<x-admin-layout>
    @dashboard('shop.dashboard')
</x-admin-layout>

This is exactly how TruCommerce (trucommerce.dashboard) and TruPayments (trupayments.dashboard) build their own dashboard pages.