Redirected from /stancl/tenancy
Tenancy for Laravel

https://github.com/archtechx/tenancy
Admin
Tenancy for Laravel is a multi-tenancy package that automatically handles tenant isolation for...
Tokens:163,518
Snippets:1,155
Trust Score:9.4
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Start containers and run tests

Source: https://github.com/archtechx/tenancy/blob/master/CONTRIBUTING.md

Starts the Docker containers and then runs the test suite.

```bash
composer docker-up
```

```bash
composer test
```

--------------------------------

### Run tenancy:install

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/commands.md

Runs the tenancy:install command, which publishes the config, routes, service-provider stub, and migrations, creates database/migrations/tenant, and asks to star the repo (skipped with --no-interaction). Uses the publish tags config, routes, providers, and migrations of Stancl\Tenancy\TenancyServiceProvider.

```php
php artisan tenancy:install
```

--------------------------------

### tenancy:install

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/commands.md

Command to install the tenancy package by publishing configuration, routes, service provider stub, and migrations.

```APIDOC
## [COMMAND] tenancy:install

### Description
Publishes the config file, routes, service-provider stub, and migrations; creates `database/migrations/tenant`; then asks to star the repo (skipped with `--no-interaction`). Uses the publish tags `config`, `routes`, `providers`, `migrations` of `Stancl\Tenancy\TenancyServiceProvider`.

### Method
COMMAND

### Endpoint
`php artisan tenancy:install`

### Parameters
#### Options
- `--no-interaction` (boolean) - Optional - Skip the prompt to star the repo.

### Request Example
```bash
php artisan tenancy:install
```

### Response
#### Success Response
No specific response body; the command publishes files and creates the tenant migrations directory.

```

--------------------------------

### Set default connection to tenant

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/database-manager.md

Example of setting the default connection to 'tenant'.

```php
$database->setDefaultConnection('tenant');
```

--------------------------------

### Checking tenant existence and getting tenant key

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/helpers.md

Demonstrates checking if a tenant exists (central context) and getting the tenant key.

```php
if (! tenant()) {
    return redirect('https://example.com'); // central context
}
echo tenant()->getTenantKey();
```

--------------------------------

### Connect to tenant and verify database name

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/database-manager.md

Example of connecting to a tenant and verifying the default connection points to the tenant database.

```php
$database->connectToTenant($tenant);
DB::connection()->getDatabaseName(); // tenant DB
```

--------------------------------

### Ensure tenant can be created with error handling

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/database-manager.md

Example of checking if a tenant database can be created, catching the exception and logging the reason.

```php
try {
    $databaseManager->ensureTenantCanBeCreated($tenant);
} catch (\Stancl\Tenancy\Contracts\TenantCannotBeCreatedException $e) {
    // $e->reason() gives the human-readable reason
    Log::warning('Skipping tenant DB creation: ' . $e->reason());
}
```

--------------------------------

### global_cache usage examples

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/helpers.md

Examples of using global_cache to put and get values, and handling invalid arguments.

```php
global_cache(['feature_flag' => true]);   // put, ttl null
global_cache(['api_key' => 'secret', 3600]); // put with TTL
$value = global_cache('some_key');         // get
$value = global_cache('some_key', 'default');
$manager = global_cache();                 // Illuminate\Cache\CacheManager
```

```php
try {
    global_cache(42); // not a string or array
} catch (InvalidArgumentException $e) {
    // "When setting a value in the cache, you must pass an array of key / value pairs."
}
```

--------------------------------

### LogChannelBootstrapper channel overrides example

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/bootstrappers-config.md

Example of setting $channelOverrides with a config-key map for 'slack' and a closure for 'custom'. Closure results must be arrays, otherwise an InvalidArgumentException is thrown.

```php
LogChannelBootstrapper::$channelOverrides = [
    'slack' => ['url' => 'slackWebhookUrl'],
    'custom' => fn (Tenant $tenant, array $channel) => array_merge($channel, ['url' => $tenant->slackUrl]),
];
```

--------------------------------

### Resolve tenant by domain example

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/resolvers.md

Example of calling resolve() with a domain. Throws TenantCouldNotBeIdentifiedOnDomainException for unknown domains.

```php
$resolver->resolve('acme.example.com'); // Tenant
// throws TenantCouldNotBeIdentifiedOnDomainException for unknown domains
```

--------------------------------

### global_asset usage example

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/helpers.md

Example of using global_asset to generate a central asset URL.

```php
echo global_asset('img/logo.png'); // https://central.example.com/img/logo.png
```

--------------------------------

### Run artisan command for each tenant with `tenants:run`

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/commands.md

Runs any artisan command for each tenant. The example clears the cache for the tenant 'acme'.

```bash
php artisan tenants:run "cache:clear" --tenants=acme
```

--------------------------------

### Using tenant() helper to get tenant and attributes

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/helpers.md

Shows how to retrieve the current tenant object and access its attributes using the tenant() helper.

```php
$tenant = tenant();         // ?Tenant
$id = tenant('id');         // mixed -- e.g. the tenant key
$plan = tenant('plan');     // any tenant column/attribute
```

--------------------------------

### Connect to tenant with failure recovery

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/database-manager.md

Example of connecting to a tenant with error handling. On failure, restores the central connection before rethrowing the exception.

```php
try {
    $database->connectToTenant($tenant);
} catch (\Throwable $e) {
    $database->reconnectToCentral(); // always restore the central context on failure
    throw $e;
}
```

--------------------------------

