Auth Laravel Package

Getting Started

grafite/auth is a repackaging of Laravel UI's auth scaffolding — controllers, traits, and Blade views published into your app. The mental model that matters from day one: it's a stub publisher, not a runtime library. You will not call into Grafite\Auth\* from your application code. You install it, publish the stubs into app/ and resources/, and then own the resulting code.

A minimal first pass:

1. Install into an app that already has a users table.

   composer require grafite/auth
   

   Like Laravel UI, this package does not ship the users migration. On a fresh skeleton, confirm you have the default create_users_table migration before anything else — otherwise your first login attempt will fail against a missing table, not against your credentials.

2. Publish interactively, not by guessing tags.

   php artisan vendor:publish
   

   Grafite packages vary in their publish tag names. Look for the Grafite\Auth\AuthServiceProvider entry in the interactive list and publish the controller and view groups. You should see output under app/Http/Controllers/Auth/ and resources/views/auth/.

3. Read the service provider before anything else. Open vendor/grafite/auth/src/ and read the service provider. It tells you exactly what gets registered, which tags are exposed, and — critically — whether Auth::routes() is auto-registered or expected from your routes/web.php. The service provider is the source of truth over any README.

4. Confirm what routes you actually have.

   php artisan route:list --path=auth
   php artisan route:list --path=login
   

   This resolves the single most common early confusion (see Gotchas) about whether the package wired routing for you.

A good first use case to build against: registration capturing an extra field (company, invite code, role) combined with per-role login redirects. That exercises the two seams you'll actually live in — RegisterController::validator()/create() and LoginController's redirectTo() — without touching anything security-sensitive. Write a feature test hitting /register and /login before you build anything on top.

Implementation Patterns

Publish-and-own is the intended lifecycle. Once stubs are copied into your app, the composer dependency exists only to re-publish. The realistic pattern is: install → publish → customize → either pin the dependency or drop it and carry the code. Many teams do the latter and treat the package as a one-time scaffold generator. Plan the handoff accordingly.

Registration extension. RegisterController has two clean seams. Add the field to the validator, then to create():

protected function validator(array $data)
{
    return Validator::make($data, [
        'name'     => ['required', 'string', 'max:255'],
        'email'    => ['required', 'string', 'email', 'max:255', 'unique:users'],
        'password' => ['required', 'string', 'min:8', 'confirmed'],
        'company'  => ['required', 'string', 'max:120'], // added
    ]);
}

protected function create(array $data)
{
    return User::create([
        'name'     => $data['name'],
        'email'    => $data['email'],
        'password' => Hash::make($data['password']),
        'company'  => $data['company'], // added
    ]);
}

Keep the extension inside create() rather than in an observer — it keeps the flow readable when someone audits the auth path later, which is the whole point of owning the stubs.

Post-login routing per role. Override redirectTo() in LoginController rather than juggling $redirectTo properties and middleware. It's the seam designed for this:

protected function redirectTo()
{
    return auth()->user()->isAdmin()
        ? route('admin.dashboard')
        : route('dashboard');
}

Wiring middleware and guards. If you need custom middleware on the auth routes (verified, throttle, role checks), do it in routes/web.php around the package's route registration rather than by re-registering routes. Group them explicitly so the route table stays readable:

Auth::routes(['verify' => true]);

Route::middleware(['auth', 'verified'])->group(function () {
    Route::get('/home', [HomeController::class, 'index']);
});

Publishing alongside, not over. When migrating an app that already has hand-rolled auth, publish this package's stubs into place next to your existing controllers. Reconcile routes, then cut over one flow at a time — login, then reset, then registration, then verification. Keep the old route registration behind a config flag so rollback is a one-line change rather than a revert commit.

Version pinning. Pin the Laravel major in composer.json and commit the lockfile. Because the stubs are copied in, the package's constraints no longer protect you after publish — the lockfile and your own CI are the only guardrail against drift.

Gotchas and Tips

Routing is the first trap. Laravel UI–derived packages differ on whether they auto-register routes or expect Auth::routes() in your web.php. Confirm with php artisan route:list before writing any controller code. If /login is not in the table, that's the gap — not a broken install.

The stubs are yours the moment you publish — including the patch obligation. There is no upstream security channel that reaches published code. Login, password reset, token generation, and session invalidation all need an owner. Treat these four files as security-sensitive and review them explicitly at adoption and after every Laravel major bump. CVE-adjacent fixes will not arrive on their own.

Silent breakage on Laravel upgrades. The nastiest failure mode is stubs that still compile but no longer match the framework's expectations — reset token handling, password reset table naming (password_resets → password_reset_tokens), and Blade syntax shifts between Laravel 8 and 11 are all live risks. After any major upgrade, exercise the full registration → verify → reset → login loop manually before trusting green CI.

Check the defaults you'd otherwise assume. Confirm explicitly whether login throttling, email verification, password confirmation, and 2FA are present in the published stubs. Forks of Laravel UI frequently omit throttling. If it's missing, add throttle: middleware to the login and reset routes — it's small, it's your responsibility, and its absence is a real vulnerability, not a style point.

User enumeration. Laravel UI's default login error ("These credentials do not match our records") is uniform, but any customization you make to the login flow can leak whether an email exists. Keep the login failure message identical for unknown-email and wrong-password, and check that your registration unique:users validation error isn't exposing the same information.

Validate the intended redirect. The redirect()->intended() pattern reads a URL from the session populated by the unauthenticated middleware. If you customize redirect handling, validate that the intended URL is local (url()->isValidUrl() against the app URL) — open redirects here are quiet and easy to ship.

Guard and middleware alignment. Mismatches between the package's assumed middleware aliases and your config/auth.php guard names surface as logout loops or "too many redirects" errors that look like infrastructure failures. Before blaming the session driver, run php artisan route:list --columns=middleware and confirm the auth middleware on each route matches your guard.

Blade view collisions. The published views land in resources/views/auth/. If your design system already has files there (or your app uses Tailwind/Bootstrap and the stubs assume the other), you'll silently shadow or be shadowed. Publish to a scratch namespace if you need to compare before overwriting.

Extension points worth knowing. The controller traits (AuthenticatesUsers, RegistersUsers, ResetsPasswords) are the intended extension surface — override the method, don't fork the trait. If you need behavior that requires editing the trait itself, you're past the package's design and should just write the controller.

Scale levers are application-side. Session store choice, an index on users.email, rate limiting on login and reset, and queued verification mail are all things you implement yourself. The package provides none of them and won't scale you — auth throughput is rarely the bottleneck anyway, but the index and throttling are non-negotiable once you have real traffic.

Debugging checklist for "login doesn't work": users table exists and has the expected columns → route:list shows POST /login → guard in config/auth.php matches the one the controller uses → CSRF token is present in the form → session driver is writable. Roughly 90% of issues resolve at steps one through three.

Fork into your repo deliberately. If you intend to depend on the package long-term, do the math: zero dependents and a single-maintainer model mean the bus factor is one. Vendoring the stubs and deleting the dependency is often the honest move — you already own the code after publish.