User Module Laravel Package

Getting Started

Know what you're installing first. This is not a Composer package you require into a fresh Laravel app. It is a module of the AsgardCMS platform and its canonical home is AsgardCMS/Platform. The idavoll/user-module repo is a read-only pointer. Day-to-day, you get this module by cloning the AsgardCMS platform and enabling the module — you do not add it standalone.

Minimum viable path:

1. Install the platform, not the module. composer create-project asgardcms/platform myapp (or whatever version your project pins). The User module ships inside the platform's Modules/User directory.
2. Enable it via config/modules.php (or the AsgardCMS module publish step) so its service provider, routes, and migrations are registered. Then run php artisan module:migrate User followed by php artisan module:publish User to push views/config into the app if you need to override them.
3. Seed the first user. The module provides registration routes, but for admin work you usually create the first account with php artisan db:seed against the module's user seeder, or via php artisan asgard:user:create if available in your platform version.
4. Log in and inspect the admin surface. The user CRUD, roles, and permissions live at /backend (or your configured admin prefix) under the "Users" and "Roles" menu entries registered by the module's menu service provider.
5. Read the source, not the docs. There is no documentation. The README is one line redirecting you to AsgardCMS/Platform. Your first reference is Modules/User/Providers/UserServiceProvider.php, then Modules/User/Http/routes.php, then the migrations under Modules/User/Database/Migrations/. That order tells you what's registered, what's routed, and what's persisted — the three things you'll touch most.

First use case to get working: the profile edit flow. Hit /profile (or the module-provided route), edit your name/email, save. Trace that request through UserController → UserRepository → EloquentUser. If that works end to end, the module is wired correctly and you can start extending.

First thing to verify before touching anything: the exact AsgardCMS/Platform version your app pins. The module's migrations, guard config, and route names differ across versions, and there is no changelog here to tell you which. Check composer.json at the platform root, then cross-reference the module's git ref.

Implementation Patterns

Extending the User model. The module provides an EloquentUser class. The supported day-to-day pattern is to extend it, not replace it — add fields via a new migration in your app's own module or app/ namespace, then override the repository or bind your own UserInterface implementation in a service provider. Do not edit files in Modules/User directly; you'll lose it on every platform update.

Repository binding pattern. The module resolves Idavoll\User\Repositories\UserRepository through the container. If you need a custom query (e.g. scoping users to a tenant), the pattern is:

• Create App\Repositories\TenantUserRepository implementing the same contract.
• Bind it in a ModuleServiceProvider (or AppServiceProvider) with $this->app->bind(UserRepositoryInterface::class, TenantUserRepository::class).
• Never monkeypatch the module's own repository class.

Roles and permissions. The module registers roles/permissions with the platform's Sentinel (or Sentry, depending on version) integration. Day-to-day usage:

• Define permissions in your module's permissions.php config or within its service provider's registerPermissions() — not in the User module itself.
• Assign roles from the admin UI, or programmatically via Sentinel::findRoleByName('admin')->users()->attach($user).
• For frontend gating, use the module's Blade directives (often @if(Sentinel::check()) style, not Gate/Policy). Modern Laravel Gate and Policy are not the native pattern here — you can add them on top, but the module won't call them.

Publishing a view override. For any profile or admin view you want to restyle:

php artisan module:publish User

This drops the Blade files into public/modules/user/ or resources/views/modules/user/ (version-dependent). Edit the published copy, never the source. The module's service provider registers a view namespace (user::), so view('user::profile.edit') resolves to your published override first.

Admin CRUD extension. To add a field to the admin user form:

1. Add the column via migration (in your app, not the module).
2. Publish views (module:publish User again).
3. Edit admin/users/edit.blade.php and admin/users/create.blade.php.
4. Add the field to the module's User transformer and to the $fillable array of your extended model — not the module's EloquentUser.
5. Validate in a FormRequest you register via the module's route group, or override the controller's rules() through a subclass.