### Cached resolver configuration example

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/resolvers.md

Example configuration for a cached resolver in tenancy.php. It enables caching with a TTL of 600 seconds and uses the Redis cache store.

```php
// Config for any cached resolver (from tenancy.php):
Resolvers\DomainTenantResolver::class => [
    'cache' => true,
    'cache_ttl' => 600,
    'cache_store' => 'redis',
],
```

--------------------------------

### MailConfigBootstrapper credentials map example

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/bootstrappers-config.md

Example of setting the $credentialsMap to map mail config keys to tenant attributes. The bootstrap() method applies each mapping by setting config(configKey) from data_get($tenant, storageKey) when non-null, and revert() restores original config.

```php
MailConfigBootstrapper::$credentialsMap = [
    'mail.mailers.smtp.username' => 'mail_username',
    'mail.mailers.smtp.password' => 'mail_password',
];
```

--------------------------------

### tenant_asset usage examples

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/helpers.md

Examples of using tenant_asset to generate asset URLs, including a Blade template usage.

```php
echo tenant_asset('uploads/avatar.png');
// https://example.com/tenancy/assets/uploads/avatar.png  (or app.asset_url-based URL)
```

```php
// In a Blade template
<img src="{{ tenant_asset('products/' . $product->image) }}" alt="">
```

--------------------------------

### findTenantByDomain usage example

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/resolvers.md

Example of calling findTenantByDomain with a domain string.

```php
$tenant = DomainTenantResolver::findTenantByDomain('acme.example.com');
```

--------------------------------

### PostgresRLSBootstrapper::bootstrap()

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/bootstrappers-core.md

Builds the tenant connection from the central one plus RLS user credentials, sets it as default, and runs a SET command to set the session variable to the tenant key. This method is called on tenancy start.

```APIDOC
## PostgresRLSBootstrapper::bootstrap()

### Description
Builds the tenant connection from the central one plus RLS user credentials, sets it as default, and runs a SET command to set the session variable to the tenant key. This method is called on tenancy start.

### Method
bootstrap()

### Parameters
None

### Configuration
- `tenancy.rls.user.username` (string) - Required - The username for the RLS user.
- `tenancy.rls.user.password` (string) - Required - The password for the RLS user.
- `tenancy.rls.session_variable_name` (string) - Default: `'my.current_tenant'` - The session variable name used for RLS.

### Behavior
- Builds the `tenant` connection from the central one plus RLS user credentials.
- Sets the tenant connection as default.
- Runs `SET {tenancy.rls.session_variable_name} = '{tenantKey}'`.

### Example Configuration
```php
// tenancy.php:
'rls' => [
    'user' => ['username' => env('TENANCY_RLS_USERNAME'), 'password' => env('TENANCY_RLS_PASSWORD')],
    'session_variable_name' => 'my.current_tenant',
],
// bootstrappers: Bootstrappers\PostgresRLSBootstrapper::class
```

### Response
No return value.
```

--------------------------------

### DatabaseCacheBootstrapper

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/bootstrappers-core.md

Documentation for the DatabaseCacheBootstrapper class, including its constructor, methods, properties, and usage example.

```APIDOC
## DatabaseCacheBootstrapper

### Description
Separates cache by the tenant **database** rather than by prefix. Must run after `DatabaseTenancyBootstrapper`.

### Class
`Stancl\Tenancy\Bootstrappers\DatabaseCacheBootstrapper`

### Constructor
- **config** (Repository) - Required - The configuration repository.
- **cache** (CacheManager) - Required - The cache manager.
- **originalConnections** (array) - Required - Original cache connections.
- **originalLockConnections** (array) - Required - Original lock connections.

### Methods

#### bootstrap(): void
- **Description**: Throws an `Exception` if there's no `tenant` connection (message: `"DatabaseCacheBootstrapper must run after DatabaseTenancyBootstrapper."`). Rewrites each affected store's `connection`/`lock_connection` config to `tenant` and points the underlying `DatabaseStore` at the tenant connection. Also sets `TenancyServiceProvider::$adjustCacheManagerUsing` so the **global cache** keeps using the central connection.

#### revert(): void
- **Description**: Restores original connections and clears the adjuster.

### Properties
- **$stores** (array|null) - `null` scopes all `database`-driver cache stores; an array restricts to those stores (all must use the `database` driver).
- **$adjustGlobalCacheManager** (bool) - Whether to adjust the global cache manager. Default: `true`.

### Usage Example
```php
DatabaseCacheBootstrapper::$stores = ['my-db-cache']; // scope only this store
```
```

--------------------------------

### Usage of RequestDataTenantResolver helpers and resolve

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/resolvers.md

Example usage of the static helpers and the resolve method. Shows default values for header and query parameter names, and resolving a tenant by payload.

```php
RequestDataTenantResolver::headerName();       // 'X-Tenant' (default)
RequestDataTenantResolver::queryParameterName(); // 'tenant' (default)

$tenant = $resolver->resolve('tenant-uuid');   // then middleware extracts the payload
```

--------------------------------

### Example implementation of ResourceSyncing trait

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/resource-syncing.md

Shows a model class that uses the ResourceSyncing trait and implements SyncMaster. It defines methods to specify central and tenant model names, synced attribute names, and a booted method for adding global scopes.

