README

Laravel 11 package for user management, authentication, authorization (roles & permissions), and user profiles.

Requirements

Laravel: 11.x
PHP: 8.2+
Database: MySQL 5.7+ or MariaDB 10.3+

Dependencies

This package requires the following packages:

Package	Version	Purpose
`laravel/sanctum`	^4.0	API authentication
`intervention/image`	^3.0	Image processing (avatars, uploads)
`intervention/image-laravel`	^1.0	Laravel integration for Intervention Image
`laravel/ui`	^4.0	Authentication scaffolding
`laravel/socialite`	^5.0	Social authentication (optional)

Installation

1. Install the package

composer require properos/laravel-users

2. Publish configuration files

php artisan vendor:publish --provider="Properos\Users\UsersServiceProvider"

3. Run migrations

php artisan migrate

This will create the following tables:

users
user_addresses
user_profiles
roles
permissions
user_roles
user_permissions
role_permissions
api_credentials
user_activity_logs

4. Run seeders (optional)

Add the following to database/seeders/DatabaseSeeder.php:

use Properos\Users\Database\Seeders\RolesPermissionsTableSeeder;
use Properos\Users\Database\Seeders\UsersTableSeeder;

public function run(): void
{
    $this->call([
        RolesPermissionsTableSeeder::class,
        UsersTableSeeder::class,
    ]);
}

Then run:

php artisan db:seed

Configuration

1. Database Configuration

In config/database.php, ensure MySQL configuration uses:

'mysql' => [
    'driver' => 'mysql',
    'host' => env('DB_HOST', '127.0.0.1'),
    'port' => env('DB_PORT', '3306'),
    'database' => env('DB_DATABASE', 'forge'),
    'username' => env('DB_USERNAME', 'forge'),
    'password' => env('DB_PASSWORD', ''),
    'unix_socket' => env('DB_SOCKET', ''),
    'charset' => 'utf8',
    'collation' => 'utf8_general_ci',
    'prefix' => '',
    'strict' => true,
    'engine' => 'InnoDB',
],

2. Authentication Configuration

In config/auth.php, update the guards and providers:

'guards' => [
    'web' => [
        'driver' => 'session',
        'provider' => 'users',
    ],

    'api' => [
        'driver' => 'sanctum',
        'provider' => 'users',
    ],
],

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

3. Service Providers

In config/app.php, add to the providers array:

Laravel\Socialite\SocialiteServiceProvider::class,

4. Middleware Registration

In app/Http/Kernel.php, register the middleware:

'role' => \Properos\Users\Middlewares\RoleMiddleware::class,
'permission' => \Properos\Users\Middlewares\PermissionMiddleware::class,
'role_or_permission' => \Properos\Users\Middlewares\RoleOrPermissionMiddleware::class,

5. Social Authentication (Optional)

If you want to enable social authentication (Facebook, Google), install Socialite:

composer require laravel/socialite

Add to config/services.php:

'facebook' => [
    'client_id' => env('FACEBOOK_CLIENT_ID'),
    'client_secret' => env('FACEBOOK_CLIENT_SECRET'),
    'redirect' => env('FACEBOOK_CALLBACK', 'http://your-app.com/auth/facebook/callback')
],

'google' => [
    'client_id' => env('GOOGLE_CLIENT_ID'),
    'client_secret' => env('GOOGLE_CLIENT_SECRET'),
    'redirect' => env('GOOGLE_CALLBACK', 'http://your-app.com/auth/google/callback')
],

Add to your .env:

FACEBOOK_CLIENT_ID=your-app-id
FACEBOOK_CLIENT_SECRET=your-app-secret
FACEBOOK_CALLBACK=http://your-app.com/auth/facebook/callback

GOOGLE_CLIENT_ID=your-app-id
GOOGLE_CLIENT_SECRET=your-app-secret
GOOGLE_CALLBACK=http://your-app.com/auth/google/callback

6. Environment Variables

Add to your .env:

# Laravel Mix / Vite
MIX_PUSHER_APP_KEY="${PUSHER_APP_KEY}"
MIX_PUSHER_APP_CLUSTER="${PUSHER_APP_CLUSTER}"

