README

A modern user management package for Laravel, built by Backstage.

✨ Introduction

backstage/laravel-users is a full-featured Laravel package that provides a complete user management foundation for Laravel 10 & 11 applications. It leverages Laravel Sanctum and Spatie Permissions to deliver robust authentication, authorization, and user preference handling.

This package includes support for user login tracking, traffic monitoring, preferences, factory seeding, and customizable scaffolding—all designed to scale with your application.

📦 Features

• ✅ Custom user model with Laravel Auth integration
• 🔐 Role and permission support via Spatie Laravel Permission
• 🔑 API token authentication via Laravel Sanctum
• 🔧 Configurable user system with feature toggles
• 🧪 Built-in factory and seeder
• 📊 Tracks login events and traffic history
• 🧩 Modular architecture with domain-driven design (DDD) patterns
• 🛠 Artisan commands for user management (make, list, delete)
• 📨 Email-based username generation
• 🔄 Password generation utility
• 🧠 Customizable notification & sub-navigation preferences

🧰 Requirements

• PHP ^8.2
• Laravel ^10.0 or ^11.0
• Composer

⚙️ Installation

Install via Composer:

composer require backstage/laravel-users

Publish configuration, migration, and seeder files:

php artisan vendor:publish --tag="laravel-users-config"
php artisan vendor:publish --tag="laravel-users-migrations"

Run database migrations:

php artisan migrate

🛠 Configuration

1. Set the User Provider

Update config/auth.php to use the package's custom user model:

'providers' => [
    'users' => [
        'driver' => 'eloquent',
        'model' => \Backstage\Laravel\Users\Models\User::class,
    ],
],

2. Enable Sanctum API Tokens

If you haven't already:

composer require laravel/sanctum
php artisan vendor:publish --provider="Laravel\\Sanctum\\SanctumServiceProvider"
php artisan migrate

3. Setup Spatie Permissions

Ensure Spatie permissions are published:

composer require spatie/laravel-permission
php artisan vendor:publish --provider="Spatie\\Permission\\PermissionServiceProvider"
php artisan migrate

Edit config/permission.php to adjust your roles and permission settings.

🧩 Customization

You can modify config/users.php to change:

• Default roles
• Middleware behavior
• Feature toggles (registration, email verification, etc.)
• UI scaffolding paths (if applicable)

🧑‍💻 Artisan Commands

The package includes a suite of CLI tools:

Example:

artisan make:user --email=user@example.com --name="John Doe" --role=admin

🧱 Architecture

Key Classes

• UserManager: Central config-driven service for runtime overrides
• Domain/Email/Actions:
  • GenerateUsernameFromEmail
  • ExtractDomainFromEmail
  • ValidateEmail
• Domain/Password/Actions:
  • GeneratePassword
• Eloquent/Concerns/User:
  • Modular traits like HasAttributes, HasScopes, HasRelations
• Models:
  • User, UserLogin, UserTraffic, UserNotificationPreferences

Migrations Included

• Adds sub-navigation and notification preferences to users
• Tracks user logins and traffic history
• Supports nullable password for third-party auth

🧪 Testing

Run PHPUnit tests via:

vendor/bin/phpunit

Ensure your .env.testing or phpunit.xml is configured with a test database.

🔬 Development

Local Package Development

If you're contributing or using this in a monorepo:

1. Clone the package into packages/ or your preferred folder
2. Add this to your Laravel app's composer.json:

"repositories": [
  {
    "type": "path",
    "url": "packages/laravel-users"
  }
],

1. Require the package:

composer require backstage/laravel-users:*

1. Refresh autoload:

composer dump-autoload

🤝 Contributing

Contributions are welcome! Please follow the PSR-12 coding standard and submit pull requests with clear descriptions.

📄 License

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

👤 Author

Manoj Hortulanus
Developer at Backstage
📧 manoj@backstagephp.com

🏁 Credits

• Backstage for sponsoring development
• Spatie for the excellent permission package
• Laravel for the amazing framework