```php
use Stancl\Tenancy\ResourceSyncing\ResourceSyncing;
use Stancl\Tenancy\ResourceSyncing\SyncMaster;
use Illuminate\Database\Eloquent\Model;

class Role extends Model implements SyncMaster
{
    use ResourceSyncing;

    public function getCentralModelName(): string { return Role::class; }
    public function getTenantModelName(): string { return \App\Models\Tenant\Role::class; }
    public function getSyncedAttributeNames(): array { return ['name', 'permissions']; }
    public static function booted(): void { static::addGlobalScope(...); /* any tenant-model scoping */ }
}
```

--------------------------------

### RedisTenancyBootstrapper::bootstrap()

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/bootstrappers-core.md

Sets the Redis prefix option on configured connections to enable tenant-scoped keys. This method is called on tenancy start.

```APIDOC
## RedisTenancyBootstrapper::bootstrap()

### Description
Sets the Redis prefix option on each configured connection's client to enable tenant-scoped keys. This method is called on tenancy start.

### Method
bootstrap()

### Parameters
None

### Configuration
- `tenancy.redis.prefix` (string) - Default: `'tenant_%tenant%_'` - The prefix pattern used for tenant keys.
- `tenancy.redis.prefixed_connections` (array) - Default: `['default']` - List of Redis connections to apply the prefix to.

### Example
```php
Redis::set('foo', 'bar'); // stored under tenant_{key}_foo in tenant context
```

### Response
No return value.
```

--------------------------------

### Run tenants:rls command with example output

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/rls-policy-managers.md

Executes the tenants:rls Artisan command to create RLS policies for tenant tables. The output shows the success message and a list of tables with policy hashes, e.g., posts (a1b2c3).

```php
php artisan tenants:rls
// "RLS policies created for tables (using TableRLSManager):"
//   • posts (a1b2c3)
//   ...
```

--------------------------------

### makeCredentials(): void

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/database-manager.md

Writes db_name (and db_username/db_password when the manager implements ManagesDatabaseUsers) onto the tenant model as internal tenancy_db_* attributes, and saves the tenant if it exists. The example shows usage and expected internal values.

```php
public function makeCredentials(): void
```

```php
$tenant->database()->makeCredentials();
$tenant->getInternal('db_name');      // e.g. 'tenant-uuid123'
$tenant->getInternal('db_username');  // e.g. 'abc123...' (only for user-managing managers)
```

--------------------------------

### Tenant Context Run and Enter/Leave

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/models.md

Using the TenantRun and InitializationHelpers concerns: run() executes a callback in the tenant context, while enter() and leave() manually initialize and end the tenant context.

```php
$tenant->run(fn () => User::count());

$tenant->enter();
// ... tenant context active
$tenant->leave();
```

--------------------------------

### Using tenancy() helper

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/helpers.md

Shows usage of the tenancy() helper to check if tenancy is initialized and to initialize a tenant.

```php
tenancy()->initialized;   // bool
tenancy()->initialize($tenant);
```

--------------------------------

### isSubdomain usage example

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/resolvers.md

Example of calling isSubdomain. Returns true when the domain ends with a central domain and is not itself central.

```php
DomainTenantResolver::isSubdomain('acme.example.com'); // true when example.com is central
```

--------------------------------

### Use the Tenancy facade

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/tenancy.md

Shows how to use the Tenancy facade to proxy static calls to the singleton instance. Import the facade and call methods like find() and initialize() directly.

```php
use Stancl\Tenancy\Facades\Tenancy;

Tenancy::find($id);
Tenancy::initialize($tenant); // via the singleton instance
```

--------------------------------

### Initialize tenancy by key or model

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/tenancy.md

Shows two ways to initialize tenancy: by tenant key or with a Tenant model instance. If tenancy is already initialized for the same tenant key, it is a no-op; for a different tenant, end() is called first.

```php
// Identify by tenant key (resolves the Tenant model internally)
tenancy()->initialize('tenant-uuid-123');

// Initialize with a model instance
$tenant = Tenancy::find('tenant-uuid-123');
tenancy()->initialize($tenant);
```

--------------------------------

### Tenancy context management with tenancy() helper

Source: https://github.com/archtechx/tenancy/blob/master/CLAUDE.md

Use the global tenancy() helper to manage tenant context transitions. initialize() switches to a tenant, run() executes atomically within a tenant, runForMultiple() applies batch operations, and central() runs in the central context.

```php
tenancy()->initialize($tenant);           // Switch to tenant
tenancy()->run($tenant, $callback);      // Atomic tenant execution
tenancy()->runForMultiple($tenants, $callback); // Batch operations
tenancy()->central($callback);           // Run in central context
```

--------------------------------

### DatabaseSessionBootstrapper::bootstrap()

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/bootstrappers-core.md

Resets the database connection used by the database session driver on tenancy start to prevent session forgery. This method is called on tenancy start.

```APIDOC
## DatabaseSessionBootstrapper::bootstrap()

### Description
Resets the database connection used by the database session driver on tenancy start to prevent session forgery. This method is called on tenancy start.

### Method
bootstrap()

### Parameters
None

### Behavior
- When `session.driver === 'database'`, sets `session.connection` to `tenant` and rebuilds the handler (`DatabaseSessionHandler` on the tenant connection).

### Response
No return value.
```

--------------------------------

### Register middleware groups in TenancyServiceProvider::boot()

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/endpoints.md

Registers the four empty middleware groups (clone, universal, tenant, central) in TenancyServiceProvider::boot(). Each group is initially empty; you add middleware as needed.

```php
Route::middlewareGroup('clone', []);
Route::middlewareGroup('universal', []);
Route::middlewareGroup('tenant', []);
Route::middlewareGroup('central', []);
```

