Auth Laravel Package

Getting Started

Install and register

composer require webman-tech/auth

Webman plugins ship their config under config/plugin/<vendor>/<name>/. After install, if the directory doesn't exist, run the plugin's install command (typically php webman plugin:install webman-tech/auth or simply restart and let webman/console copy it). Then add nothing to config/plugin/webman/app.php beyond what the package documents — most webman-tech/* packages auto-register their service provider.

Where to look first

1. config/plugin/webman-tech/auth/ — this is the real API surface. Guard definitions, driver choice (session/token/JWT), user provider/model class, and the login/logout route whitelist all live here.
2. The middleware class shipped by the plugin — grep the package for Middleware in vendor/webman-tech/auth/src. This tells you exactly what gets injected into the request and what happens on failure (redirect vs. 401 JSON).
3. The Auth manager/facade — usually a static or container-resolved entry point (Auth::guard(), Auth::user(), Auth::check()). Read its public methods before writing any glue code; most of what you'd hand-roll already exists.

First use case

Protect a controller behind a login wall and read the current user:

// config/route.php (or app/route/*.php)
Route::group('/api/admin', function () {
    Route::get('/profile', [App\Controller\AdminController::class, 'profile']);
})->middleware([WebmanTech\Auth\Middleware\Authenticate::class]);

// in the controller
public function profile(Request $request)
{
    $user = Auth::user();          // resolved user object or null
    return json(['id' => $user->id, 'name' => $user->name]);
}

That single middleware + Auth::user() call is 80% of what you'll ever need from this package.

Implementation Patterns

Route-group middleware, not per-controller annotations. Webman middleware is cheap and composable; apply Authenticate at the group level and keep controllers free of guard logic. Put public endpoints (login, register, health) in a separate group without the middleware — do not try to maintain a skip-list inside the middleware.

Two-tier protection. Combine the authentication middleware with an authorization check:

Route::group('/api/admin', function () {
    Route::get('/users', [UserController::class, 'index']);
})->middleware([
    WebmanTech\Auth\Middleware\Authenticate::class,
    App\Middleware\RequireRole::class,   // your own, thin wrapper
]);

Keep your own RequireRole middleware thin — it should call Auth::user()->can(...) (or the package's permission helper) and throw/return a 403. Resist putting role strings in route definitions; you'll want them in DB/config eventually.

Request-scoped user caching. In Webman, a worker handles many requests sequentially, so Auth::user() should be memoized per request and reset between them. Verify this by logging in as user A, then issuing a request as user B on the same worker (use php start.php start without reload to simulate). If you see user bleed, you've got a stale singleton — this is the single most important thing to check before shipping.

Login/logout flow. Centralize token/session creation in a small service, not in the controller:

class LoginService
{
    public function attempt(string $account, string $password): ?string
    {
        $user = User::where('account', $account)->first();
        if (!$user || !password_verify($password, $user->password)) {
            return null;
        }
        return Auth::guard()->login($user);   // returns token or sets session
    }
}

This keeps the "how do I authenticate" question out of HTTP handlers and makes it reusable for CLI commands (seeding, impersonation, tests).

Multi-guard for admin vs. app users. If the package supports multiple guards, define them in the plugin config with distinct user providers and distinct middleware instances. Webman has no notion of a "guard" beyond what you configure, so give each guard a named middleware (AuthenticateAdmin, AuthenticateApp) rather than passing guard names to the package middleware — it's clearer at the route level.

Testing. Because the plugin resolves the user through a manager, you can usually stub it in a test bootstrap by binding a fake user to the container before dispatching the request. If that's not exposed, wrap Auth::user() in your own CurrentUser service and fake that — you'll want the indirection anyway when you migrate auth approaches.

Gotchas and Tips

Restart required after config changes. Webman loads plugin config at worker boot. Editing config/plugin/webman-tech/auth/*.php while running does nothing until php start.php restart (a plain reload is often enough but not guaranteed for plugin configs). Budget for this every time you're tuning guards.

Request-scoped state in a long-running process. Any static $user cache inside the package, or a singleton you register yourself, lives for the lifetime of the worker. If logout doesn't actually log out, or a request shows the previous user, this is the cause. Look for a reset()/clear() call the plugin makes at request boundaries and confirm it's wired into the middleware order.

Middleware ordering matters. Webman runs middleware outside-in for the request and inside-out for the response. If your CORS middleware sits after Authenticate, preflight OPTIONS requests get 401'd before CORS headers are emitted. Registration order in config/middleware.php (global) is your lever.

Return-shape on auth failure. Out of the box the middleware may redirect (web) or return 401 JSON (API). For an API-only project, confirm the failure response is JSON and matches your error envelope — otherwise every unauthenticated call returns an HTML redirect body and your frontend blows up on JSON.parse. Override via a custom exception handler or the package's exception mapping config if exposed.

Token expiry and clock skew. If a token driver is in play, expiry checks happen server-side against PHP's clock. In containers with drifted clocks (or when testing near the boundary), you'll get sporadic 401s. Use a small leeway if the config exposes it; if not, keep token TTLs comfortably above your request timeout.

Low-maintenance dependency — pin it. The package is small and low-traffic. Pin the minor version in composer.json ("webman-tech/auth": "~1.0" rather than ^1.0) and read the diff on every update; you're unlikely to get a security advisory notification for a package this size. Also check that its supported Webman version matches yours before upgrading Webman itself.

Extension points worth knowing. Most webman-tech packages are written to be replaced rather than patched: expect a user-provider interface (swap for a different model or an external identity service) and a guard/driver interface (swap for JWT, session, or a remote call). If you find yourself editing a file under vendor/, stop — either the binding is configurable or you should write your own thin middleware and drop the package's.

Debugging checklist for "why is this user null".

1. Is the middleware actually attached? Log inside it.
2. Did the guard resolve? Log Auth::guard()->getName() (or equivalent).
3. Did the provider find the user? Log the identifier being looked up.
4. Is the token/session cookie reaching the app? Check $request->cookie() / headers — reverse proxies and SameSite settings are frequent culprits.