tenancy/resources/boost/skills/laravel-tenancy/references/package.md

# Tenancy Package Reference

This reference is for package-specific details that do not need to live in `SKILL.md`.


## Focused References

Load these smaller references for topic-specific work:

- `installation.md` for install, publishing, and setup checks
- `configuration.md` for `config/tenancy.php` sections
- `identification.md` for middleware and resolvers
- `routing-assets.md` for tenant routes, route modes, cloned routes, and asset routes
- `context-api.md` for `tenancy()`, `tenant()`, `run()`, and `central()` behavior
- `bootstrappers.md` for tenant-aware Laravel service scoping
- `database-tenancy.md` for database isolation and tenant database managers
- `migrations-commands.md` for tenant Artisan commands
- `models-domains.md` for tenant/domain models and single-database traits
- `filesystem-cache-queue.md` for storage, cache, sessions, Redis, and queues
- `lifecycle-jobs.md` for events, provisioning, and cleanup pipelines
- `resource-syncing.md` for synced central and tenant resources
- `impersonation.md` for tenant user impersonation
- `pending-tenants.md` for pending tenant pools
- `rls.md` for PostgreSQL row-level security
- `features.md` for optional package features
- `integrations.md` for URL, mail, broadcasting, Fortify, Scout, Livewire, Telescope, and Vite
- `testing.md` for test coverage guidance

## Main Entry Points

- `src/TenancyServiceProvider.php`
- `src/Tenancy.php`
- `assets/config.php`
- `assets/routes.php`
- `src/helpers.php`

## Published Files

The package publishes:

- `config/tenancy.php`
- `routes/tenant.php`
- `app/Providers/TenancyServiceProvider.php`
- `database/migrations/2019_09_15_000010_create_tenants_table.php`
- `database/migrations/2019_09_15_000020_create_domains_table.php`
- impersonation migrations
- resource syncing migrations

`tenancy:install` also creates `database/migrations/tenant`.

## Service Provider Behavior

`TenancyServiceProvider`:

- merges `assets/config.php` into `tenancy`
- binds `Stancl\Tenancy\Database\DatabaseManager` as a singleton
- binds `Stancl\Tenancy\Tenancy` as a singleton
- binds the current tenant to the `Stancl\Tenancy\Contracts\Tenant` contract
- binds the current domain to the `Stancl\Tenancy\Contracts\Domain` contract
- registers configured bootstrappers as singletons
- binds the configured unique ID generator to `UniqueIdentifierGenerator`
- registers package commands
- publishes config, routes, provider, and migrations
- loads package asset routes when `tenancy.routes` is enabled
- boots configured features through `tenancy()->bootstrapFeatures()`
- registers middleware groups: `clone`, `universal`, `tenant`, `central`

## Core Runtime API

`Stancl\Tenancy\Tenancy` exposes:

- `initialize(Tenant|int|string $tenant): void`
- `run(Tenant $tenant, Closure $callback): mixed`
- `central(Closure $callback): mixed`
- `end(): void`
- `reinitialize(): void`
- `bootstrapFeatures(): void`
- `getBootstrappers(): array`
- `find(int|string $id, ?string $column = null, bool $withRelations = false)`

Use these runtime methods instead of rolling your own context switch logic.

## Default Models

From `assets/config.php`:

- `tenancy.models.tenant` => `Stancl\Tenancy\Database\Models\Tenant`
- `tenancy.models.domain` => `Stancl\Tenancy\Database\Models\Domain`
- `tenancy.models.impersonation_token` => `Stancl\Tenancy\Database\Models\ImpersonationToken`

The default tenant key relation column is `tenant_id`.

## Tenant ID Generators

Supported generators exposed in config:

- `UUIDGenerator`
- `ULIDGenerator`
- `UUIDv7Generator`
- `RandomHexGenerator`
- `RandomIntGenerator`
- `RandomStringGenerator`

Set `tenancy.models.id_generator` to `null` only when the app intentionally uses auto-incrementing tenant IDs.

## Identification Middleware

Available middleware:

- `InitializeTenancyByDomain`
- `InitializeTenancyBySubdomain`
- `InitializeTenancyByDomainOrSubdomain`
- `InitializeTenancyByPath`
- `InitializeTenancyByRequestData`
- `InitializeTenancyByOriginHeader`
- `PreventAccessFromUnwantedDomains`
- `CheckTenantForMaintenanceMode`
- `ScopeSessions`

All package identification middleware inherit package failure handling through `IdentificationMiddleware::initializeTenancy()`. Failed identification throws a package exception unless an `onFail` callback is registered.

## Resolvers

Resolvers configured in `tenancy.identification.resolvers`:

- `DomainTenantResolver`
- `PathTenantResolver`
- `RequestDataTenantResolver`

Resolver config includes:

- cache enablement
- cache TTL
- cache store
- path tenant parameter name
- route name prefix
- request header, cookie, and query parameter names
- custom tenant model lookup column

## Default Bootstrappers

Enabled by default:

- `DatabaseTenancyBootstrapper`
- `CacheTenancyBootstrapper`
- `FilesystemTenancyBootstrapper`
- `QueueTenancyBootstrapper`
- `DatabaseSessionBootstrapper`

Optional bootstrappers:

- `CacheTagsBootstrapper`
- `DatabaseCacheBootstrapper`
- `RedisTenancyBootstrapper`
- `TenantConfigBootstrapper`
- `RootUrlBootstrapper`
- `UrlGeneratorBootstrapper`
- `MailConfigBootstrapper`
- `BroadcastingConfigBootstrapper`
- `BroadcastChannelPrefixBootstrapper`
- `Bootstrappers\Integrations\FortifyRouteBootstrapper`
- `Bootstrappers\Integrations\ScoutPrefixBootstrapper`
- `PostgresRLSBootstrapper`
- `PersistentQueueTenancyBootstrapper`

## Bootstrapper Semantics

- `DatabaseTenancyBootstrapper`
  switches the active database connection into tenant context and reverts back to the central connection.
- `CacheTenancyBootstrapper`
  scopes supported cache stores by prefix and can also scope cache-backed sessions.
- `CacheTagsBootstrapper`
  is the older tag-based cache isolation approach and is less complete than prefix-based cache scoping.
- `DatabaseCacheBootstrapper`
  scopes cache by moving database-backed cache stores onto the tenant connection instead of using prefixes.
- `FilesystemTenancyBootstrapper`
  suffixes `storage_path()`, rewrites configured local disk roots, can scope file cache and file sessions, and can enable tenant-aware asset URLs.
- `QueueTenancyBootstrapper`
  injects `tenant_id` into queued job payloads and re-initializes tenancy around queue job execution.
- `PersistentQueueTenancyBootstrapper`
  is the queue bootstrapper variant for cases where worker processes should stay tenant-aware across jobs.
- `DatabaseSessionBootstrapper`
  makes the database session driver use the tenant connection.
- `RedisTenancyBootstrapper`
  sets Redis connection prefixes for configured direct Redis connections.
- `TenantConfigBootstrapper`
  maps tenant attributes into arbitrary config keys during tenancy.
- `RootUrlBootstrapper`
  overrides `app.url` and the URL generator root URL, primarily for CLI URL generation in tenant context.
- `UrlGeneratorBootstrapper`
  swaps in `TenancyUrlGenerator` so route names and tenant parameters are generated correctly for path or query-string identification.
- `MailConfigBootstrapper`
  maps tenant attributes into mail configuration at runtime.
- `BroadcastingConfigBootstrapper`
  maps tenant-specific broadcaster credentials into broadcasting config and swaps in a tenancy-aware broadcast manager.
- `BroadcastChannelPrefixBootstrapper`
  prefixes actual broadcast channel names with the tenant key for supported broadcasters.
- `Bootstrappers\Integrations\FortifyRouteBootstrapper`
  rewrites Fortify redirect targets so tenant auth flows can land on tenant routes.
- `Bootstrappers\Integrations\ScoutPrefixBootstrapper`
  sets `scout.prefix` to the tenant key.
- `PostgresRLSBootstrapper`
  swaps the tenant connection to the configured PostgreSQL RLS user and session variable model.

## Database Isolation Options

The config supports:

- separate tenant databases
- PostgreSQL schema isolation
- optional permission-controlled database managers
- PostgreSQL RLS

Database manager mappings exist for:

- `sqlite`
- `mysql`
- `mariadb`
- `pgsql`
- `sqlsrv`

`tenancy.database.drop_tenant_databases_on_migrate_fresh` controls whether `migrate:fresh` also drops tenant databases through the package override.

## Cache, Filesystem, Queue, And Session Scoping

Important config sections:

- `tenancy.cache`
- `tenancy.filesystem`
- `tenancy.redis`
- `tenancy.migration_parameters`
- `tenancy.seeder_parameters`

Notable filesystem behavior:

- local disks can have tenant-specific root overrides
- `Storage::disk()->url()` can be overridden with tenant-aware public names
- `storage_path()` can be suffixed per tenant
- file cache and file sessions can be scoped
- `asset()` tenancy can be enabled, but may affect packages that assume global assets

## Routes

`assets/routes.php` registers:

- `/tenancy/assets/{path?}` named `stancl.tenancy.asset`
- `/{tenant}/tenancy/assets/{path?}` named `tenant.stancl.tenancy.asset` for path identification, behind the `tenant` middleware

The package route mode enum is `Stancl\Tenancy\Enums\RouteMode`, with central as the default route mode in config.

The service provider also registers empty middleware groups named:

- `clone`
- `universal`
- `tenant`
- `central`

These route modes and middleware groups are part of the package routing model and should be preferred over ad hoc tenant-versus-central route branching.

## Optional Features

Feature classes shipped in `src/Features`:

- `CrossDomainRedirect`
- `DisallowSqliteAttach`
- `TelescopeTags`
- `TenantConfig`
- `UserImpersonation`
- `ViteBundler`

Features bootstrap independently from tenant initialization and are intended to be enabled through `tenancy.features`.

Feature behavior:

- `CrossDomainRedirect`
  adds a `RedirectResponse::domain(string $domain)` macro that swaps the redirect host without rebuilding the whole URL.
- `DisallowSqliteAttach`
  blocks SQLite `ATTACH` usage by registering an authorizer on SQLite PDO connections, using a native authorizer on PHP 8.5+ and a loadable extension fallback on older runtimes.
- `TelescopeTags`
  adds a `tenant:{tenantKey}` Telescope tag when tenancy is initialized.
- `TenantConfig`
  maps tenant attributes into config values using event listeners. This feature is deprecated in favor of `TenantConfigBootstrapper`.
- `UserImpersonation`
  adds a `tenancy()->impersonate()` macro, stores impersonation tokens in the configured impersonation token model, validates token TTL and tenant match, logs the user in with the configured guard, and exposes `isImpersonating()` plus `stopImpersonating()`.
- `ViteBundler`
  configures Vite asset path generation to use `global_asset()` so asset URLs stay central rather than tenant-scoped.

## Pending Tenants

Pending tenant support is configured under `tenancy.pending`.

Important behavior:

- `include_in_queries` controls whether pending tenants are included in normal tenant queries.
- `count` controls the maintained size of the pending-tenant pool.
- the package ships dedicated commands for creating and clearing pending tenants.

If a task touches pre-provisioned tenant pools, inspect the pending-tenant commands and model scopes before implementing custom provisioning logic.

## Commands

Commands registered by `TenancyServiceProvider`:

- `tenancy:install`
- `tenants:up`
- `tenants:run`
- `tenants:down`
- `tenants:link`
- `tenants:seed`
- `tenant:tinker`
- `tenants:migrate`
- `tenants:rollback`
- `tenants:list`
- `tenants:dump`
- `tenants:migrate-fresh`
- `tenants:pending-clear`
- `tenants:pending-create`
- `tenants:purge-impersonation-tokens`
- `tenants:rls`

Prefer these commands over hand-written loops for tenant maintenance tasks.

Command notes:

- `tenancy:install`
  publishes config, routes, service provider, and core migrations, then creates `database/migrations/tenant`.
- `tenants:migrate`
  applies `tenancy.migration_parameters`, supports concurrent execution, and can continue with `--skip-failing`.
- `tenants:rollback`
  rolls back tenant migrations.
- `tenants:migrate-fresh`
  rebuilds tenant schema from scratch.
- `tenants:dump`
  dumps a tenant schema and defaults the dump path from `tenancy.migration_parameters.--schema-path`.
- `tenants:seed`
  uses `tenancy.seeder_parameters`.
- `tenants:run`
  runs arbitrary artisan commands against tenant context.
- `tenant:tinker`
  opens Tinker in a selected tenant context and supports searching by tenant key or domain.
- `tenants:link`
  manages tenant storage symlinks used by tenant-aware public disk URLs.
- `tenants:down` / `tenants:up`
  toggle tenant maintenance mode.
- `tenants:pending-create` / `tenants:pending-clear`
  manage the pending-tenant pool.
- `tenants:purge-impersonation-tokens`
  removes expired impersonation tokens.
- `tenants:rls`
  creates the shared RLS user and row-level-security policies for tenant-related tables.

## Related Subsystems

The package also includes:

- `src/Events/*` for tenancy lifecycle, tenant, domain, database, storage, and pending-tenant events
- `src/Listeners/*` for bootstrapping and reverting context
- `src/Jobs/*` for database and storage lifecycle jobs
- `src/ResourceSyncing/*` for central-to-tenant resource syncing
- `src/RLS/*` for PostgreSQL row-level security support
- `src/Actions/*` for route cloning and storage symlink helpers

When a task touches one of these areas, inspect the relevant namespace before inventing a parallel abstraction in app code.