--------------------------------

### initialize() method signature

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/tenancy.md

Signature of the initialize method. It accepts a Tenant instance or a tenant key/ID to resolve via Tenancy::find().

```php
public function initialize(Tenant|int|string $tenant): void
```

--------------------------------

### tenant(?string $key = null)

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/helpers.md

Gets the current tenant or a property from it.

```APIDOC
## tenant(?string $key = null): mixed

### Description
Gets the current tenant, or a property from it. With no argument, returns the current tenant bound in the container, or null in central context. With a key, returns the tenant's attribute value.

### Signature
```php
function tenant(?string $key = null): mixed
```

### Parameters
- **$key** (?string) - Optional - Tenant attribute key to fetch. Defaults to null.

### Returns
- **mixed** - The current tenant instance (when no key) or the tenant attribute value (when key provided). May be null.

### Example
```php
$tenant = tenant();         // ?Tenant
$id = tenant('id');         // mixed -- e.g. the tenant key
$plan = tenant('plan');     // any tenant column/attribute
```

```php
if (! tenant()) {
    return redirect('https://example.com'); // central context
}
echo tenant()->getTenantKey();
```
```

--------------------------------

### Create and pull pending tenants

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/models.md

Shows how to create a pre-provisioned pending tenant and claim ready tenants synchronously or from a pool.

```php
Tenant::createPending(['plan' => 'pro']); // pre-provisioned tenant

$tenant = Tenant::pullPending();          // claim a ready tenant synchronously
$tenant = Tenant::pullPendingFromPool(true, ['plan' => 'pro']);
```

--------------------------------

### Reconnect to central database

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/database-manager.md

Example of reconnecting to the central database after tenant operations.

```php
$database->reconnectToCentral();
```

--------------------------------

### Using RouteMode::TENANT

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/types.md

Example usage of the RouteMode enum to check if a route is in tenant mode.

```php
use Stancl\Tenancy\Enums\RouteMode;
use Stancl\Tenancy\Enums\Context;

if (Tenancy::getRouteMode($route) === RouteMode::TENANT) { /* ... */ }
```

--------------------------------

### SQLiteDatabaseManager

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/database-managers.md

Documentation for the SQLiteDatabaseManager class, including static configuration properties, methods, and an example usage.

```APIDOC
## SQLiteDatabaseManager

### Description
Manages SQLite tenant databases, supporting both file-based and in-memory databases. Provides methods to create, delete, check existence, and configure connections for tenant databases.

### Static Configuration

| Property | Type | Default | Description |
|-----------|------|---------|-------------|
| `$path` | `string\|null` | `null` | Directory for tenant DB files; defaults to `database_path()`. |
| `$persistInMemoryConnectionUsing` | `?Closure(PDO, string)` | `null` | Called in `makeConnectionConfig()` for in-memory DBs to keep the PDO connection alive (receives the `PDO` and the DSN). |
| `$closeInMemoryConnectionUsing` | `?Closure(Tenant)` | `null` | Called on tenant deletion to clear the in-memory database. |
| `$allowedDatabaseNameCharacters` | `string` | `'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-.'` | Allowlist for database names. |

### Methods

#### `createDatabase(TenantWithDatabase $tenant)`

- **Returns**: `bool`
- **Description**: For in-memory names, rewrites the tenant's `db_name` to a **named** in-memory DSN (`file:_tenancy_inmemory_{key}?mode=memory&cache=shared`) and saves the tenant. Otherwise creates an empty file at `getPath($name)`.

#### `deleteDatabase(TenantWithDatabase $tenant)`

- **Returns**: `bool`
- **Description**: In-memory: calls `$closeInMemoryConnectionUsing` and returns `true`. File-based: unlinks `-journal`/`-wal`/`-shm` companions then the DB file; returns `false` on failure.

#### `databaseExists(string $name)`

- **Returns**: `bool`
- **Description**: `isInMemory($name) || file_exists(getPath($name))`.

#### `makeConnectionConfig(array $baseConfig, string $databaseName)`

- **Returns**: `array`
- **Description**: In-memory: validates with `extraAllowedCharacters: ':?=&'`, uses the DSN as the database, optionally creates the persisted PDO. File-based: sets the resolved file path.

#### `getPath(string $name)`

- **Returns**: `string`
- **Description**: Validates the name; returns `path/$name` or `database_path($name)`.

#### `static isInMemory(string $name)`

- **Returns**: `bool`
- **Description**: `':memory:'` or a `file:_tenancy_inmemory_*?mode=memory&cache=shared` name.

### Exceptions

- **Throws** `InvalidArgumentException` from validation: empty name, directory name, or forbidden characters.

### Example

```php
SQLiteDatabaseManager::$path = storage_path('tenant-dbs');

// In-memory: keep the connection alive via the container
SQLiteDatabaseManager::$persistInMemoryConnectionUsing = function (PDO $pdo, string $dsn) {
    app()->singleton('tenant_db_' . $dsn, fn () => $pdo);
};
```
```

--------------------------------

### run() method signature

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/tenancy.md

Signature of the run method. It atomically initializes tenancy for the given tenant, runs the callback, and reverts to the previous context in a finally block.

```php
/**
 * @template T
 * @param Closure(Tenant): T $callback
 * @return (T is PendingDispatch ? null : T)
 */
public function run(Tenant $tenant, Closure $callback): mixed
```

--------------------------------

### Invoke CreateStorageSymlinksAction

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/jobs-actions.md

