README

Laravel MultiPersona is a lightweight context-layer system for Laravel users.

Laravel MultiPersona is a lightweight context-layer system for Laravel users.
It allows a single user to switch between different roles, accounts, or tenants dynamically, without creating multiple logins or sessions.

🔍 What It Solves

Switch between "personas" (admin ↔ client, company A ↔ company B)
Contextual permissions and role handling
No UI or API enforced – 100% backend, policy, and middleware-driven

📦 Installation

composer require grazulex/laravel-multipersona

🧩 Core Concepts

Persona: A context attached to a user (e.g. company, role, project)
Active Persona: The currently selected context
Persona Manager: A service to query, switch, or manipulate personas
Middleware: Force or apply a persona context

✅ Quick Example

// Get current active persona
$currentPersona = persona();

// List all user personas
$userPersonas = auth()->user()->personas;

// Create a new persona
$persona = auth()->user()->createPersona([
    'name' => 'Company Admin',
    'context' => [
        'role' => 'admin',
        'company_id' => 123,
        'permissions' => ['read', 'write', 'delete']
    ]
]);

// Switch to persona
auth()->user()->switchToPersona($persona);

🧱 What's Provided

Trait: HasPersonas for your User model
Middleware: EnsureActivePersona, SetPersonaFromRequest
Helpers: persona(), personas($user)
Events: Complete event system for persona lifecycle
Service: PersonaManager for programmatic access
Contract: PersonaInterface for custom implementations

❌ What's Not Included

No routes or controllers
No CLI or HTTP APIs
No UI layer – you choose how to expose it

📚 Complete Documentation

Getting Started

📖 Installation Guide - Complete setup instructions
� Usage Guide - Basic and advanced usage examples
⚡ Quick Start Example - Working code examples

Core Features

🎭 Events Guide - Event system and listeners
🛡️ Middleware Guide - Route protection and context
🏗️ Architecture - System design and components

Advanced Topics

🎯 Advanced Patterns - Multi-tenant, role hierarchy, delegation
🌐 Frontend Integration - Vue.js, React, Alpine.js examples
📋 API Reference - Complete method documentation

Use Cases

Multi-tenant SaaS: Users switch between different company contexts
Role-based Access: Same user, different permissions per context
Agency Management: Manage multiple client accounts
Marketplace Platforms: Buyer/seller context switching
Enterprise Systems: Department or project-based access

🎯 Real-World Examples

Multi-tenant Application

// User switches between companies
$companyA = $user->createPersona([
    'name' => 'Acme Corp Admin',
    'context' => [
        'company_id' => 1,
        'role' => 'admin',
        'permissions' => ['manage_users', 'view_reports']
    ]
]);

$companyB = $user->createPersona([
    'name' => 'TechStart User', 
    'context' => [
        'company_id' => 2,
        'role' => 'user',
        'permissions' => ['view_dashboard']
    ]
]);

Middleware Protection

// Protect routes requiring specific roles
Route::middleware(['auth', 'persona.required', 'role:admin'])->group(function () {
    Route::get('/admin/dashboard', [AdminController::class, 'dashboard']);
});

Frontend Integration

<!-- Vue.js component -->
<PersonaSelector 
    :current-persona="currentPersona"
    :available-personas="availablePersonas"
    @persona-changed="handlePersonaChange"
/>

🧪 Testing

The package includes comprehensive test coverage:

composer test

Current test metrics:

58 tests across Unit, Feature, Integration, and Listeners
87% code coverage
149 assertions ensuring reliability

🤝 Contributing

We welcome contributions! See our Contributing Guide for details.

Development Setup

git clone https://github.com/grazulex/laravel-multipersona.git
cd laravel-multipersona
composer install
composer test

🔒 Security

If you discover any security vulnerabilities, please review our Security Policy.

📄 License

Laravel MultiPersona is open-sourced software licensed under the MIT license.

Made with ❤️ for the Laravel community

📖 Documentation • 🐛 Report Issues • 💬 Discussions

grazulex / laravel-multipersona

Maintainers

Details