Route customization pattern. The module registers routes under /backend/user* and /auth/* (login, register, reset). If you need them elsewhere, the day-to-day approach is to register your own route group in a bootstrapped service provider before the module's and mark the module's as disabled via the module config. Do not edit the module's routes.php.

Integration with sibling modules. The User module references Media (avatars) and Setting (config). When adding avatar upload, wire through the Media module's repository — do not upload directly. This coupling is why the module can't be lifted out on its own.

Gotchas and Tips

No install path without the platform. Trying to composer require idavoll/user-module into a modern Laravel app will fail on version constraints, and even if you force it in, the service provider expects AsgardCMS's module loader, its asset pipeline, and its Menu/Dashboard contracts. If you're not inside AsgardCMS, stop — you're evaluating a platform fragment, not a package.

PHP/Laravel version ceiling. This code targets PHP 5.x/7.0 and Laravel 4.2–5.x. Do not attempt to mix it into PHP 8.1+ / Laravel 9+ without a full audit. The auth guard signatures, bcrypt() usage, and password-reset token handling all predate current contracts. Modern Laravel will either break outright or silently misbehave on security-sensitive paths.

License is NOASSERTION. Before you write a single line of production code, get legal to read the literal LICENSE file on the AsgardCMS/Platform repo. NOASSERTION means the SPDX scanner found text it couldn't classify — it is not a grant. For an auth module, that's a compliance blocker, not a nuisance.

No upstream support when auth breaks. Read-only repo means no security patches, no CVE responses, no dependency bumps. Every fix is your fork. If you're going to run this in production, budget for a named internal owner and an auth incident runbook before go-live. There is no Stack Overflow corpus, no blog posts, no dependent projects to consult during an incident.

Zero dependents means zero compatibility evidence. Nothing you read online about this module working has been validated in years. Every migration, every service provider signature, every published view path must be verified against your platform version — not the latest, not the docs', your pinned one.

Mass-assignment on role fields is a real risk. Audit the admin user create/edit flow before exposing it. Older Laravel-era modules frequently passed role IDs through $request->all() into a Sentinel Role::users()->attach(). If you find that, add explicit validation and a policy check.

Password reset token handling. Verify the reset token generation, expiry, and single-use behaviour in Modules/User/Http/Controllers/Auth/PasswordController.php (path will vary by version). Legacy modules have historically shipped with reusable tokens or tokens not bound to the user's current email. Test this explicitly — it's the single most common auth vulnerability in modules of this vintage.

Debugging auth failures. Errors surface in three places: the module's service provider boot (registration/routes), the config/auth.php guard definition (must still point at the Sentinel guard, not the default Laravel web guard), and the session driver (legacy modules assume file-based sessions). If login "works" but the user isn't authenticated on the next request, check the guard binding first — the container has likely resolved the wrong UserProvider.

Permission checks hit the database per request. The module's Sentinel::check()/hasAccess() calls are not cached by default. If traffic grows, wrap permission resolution in a request-scoped cache or a dedicated cache decorator. Verify the invalidation story before adding the cache — legacy modules rarely ship one.

Fork provenance matters if you patch. If you must modify the module (and eventually you will), do not fork from this read-only repo. Fork from AsgardCMS/Platform, record the exact commit SHA in your composer.json as a dev-<branch>#<sha> constraint, and vendor it under an internal namespace so upgrades are explicit, not accidental.

Extension points, ranked by safety:

1. Your own service provider binding interface overrides (safest).
2. Publishing and editing views (safe — the platform re-publishes cleanly).
3. Extending EloquentUser and adding migrations (safe).
4. Subclassing controllers (acceptable, but keep the parent's route registration).
5. Editing Modules/User/ in place (never — platform updates will clobber it, and you lose the ability to reason about what's "the module" versus "our code").

When to abandon the module instead. If the target is greenfield, if the target stack is Laravel 8+, if MFA/OIDC/passkeys are on the roadmap, or if the license cannot be resolved — the correct leverage is: read the module's schema and role/permission wiring as a reference, then reimplement on Laravel Breeze/Jetstream + spatie/laravel-permission. The data model is small and portable. The code is not. Mining the patterns is the only long-term-safe way to "use" this repository.