Auth Laravel Package

Getting Started

Cortex Auth is a frontend scaffolding layer that sits on top of rinvex/laravel-auth — it does not implement authentication itself, it wires up the controllers, views, routes, and middleware that let you actually use the underlying auth package in a Laravel application.

Minimal steps:

1. Require the package (and its auth backend) via Composer:

   composer require rinvex/cortex-auth rinvex/laravel-auth
   

   Because the repo is archived, pin versions explicitly in composer.json and verify the laravel/framework constraint against your app — recent Laravel versions are unlikely to resolve cleanly.

2. Publish the config and assets so you can see what the package actually ships:

   php artisan vendor:publish --provider="Rinvex\CortexAuth\Providers\CortexAuthServiceProvider"
   

   This exposes the route file, view overrides, and config (config/cortex/auth.php or similar) that control route prefixes, middleware, and namespacing.

3. Run the migrations from rinvex/laravel-auth (Cortex Auth itself adds no schema, but the backend package does). Confirm the users/roles/permissions tables exist before hitting any route.

4. Visit the registered dashboard route (default is under an /admin or configurable prefix) after seeding an admin user. That dashboard is the "first use case": a complete user-management UI — user list, role assignment, permission editing — out of the box.

Where to look first: the published config file and the package's routes/ directory. Those two files tell you everything about how the package expects to be mounted and which middleware guards its endpoints. Read laravel-auth's README too, since half the real behavior (role/permission checks, verification flows) lives there and Cortex Auth only surfaces it.

Implementation Patterns

Route customization before anything else. The package's value is its routes; its burden is that they're opinionated. In the published config you can change the URL prefix, the middleware stack (add auth, verified, can:manage-users, or a gate), and the route name prefix. Do this in a service provider's boot() method so the changes survive package updates:

config([
    'cortex.auth.route_prefix'     => 'admin/users',
    'cortex.auth.route_middleware' => ['web', 'auth', 'can:access-admin'],
]);

View overrides via namespace publishing. Don't edit vendor views. Publish them to resources/views/vendor/cortex/auth/ and Laravel's view finder will prefer your copies. This is how you rebrand the dashboard, add fields, or swap the layout — the recommended day-to-day customization path.

Extending controllers through container binding. Cortex Auth resolves its controllers through the IoC container, so you can subclass a controller (e.g. UsersController) in your app and bind it in a provider:

$this->app->bind(
    \Rinvex\CortexAuth\Http\Controllers\UsersController::class,
    \App\Http\Controllers\Admin\UsersController::class
);

Override only the methods you need (usually index, edit, update) and call parent:: for the rest. This keeps you on the package's routes and middleware while letting you inject tenant scoping, audit logging, or custom validation.

Middleware as the integration seam. In practice you rarely touch the auth logic — you wrap it. Common patterns:

• Add a can: middleware that maps to a policy/gate you define in the host app.
• Stack a tenant-resolution middleware before the package routes so all queries are scoped.
• Add an audit middleware that logs every write to the users/roles tables.

Role and permission seeding as a deploy step. Because the backend uses structured role/permission tables, treat seeding as part of deployment: a RolePermissionSeeder that recreates the expected roles (admin, user, etc.) and their abilities. This is especially important in multi-environment setups where a missing role silently breaks the admin dashboard with 403s.

Pair with the underlying auth package for anything beyond the dashboard. Login, registration, password reset, and email verification are laravel-auth features. Use laravel-auth's facades/traits directly in your own app code; treat Cortex Auth purely as the admin UI layer. Don't try to extend Cortex Auth for business auth logic.

Gotchas and Tips

Archived and unmaintained — pin everything. The repo is archived with 12 stars and zero dependents. Treat it as frozen infrastructure: commit your composer.lock, avoid ^ constraints on its Laravel dependency, and expect friction on newer Laravel releases. Budget time for a vendored fork if you must run it on Laravel 10+/11.

Route collisions. The package registers routes at boot; if your host app already has conflicting paths (e.g. a users resource), you'll get silent 404s or wrong-controller dispatch. Run php artisan route:list | grep -i cortex to confirm exactly what got registered and under which middleware. If the package's provider is ordered after your RouteServiceProvider, precedence can flip unexpectedly — adjust provider order in config/app.php or disable auto-discovery for this package.

Config caching bite. Because route/middleware changes live in config, running php artisan config:cache during deploy locks them in. If you change middleware in AppServiceProvider::boot() and use config caching, verify the change actually applied — a stale cache is the most common "my middleware isn't running" bug with this kind of package. Always clear with php artisan optimize:clear when debugging auth/route behavior.

Missing migrations produce confusing errors. Cortex Auth assumes laravel-auth migrations have run. The dashboard will load but role listings, permission checks, and user creation will fail in odd places (null role, 500 on store) if tables are missing. Check php artisan migrate:status for users, roles, permissions, and pivot tables before debugging UI.

View namespace mismatch. If you publish views and they don't pick up, check the exact namespace the controllers use (view('cortex/auth::...') vs view('cortex-auth::...')). Directory placement under resources/views/vendor/ must mirror the namespace folder exactly; a single mislabeled folder means your overrides are ignored silently.

Extending controllers has a ceiling. Binding a subclass works for public methods, but private/protected helpers and constructor-injected dependencies in the parent can't be easily swapped. For anything nontrivial, prefer "middleware + events" (e.g. listen to the underlying auth package's user-created events and enrich there) over deep subclassing.

Debugging checklist for the dashboard returning 403/500: (1) php artisan route:list, (2) confirm middleware stack includes web + your auth guard, (3) migrate:status, (4) seeded roles present, (5) config:clear and retry, (6) disable the host app's Auth::routes() if it's colliding.

Extension points worth knowing: the service provider (bindings/route config), the published views (all UI), the underlying laravel-auth traits/facades (all business auth logic), and Laravel events from the backend package (hooks for audit/side-effects). Anything else — schema changes, new controllers — you own in the host app, not the package.