Example of resolving and invoking CreateStorageSymlinksAction with a tenant, using relative links and not forcing overwrite.

```php
$action = app(CreateStorageSymlinksAction::class);
$action($tenant, relativeLink: true, force: false);
```

--------------------------------

### global_cache function signature

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/helpers.md

Function signature for global_cache, which gets or sets values in the global cache store.

```php
/**
 * @param  dynamic  key|key,default|data,expiration|null
 * @return mixed|Illuminate\Cache\CacheManager
 *
 * @throws InvalidArgumentException
 */
function global_cache(): mixed
```

--------------------------------

### Run tenants:migrate with tenant selection, skip-failing, and parallel processes

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/commands.md

Runs migrations for all or selected tenants using config('tenancy.migration_parameters') defaults unless overridden. The second command selects tenant acme, continues on per-tenant failures with --skip-failing, and enables parallel execution with -p. Exit code is 0 on success, 1 when any tenant failed; throws TenantDatabaseDoesNotExistException or QueryException unless --skip-failing.

```php
php artisan tenants:migrate
php artisan tenants:migrate --tenants=acme --skip-failing -p
```

--------------------------------

### tenant() helper function signature

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/helpers.md

Signature of the tenant() helper function. It gets the current tenant or a property from it.

```php
function tenant(?string $key = null): mixed
```

--------------------------------

### initialize(Tenant|int|string $tenant): void

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/tenancy.md

Initializes tenancy for a given tenant, either by model instance or by tenant key/ID. Handles switching between tenants and fires initialization events.

```APIDOC
## initialize(Tenant|int|string $tenant): void

### Description
Initializes tenancy for the passed tenant. If the argument is not a `Tenant` instance, the tenant is looked up with `find()`.

### Method
initialize

### Signature
`public function initialize(Tenant|int|string $tenant): void`

### Parameters
- **$tenant** (`Tenant|int|string`) - Required - A tenant model instance, or a tenant key/ID to resolve via `Tenancy::find()`.

### Behavior
- If tenancy is already initialized for the **same** tenant key, this is a no-op.
- If tenancy is initialized for a **different** tenant, `end()` is called first.
- Fires `Events\InitializingTenancy` (before) and `Events\TenancyInitialized` (after). The `BootstrapTenancy` listener on `TenancyInitialized` runs all bootstrappers and fires `BootstrappingTenancy`/`TenancyBootstrapped`.

### Throws
- `Stancl\Tenancy\Exceptions\TenantCouldNotBeIdentifiedByIdException` - The passed ID/key does not resolve to an existing tenant.

### Examples
```php
// Identify by tenant key (resolves the Tenant model internally)
tenancy()->initialize('tenant-uuid-123');

// Initialize with a model instance
$tenant = Tenancy::find('tenant-uuid-123');
tenancy()->initialize($tenant);
```

```php
// Error handling: unknown tenant keys are rejected
try {
    tenancy()->initialize('non-existent-id');
} catch (\Stancl\Tenancy\Exceptions\TenantCouldNotBeIdentifiedByIdException $e) {
    // "Tenant could not be identified by tenant key: non-existent-id"
    report($e);
}
```
```

--------------------------------

### Run tenants:migrate-fresh with tenant option

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/commands.md

Drops all tenant tables using db:wipe --database=tenant, then re-runs tenants:migrate. Supports options like --drop-views, --step, --force, -p/--processes, -P/--forceProcesses, and common tenant options. Requires confirmation in production via confirmToProceed().

```php
php artisan tenants:migrate-fresh --tenants=acme
```

--------------------------------

### TenantCollection::runForEach

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/models.md

Documentation for the TenantCollection::runForEach method.

```APIDOC
## TenantCollection::runForEach

### Description
Runs a callable for every tenant in the collection, executing it in each tenant's context and reverting afterwards.

### Method
runForEach

### Signature
`runForEach(Closure $callable): self`

### Parameters
- **$callable** (Closure) - Required - The callable to run for each tenant.

### Returns
- **self** - The collection instance.

### Example
```php
Tenant::all()->runForEach(function ($tenant) {
    // executed in each tenant's context, reverting afterwards
});
```
```

--------------------------------

### Creating a domain and handling occupation exception

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/models.md

Shows how to create a domain with mixed-case input, which is saved lowercase, and how to catch the DomainOccupiedByOtherTenantException when attempting to create a domain that is already occupied.

```php
$domain = Domain::create(['domain' => 'Acme.Example.com', 'tenant_id' => $tenantKey]);
// saved as 'acme.example.com'

try {
    Domain::create(['domain' => 'acme.example.com', 'tenant_id' => $otherTenantKey]);
} catch (\Stancl\Tenancy\Exceptions\DomainOccupiedByOtherTenantException $e) {
    // "The acme.example.com domain is occupied by another tenant."
}
```

--------------------------------

### Path map structure

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/rls-policy-managers.md

Example structure of the $paths parameter for generateQueries. Each table maps to an array of steps leading to the tenants table.

```php
[
    'table_name' => [...$stepsLeadingToTenantsTable],
]
```

--------------------------------

### Implement UsableWithEarlyIdentification trait

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/middleware.md

Example implementation of an identification middleware using the trait. Must implement requestHasTenant to determine if the request has a tenant.

```php
// Users implement this pattern:
class MyIdentificationMiddleware extends IdentificationMiddleware
{
    use UsableWithEarlyIdentification;

    public function requestHasTenant(Request $request): bool
    {
        return $request->has('tenant');
    }
}
```

