Laravel Sentinel Laravel Package

Getting Started

This package layers a root/superuser permission bypass on top of Laravel's authorization stack. The 1.0.6 patch fixes how root status is evaluated during permission checks, so it's worth re-verifying any code paths that assume root users short-circuit normal permission logic.

1. Install and publish config — composer require the package (1.0.6 or later, since the root check fix is the reason to be on this version), then publish any config/asset files per the package README. Confirm the service provider is auto-discovered.
2. Look first at the root detection entry point — find the method that decides whether the current user is root (isRoot(), a trait, or a gate before callback). This is the single most important piece of the package and the thing 1.0.6 changed. Understand exactly what it checks: a column on the users table, a config-listed user ID, a role, or an env flag.
3. First use case — protect a single route with a permission check and confirm two behaviors: a normal user with the required permission passes, a normal user without it gets a 403, and a root user passes regardless of granted permissions. If root does not bypass, or a non-root user is incorrectly treated as root, you're seeing the bug 1.0.6 addresses.

Start in config/ and the authorization trait on your User model before touching controllers — most day-to-day issues are configuration, not code.

Implementation Patterns

Root bypass as a gate before callback. The idiomatic integration is to register root handling ahead of your normal gates/policies so a root user never fails a downstream check:

Gate::before(function ($user, $ability) {
    return $user->isRoot() ? true : null; // null = fall through to policies
});

Returning null (not false) is essential — false would deny everything for non-root users. Make sure your root check runs before per-ability policies, not inside them.

Policy-level integration. Where you prefer explicit checks, resolve root inside each policy's before method rather than repeating it in every ability method:

public function before(User $user)
{
    return $user->isRoot() ? true : null;
}

Blade and middleware usage. Permission checks in views and route middleware should route through the same package helpers so the root logic is consistent. Avoid re-implementing isRoot() inline — one implementation, one place to fix (exactly the class of bug 1.0.6 landed).

Testing patterns. Write three-way test cases for every protected ability: root user, permitted user, unpermitted user. A root-user test that also has the ability granted is a false negative — it passes even when the root bypass is broken. Always test root with zero explicit permissions.

Cache-aware checks. If your permission set is cached per user, ensure the root flag is invalidated alongside permission caches when a user's role or root status changes, otherwise stale privilege persists after a downgrade.

Gotchas and Tips

• Root check ordering. If your root bypass is inside a policy rather than a global before, a more specific gate or an earlier-registered before callback can win first. Register root handling last among before callbacks so it isn't shadowed — but verify against your Laravel version's precedence, since before callbacks run in registration order and the first non-null result wins.
• false vs null. The most common self-inflicted bug: returning false from a root before for non-root users denies the entire application. Always null.
• Guard mismatch. Multi-guard apps (admin/user, API/session) frequently fail here: a root check against one guard returns true while the check is evaluated against another. Confirm the package resolves the user from the active guard, and test root checks per guard.
• Debugging a suspected root bug. Log the values feeding the root decision (user ID, role, config entry) at the point of check. If a user is unexpectedly treated as root, suspect null/0 ID coercion — an empty or zero user ID matching a loosely-typed config comparison is a classic.
• Upgrade step for 1.0.6. Re-run your permission test suite after upgrading, specifically any tests asserting that non-root users are denied. The fix changes a comparison path, and code that had compensated for the old behavior may now behave differently.
• Extension point. If the package exposes a root-resolution contract or macro, hook there rather than overriding the trait — you get the package's bug fixes for free instead of maintaining a fork of the very method that just changed.
• Version pin. Pin to ^1.0.6 rather than ^1.0 so downstream installs don't resolve to a pre-fix build in a lockfile-less environment.