Super Admin Laravel Package

Getting Started

Install and pin the version. Given the sparse release history (v1.1.5 is described only as “First relase of super-admin”), pin explicitly so a surprise patch can’t change privileged-access behavior under you:

composer require super-admin-org/super-admin:^1.1.5

Laravel’s package discovery should register the service provider automatically; if not, confirm it in bootstrap/providers.php (Laravel 11+) or config/app.php.

Publish everything, then read it. Run the publish command with each tag the provider exposes (typically config, migrations, assets, views — check php artisan vendor:publish --provider="SuperAdmin\\...\\ServiceProvider" without a tag to list them). Before running any migration, open the generated migration files and confirm whether they add new tables (organizations, memberships) or alter users.

Where to look first, in order:

1. config/super-admin.php (or similarly named) — route prefix, middleware stack, guard, table names, model bindings.
2. The package’s routes/ file — what endpoints exist and what middleware protects them.
3. Migrations — schema for organizations/memberships.
4. The gate/middleware class — how “super admin” is actually determined.

First use case: give one trusted operator a bypass of normal authorization, plus organization-scoped user management. Create the admin user, attach the super-admin role/flag the package expects (check the config/seeder/docs for how), assign them to an organization, then hit the admin route prefix (default is usually /super-admin or similar — verify in config) while authenticated as that user.

Implementation Patterns

Gate-check the bypass once, centrally. Rather than sprinkling checks, define a single gate (e.g. Gate::before(fn ($user) => $user->isSuperAdmin() ? true : null) or use the package’s middleware) so the bypass is auditable in one place and easy to remove later.

Protect the admin surface with middleware, not just route prefixes. Apply the package middleware to the whole admin route group and verify it’s in the web + auth stack:

Route::middleware(['web', 'auth', 'super-admin'])->prefix('super-admin')->group(...);

Extend with your own admin modules. The package advertises “extensible services and routes,” so register domain-specific admin routes alongside the package’s rather than editing published files — keeps upstream upgrades trivial.

Organization scoping as a query layer. For any custom admin listing, resolve the current organization (or operator-selected org) and scope queries through the membership pivot, e.g. $user->organizations()->where('organizations.id', $orgId). Don’t rely on middleware alone to scope data — enforce it in queries/policies too.

Override Blade scaffolding, don’t fork it. Publish views to resources/views/vendor/super-admin/ and restyle there. For behavior changes, extend controllers/services via container bindings or subclass the published route targets.

Seed a super admin in local/dev only. Gate the seeder behind app()->environment('local') or a dedicated seeder class so it can’t create privileged accounts in production.

Feature-flag the rollout. Wrap the admin routes and bypass gate behind a config flag (config('super-admin.enabled')) so you can disable the privileged layer without a redeploy if something goes wrong.

Gotchas and Tips

• Sparse docs. Treat the source as the spec — read the service provider, config, and middleware before trusting any README. The changelog between v1.1.3 and v1.1.5 is not published in any detail here, so diff them if you’re upgrading.
• Test migrations on a copy first. Verify the generated migrations are reversible; admin/privilege tables are exactly the ones you don’t want to half-migrate in production.
• Middleware may fail open if misconfigured. Confirm the middleware is actually applied (use php artisan route:list) and that an unauthenticated/non-admin user is rejected — test with a plain user explicitly, not just the happy path.
• Guard compatibility. If you use Sanctum, multiple guards, or UUID primary keys, validate the package config against your stack — package migrations often assume bigint users.id.
• Lockout recovery. Document how to grant/revoke super-admin directly in the DB and how to disable the package via config. Add a runbook before production.
• No built-in audit trail. The description doesn’t promise audit logs; wrap privileged actions in your own logging (impersonation, role changes, deletions) if compliance matters.
• Cache invalidation. If roles/permissions are cached, ensure revocation invalidates the cache — otherwise a demoted admin can stay privileged until TTL expiry.
• Config caching. After publishing config, run php artisan config:clear locally and config:cache in deploy; stale config is the usual cause of routes silently missing.
• Route collisions. Check the configured admin prefix against existing routes (route:list --path=super-admin).
• Scope expectations. Use this for internal ops/support, not customer-facing authorization. If you need granular permissions, audit trails, or SSO, plan to wrap this or move to a fuller admin stack — don’t grow it into one incrementally.
• Version pinning and review cadence. With 0 dependents and a single visible release note, assign an owner to watch upstream and re-read the middleware on every minor bump.