Manage Laravel user accounts with configurable access, views, roles, email, avatars, and account settings.

• Framework Support
• Requirements
• Installation
• Quick Start
• Features
• Configuration
• Changing Frameworks
• Artisan Commands
  • Install Options
• Routes
• Optional Integrations
  • Packages That Work Together
  • Related Package
• Project Layout
• Testing
• Documentation
• Screenshots
  • Mobile
  • Tablet
  • Desktop
• License

This release supports Blade with Bootstrap 4 and Bootstrap 5. Bootstrap 4 remains the default for existing applications. Switching CSS preserves routes, authentication, models, configuration, and published custom views.

Only Blade and the two Bootstrap choices are offered by the release installer. Deferred CSS frameworks and application runtimes are tracked separately in the roadmap, with release dates and order still to be determined.

The package's documented compatibility suite covers Laravel 8 through 13, with framework and PHP versions paired in the CI matrix. Older Laravel applications should use a package version compatible with their framework and PHP runtime. See framework setup and commands.

• PHP 8.1 or newer.
• Laravel 8 or newer, with compatibility validated against the versions in the CI matrix.
• An existing application user model, users table, and authentication guard.
• Composer.

The package does not create or alter the host users table, add an authentication system, or grant administrator access. Optional features may require their own published migrations, queue worker, or cache configuration. Those features are disabled by default.

Install the package and run its setup command:

composer require jeremykenedy/laravel-users
php artisan laravelusers:install

The installer keeps Blade and Bootstrap 4 as the defaults, detects existing package configuration through the current settings, and preserves existing configuration and published views. It offers settings for Bootstrap CSS, theme, view publishing, avatars, notifications, and optional integrations. Use --no-interaction for scripted setup. Review the installation and update guide before enabling optional migrations or package changes.

The original publish command remains available:

php artisan vendor:publish --tag=laravelusers

The package also provides php artisan laravelusers:publish, with laravel-users:publish as an alias. It publishes configuration, translations, views, and versioned assets in public/vendor/laravelusers/ while preserving existing host files. Install and update also publish these assets. The bundled templates do not depend on Laravel Collective HTML. If you have custom published views, check them for their own form-builder calls before removing a host application's dependency.

The default setup preserves Blade and Bootstrap 4:

php artisan laravelusers:install --frontend=blade --css=bootstrap4 --no-interaction

To use Bootstrap 5:

php artisan laravelusers:install --frontend=blade --css=bootstrap5 --no-interaction

Sign in with an account authorized by the host application's middleware, then open /users. Existing installations can use laravelusers:update with the same flags. For application-owned navigation, link to the package route:

<a href="{{ route('users') }}">Manage users</a>

See standalone navigation components for the Blade controls that can be embedded in a host layout, and the roadmap for future frontend work.

• Create, view, edit, search, sort, filter, and delete users with paginated table or card layouts.
• Preserve Bootstrap 4 and Blade by default, with Bootstrap 5 available through an explicit choice.
• Keep soft-deleted users in a separate list, with authorized restore and permanent-delete actions.
• Restrict management routes and individual actions with host middleware, gates, roles, permissions, and supported role levels.
• Integrate optionally with Laravel Roles, Spatie Laravel Permission, and compatible custom role models.
• Track latest login time, IP address, device, operating system, browser, and recent online status when enabled.
• Select global or per-user avatar sources, including initials, local generators, Gravatar, DiceBear, and host-provided images.
• Send customizable welcome, password reset, account recovery, goodbye, and custom emails, individually or in bulk.
• Set global welcome-email defaults and enable or disable welcome actions from the administrator settings page.
• Preview email content before sending and retain edits when returning to the composer.
• Configure password strength rules and confirmation feedback for account creation and editing.
• Customize independent light/dark card colors, gradient highlight colors and strength, with inherited per-user overrides.
• Choose inline alerts, installed Laravel Toast notifications, or both, with configurable Toast behavior.
• Preview unsaved notification choices in the browser before saving settings.
• Use consistent page icons, headers, tabs, and content width across the Bootstrap interfaces.
• Install, configure, and remove supported optional packages through authorized settings controls with worker verification and visible progress.
• Add a signed-in account page with profile, avatar, appearance, email, password, and account-removal controls.
• Use the theme toggle and user menu as standalone Blade components.
• Impersonate another account with role-based authorization, expiring sessions, verified state, and an exit control when explicitly enabled.
• Keep new account settings, cleanup, activity, and package-management features disabled unless explicitly enabled.

See configuration and the individual feature guides for defaults, requirements, and upgrade notes.

The package configuration is src/config/laravelusers.php. Existing installations retain Bootstrap 4 and existing option defaults. Every configuration option supports its documented LARAVEL_USERS_* environment variable fallback. The detailed configuration reference is maintained in docs/configuration.md.

The settings page is separately enabled with a migration and a host-defined authorization gate. Optional activity, account settings, per-user avatars, per-user appearance, deleted-account links, cleanup, Toast notifications, and managed package changes each have separate requirements. Do not enable them before reviewing settings and access rules, activity, and integrations.

