Download the PHP package angelitosystems/filament-tenancy without Composer

Filament Tenancy

A comprehensive multi-tenancy package for Filament with support for multiple databases, central management, advanced logging, and performance monitoring.

Features

• 🚀 Easy Installation - Interactive installer with automatic setup
• 👥 User Management - Create and manage tenant users with roles and permissions
• 🔐 Roles & Permissions - Complete Spatie-like RBAC system for tenant access control
• 📦 Asset Sharing - Share Livewire, Filament, and custom assets from central to tenants
• 👥 Admin User Creation - Interactive admin user creation during installation
• 🗄️ Multi-database tenancy - Complete isolation between tenants
• 🎛️ Central tenant management - Unified control panel for all tenants
• ⚡ Automatic database creation and migration - Seamless tenant provisioning
• 🔄 Tenant-aware middleware - Automatic context switching
• 🎨 Filament integration - Native Filament admin panel support
• 🔐 Secure credential management - Encrypted credential storage with rotation
• 📊 Enhanced Debug Logging - Environment-aware logging with production-safe output
• 📈 Performance monitoring - Real-time metrics and connection monitoring
• 🔌 Connection pooling - Optimized database connection management
• 💳 Plans & Subscriptions - Built-in plan and subscription management
• 💳 PayPal Integration - Complete PayPal payment integration with webhooks support
• 🛡️ Database compatibility check - Automatic validation of database requirements
• 🧹 Smart error handling - Automatic retry and cleanup on connection errors
• 🌐 APP_DOMAIN Auto-Detection - Automatic domain detection from APP_URL for subdomain tenancy
• 🔧 Enhanced Tenant Creation - Interactive wizard with automatic domain configuration
• 🎨 Custom 404 Page - Beautiful personalized 404 page for tenant not found errors with Livewire component support
• ⚖️ License-Based - Future licensing model for commercial use (currently public access)

Installation

Quick Install

The easiest way to install Filament Tenancy is using the interactive installer:

The installer will:

• ✅ Check if Filament is installed and install it if needed
• ✅ Verify database compatibility (MySQL/PostgreSQL required)
• ✅ Configure database connection interactively if needed
• ✅ Publish configuration files
• ✅ Run migrations automatically
• ✅ Create default plans automatically (Basic, Premium, Enterprise)
• ✅ Register the ServiceProvider automatically
• ✅ Register middlewares automatically in bootstrap/app.php (Laravel 11) or via ServiceProvider (Laravel 10)
• ✅ Configure custom 404 page - Ask if you want to publish components and views for tenant not found errors

Manual Installation

If you prefer manual installation:

Central Database Setup

After installation, you need to set up the central database with roles and permissions for the landlord/central administration:

The central database setup includes:

• 🏛️ Central Roles & Permissions: Separate permission system for central administration
• 👑 Super Admin Role: Complete access to all central features
• 🛡️ Landlord Admin Role: Manage tenants, plans, and subscriptions
• 🎧 Support Role: Read-only access for support staff
• 👤 Central Admin User: Automatically created with Super Admin role

Central Permissions Available:

• manage tenants - Create, edit, delete tenants
• manage plans - Manage subscription plans
• manage subscriptions - Handle tenant subscriptions
• manage central users - Manage central admin users
• manage central roles - Manage central roles and permissions
• view central dashboard - Access central dashboard
• manage system settings - Configure system-wide settings
• access landlord panel - Access landlord administration panel
• manage tenant databases - Manage tenant database operations

Requirements

• PHP: 8.1 or higher
• Laravel: 10.x or 11.x
• Filament: ^4.0
• Database: MySQL 5.7+ or PostgreSQL 10+ (SQLite is not supported for multi-database tenancy)

Configuration

The package configuration is located at config/filament-tenancy.php. Key configuration options include:

Tenant Resolution

Note: The package now supports APP_DOMAIN environment variable for subdomain-based tenancy. When creating tenants with subdomains, the package will automatically detect and suggest configuring APP_DOMAIN from your APP_URL if it's not already set.

Database Configuration

Environment Variables

The package uses the following environment variables:

