README

Matrix is a comprehensive multi-tenant library designed to seamlessly integrate multi-tenancy into your Hyperf applications. It provides an easy-to-use and flexible system to manage multiple tenants, ensuring data isolation, dynamic database connection management, and tenant identification based on request parameters.

🌟 Features

Dynamic Tenant Database Connections: Automatically switch database connections based on the identified tenant, ensuring that each tenant's data remains isolated and secure.
Customizable Tenant Identification: Flexibly define how tenants are identified from incoming requests, whether by subdomain, path, headers, or other custom strategies.
Extensible Architecture: Easily extend or override default behaviors with custom implementations, thanks to the library's use of Hyperf's dependency injection and configuration systems.
Command for Publishing Migrations: Includes a command to publish necessary migrations to the application, making setup quick and straightforward.

🚀 Installation

To install Matrix, run the following command in the root of your Hyperf project:

composer require ananiaslitz/matrix

After installation, you should publish the default migrations provided by Matrix:

php bin/hyperf.php matrix:publish

This command copies necessary migration files to your project's migrations directory.

Configuration

Publish Configuration (Optional): If you want to customize the tenant identification logic or use a custom TenantFinder, publish the Matrix configuration file:

php bin/hyperf.php vendor:publish ananiaslitz/matrix

This will copy the default configuration file to config/autoload/matrix.php.

Define Tenant Finder: In config/autoload/matrix.php, specify your custom TenantFinder implementation if necessary:

return [
    'tenant_finder' => App\Tenant\CustomTenantFinder::class,
];

Middleware Registration: Register the TenantMiddleware in your application's middleware stack, typically in config/autoload/middlewares.php:

return [
    'http' => [
        \Ananiaslitz\Matrix\Http\Middleware\TenantMiddleware::class,
    ],
];

Usage

To use Matrix in your application, simply proceed with your business logic as usual. The library handles tenant identification and database connection switching automatically based on your configuration.

Ensure that your tenant-specific models use the dynamic tenant connection, which Matrix configures based on the identified tenant:

namespace App\Model;

use Hyperf\DbConnection\Model\Model;
use Ananiaslitz\Matrix\Model\Traits\UsesTenantConnection;

class YourTenantModel extends Model
{
    use UsesTenantConnection;
}

Customizing Tenant Identification

To customize how tenants are identified, implement your own TenantFinderInterface and specify it in the config/autoload/matrix.php configuration file. Your custom finder should return the tenant identifier based on the request, which Matrix will use to configure the database connection.

Contributing

Contributions are welcome! Please feel free to submit pull requests or create issues for bugs, questions, and feature requests.

ananiaslitz / matrix

Maintainers

Details