Download the PHP package codenzia/laravel-superadmin without Composer

Laravel SuperAdmin — Zero-friction protected admin account

Drop-in protected super-admin account for Laravel. Composer require, run migrate, and you have a working super-admin login. One env var (or one interactive command) overrides the defaults. No friction, no ceremony.

What you get

• A single protected user that is auto-created on first migrate. Default email derived from APP_URL / APP_NAME. Default password superadmin.
• An Eloquent observer that blocks deletion, email changes, unprotect attempts (true → false), and mass-assignment privilege escalation (false → true) on the is_protected flag.
• A Gate::before hook so the super admin authorizes for every ability — works without Spatie, Shield, or any policies wired up.
• Late role assignment. Solves the MigrationsEnded vs Spatie-Role-row race: when spatie/laravel-permission is in use, the super_admin role row often doesn't exist yet at auto-install time, so the role would silently fail to attach. A wildcard eloquent.created listener retroactively assigns the configured role the moment the row appears in a later seeder run. Idempotent and best-effort; no-ops cleanly when Spatie isn't installed.
• A Filament plugin that hides destructive row actions (delete, suspend, ban, impersonate, …) and disables privileged form fields (roles, status, email, …) on the protected user row — automatically, across every consumer app, with no per-resource code.
• A superadmin:ensure command that interactively rotates name + email + password. DB-only — never reads or writes .env.
• A superadmin:status command (with --verbose for full health diagnostics) so you can verify the install in one shot.

Quick start

That's the whole install. The package listens to MigrationsEnded and creates the protected user once, if and only if no protected user exists. Re-running migrate is a no-op.

Override the defaults — two paths

v0.4.0+ keeps identity fields (name / email / password) out of .env and config entirely. Plaintext credentials never live on the host filesystem. Two override paths:

(1) Pin the values in your seeder — runs every migrate:fresh --seed / on first install:

Pass any subset of ['name', 'email', 'password']. Omitted keys fall back to package defaults on create; on update they're left unchanged (password specifically — omit to keep the current hash).

(2) Rotate post-install — DB-only artisan command:

Non-interactive variant:

superadmin:ensure never reads or writes .env. Plaintext only lives in the seeder source (committed to your repo with code) or in the operator's terminal during rotation.

Production password warning. The default superadmin is deliberately memorable for local dev and internal use. Always override via the seeder or rotate via superadmin:ensure before exposing the app to anyone.

Default email resolution

When the seeder doesn't pass email, the package derives one from your host's own config — never a vendor domain:

1. superadmin@<host> where <host> = parse_url(config('app.url'), PHP_URL_HOST)
2. else superadmin@<slug>.local where <slug> = Str::slug(config('app.name'))

So APP_URL=https://myshop.com → [email protected]. APP_NAME="My Shop" with no URL → [email protected].

Default role resolution (Filament Shield bridge)

When bezhansalleh/filament-shield is installed, configuredRole() auto-discovers Shield's super-admin role name from filament-shield.super_admin.name. Apps don't need to set the role name in two places. When Shield is not present, the package falls back to the literal 'super_admin'.

How protection works

The package identifies the protected row via the users.is_protected = true DB column. v0.4.0+ removed the secondary email-match path since identity is no longer env-driven — the flag is the single source of truth, set by install() / ensure() and defended by the observer.

Four protection layers — each independent, so tampering with one doesn't silently disable the others:

The observer is defense-in-depth. Use the facade in your policies for proper HTTP 403s (see UserPolicy below).

App-side defense-in-depth (recommended)

Even with the observer guarding false → true promotion, you should keep is_protected out of the User model's $fillable. The observer only fires on update, and only inside Eloquent — raw DB::table('users')->update(...) calls bypass it. The two-layer pattern:

Commands

Configuration

The package config is small. After php artisan vendor:publish --tag=superadmin-config:

Seeder integration

SuperAdmin::ensure() is the seeder-safe primitive. Two modes:

You don't strictly need the no-args call — the MigrationsEnded auto-install already handles fresh installs. The array form is the recommended pattern when a project wants stable, repo-tracked superadmin credentials across all of its environments.

For raw create/update with explicit credentials, use SuperAdmin::install($password, $email, $name).

Integration patterns

User model trait (optional)

Adds isSuperAdmin() plus two query scopes:

UserPolicy

The observer throws — your policy should return a proper 403 first:

Filament

