Maintenance Banner

MaintenanceBannerModule renders a read-only page notice for maintenance windows, degraded-service warnings, deployment freezes, and other operator-facing states.

Use it when admins must see a clear status message before working with the rest of the page. The module does not submit forms, call handlers, write records, or create routes.

use AlexKudrya\Adminix\AdminixPage;
use AlexKudrya\Adminix\Modules\Maintenance\MaintenanceBannerModule;
use AlexKudrya\Adminix\Modules\Module;

AdminixPage::uri('operations')
    ->name('operations')
    ->addModules(
        Module::maintenanceBanner()
            ->name('maintenance-window')
            ->title('Maintenance window')
            ->message('Tenant 9 is in read-only maintenance mode while the queue drains.')
            ->severity(MaintenanceBannerModule::SEVERITY_DANGER)
            ->icon('bi bi-tools'),

        Module::list()
            ->name('jobs')
            ->dataSource(JobStatus::class)
            ->criteria([
                ['tenant_id', '=', 'param:0'],
            ])
    );

Result: Adminix renders a full-width notice with an icon, title, message, and severity accent. Because the banner is read-only, users can inspect the message but cannot trigger a package action from it.

Rendered example:

Configuration

name() is required and must be unique on the page.
title() renders the short heading.
message() renders the notice body. body() is an alias for teams that already use text-module wording.
severity() accepts info, success, warning, danger, or neutral.
icon() accepts a Bootstrap icon class. If omitted, Adminix chooses an icon from the severity.
format('text') escapes text and preserves line breaks. This is the default.
format('markdown') renders the compact Adminix-safe markdown subset.
format('html') renders trusted developer-authored HTML.
compact() reduces padding for secondary notices.
fullWidth() spans the page width. This is the default.
halfWidth() lets the banner sit in a half-width module column on wide screens.

Use visibleUsing(), can(), or canAny() when the banner should appear only for a tenant, role, feature flag, or application maintenance state:

Module::maintenanceBanner()
    ->name('readonly-mode')
    ->title('Read-only mode')
    ->message('Writes are temporarily disabled for this tenant.')
    ->severity('warning')
    ->visibleUsing(fn () => app(MaintenanceState::class)->tenantIsReadOnly());

Doctor

adminix:doctor reports common banner mistakes:

missing message();
invalid severity().

Invalid severity falls back to warning during rendering, but Doctor still reports it so the PHP configuration can be corrected.

Security

The banner is intentionally display-only. Do not use it as a substitute for application authorization, tenant scoping, write locks, or policy checks.

If maintenance mode must block writes, enforce that in the consuming application's policies, routes, jobs, commands, or datasource criteria. The banner should explain the state; it should not be the only protection.

Use format('html') only for trusted PHP configuration. Do not pass request data, database content, or third-party HTML into the banner unless the consuming application sanitizes it first.

Last modified: 23 July 2026