Sentinel Laravel Package

Getting Started

Install via Composer for Laravel 12+ (requires PHP 8.3+):

composer require cartalyst/sentinel

Auto-discovery registers the service provider—no manual providers entry needed. Publish config and migrations with:

php artisan vendor:publish --provider="Cartalyst\Sentinel\Laravel\SentinelServiceProvider"

Review config/sentinel.php to tailor activation requirements, persistence lifetimes, and permission resolution logic. Run migrations to seed tables (users, roles, permissions, activations, reminders, persistences). Crucially, the very first user created via Sentinel::registerAndLogin() auto-activates, so avoid assuming all users require manual activation—this behavior only applies to the first registered user.

Implementation Patterns

• Authentication: Use Sentinel::authenticate($credentials) for login (validates password & activation) and Sentinel::check() to verify session state. For API use, prefer Sentinel::findByCredentials($credentials) + manual persistence handling to avoid session side effects.
• Role & Permission Checks: Assign roles via $user->roles()->attach($role). Check with instance methods ($user->inRole('admin')) or static helpers (Sentinel::hasAccess('admin.dashboard')). Define permissions hierarchically in sentinel.php config (e.g., 'admin' => ['user.*']) and use wildcard patterns ('admin.*') for scalable access control.
• User Registration & Activation: Register with Sentinel::register($attributes), then either call Sentinel::activate($user) or rely on auto-activation (only for first user). For password resets, generate reminders via Sentinel::getReminderRepository()->create($user) and validate with Sentinel::completeRemind($user, $code).
• Throttling: Sentinel automatically blocks repeated failures—configurable via throttle section. Manually inspect via Sentinel::throttle()->check($user) or clear blocks with Sentinel::throttle()->resume($user) after manual review.
• Custom User Models: Extend Cartalyst\Sentinel\Users\EloquentUser to add soft deletes, custom attributes, or relationships. Register the model in config('sentinel.users') to override defaults.

Gotchas and Tips

• Activation Gotcha: Auto-activation only applies to the first user in the database. Subsequent users must be explicitly activated via Sentinel::activate(). Always verify $user->hasAccess() before assuming activation status.
• Permission Precedence: Specific permissions (e.g., 'user.edit') override wildcard patterns (e.g., 'user.*'). Avoid overlapping rules—e.g., defining both 'user' => ['edit', 'delete'] and 'user.*' => true can cause unpredictable hasAccess() results.
• Persistence ≠ Sessions: Persistent logins rely on the persistences table and cookies. Never delete entries manually; always use Sentinel::logout() to invalidate both session and persistence. For long-lived sessions, use Sentinel::loginAndEnterPersistence($user, true).
• Stateless APIs: Sentinel defaults to cookie-based persistence. For SPAs or APIs, disable sentinel.persistence.driver = cookie and handle tokens manually using findUserByPersistenceCode($code) + custom auth guards.
• Debugging Failures: When authentication fails silently, inspect checkpoints with Sentinel::getCheckpoints()—this reveals whether failures stem from activation, throttling, or password validation.
• Upgrade Caution: Major version bumps (e.g., v6→v7) require matching PHP/Laravel versions first. Check migration diffs—schema changes (e.g., string length, indexes) may need manual intervention during php artisan migrate.