The plugin registers three defense-in-depth UX layers on the protected user row, all toggleable via config/superadmin.php and active by default:

1. DeleteAction / ForceDeleteAction auto-hide — original behavior. Admins never see a button that would only error at the observer layer.
2. Custom destructive row actions auto-hide. Any Filament\Actions\Action whose getName() is in filament.hidden_action_names is hidden on the protected user. The default list catches the verbs we ship across our consumer apps: delete, forceDelete, suspend, unsuspend, ban, unban, markEmailVerified, verify, unverify, impersonate, demote.
3. Privileged form fields auto-disable. Any Filament\Forms\Components\Field whose getName() is in filament.locked_field_names is disabled when the form's record is the super admin. Default list: roles, role, permissions, status, is_protected, email, user_type. Closes the "admin demotes the super admin via the roles Select" loophole.

Apps extend the defaults via config, no code:

Caveat. Filament's ->hidden() and ->disabled() setters replace prior conditions (they don't AND/OR). If app code chains an explicit ->hidden(false) after construction, the package's auto-hide is overridden. Apps that rely on ->visible(fn () => ...) for conditional showing (the common pattern) are unaffected because visible and hidden are separate fields and an action is hidden when either hides it.

To also hide the protected row from non-super-admin viewers:

Authorization modes

The package never creates the role row, defines permissions, or installs Shield — those remain your project's responsibility. In default mode, you don't need any of them: Gate::before covers authorization on its own.

What's new since 0.3.0

0.3.2 (2026-05-22). Adds late role assignment for the MigrationsEnded-vs-Spatie-Role-row race, and Filament auto-lock for the protected user row: every consumer app now auto-hides destructive row actions and auto-disables privileged form fields with no per-resource code. New config keys: late_role_assignment, filament.hidden_action_names, filament.locked_field_names. Tests grew from 84 to 105.

0.3.1 (2026-05-21). Security: the observer now blocks is_protected: false → true promotion via Eloquent update (mass-assignment privilege escalation defense). Previously only the downgrade direction was guarded. Also cleans up three stale protection.block_* config reads that were documented as removed in 0.3.0 but never deleted from the observer code.

See CHANGELOG.md for the full release notes.

Upgrading from 0.3.x to 0.4.0

v0.4.0 moves identity (name / email / password / role) entirely out of .env and config. Per-app upgrade:

1. composer update codenzia/laravel-superadmin

2. Move any per-app overrides from .env into your seeder:

3. Delete SUPER_ADMIN_PASSWORD, SUPER_ADMIN_EMAIL, SUPER_ADMIN_ROLE, SUPER_ADMIN_NAME from every .env and .env.example. These env vars are no longer honored — leaving them set is harmless but stale.
4. If you publish the package config: delete the email, password, role keys from config/superadmin.php. They're no longer read.
5. Update any callers of php artisan superadmin:setup to php artisan superadmin:ensure. The old command name was removed.
6. If you use Filament Shield: nothing to do — configuredRole() now auto-discovers filament-shield.super_admin.name.

Removed in 0.4.0

Upgrading from 0.2.x

v0.3.0 was a clean break. The vendor-friction model is gone. Per-app upgrade:

1. composer update codenzia/laravel-superadmin
2. php artisan migrate — auto-installs the protected user if none exists; no-op if one does.
3. Replace any seeder calls to SuperAdmin::install(...) with SuperAdmin::ensure() (or keep install() if you need explicit credentials).
4. Delete .env entries that are no longer recognized (see table below).

Removed in 0.3.0

Kept

• is_protected column + Eloquent observer
• Gate::before authorization
• Filament destructive-action hiding
• IsSuperAdmin trait + query scopes
• SuperAdmin facade — is(), user(), exists(), install(), email(), userModel(), isConfigured(), assignRole(), hasConfiguredRole(), withoutProtection()
• Facade methods: ensure(?array), defaultEmail(), defaultPassword(), defaultName()

Testing

105 Pest tests, 173 assertions. Covers the manager, the observer (delete + email + unprotect + promote-escalation), Gate::before, the MigrationsEnded auto-install hook, the late-role-assignment listener, the setup command, the env writer, and the Filament plugin (DeleteAction / ForceDeleteAction hiding, custom-named-action auto-hide, locked form-field auto-disable, master-switch kill, app-extended allowlists).

License

MIT © Codenzia. See LICENSE.md.