Auth Laravel Package

Getting Started

1. Install and inspect before integrating. Run composer require cerbero/auth, then immediately open the package's composer.json to check its illuminate/* version constraints. This package predates the current Laravel release line, so confirm it resolves against your framework version before writing any code.
2. Where to look first, in order:
   • composer.json — supported Laravel/PHP versions and required dependencies (Socialite, etc.).
   • The service provider (src/*ServiceProvider.php) — this is the real map of the package: what it binds, what it publishes, what routes/migrations/views it registers.
   • config/ — published configuration is the primary control surface.
   • routes/ — the package likely registers its own auth routes; run php artisan route:list after install to see exactly which endpoints you inherit.
   • src/Http/Controllers and src/Traits — the classes you'll extend or use on your User model.
3. Register the provider manually if your Laravel version doesn't support package discovery for this package; then publish assets:

   php artisan vendor:publish --provider="Cerbero\Auth\AuthServiceProvider"
   

   Publish config, views, and migrations separately so you can review each before committing.
4. First use case — a working login/registration flow. Point a fresh app at the package's provided routes, run the migrations, and log in. Do this in a scratch branch or throwaway app first. Once the default flow works end-to-end, you have a baseline to diff against when you start customizing.

Implementation Patterns

Treat the package as a scaffold, not a dependency you call into. The productive pattern with auth modules of this vintage is: publish everything the provider offers, then own the code locally. Your controllers extend the package's, your views override the published ones, your User model uses the package traits. This keeps you upgrade-safe in practice (you won't upgrade — see Gotchas) and lets you actually change behavior.

Model traits over inheritance. Add the package's authentication/confirmation traits to App\Models\User rather than swapping your model for one shipped by the package. This keeps your existing relationships, casts, and accessors intact.

Routes: inherit, then narrow. Start with the package's routes enabled to validate the flow, then either (a) keep them and layer middleware on top via Route::group in your own routes/web.php, or (b) disable the package's route registration in config and re-declare only the endpoints you want, pointing at the package controllers. Option (b) is usually correct in production because it makes the public surface explicit and auditable.

Views: publish and namespace. Published views normally land under a package view namespace (e.g. auth::login). Override by editing the published files rather than redefining the namespace, so view:clear doesn't surprise you.

Hook into lifecycle events, not controller overrides. If the package dispatches events on register/login/password-reset, prefer listeners over rewriting controllers — it survives your own refactors. If it doesn't dispatch events, this is your first genuine code change, and you should add them.

Guard alignment. Whatever guard the package's controllers authenticate against must match config/auth.php (web guard, users provider, session driver). Mismatches here are the single most common cause of "login succeeds but I'm still a guest."

Testing. Because the routes are conventional, write feature tests against the HTTP endpoints (post('/login'), assert authenticated) rather than unit-testing the package internals. That gives you a regression net that survives your own customizations.

Gotchas and Tips

• Maintenance risk is the headline issue. 48 stars and no dependents means effectively no upstream support. Check the last commit date and open issues before committing; assume you are now the maintainer of your fork. Vendor the code or fork it deliberately rather than relying on composer update behaving.
• Version drift. Old auth packages typically reference Illuminate\Contracts\Auth\Guard signatures, AuthenticatesUsers traits, or Redirect helpers that changed across Laravel 8/9/10+. Expect to patch method signatures on first install. Diff against the framework's own laravel/ui/breeze scaffolding — the framework's version is the correct reference.
• Migration collisions. The package ships a users migration. If you already have one, don't run both. Compare columns and fold any missing ones (confirmation token, remember token, etc.) into your existing migration instead of publishing theirs.
• Config caching bites late. If auth behaves oddly only in a deployed environment, it's almost always php artisan config:cache holding a stale value after you edited the published config. Always config:clear when debugging locally, and re-cache in deploy.
• Auto-discovery traps. If the provider wasn't discovered, you get confusing "class not found" or missing-route errors rather than a clean failure. Verify with php artisan about (or route:list) that the package is actually loaded.
• Debugging approach: php artisan route:list --path=login, then dd() inside the resolved controller's method, then check the guard in Auth::guard()->check() at each step. Isolate whether failure is in validation, credential check, session regeneration, or the guard config — don't guess.
• Extension points to prefer: service container bindings in the provider (swap implementations without editing package code), events/listeners, published config, and view overrides. Treat direct edits to vendor/ as a last resort; if you must, fork.
• Socialite/email confirmation features carry external dependencies (OAuth credentials, mailer config, signed URL validity). These fail silently in development — test with a real mail trap and real OAuth redirect URI, not mocks.
• Don't inherit its security posture blindly. Review password reset token handling, rate limiting on login, and session regeneration on privilege change. Where the package is thin, add Laravel's ThrottleRequests middleware and ensure $request->session()->regenerate() happens on login.