Authentication Sentry Laravel Package

Getting Started

This is a fork of Cartalyst Sentry (the Laravel 4-era auth + ACL package) adapted to plug into the jacopo/authentication abstraction. Treat it as a driver package, not a standalone auth solution: it exists to make Sentry satisfy someone else's authentication/ACL contract.

First steps:

1. Read the fork, not the docs. With 2 stars and 0 dependents, the README will be thin and upstream Sentry docs will be the closest thing to a manual. Open composer.json first to confirm which jacopo/authentication version it targets, then read the driver class — that class is the entire public surface you'll actually call.
2. Install alongside the parent package, not alone:

   composer require jacopo/authentication jacopo/authentication-sentry
   

3. Publish and run Sentry's migrations. The fork inherits Cartalyst's schema (users, groups, users_groups, permissions, persistences or sessions, throttle). These tables are non-negotiable — the driver queries them directly.
4. Register the driver where your authentication manager resolves drivers (service provider binding or the package's driver map). A minimal config typically needs: Sentry's own config/packages/cartalyst/sentry/config.php for session/cookie/hashing behavior, plus whatever driver key the parent manager expects.
5. First use case: authenticate a user through the abstraction, then check a permission through the ACL half.

   $auth->authenticate(['email' => $email, 'password' => $password]);
   $user = $auth->user();
   $can  = $auth->can('posts.edit'); // routed to Sentry's permission check
   

6. If your app is on Laravel 5+, stop and evaluate whether this is the right layer at all — see Gotchas.

Implementation Patterns

Wrap, don't scatter. The value of this package is that your controllers and middleware talk to the jacopo/authentication contract, not to Sentry:: statics. Keep it that way: resolve the manager/driver from the container and never call Cartalyst\Sentry\Facades\Laravel\Sentry directly in application code. If you find yourself needing a Sentry method the driver doesn't expose, extend the driver rather than bypassing the abstraction.

Auth + ACL in one call site. The natural pattern with this package is a thin application-level AuthService that composes both halves:

class AuthService
{
    public function __construct(private $auth) {}

    public function attempt(string $email, string $password): bool
    {
        try {
            $this->auth->authenticate(compact('email', 'password'));
            return true;
        } catch (\Exception $e) {
            return false; // throttled, not found, wrong password — see Gotchas
        }
    }
}

Middleware / filter integration. Because the driver satisfies an auth contract, your route protection should bind to that contract's "check current user" method in middleware. This keeps route guards swappable and is the single biggest reason to use the fork over raw Sentry.

Group and permission modelling. Sentry's ACL is group-based with per-user overrides. In practice: create groups in seeders (Sentry::createGroup via the driver if exposed, otherwise a one-off script), assign users at registration, and resolve permissions by name (posts.edit) rather than by ID. Cache the resolved permission set per request — Sentry will re-query groups and permissions on every can() call otherwise.

Registration and profile changes. Sentry handles password hashing internally, so do not pre-hash. Pass plaintext into the driver's register/create path and let it hash. If the interface expects a user array, map it to Sentry's expected keys (email, password, plus any first_name columns you added).

Testing. Don't hit the real driver in unit tests. Bind a fake implementation of the jacopo/authentication contract in the container and assert your application called authenticate/can correctly. Reserve one or two integration tests against the real Sentry driver, run against a migrated SQLite/MySQL test database, to catch schema drift.

Gotchas and Tips

Abandonment is the headline risk. Zero dependents, two stars, and a PHP 5.3+ baseline mean this is a preserved fork of a package whose upstream (Cartalyst Sentry) was itself deprecated years ago. There will be no security patches for you. Before adopting, confirm your Laravel version — Sentry's session handling and its Sentry:: facade are tightly coupled to Laravel 4/early 5 internals and will not survive Laravel 8+ without surgery.

The "wrong password" problem. Sentry throws distinct exceptions for UserNotFoundException, UserNotActivatedException, UserSuspendedException, UserBannedException, and WrongPasswordException — some forks also throw a throttle exception. If the jacopo/authentication contract collapses these into a boolean, you lose the ability to give users a useful message. Catch specific exception types in your service layer before the abstraction swallows them.

Login attribute is configurable and bites you. Sentry's login_attribute defaults to email, but the driver may pass a username. Verify both the config and the driver's authenticate implementation — mismatches here produce silent "user not found" failures that look like bad passwords.

Throttling is on by default and persists in the database. Failed logins write to the throttle table; a developer repeatedly testing a login flow will lock the account and then spend an hour debugging. Clear the throttle table between test runs, and confirm whether the driver surfaces the throttle wait time.

Migration conflicts. The fork's migrations may assume table names (users, groups) that clash with your existing app tables, or Sentry's users table may not match your app's user model. Decide early: adopt Sentry's user model wholesale, or add a foreign key and keep them separate. Do not attempt to share a users table with an existing app schema without auditing every column Sentry writes.

Permission caching goes stale. Sentry caches groups/permissions on the user object for the duration of the request. If you modify permissions mid-request (rare, but it happens in admin tooling), re-fetch the user rather than reusing the instance.

Config file location is version-sensitive. Sentry's config must be published to config/packages/cartalyst/sentry/ and is loaded by the parent package's service provider. If the driver appears to ignore your config, the package isn't being registered or the config namespace is wrong — this is the most common "nothing works" failure.

Extension points worth knowing. The two useful seams are (a) subclassing the driver to add methods your app needs and rebinding it in the container, and (b) Sentry's hasher strategy, if you need to migrate password hashes. Both are documented only in the source. Read the driver class top to bottom before your first non-trivial change — at this package's maturity, the source is the specification.