Bootstrap 4 remains the default. Use laravelusers:update for interactive setup or explicit flags. It preserves the main config file and existing custom view overrides:

php artisan config:clear
php artisan laravelusers:update
php artisan laravelusers:update --frontend=blade --css=bootstrap5 --theme=system --no-interaction
php artisan config:cache

For a direct change without prompts, use laravelusers:switch:

php artisan laravelusers:switch --css=bootstrap4
php artisan laravelusers:switch --framework=bootstrap4 --theme=light

The commands publish compiled package CSS and runtime assets automatically. Run npm run build after switching if your host application imports or modifies its own assets; the bundled screens do not require a host Node build. Existing host overrides take precedence. Read upgrading and rollback before replacing published views.

Install, update, and switch share flags for runtimes, CSS, views, themes, role package selection, avatars, Toast, and optional setup tasks. Both laravelusers:* and laravel-users:* spellings are available for those commands. These three commands publish versioned assets and register the impersonation-state guard in an existing host web routes file. The full option list, publishing safeguards, queue setup, and safe removal steps are in Artisan commands.

Optional package installation and migration flags are documented in the complete command reference.

The package provides /users for the directory, /users/deleted for soft-deleted accounts, /users/settings for optional global settings, and /users/account for the signed-in account page. Account recovery links use /users/account-link/{token} when enabled. The complete route names, methods, middleware, and feature requirements are in docs/routes.md.

Management routes use authentication and the configured package middleware. Authentication by itself does not grant administrator authorization. Configure a role middleware, a gate, or explicit access rules before exposing user management to ordinary signed-in accounts. The package prevents deleting the current authenticated user through its management actions.

The package has no required Laravel Collective HTML or roles package dependency. Supported optional integrations include Laravel Roles, Spatie Laravel Permission, Laravel Toast, local DiceBear libraries, and host-provided avatar, UI, dark-mode, IP-capture, and seed services.

The install and update commands can show setup instructions and configure supported optional packages. The settings page can manage package installation or removal only when the queue, worker, cache, and authorization requirements are met. A second roles package cannot be installed alongside an already detected roles integration. Read integrations, roles, and package settings before making dependency changes.

Laravel Users fits into a collection of focused Laravel packages. Choose the parts your application needs; all of the integrations below are optional.

Spatie Laravel Permission is an alternative role integration. Official dicebear/core and dicebear/styles libraries provide optional local avatars. Required runtime dependencies are PHP-Parser, for preserving host routes during setup, and UA Parser, for optional device and browser details.

Laravel Notifications adds an in-app notification center with bell and badge controls, read/unread tracking, mark-all-read, deletion, and a REST API. It complements Toast's immediate feedback when your application needs a place to keep and revisit notifications. It is a separate host integration; Laravel Users does not currently install it or send notices to its notification center automatically.

src/
  Actions/                 Account, email, and user operations
  App/Http/                Controllers, middleware, and requests
  App/Console/Commands/    Install, update, switch and publish commands
  Console/                 Compatible command classes and maintenance commands
  Support/                 Package integrations and configuration
  database/                Opt-in package migrations
  resources/assets/        Compiled CSS, runtime scripts and license notices
  resources/views/         Blade screens, components, and email templates
  routes/                  Package routes
docs/                      Setup, feature, and upgrade guides
art/                       Theme banners and browser screenshots
tests/                     Feature, integration, and browser tests
phpunit.xml                Tests across the supported Laravel versions
phpunit.coverage.xml       PHP coverage configuration for PHPUnit 12

Run the package checks locally:

composer validate --strict
composer check
npm ci
npm run build
npm run test:runtime
npm run test:browser

CI covers PHP and Laravel compatibility, optional roles and presentation integrations, code style, dependency audit, coverage collection, and browser tests. Browser jobs exercise Bootstrap 4 and 5 in Chromium, Firefox and WebKit. See testing and CI for the commands, matrix, and fixture details. Browser fixtures use isolated temporary databases and sample users.

PHP coverage uses phpunit.coverage.xml with PHPUnit 12 and Xdebug. It includes package logic, routes, configuration and migrations. Blade templates and generated assets are checked by the browser suite. The requested 100% coverage target has not yet been reached.

All guides are available in the docs/ folder:

• Activity tracking and online status
• Avatar sources and local generators
• Artisan commands, install, update, and package setup
• Configuration and environment variables
• Email templates, previews, expiration, and account recovery
• Optional integrations
• User impersonation and session security
• Standalone navigation components
• Roles, permissions, and middleware
• Routes and authorization
• Global settings and access rules
• Testing and CI
• Upgrade and rollback guide
• Changelog and historical versions
• Roadmap and future frontend choices
• Canonical release notes

These screenshots use sample accounts from the isolated preview application. The pages below are captured from the current Bootstrap 5 interface.

User directory

User directory	User profile

Active users	Deleted users	Create user
Edit user	Edit deleted user	User profile
Global settings	Email settings	Account settings
Notification settings	Account access settings	Cleanup settings
Optional package settings
Email preview	Account link confirmation

This package is open-sourced software licensed under the MIT license.