--------------------------------

### tenancy() helper function

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/helpers.md

Returns the Stancl\Tenancy\Tenancy singleton, equivalent to the Tenancy facade. Use it to access tenancy state or initialize a tenant.

```php
function tenancy()
{
    return app(Tenancy::class);
}
```

--------------------------------

### static model(): Tenant&Model

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/tenancy.md

Returns a fresh instance of the configured tenant model class.

```php
public static function model(): Tenant&Model
```

```php
$tenantClass = get_class(Tenancy::model()); // Stancl\Tenancy\Database\Models\Tenant (default)
```

--------------------------------

### Register CheckTenantForMaintenanceMode middleware

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/middleware.md

Apply the middleware to a route group. The comment shows an example maintenance_mode payload with secret, redirect, and status keys.

```php
Route::middleware([CheckTenantForMaintenanceMode::class])->group(...);
// tenant('maintenance_mode') == ['secret' => 'secret-token', 'redirect' => '/', 'status' => 503]
```

--------------------------------

### Run tenants:seed with class and tenant options

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/commands.md

Seeds tenant databases using config('tenancy.seeder_parameters') defaults, with --class defaulting to Database\Seeders\DatabaseSeeder. Fires SeedingDatabase and DatabaseSeeded events.

```php
php artisan tenants:seed --class=Database\Seeders\TenantSeeder --tenants=acme
```

--------------------------------

### Clone a route with middleware and domain variant

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/overrides.md

Demonstrates cloning a route with the 'clone' middleware, resulting in a /{tenant}/foo route named tenant.foo with tenant middleware. Also shows a domain-based variant that disables the tenant parameter and sets a domain.

```php
Route::get('/foo', FooController::class)->name('foo')->middleware('clone');

$action = CloneRoutesAsTenant::make();
$action->handle();
// Clone of /foo → /{tenant}/foo, named tenant.foo, middleware ['tenant']

// Domain-based variant without the tenant parameter:
$action->addTenantParameter(false)->domain('central.localhost')->handle();
```

--------------------------------

### GET /tenancy/assets/{path?}

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/endpoints.md

Central asset route that serves files from the tenant's storage `app/public` directory or a configured public disk.

```APIDOC
## [GET] /tenancy/assets/{path?}

### Description
Serves an asset file from the tenant's storage `app/public` directory (or a configured public disk) in the central context. The route is registered when `config('tenancy.routes')` is `true`.

### Method
GET

### Endpoint
`/tenancy/assets/{path?}` where `{path}` matches `(.*)`

### Parameters
#### Path Parameters
- **path** (string) - Optional - File path relative to the asset root. Default `null` results in a `404`.

### Response
#### Success Response (200)
- **body** (binary) - The requested asset file.
- **headers** (array) - Custom headers from `TenantAssetController::$headers` (default `[]`).

#### Response Example
Binary file content with appropriate Content-Type header.

#### Error Responses
- **404** - Returned when `path` is empty/null, storage root missing, file doesn't exist, path escapes the asset root, or any `Throwable` occurs while serving.

### Example
```php
$url = route('stancl.tenancy.asset', ['path' => 'uploads/logo.png']);
// "GET /tenancy/assets/uploads/logo.png" streams storage/tenant{key}/app/public/uploads/logo.png
```
```

--------------------------------

### Run callback in tenant context

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/tenancy.md

Shows using run() to execute a callback in a tenant's context. The context is reverted even if the callback throws, due to the finally block. If the callback returns a PendingDispatch, null is returned instead.

```php
$count = $tenant->run(fn () => User::count()); // atomic: reverts to previous context afterwards

// Context is reverted even if the callback throws (finally block)
try {
    $tenant->run(function () {
        throw new RuntimeException('boom');
    });
} catch (RuntimeException $e) {
    // tenancy context has already been restored
}
```

--------------------------------

### Catch existing symlink exception

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/jobs-actions.md

Example of catching the exception thrown when a symlink already exists and force is false. The error message is shown in the comment.

```php
try {
    $action($tenant);
} catch (Exception $e) {
    // "The [public/storage/tenant1] link already exists."
}
```

--------------------------------

### Configure Docker for Apple Silicon

Source: https://github.com/archtechx/tenancy/blob/master/CONTRIBUTING.md

Symlinks docker-compose-m1.override.yml to docker-compose.override.yml to reconfigure services for Apple Silicon (M1).

```bash
composer docker-m1
```

--------------------------------

### Dispatch CreateDatabase and pipeline usage

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/jobs-actions.md

Shows how to dispatch `CreateDatabase` directly and how to use it in a job pipeline with `MigrateDatabase`.

```php
CreateDatabase::dispatch($tenant);

// Pipeline usage:
use Stancl\JobPipeline\JobPipeline;
JobPipeline::make([CreateDatabase::class, MigrateDatabase::class])->send($tenant)->then(fn () => ...)->dispatch();
```

--------------------------------

### Using TableRLSManager with $scopeByDefault false

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/rls-policy-managers.md

Shows how to set $scopeByDefault to false and call generateQueries and shortestPaths. The comment shows an example output path structure.

```php
TableRLSManager::$scopeByDefault = false;

$queries = app(TableRLSManager::class)->generateQueries();
$paths = app(TableRLSManager::class)->shortestPaths();
// ["posts" => [["localColumn" => "tenant_id", "foreignTable" => "tenants", "foreignColumn" => "id"]]]
```

