Download the PHP package muhammad-nawlo/multitenant-plugin without Composer

Filament Multitenant Plugin

A comprehensive multitenant plugin for Filament that integrates seamlessly with stancl/tenancy and spatie/laravel-permission to make multitenant applications easier to build and manage. This plugin provides complete tenant management with role-based permissions and beautiful Filament interfaces.

Features

• 🏢 Tenant Management: Complete CRUD operations for tenants through Filament
• 📊 Tenant Dashboard: Beautiful dashboard with tenant statistics and quick actions
• 🔧 Easy Integration: Simple traits to make your resources tenant-aware
• 🔒 Role-based Permissions: Tenant-specific access control using Spatie Laravel Permission
• ⚙️ Flexible Configuration: Extensive configuration options
• 🚀 Quick Setup: Automated setup command for fast deployment
• 🎨 Modern UI: Beautiful Filament interface for tenant management
• 🔒 Robust Error Handling: Graceful degradation when tenancy isn't available
• 📝 Comprehensive Documentation: Detailed examples and usage guides
• 🛠️ Production Ready: Thoroughly tested with proper error handling and edge cases covered

Installation

1. Install the package via Composer:

2. Install required dependencies (if not already installed):

3. Publish required configurations:

4. Run the setup command:

5. Add the plugin to your Filament panel:

Installation Notes

• The plugin depends on stancl/tenancy and spatie/laravel-permission but does not automatically publish their configs
• You need to manually publish the config files for these dependencies if you haven't already
• This gives you full control over the configuration of these packages

Quick Start

Making Resources Tenant-Aware

Use the TenantAwareResource trait in your Filament resources:

Making Resources Tenant-Aware with Permissions

Use the TenantAwareResource trait for resources that need both tenancy and permissions:

Making Pages Tenant-Aware

Use the TenantAwarePage trait in your Filament pages:

Making Pages Tenant-Aware with Permissions

Use the TenantAwarePage trait for pages that need both tenancy and permissions:

Making Models Tenant-Aware

Add the BelongsToTenant trait to your models:

Configuration

The plugin provides extensive configuration options in config/multitenant-plugin.php:

Usage

Tenant Management

The plugin provides a complete tenant management interface:

• List Tenants: View all tenants with search and filtering
• Create Tenant: Add new tenants with custom data
• Edit Tenant: Modify tenant information
• Delete Tenant: Remove tenants safely
• Switch Tenant: Switch between tenant contexts

Tenant Dashboard

Access the tenant dashboard to see:

• Current tenant information
• Tenant statistics (total, active, recent)
• Quick actions for tenant management
• Navigation to tenant resources

API Methods

The traits provide several useful methods:

Commands

Setup Command

This command will:

• Publish tenancy configuration
• Publish and run migrations
• Create tenant model
• Update User model to be tenant-aware
• Create tenant middleware

Generate Tenant Permissions

This command will:

• Create tenant-specific permissions for all existing permissions
• Optionally assign permissions to specified roles
• Support bulk generation for all tenants
• Create tenant-specific permission names (e.g., view_any_post_tenant-1)

Force Setup

Force setup even if tenancy is already configured.

Grant All Permissions to Super Admin

This command grants all permissions in the database to the super admin role (configurable via MULTITENANT_PLUGIN_SUPER_ADMIN_ROLE in your .env).

• Finds or creates the super admin role.
• Assigns all permissions to this role, ensuring super admins can access all resources, pages, and widgets.

Generate All Permissions for a Resource

This command generates all standard permissions (view, create, update, delete, etc.) for a given Filament resource.

• {resource}: The fully qualified class name of the resource (e.g., App\Filament\Resources\PostResource).
• Permissions generated: view_any_{resource}, view_{resource}, create_{resource}, update_{resource}, delete_{resource}, delete_any_{resource}, restore_{resource}, force_delete_{resource}.
• Uses the resource's getSlug() if available, otherwise uses a snake_case version of the class name.

Generate Permissions and Policies for Panels/Resources

This command generates all standard permissions (and optionally policy stubs) for resources registered to your Filament panels, similar to Shield's generator.

Options:

• --all — Generate for all resources in all panels
• --panel= — Only for a specific panel (FQCN)
• --resource= — Only for specific resources (comma-separated, by class basename)
• --exclude — Exclude the given resources
• --policies — Also generate policy stubs (extendable)
• --minimal — Minimal output (just counts)

Example:

This will generate all permissions and policy stubs for all resources in all panels.

Middleware

The plugin includes middleware for tenant initialization:

Advanced Usage

Custom Tenant Identification

You can customize how tenants are identified by modifying the middleware:

Error Handling

The plugin is designed to be robust and handle cases where dependencies aren't available:

• Tenancy not available: Plugin works without tenant-specific features
• Permissions not available: Plugin works without permission features
• Graceful degradation: Features are disabled rather than causing errors
• Test environment support: Plugin works in testing contexts with proper null checks
• Asset registration: Removed problematic asset registration that caused composer require errors

Custom Tenant Data

Store additional tenant data in the data column:

Tenant-Specific Permissions

The plugin automatically creates tenant-specific permissions. For example:

This allows you to control access per tenant:

Using the Permission Service

Testing

Troubleshooting

Common Issues

1. "Target class [Stancl\Tenancy\TenancyManager] does not exist"

   • Make sure you have installed stancl/tenancy
   • Run composer require stancl/tenancy
   • Follow the tenancy package setup instructions
   • The plugin will work without tenancy, but tenant-specific features will be disabled

2. Setup command fails

   • Ensure you have write permissions to your app directory
   • Check that the User model exists and is writable
   • Run php artisan multitenant:setup --force to overwrite existing files
   • The command will create missing directories automatically

3. Permissions not working

   • Ensure spatie/laravel-permission is properly installed and configured
   • Run php artisan permission:create-role super_admin to create a super admin role
   • Then run php artisan multitenant:generate-permissions --all
   • Check that your User model has the HasRoles trait

4. "Class not found" errors in TenantResource

   • This usually happens when page namespaces are incorrect
   • The plugin now uses fully qualified namespaces to avoid this issue
   • If you encounter this, try running the setup command again

5. Syntax errors in User.php after setup

   • The setup command now uses regex to properly insert the trait
   • If you encounter syntax errors, check the User model file
   • Run php artisan multitenant:setup --force to fix the User model
6. Plugin not working in test environment
   • This is expected behavior as the plugin requires a proper Laravel application
   • The plugin includes null checks and try-catch blocks for test environments
   • Features will be gracefully disabled in test contexts

Debugging

To debug issues with the plugin:

Getting Help

If you're still experiencing issues:

1. Check the stancl/tenancy documentation
2. Check the spatie/laravel-permission documentation
3. Open an issue on the GitHub repository with detailed error messages

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Muhammad Nawlo
• All Contributors

License

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

TenantManagementPanel

This plugin provides a dedicated Filament panel for tenant management, accessible at /tenant-management.

Features

• Isolated panel for managing tenants
• Only users with the super_admin role can access this panel
• Integrates with stancl/tenancy and spatie/laravel-permission
• All tenant management resources and pages are registered only in this panel

Dependencies

• stancl/tenancy
• spatie/laravel-permission

Access Control

• The panel uses middleware to restrict access to users with a configurable super admin role:
  • By default, only users with the super_admin role can access this panel.
  • You can change the role name by setting MULTITENANT_PLUGIN_SUPER_ADMIN_ROLE in your .env file.
  • Example: MULTITENANT_PLUGIN_SUPER_ADMIN_ROLE=your_custom_role
  • If a user is not authenticated or does not have the configured role, they will receive a 403 error.

Testing

1. Install this package in a Laravel app with Filament, stancl/tenancy, and spatie/laravel-permission installed.
2. Ensure your user has the super_admin role (using Spatie/Permission or Shield).
3. Visit /tenant-management in your browser.
4. Only super admins should be able to access and manage tenants.

Plugin Manager Class

• The main plugin manager class is now MultitenantPluginManager (previously MultitenantPluginPlugin).
• Use MuhammadNawlo\MultitenantPlugin\MultitenantPluginManager for any manual registration or advanced usage.