APP_DOMAIN: This variable is automatically detected and configured when creating tenants. If your APP_URL contains a valid domain (e.g., http://hola.test), the package will ask if you want to use it as APP_DOMAIN. This is essential for subdomain-based tenancy.

Central Domains: APP_DOMAIN is automatically considered a central domain and will not resolve tenants. Additional domains can be configured in central_domains config array. Central domains typically host the admin panel for managing tenants. The middleware automatically allows access to these domains without tenant resolution.

Security: The middleware automatically:

• Returns 404 for domains/subdomains that don't match any tenant
• Only resolves active tenants (is_active = true and not expired)
• Protects central domains from tenant resolution
• Validates tenant status before allowing access

Filament Integration

Usage

Creating Tenants

Using Artisan Commands (Interactive)

The easiest way to create tenants is using the interactive command:

The command will guide you through:

• APP_DOMAIN Detection: Automatically detects and configures APP_DOMAIN from APP_URL if needed
• Tenant name and slug
• Domain or subdomain configuration (subdomains use APP_DOMAIN automatically)
• Database name (auto-generated if not provided)
• Plan selection: Shows plans from database with prices and billing cycles (Basic, Premium, Enterprise)
• Active status and expiration date
• Automatic subscription creation: Creates an active subscription when a plan is selected

APP_DOMAIN Auto-Configuration:

• Valid Domain Detection: If APP_URL contains a valid domain (e.g., http://hola.test), the command will detect it and ask if you want to use it as APP_DOMAIN
• Localhost/Port Detection: If APP_URL is localhost or has a port (e.g., http://localhost:8000), you'll be prompted to configure APP_DOMAIN manually
• Automatic .env Updates: The APP_DOMAIN variable is automatically added or updated in your .env file
• Subdomain Support: When using subdomains, the full domain is automatically constructed using APP_DOMAIN (e.g., tenant.APP_DOMAIN)

Creating Tenant Users

Create users for specific tenants with roles and permissions:

Features:

• Interactive tenant selection with numbered options
• Automatic password generation
• Role and permission assignment
• Email validation
• Comprehensive user information display

Using Artisan Commands (Non-Interactive)

Note: When using --plan, the plan slug must exist in the tenancy_plans table. If a plan is provided, a subscription will be automatically created for the tenant.

Programmatically

Working with Models

User Model with Roles & Permissions

Add the HasRoles trait to your User model to enable role-based access control:

Using Roles and Permissions

Asset Sharing

Use the tenant_asset() helper to access shared assets:

The helper automatically:

1. Checks for the asset in the tenant's storage disk
2. Falls back to the central storage disk if not found
3. Uses Laravel's asset() helper as final fallback

Tenant Models

For models that belong to tenants, use the BelongsToTenant trait:

Central/Landlord Models

For models that should always use the central database, use the UsesLandlordConnection trait:

Filament Panel Configuration

Landlord Panel

Create a landlord panel for managing tenants:

Tenant Panel

Create a tenant panel:

Middleware

The package provides several middleware for tenant management:

• InitializeTenancy:

  • Automatically resolves tenant from domain/subdomain
  • Returns custom 404 page if tenant is not found (if published, otherwise standard 404)
  • Verifies tenant is active before allowing access
  • Allows access to landlord/admin routes even with inactive tenants (configurable)
  • Registered globally by default (can be disabled in config)
• EnsureTenantAccess:
  • Ensures a tenant is present and active
  • Returns 404 if no tenant is found
  • Returns 403 if tenant is inactive or expired
• PreventAccessFromCentralDomains: Prevents tenant access from central domains

Custom 404 Page

The package includes a beautiful, personalized 404 page for tenant not found errors. During installation, you'll be asked if you want to publish the components and views for customization.

Publishing Components

Published Files

If you choose to publish during installation:

• Views: resources/views/vendor/filament-tenancy/errors/tenant-not-found.blade.php
• Livewire Component: app/Livewire/TenantNotFound.php (if Livewire is available)

Customization

Once published, you can fully customize:

• Blade View: Edit resources/views/vendor/filament-tenancy/errors/tenant-not-found.blade.php to change the design, colors, layout, or content
• Livewire Component: Edit app/Livewire/TenantNotFound.php to add dynamic functionality or interactivity

Automatic Registration

The installer automatically registers the custom 404 page in bootstrap/app.php (Laravel 11) for handling tenant not found errors. The page will:

• Display a beautiful error message
• Show request details (domain, resolver, APP_DOMAIN)
• Provide a link back to the homepage
• Work without Livewire if not published

Without Publishing

If you choose not to publish, the package will use its internal views and components. The 404 page will still work, but you won't be able to customize it.

Database Migrations

Running Tenant Migrations

Creating Tenant-Specific Migrations

Place tenant-specific migrations in database/migrations/tenant/:

Events

The package dispatches several events:

• TenantCreated: When a new tenant is created
• TenantDeleted: When a tenant is deleted
• TenantSwitched: When switching between tenants

Advanced Usage

Custom Tenant Resolution

You can extend the tenant resolver for custom logic:

Custom Database Configuration

Override database configuration per tenant:

Tenant Data Storage

Store additional tenant data using the JSON data column:

APP_DOMAIN Configuration

The APP_DOMAIN environment variable is used for subdomain-based tenancy. It's automatically detected and configured during tenant creation:

Automatic Detection:

• When running php artisan tenancy:create, the package checks your APP_URL
• If APP_URL contains a valid domain (e.g., http://hola.test), it suggests using it as APP_DOMAIN
• If APP_URL is localhost or has a port, you'll be prompted to configure APP_DOMAIN manually

Manual Configuration:

Usage:

• When creating tenants with subdomains, the full domain is automatically constructed: {subdomain}.{APP_DOMAIN}
• For example, if APP_DOMAIN=hola.test and subdomain is acme, the full domain becomes acme.hola.test
• The Tenant::getFullDomain() method uses APP_DOMAIN when available, falling back to central_domains configuration

Example:

Testing

Run the package tests:

Debug Logging

The package includes enhanced debug logging that is environment-aware:

DebugHelper Class

The DebugHelper class provides environment-aware logging:

Environment Configuration

Log Behavior

• Development (APP_ENV=local, APP_DEBUG=true): All logs are visible
• Production (APP_ENV=production OR APP_DEBUG=false): Only errors and criticals are logged
• Debug/Info/Warning: Only shown in development environment
• Error/Critical: Always logged regardless of environment

Security

This package includes several security features:

• Cross-tenant isolation: Prevents data leakage between tenants
• Domain validation: Ensures tenants can only be accessed from their domains
• Database separation: Each tenant has its own database
• Middleware protection: Automatic tenant context validation
• Automatic 404 for invalid domains: Domains/subdomains that don't match any tenant automatically return a beautiful custom 404 page
• Customizable 404 page: Personalized error page with request details and optional Livewire component support
• Active tenant verification: Only active tenants can be accessed (checks is_active and expires_at)
• Central domain protection: Central domains are protected from tenant resolution

Contributing

Please see CONTRIBUTING.md for details.

License

This package is currently available for public use, but will transition to a license-based distribution model in the future.

⚖️ License Terms & Usage Rights

Current Status: Public Access (Temporary)

• ✅ You CAN: Use this software in your projects (personal, commercial, educational)
• ✅ You CAN: Install and use the package via Composer
• ✅ You CAN: Customize configurations and extend functionality
• ❌ You CANNOT: Create replicas, forks, or copies of this package
• ❌ You CANNOT: Redistribute this package as your own
• ❌ You CANNOT: Remove or modify license headers
• ❌ You CANNOT: Use this package to create competing multi-tenancy solutions

🔮 Future Licensing Model

Important: This package will transition to a paid license model in the future. Users who adopt the package now will receive preferential treatment when licensing becomes available.

• License-based distribution (coming soon)
• Commercial use will require a valid license
• Enterprise features will be license-gated
• Early adopters will have migration paths to licensed versions

⚠️ What Happens If You Violate the License?

Legal Consequences:

• You may be subject to legal action for copyright infringement
• Distribution of unauthorized copies may result in cease and desist orders
• Commercial use without proper licensing will be pursued legally
• Creation of replicas or competing solutions will be treated as intellectual property theft

Technical Consequences:

• Package updates may include license validation
• Unauthorized usage may be detected and blocked
• Support will not be provided to unlicensed users
• Access to future versions may be restricted

📄 License Compliance

To ensure compliance:

• ✅ Use the package via official Composer repository only
• ✅ Do not copy, fork, or replicate the source code
• ✅ Respect intellectual property rights
• ✅ Contact us for licensing inquiries: [email protected]

Current License: MIT License (subject to above restrictions)

For complete license terms, please read the LICENSE file.

Available Commands

Central Database Commands

Tenant Management Commands

Migration Commands

Monitoring Commands

Documentation

Additional Guides

• PayPal Configuration Guide - Complete guide for setting up PayPal payment integration, including webhooks, credentials, and troubleshooting.

Credits

• Angelito Systems
• All Contributors

Support

For support, please open an issue on GitHub or contact us at [email protected].