README

Production-ready Laravel package for building Multi-Tenant SaaS APIs with Super Admin and Tenant Admin capabilities.

Features

Multi-Tenancy

✔ Path-based tenant identification (/tenant-slug/api/...)
✔ Automatic database isolation per tenant (powered by Stancl/Tenancy)
✔ Tenant-aware caching (Redis)
✔ Tenant-specific storage (S3/local)
✔ Complete tenant isolation

Three-Level Access System

Super Admin Level - Manage all tenants, system analytics, global settings
Central Level - Authentication, tenant selection, user profile
Tenant Level - Tenant admin manages tenant resources

Authentication & Authorization

✔ Laravel Sanctum - Token-based authentication
✔ OAuth 2.0 - Google, Microsoft, LinkedIn, Facebook
✔ Laravel ARBAC - Advanced RBAC + ABAC hybrid
✔ Multi-tenant user access - Users can belong to multiple tenants
✔ Email verification & password reset

External ID System

✔ Nano ID with custom prefixes (USR_xxx, TNT_xxx, CLI_xxx)
✔ Never expose internal database IDs
✔ URL-safe, collision-resistant
✔ Automatic generation via model trait

API Standards

✔ JSON:API v1.1 compliant responses
✔ RESTful design principles
✔ API versioning (/api/v1/...)
✔ Cursor-based pagination for scalability
✔ Filtering, sorting, and including relationships

API Documentation

✔ Swagger/OpenAPI 3.0 specification
✔ Interactive API documentation (Swagger UI)
✔ Auto-generated from code annotations

System Health Monitoring

✔ Health check endpoints (/health, /ping, /version, /status)
✔ Database, Redis, Storage, Queue monitoring
✔ Performance metrics

Security

✔ Rate limiting added to all authentication endpoints (Login, Register, Password Reset)
✔ CSRF protection implemented for OAuth flows via cryptographically secure state parameters
✔ Dedicated Super Admin middleware for robust access control
✔ CORS configuration
✔ Security headers (CSP, X-Frame-Options, etc.)
✔ SQL injection prevention (Eloquent ORM)
✔ XSS protection

Performance

✔ Redis caching (tenant-aware)
✔ Database query optimization (High-performance indexes added for status, email, and plan lookups)
✔ Optimized relationships via eager loading hints
✔ Queue support for heavy operations
✔ Horizontal scalability

Requirements

PHP: 8.1 or higher
Laravel: 10.x, 11.x, or 12.x (First-class support for Laravel 12)
MySQL: 8.0+ or PostgreSQL: 13+
Redis: 6.0+ (for caching and queues)
Composer: 2.5+

PHP Extensions

BCMath, Ctype, Fileinfo, JSON, Mbstring, OpenSSL, PDO, Tokenizer, XML, cURL, Redis

Installation

# Install via Composer
composer require amrshah/tenant-engine

# Publish configuration and migrations
php artisan vendor:publish --provider="Amrshah\TenantEngine\Providers\TenantEngineServiceProvider"

# Run installation command
php artisan tenant-engine:install

The installation command will:

✔ Publish configuration files
✔ Publish and run migrations
✔ Create default roles and permissions
✔ Generate Swagger documentation
✔ Set up example tenant (optional)

🔄 Migration Guide

Upgrading to v1.0.0 (from alpha)

If you are upgrading an existing installation, follow these steps to apply the latest security and performance fixes:

Update Package:
```
composer update amrshah/tenant-engine
```
Run New Migrations (Adds performance indexes):
```
php artisan migrate
```

Refresh Configuration & Cache:

php artisan config:clear
php artisan route:clear
php artisan cache:clear

Verify Rate Limiting: Check your authentication endpoints to ensure rate limiting is active.

✔ Configuration

Add to your .env file:

# Multi-Tenant Configuration
TENANT_ENGINE_ENABLED=true
TENANT_DB_PREFIX=tenant_

# OAuth Providers (Optional)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_REDIRECT_URI="${APP_URL}/api/v1/auth/oauth/google/callback"

MICROSOFT_CLIENT_ID=your-microsoft-client-id
MICROSOFT_CLIENT_SECRET=your-microsoft-client-secret
MICROSOFT_REDIRECT_URI="${APP_URL}/api/v1/auth/oauth/microsoft/callback"