MIX_HOST="${DOMAIN}"
MIX_API_BASE_URL=
MIX_CDN_URL=

MIX_ADMIN_WEB_PREFIX='/admin'
MIX_ADMIN_WEB_API_PREFIX='/api/admin'

Asset Compilation

1. Install npm dependencies

npm install
npm install moment --save

2. Configure webpack.mix.js

Add to webpack.mix.js:

.js('resources/assets/js/be/modules/users/js/user.js', 'public/be/js/modules/user.js')

3. Configure bootstrap.js

In resources/assets/bootstrap.js, add:

import Helpers from './misc/helpers'

window.moment = require('moment')
window.Vue = require('vue');
window.Helpers = Helpers;

4. Compile assets

npm run watch
# or
npm run prod

Usage

Using Models

use Properos\Users\Models\User;
use Properos\Users\Models\Role;
use Properos\Users\Models\Permission;

// Get all users
$users = User::all();

// Find user by ID
$user = User::find(1);

// Get user roles
$roles = $user->roles;

// Get user permissions
$permissions = $user->permissions;

Using Routes

Add to routes/web.php:

use Illuminate\Support\Facades\Route;

Route::get('/admin/dashboard', function(){
    return view('be.index');
})->middleware(['auth', 'role:admin']);

Route::get('/admin/users', [UserController::class, 'index'])
    ->middleware(['auth', 'permission:users.view']);

Using Middleware

// Role-based
Route::middleware(['role:admin'])->group(function () {
    // Admin only routes
});

// Permission-based
Route::middleware(['permission:users.edit'])->group(function () {
    // Users edit only routes
});

// Role OR Permission
Route::middleware(['role_or_permission:super-admin'])->group(function () {
    // Routes accessible by super-admin role OR super-admin permission
});

Using Classes

use Properos\Users\Classes\CUser;

$cuser = new CUser();

// Create user
$user = $cuser->create([
    'firstname' => 'John',
    'lastname' => 'Doe',
    'email' => 'john@example.com',
    'password' => 'password123',
    'avatar' => $uploadedFile // Optional UploadedFile
]);

// Assign role
$cuser->assignRole([
    'user_id' => $user->id,
    'role_id' => 1
]);

// Assign permission
$cuser->assignPermission([
    'user_id' => $user->id,
    'permission_id' => 1
]);

// Change password
$cuser->changePassword([
    'user_id' => $user->id,
    'password' => 'newpassword123',
    'password_confirmation' => 'newpassword123'
]);

Features

User Management

Create, read, update, delete users
User profiles and addresses
Avatar upload and processing
User activity logging

Authentication

Email/password authentication
Social authentication (Facebook, Google)
Password reset
API authentication via Sanctum

Authorization

Role-based access control (RBAC)
Permission-based access control
Flexible role/permission assignment
Middleware for route protection

User Profile

First name, last name, email, phone
Company information
Avatar management
Address management

Activity Logging

Automatic user activity tracking
Login/logout logging
Custom action logging

Troubleshooting

Migration errors

If you get migration errors about duplicate tables:

php artisan migrate:rollback --step=1
# Then check if tables exist and drop them if needed
php artisan migrate

Service provider not found

Make sure the service provider is registered in config/app.php:

Properos\Users\UsersServiceProvider::class,

Middleware not working

Ensure middleware is registered in app/Http/Kernel.php with the correct aliases.

Image upload not working

Check that intervention/image and intervention/image-laravel are installed
Ensure the public disk is configured in config/filesystems.php
Check file permissions on storage/app/public

Vue components not rendering

Ensure assets are compiled: npm run prod
Check that webpack.mix.js is configured correctly
Verify that bootstrap.js includes the required dependencies

Sanctum authentication not working

Ensure laravel/sanctum is installed
Run php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
Add Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful to app/Http/Kernel.php
Configure stateful domains in config/sanctum.php

Breaking Changes from Previous Versions

Laravel Version: Requires Laravel 11.x (minimum)
PHP Version: Requires PHP 8.2+
Intervention Image: Updated to v3 with new API
Database Collation: Default collation is now utf8_general_ci

License

MIT License. See LICENSE file for details.

properos / laravel-users

Maintainers

Package info

Statistics

Security