Panel
Panel-level configuration: routing, appearance, navigation, chrome and the command palette.
Panel-level configuration: routing, appearance, navigation, chrome and the command palette.
PanelConfig
Tbtop\Admin\Panels\PanelConfig
| Method | What it does |
|---|---|
authStack(): array | The panel's auth/app middleware layer a page spreads to add to it, e.g. middleware(PanelConfig $p): array { return [...$p->authStack(), 'throttle:30,1']; }. Access rules belong in Page::can(), which MCP calls also enforce. Excludes SetCurrentPanel/SetAdminLocale — the route layer always applies those. AuthenticateSession follows auth: it reads the user that auth:{guard} resolves, and ends a session whose password hash no longer matches the user's (a reset elsewhere). RequireTwoFactor follows it: while the panel serves a TwoFactorChallengePage subclass, a user with a second factor who has not passed it in this session goes to the challenge. RequireVerifiedEmail comes last: while the panel serves an EmailVerificationPage, a MustVerifyEmail user with an unverified email is sent there. |
brand(string $brand): static | Brand name shown in the chrome (sidebar/topbar header); the logo's alt text when a logo is set. |
brandLogo(string $url): static | Logo image URL shown in the chrome's logo block instead of the brand name. |
brandLogoHeight(string $height): static | Rendered logo height as a CSS length in px, rem or em (default '1.5rem'). |
breadcrumbs(bool $enabled = true): static | Whether pages build and send the breadcrumbs prop. |
chrome(string $chrome): static | Class-string of a Chrome subclass that authors the shell (header/sidebar/ footer). Override headerItems()/sidebarItems() and spread the parent to append to the stock shell; override header()/sidebar()/footer() to replace an area outright. |
commandPalette(Closure|bool $config = true): static | Enable (default), disable with false, or configure the ⌘K command palette via a closure. The closure receives the CommandPaletteConfig to mutate (->commands([Command::make(...)...])) and returns nothing. |
darkMode(bool $enabled = true): static | Allow or disable the dark-mode toggle entirely (default: allowed). |
darkModeBrandLogo(string $url): static | Logo image URL used while the panel is in dark mode; falls back to brandLogo(). |
defaultLocale(string $locale): static | Default admin UI locale, overriding the first entry of locales(). |
defaultThemeMode(string $mode): static | Initial theme when the visitor has no saved preference. |
density(string $mode): static | Shell density: 'compact' tightens control heights, spacing, and the sidebar width. |
discoverPages(string $in, string $for): static | Adds a recursive page discovery directory and its Composer-autoloadable namespace; rebuild the page cache after adding pages. |
environmentIndicator(Closure|array|bool $indicator = true): static | Show the app environment as a colored header badge and top strip; hidden in production. Pass an array to override per environment (['staging' => 'warning', 'qa' => ['label' => 'QA', 'color' => 'info'], 'local' => false] — listing production shows it), or a Closure returning ['label' => …, 'color' => …] or null, called per request. Colors are the badge names: gray, primary, success, warning, danger, info. |
favicon(string $url): static | Browser-tab icon URL (.ico, .png or .svg) for every page of the panel. |
guard(string $guard): static | Auth guard checked by authStack(). Defaults to 'web'. |
id(string $id): static | Feeds the route-name namespace (tbtop.{id}.*) — changing it on an existing panel renames every route. |
locales(array $locales): static | Admin UI locales. First entry is the default unless defaultLocale() is set. |
maxContentWidth(string $width): static | Center page content to a Tailwind max-w token (e.g. '7xl'). |
mcp(array $middleware, string $path = 'mcp'): static | Expose this panel to AI agents over MCP at POST {prefix}/{$path} (needs composer require laravel/mcp). $middleware is the route's whole auth and access stack — it REPLACES the panel's middleware, which does not run for MCP calls: name stateless token auth and repeat the panel's role checks, e.g. ['auth:sanctum', 'abilities:tbtop-mcp', 'role:admin', 'throttle:60,1']. A page's own restriction belongs in Page::can(), which MCP enforces. An empty list throws: it would serve the panel without authentication. |
mcpAllowedOrigins(array $origins): static | Browser origins, besides the origin of app.url, that may call the MCP endpoint (https://agent.example.com). A request whose Origin is neither gets 403; one with no Origin — a desktop or CLI client — is not affected. |
mediaGate(?string $ability): static | Gate ability every media-manager endpoint (list, show, download, upload, URL import, edit, replace, delete, folders) requires; a user who fails it gets 403. Null, the default, leaves the API open to every user who passes the panel's middleware. |
middleware(array $middleware): static | Replaces the default ['web'] app-middleware stack rather than appending to it; authStack() adds auth:{guard}, AuthenticateSession and RequireVerifiedEmail on top at read time. |
navigation(string $navigation): static | Shell navigation layout: 'sidebar' (default), 'topbar', 'topbar-sidebar' (full-width bar with a sidebar beneath it), or 'rail-sidebar' (a rail of labeled nav-group icons beside a sidebar listing only the active group). The client renders the same chrome blocks; only their arrangement changes. All layouts collapse to a burger drawer on mobile. |
navigationGroups(array $groups): static | Per-group nav metadata as a list of NavGroup::make('Content')->icon('file-text') ->collapsible(), matched to a page's nav()['group'] by that label. |
navigationItems(array $items): static | Extra always-shown nav entries with no page/gate (e.g. an external link), merged into the built tree alongside page-derived items, grouped by label the same way navigationGroups() matches groups. |
notificationsPolling(?int $seconds): static | Seconds between header-bell polls for new notifications. null disables auto-polling (the bell still fetches when opened). Mirrors Filament's databaseNotificationsPolling(); only active when the chrome renders a notifications bell. |
pages(array $pages): static | Replaces manual pages; discovery merges them first and removes duplicate classes. |
passwordBroker(?string $broker): static | Password broker from config/auth.php for the auth pages' reset flow; null uses the app default. A guard on a non-default provider needs its own broker. |
prefix(string $prefix): static | URL path prefix the panel is mounted under. Defaults to the panel id when unset — see getPrefix(). |
rootView(string $view): static | Blade root view rendered on first visit (per-panel Vite entry escape hatch). |
stylePreset(string $style): static | Component style from ui.shadcn.com/create (its "Style" choice): 'vega' (default), 'nova', 'maia', 'lyra', 'mira', 'luma', 'sera' or 'rhea'. Shapes sizes, spacing, radii and shadows; colors stay in your CSS tokens. The root Blade's <html> carries CurrentPanel::current()?->stylePresetClass(). |
unsavedGuard(bool $enabled = true): static | Default for the unsaved-changes navigation guard on forms. |
userMenuItems(array $items): static | Custom profile-dropdown entries rendered alongside the fixed theme/locale/logout controls. Link-only (label/icon/href/newTab) — chrome trees are page-independent (no per-request endpoint for a server closure to resolve against), same constraint as NotificationAction. |
Chrome
Tbtop\Admin\Panels\Chrome
| Method | What it does |
|---|---|
footer(S $s): ?Node | No footer in the stock shell. |
header(S $s): ?Node | Topbar content. The shell right-aligns it; align: center keeps items of differing heights on one axis instead of stretching to the tallest. |
sidebar(S $s): ?Node | Sidebar content: logo on top, nav groups below. |
NavGroup
Tbtop\Admin\Navigation\NavGroup
| Method | What it does |
|---|---|
collapsed(bool $collapsed = true): self | Start the group collapsed (implies collapsible). |
collapsible(bool $collapsible = true): self | Render the group header as a collapse toggle. |
description(Closure|string $description): self | One muted line under the group's title, in every navigation layout: the rail-sidebar column, the sidebar heading, and the top of a dropdown menu. Pass a Closure for the same request-time translation reason as label(). |
icon(Closure|string $name, Closure|string $position = 'left'): static | $name is a kebab-case Lucide icon name (e.g. 'circle-check') resolved against the client's icon registry; register custom names client-side via registerIcon before using them here. $position is 'left' (default) or 'right', placing the icon relative to the label. Either may be a Closure; a closure-supplied position is validated when it resolves. |
label(Closure|string $label): self | Translated header text shown in the sidebar. Pass a Closure to defer translation to request time — panel config is built once (singleton), so a bare __() there would freeze on the first request's locale. |
sections(array $sections): self | Named sections inside the group, in render order, as key => heading. Pages opt in with nav()['section'] => key; items without a section render first, unheaded. Pass Closure labels for the same request-time translation reason as label(). |
NavItem
Tbtop\Admin\Navigation\NavItem
| Method | What it does |
|---|---|
can(array|string|null $gate): self | Show the item only to users the gate allows: an ability, or an ability plus the model class its policy resolves from — the same value a Page::can() returns, so ->can(SomePage::can()) hides a link to a page its user may not open. Null (the default) shows it to everyone. |
group(string $group): self | Sidebar group heading this item is listed under (nav context only); unset = ungrouped, no heading. |
icon(Closure|string $name, Closure|string $position = 'left'): static | $name is a kebab-case Lucide icon name (e.g. 'circle-check') resolved against the client's icon registry; register custom names client-side via registerIcon before using them here. $position is 'left' (default) or 'right', placing the icon relative to the label. Either may be a Closure; a closure-supplied position is validated when it resolves. |
newTab(bool $newTab = true): self | Deprecated (removed in 1.0): use url()->openUrlInNewTab(). |
openUrlInNewTab(bool $condition = true): self | Open url() in a new browser tab instead of navigating in place. |
section(string $section): self | Section key within its group, declared on NavGroup::sections() (nav context only). Ignored for ungrouped items and in the user menu. |
sort(int $order): self | Sort position within its group (nav context only). |
url(string $url): self | Destination URL — an internal path or an external link. |
CommandPaletteConfig
Tbtop\Admin\CommandPalette\CommandPaletteConfig
| Method | What it does |
|---|---|
commands(array $commands): static | Replaces the custom command list; additive to includeNav()'s auto-listed sidebar destinations, not a substitute for it. |
disable(): static | Sugar for enable(false); a disabled palette is omitted from the wire entirely. |
enable(bool $enabled = true): static | Palette is enabled by default; pass false to disable it (same as disable()). |
hotkey(string $spec): static | Keybinding that opens the palette (default ⌘K / Ctrl+K). |
includeNav(bool $include = true): static | Auto-list sidebar destinations (default true). false = commands only. |
placeholder(string $text): static | Placeholder text for the palette search input. |
Command
Tbtop\Admin\CommandPalette\Command
| Method | What it does |
|---|---|
group(string $group): self | Group heading the command is listed under. |
handler(string $name): self | Run a client handler registered via definePaletteCommand() instead of navigating. |
icon(Closure|string $name, Closure|string $position = 'left'): static | $name is a kebab-case Lucide icon name (e.g. 'circle-check') resolved against the client's icon registry; register custom names client-side via registerIcon before using them here. $position is 'left' (default) or 'right', placing the icon relative to the label. Either may be a Closure; a closure-supplied position is validated when it resolves. |
keywords(array $keywords): self | Extra search terms beyond the label. |
openInNewTab(bool $newTab = true): self | Deprecated (removed in 1.0): use url()->openUrlInNewTab(). |
openUrlInNewTab(bool $condition = true): self | Open url() in a new browser tab instead of navigating in place. No effect when handler() is used instead of url(). |
url(string $url): self | Navigate to a URL — an internal path (Inertia visit) or an external link. |
Notifications
Database notifications surfaced in the admin bell. Backed by Laravel's database channel — the payload is page-independent, so actions are links only, never server closures.
Testing
The testing API: tbtop(Page::class, $params) (or $this->tbtop() with the InteractsWithTbtop trait) visits a page through its real endpoints and asserts on the wire. Guide in testing.md.