--------------------------------

### Configuring FortifyRouteBootstrapper

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/bootstrappers-config.md

Shows how to configure the FortifyRouteBootstrapper by setting the $fortifyRedirectMap to redirect 'password.confirm' to 'tenant.password.confirm' and enabling $passTenantParameter for path or query identification.

```php
FortifyRouteBootstrapper::$fortifyRedirectMap = [
    'password.confirm' => 'tenant.password.confirm',
];
FortifyRouteBootstrapper::$passTenantParameter = true; // for path/query identification
```

--------------------------------

### PreventAccessFromUnwantedDomains: Custom abort behavior

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/middleware.md

Set the static $abortRequest property to customize the response when access is blocked. The example returns a 403 Forbidden response.

```php
PreventAccessFromUnwantedDomains::$abortRequest = function ($request, $next) {
    return response('Forbidden', 403);
};
```

--------------------------------

### Configure InitializeTenancyBySubdomain subdomain index and onFail

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/middleware.md

Shows how to configure the middleware: set $subdomainIndex to 1 when the hostname is prefixed with 'www', and provide a closure for $onFail that redirects to the central domain when a NotASubdomainException occurs.

```php
InitializeTenancyBySubdomain::$subdomainIndex = 1; // e.g. 'www.acme.example.com'

InitializeTenancyBySubdomain::$onFail = function (NotASubdomainException $e, $request, $next) {
    return redirect('https://central.example.com');
};
```

--------------------------------

### Get identification middleware classes

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/tenancy.md

Returns the identification middleware classes from the tenancy configuration. Use this to retrieve all middleware classes that identify the tenant for the current request.

```php
/**
 * @return array<class-string<Middleware\IdentificationMiddleware>>
 */
public static function middleware(): array
```

--------------------------------

### DatabaseTenancyBootstrapper class skeleton

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/bootstrappers-core.md

Shows the class structure and key methods of DatabaseTenancyBootstrapper. The bootstrap method throws an exception if the template connection has a URL, verifies the tenant database exists in local/testing, connects to the tenant, and optionally hardens. The revert method reconnects to central.

```php
class DatabaseTenancyBootstrapper implements TenancyBootstrapper
{
    /** When true, throw an exception if a tenant gets connected to another tenant's database or to the central database. */
    public static bool $harden = false;

    public function __construct(DatabaseManager $database)

    public function bootstrap(Tenant $tenant): void
    public function revert(): void
}
```

--------------------------------

### TelescopeTags: Tag entries with tenant:{id}

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/features.md

Comment indicating that Telescope entries are tagged with 'tenant:{id}' when tenancy is initialized. The feature is a no-op if Laravel Telescope is not installed.

```php
// Every Telescope entry in tenant context gets tagged 'tenant:{id}'
```

--------------------------------

### GET /{tenant}/tenancy/assets/{path?}

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/endpoints.md

Tenant asset route that serves files from the tenant's storage `app/public` directory or a configured public disk, with tenant identification.

```APIDOC
## [GET] /{tenant}/tenancy/assets/{path?}

### Description
Serves an asset file from the tenant's storage `app/public` directory (or a configured public disk) in the tenant context. The route is registered when `config('tenancy.routes')` is `true`.

### Method
GET

### Endpoint
`/{tenant_parameter_name}/tenancy/assets/{path?}` - prefix uses `PathTenantResolver::tenantParameterName()` (default `'tenant'`), so `/{tenant}/tenancy/assets/{path?}`; `{path}` matches `(.*)`

### Parameters
#### Path Parameters
- **tenant** (string) - Required - Tenant key; used for path identification before the controller runs.
- **path** (string) - Optional - File path relative to the asset root. Default `null` results in a `404`.

### Response
#### Success Response (200)
- **body** (binary) - The requested asset file.
- **headers** (array) - Custom headers from `TenantAssetController::$headers` (default `[]`).

#### Response Example
Binary file content with appropriate Content-Type header.

#### Error Responses
- **404** - Returned when `path` is empty/null, storage root missing, file doesn't exist, path escapes the asset root, or any `Throwable` occurs while serving.

### Example
```php
$url = route('tenant.stancl.tenancy.asset', ['tenant' => $tenantKey, 'path' => 'uploads/logo.png']);
// "GET /{tenant}/tenancy/assets/uploads/logo.png" streams storage/tenant{key}/app/public/uploads/logo.png
```
```

--------------------------------

### Run tenants:rollback with step and tenant options

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/commands.md

Rolls back tenant database migrations. Applies the same tenant options and --skip-failing as the base command. Fires RollingBackDatabase and DatabaseRolledBack events. Ignores --seed, --seeder, --isolated, and --schema-path from migration_parameters.

```php
php artisan tenants:rollback --step=2 --tenants=acme
```

--------------------------------

### Get default identification middleware class

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/tenancy.md

Returns the default identification middleware class from the tenancy configuration. Used by components like TenantAssetController when no specific middleware is set.

```php
/**
 * @return class-string<Middleware\IdentificationMiddleware>
 */
public static function defaultMiddleware(): string
```

--------------------------------

### PathTenantResolver usage with custom config

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/resolvers.md

Example usage with a custom tenant parameter name and model column. The route uses the 'team' parameter and the resolver returns the slug value 'acme'.

```php
// With this config:
// 'tenant_parameter_name' => 'team', 'tenant_model_column' => 'slug',
// 'allowed_extra_model_columns' => ['slug']
Route::get('/{team}/dashboard', DashboardController::class)->middleware(InitializeTenancyByPath::class);

$slug = PathTenantResolver::tenantParameterValue($tenant); // 'acme'
```

