Security User Laravel Package

Getting Started

youshido/security-user is a framework-agnostic PHP user/security component, not a Laravel package. There is no service provider, facade, config file, or migration to publish — so "getting started" means deciding whether you should be here at all before writing glue code.

1. Check installability first. Run composer require youshido/security-user on a throwaway branch. The last release was February 2016, so expect PHP constraint conflicts on PHP 8.1+ (Laravel 10/11). If Composer refuses, that is your signal — do not force it with --ignore-platform-reqs for auth code.
2. Read in this order: composer.json (autoload + PHP constraint), the README, then the top-level classes in src/. Map which classes are interfaces vs. concrete — only the interfaces are safe to lean on.
3. First use case: defining a user identity object and checking credentials/password validity. Wire it by hand in a small SecurityUserServiceProvider you own, bound as a singleton in config/app.php providers.
4. Prove it in isolation before touching the app. Write a one-off script or Tinker snippet that constructs a user and validates a password against it. Do not start with a custom Auth::guard() — isolate the package's behavior first.

The realistic starting point for most teams: treat this as a reference implementation to read, not code to ship.

Implementation Patterns

Because the package knows nothing about Laravel, every viable pattern is an adapter:

• Custom guard. Implement Illuminate\Contracts\Auth\Guard (or extend SessionGuard) and delegate credential validation to the package. Keep the package entirely behind the guard so the rest of the app only ever sees Auth::user().
• Authenticatable adapter. Write a class that implements Illuminate\Contracts\Auth\Authenticatable and decorates the package's user object. You must forward getAuthIdentifier(), getAuthPassword(), getRememberToken(), and setRememberToken() correctly or Auth::login() and "remember me" silently break.
• Repository bridge. If the package exposes a user repository/provider interface, implement it against Eloquent rather than the package's own storage — this keeps your migrations, timestamps, soft deletes, and casts intact.
• Request flow. Controller + FormRequest → Auth::attempt($credentials) → your guard → adapter → package credential check → session login. That is the entire happy path; anything more belongs in a service class, not a controller.
• Authorization mapping. If the package carries roles/permissions, translate them into Laravel Gates/Policies inside AuthServiceProvider. Never check package roles directly in Blade or controllers — that is how you end up unable to swap the package later.
• Testing. Bind a stub implementation of the package's interfaces in tests/TestCase so feature tests exercise your adapter, not the package's internals.

Gotchas and Tips

• Abandoned since 2016. 1 star, zero dependents, no security patches. For anything touching passwords or sessions this is a genuine liability. Use it only in a legacy app already committed to it, or as a learning reference.
• No Laravel integration at all. No auto-discovery, no facade, no config, no migrations. Every line of integration is yours to write and maintain — budget for that.
• Password hashing. If the package ships its own hasher, do not use it. Use Hash::make() / Hash::check() (bcrypt/argon2) and borrow only the identity abstraction. Old hashers are the most common source of silent security regressions.
• Autoload quirks. Older packages sometimes ship PSR-0 mappings or miss the psr-4 key. If you get class-not-found on the first bind, run composer dump-autoload -o and inspect composer.json autoload before debugging anything else.
• Session/remember-me contract. Laravel's SessionGuard relies on exact method names on the Authenticatable. A missing getRememberToken() produces no error — it just quietly fails to persist the session. Test login + remember + logout explicitly.
• Debugging checklist. "Class not found" → autoload/binding. "Target interface not implemented" → your adapter drifted from the contract. Auth silently returning null → adapter returning a different identifier type than the session expects (e.g. string vs int).
• Extension point. Keep the adapter thin and interface-driven so you can replace the package with Breeze, Fortify, or plain Auth::attempt() without rewriting controllers.
• Bottom line: for day-to-day Laravel work, the leverage here is near zero. Laravel's built-in guards, Auth::attempt(), and Gates do the same job with active maintenance and a security team behind them. Adopt this only under legacy constraints, and isolate it so removal is a one-file change.