# API Configuration
API_RATE_LIMIT=1000
API_RATE_LIMIT_TENANT=10000

Quick Start

Create Super Admin

php artisan tenant-engine:create-super-admin \
    --name="Admin" \
    --email="admin@example.com" \
    --password="SecurePassword123!"

Create First Tenant

php artisan tenant-engine:tenant:create \
    --name="Acme Corporation" \
    --email="admin@acme.com" \
    --slug="acme-corp"

Access API Documentation

Navigate to:

http://localhost:8000/api/documentation

API Endpoints

Super Admin APIs

# Tenant Management
GET    /api/v1/super-admin/tenants
POST   /api/v1/super-admin/tenants
GET    /api/v1/super-admin/tenants/{tenant}
PATCH  /api/v1/super-admin/tenants/{tenant}
DELETE /api/v1/super-admin/tenants/{tenant}
POST   /api/v1/super-admin/tenants/{tenant}/suspend
POST   /api/v1/super-admin/tenants/{tenant}/activate

# System Analytics
GET    /api/v1/super-admin/analytics/overview
GET    /api/v1/super-admin/analytics/tenants
GET    /api/v1/super-admin/analytics/users

# User Impersonation
POST   /api/v1/super-admin/impersonate/{user}
POST   /api/v1/super-admin/stop-impersonation

Central APIs

# Authentication
POST   /api/v1/auth/register
POST   /api/v1/auth/login
POST   /api/v1/auth/logout
GET    /api/v1/auth/me

# OAuth
GET    /api/v1/auth/oauth/{provider}
GET    /api/v1/auth/oauth/{provider}/callback

# Tenant Selection
GET    /api/v1/tenants
POST   /api/v1/tenants/{tenant}/switch

Tenant Admin APIs

# User Management
GET    /{tenant}/api/v1/users
POST   /{tenant}/api/v1/users
GET    /{tenant}/api/v1/users/{user}
PATCH  /{tenant}/api/v1/users/{user}
DELETE /{tenant}/api/v1/users/{user}

# Role & Permission Management
GET    /{tenant}/api/v1/roles
POST   /{tenant}/api/v1/roles
GET    /{tenant}/api/v1/permissions

# Tenant Settings
GET    /{tenant}/api/v1/settings
PATCH  /{tenant}/api/v1/settings

System Health

GET    /api/v1/health    # System health check
GET    /api/v1/ping      # Simple ping
GET    /api/v1/version   # Version info
GET    /api/v1/status    # System status (authenticated)

Documentation

Testing

# Run all tests
composer test

# Run with coverage
composer test:coverage

# Run Pest tests
composer test:pest

# Run static analysis
composer analyse

# Format code
composer format

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

Security

If you discover any security-related issues, please email security@amrshah.dev instead of using the issue tracker.

License

The MIT License (MIT). Please see LICENSE for more information.

Author

Ali Raza (a.k.a Amr Shah)

GitHub: @amrshah
Email: amrshah@gmail.com
Website: amrshah.github.io

Acknowledgments

This package is built on top of excellent open-source packages:

Laravel - The PHP framework
Stancl/Tenancy - Multi-tenancy for Laravel
Laravel Sanctum - API authentication
Laravel Socialite - OAuth authentication
Laravel ARBAC - Advanced RBAC + ABAC
L5-Swagger - Swagger documentation
Nano ID - Unique ID generator

Made with ❤️ by Ali Raza (Amr Shah)

Version: 1.0.1
Last Updated: 2025-12-19

amrshah / tenant-engine

Maintainers

Details

README

Features

Multi-Tenancy

Three-Level Access System

Authentication & Authorization

External ID System

API Standards

API Documentation

System Health Monitoring

Security

Performance

Requirements

PHP Extensions

Installation

🔄 Migration Guide

Upgrading to v1.0.0 (from alpha)

✔ Configuration

Quick Start

Create Super Admin

Create First Tenant

Access API Documentation

API Endpoints

Super Admin APIs

Central APIs

Tenant Admin APIs

System Health

Documentation

Testing

Contributing

Security

License

Author

Acknowledgments