--------------------------------

### Use BelongsToPrimaryModel trait and scope-bypassing macros

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/models.md

Example model using the BelongsToPrimaryModel trait, which requires implementing getRelationshipToPrimaryModel(). Also shows the withoutTenancy() and withoutParentModel() macros to bypass the respective scopes.

```php
class PostComment extends Model
{
    use BelongsToPrimaryModel; // requires getRelationshipToPrimaryModel()

    public function getRelationshipToPrimaryModel(): string
    {
        return 'post';
    }
}

Post::withoutTenancy()->get();       // TenantScope macro
PostComment::withoutParentModel()->get(); // ParentModelScope macro
```

--------------------------------

### List all tenants with `tenants:list`

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/commands.md

Lists all tenants with their key name and domains. Uses the `domains` relation or `domain` property for `SingleDomainTenant`.

```bash
php artisan tenants:list
```

--------------------------------

### connection(): array

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/database-manager.md

Returns the tenant's own DB connection config: the template connection merged with $tenantConfig, processed by the manager's makeConnectionConfig() with the database name. This is what gets stored as database.connections.tenant.

```php
public function connection(): array
```

--------------------------------

### static model(): Tenant&Model

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/tenancy.md

Returns a fresh instance of the configured tenant model class.

```APIDOC
## static model(): Tenant&Model

### Description
Returns a fresh instance of the configured tenant model class.

### Method
model

### Endpoint
Tenancy::model()

### Parameters
None

### Request Example
```php
$tenantClass = get_class(Tenancy::model()); // Stancl\Tenancy\Database\Models\Tenant (default)
```

### Response
#### Success Response
- **Tenant&Model** - A fresh instance of the configured tenant model.

```

--------------------------------

### Configure and generate queries with TraitRLSManager

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/rls-policy-managers.md

Example configuration and usage of TraitRLSManager. Sets additional model directories, excludes a model class, enables implicit RLS, and generates queries by resolving the manager from the container.

```php
TraitRLSManager::$modelDirectories = ['app/Models', 'app/Domain']; // extra locations
TraitRLSManager::$excludedModels = [\App\Models\AuditLog::class];
TraitRLSManager::$implicitRLS = true; // scope all tenant tables via RLS

$queries = app(TraitRLSManager::class)->generateQueries();
```

--------------------------------

### InitializeTenancyByDomain class

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/middleware.md

Concrete middleware that initializes tenancy based on the request host. Uses the UsableWithEarlyIdentification trait, skips when shouldBeSkipped(), and throws TenantCouldNotBeIdentifiedOnDomainException for unknown domains.

```php
class InitializeTenancyByDomain extends IdentificationMiddleware
{
    use UsableWithEarlyIdentification;

    public static ?Closure $onFail = null;

    public function __construct(
        protected Tenancy $tenancy,
        protected DomainTenantResolver $resolver,
    ) {}

    /** @return \Illuminate\Http\Response|mixed */
    public function handle(Request $request, Closure $next): mixed
    public function requestHasTenant(Request $request): bool
    public function getDomain(Request $request): string
}
```

--------------------------------

### StatefulTenantDatabaseManager interface

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/types.md

Extends TenantDatabaseManager to add methods for getting and setting the database connection used by the manager. The setConnection method throws a NoConnectionSetException if no connection is set. This interface is implemented by the abstract TenantDatabaseManager base class.

```php
interface StatefulTenantDatabaseManager extends TenantDatabaseManager
{
    /** Get the DB connection used by the tenant database manager. */
    public function connection(): Connection;

    /**
     * Set the DB connection that should be used by the tenant database manager.
     *
     * @throws NoConnectionSetException
     */
    public function setConnection(string $connection): void;
}
```

--------------------------------

### Run tenants:dump with tenant and prune options

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/commands.md

Dumps the schema of one tenant into config('tenancy.migration_parameters.--schema-path') (database/schema/tenant-schema.dump). The --tenant option selects the tenant (defaults to current, then asks, then first tenant). --prune deletes database/migrations/tenant after dumping. Runs inside tenancy()->run(...).

```php
php artisan tenants:dump --tenant=acme
```

```php
php artisan tenants:dump --tenant=acme --prune
```

--------------------------------

### Custom database name and password generators

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/database-manager.md

Example usage of the static setters to customize database name and password generation. The first sets a database name prefix 'db_', the second generates a random 32-character password.

```php
DatabaseConfig::generateDatabaseNamesUsing(fn ($tenant, $config) => 'db_' . $tenant->getTenantKey());
DatabaseConfig::generatePasswordsUsing(fn ($tenant, $config) => Str::random(32));
```

--------------------------------

### InitializeTenancyByPath middleware class structure

Source: https://github.com/archtechx/tenancy/blob/master/_autodocs/api-reference/middleware.md

Defines the constructor and method signatures for the InitializeTenancyByPath middleware. The handle method initializes tenancy from the route's tenant parameter or throws RouteIsMissingTenantParameterException if the parameter is missing. requestHasTenant checks if the matched route has the tenant parameter.

```php
public function __construct(
    protected Tenancy $tenancy,
    protected PathTenantResolver $resolver,
) {}

/** @return \Illuminate\Http\Response|mixed */
public function handle(Request $request, Closure $next): mixed
public function requestHasTenant(Request $request): bool
```
Tokens:
Raw