From fde2bf0cf4f2d2c102b72e358ef510b67fe611d9 Mon Sep 17 00:00:00 2001 From: eramitgupta Date: Tue, 2 Jun 2026 12:33:02 +0530 Subject: [PATCH] Add detailed tenancy references and guidelines to boost resources --- resources/boost/guidelines/core.blade.php | 901 ++++++++++++++++++ resources/boost/skills/tenancy/SKILL.md | 25 +- .../tenancy/references/bootstrappers.md | 42 + .../tenancy/references/configuration.md | 34 + .../skills/tenancy/references/context-api.md | 45 + .../tenancy/references/database-tenancy.md | 36 + .../skills/tenancy/references/features.md | 30 + .../references/filesystem-cache-queue.md | 41 + .../tenancy/references/identification.md | 43 + .../tenancy/references/impersonation.md | 36 + .../skills/tenancy/references/installation.md | 73 ++ .../skills/tenancy/references/integrations.md | 44 + .../tenancy/references/lifecycle-jobs.md | 46 + .../tenancy/references/migrations-commands.md | 56 ++ .../tenancy/references/models-domains.md | 42 + .../skills/tenancy/references/package.md | 24 + .../tenancy/references/pending-tenants.md | 33 + .../tenancy/references/resource-syncing.md | 32 + .../boost/skills/tenancy/references/rls.md | 33 + .../tenancy/references/routing-assets.md | 49 + .../skills/tenancy/references/testing.md | 43 + 21 files changed, 1707 insertions(+), 1 deletion(-) create mode 100644 resources/boost/guidelines/core.blade.php create mode 100644 resources/boost/skills/tenancy/references/bootstrappers.md create mode 100644 resources/boost/skills/tenancy/references/configuration.md create mode 100644 resources/boost/skills/tenancy/references/context-api.md create mode 100644 resources/boost/skills/tenancy/references/database-tenancy.md create mode 100644 resources/boost/skills/tenancy/references/features.md create mode 100644 resources/boost/skills/tenancy/references/filesystem-cache-queue.md create mode 100644 resources/boost/skills/tenancy/references/identification.md create mode 100644 resources/boost/skills/tenancy/references/impersonation.md create mode 100644 resources/boost/skills/tenancy/references/installation.md create mode 100644 resources/boost/skills/tenancy/references/integrations.md create mode 100644 resources/boost/skills/tenancy/references/lifecycle-jobs.md create mode 100644 resources/boost/skills/tenancy/references/migrations-commands.md create mode 100644 resources/boost/skills/tenancy/references/models-domains.md create mode 100644 resources/boost/skills/tenancy/references/pending-tenants.md create mode 100644 resources/boost/skills/tenancy/references/resource-syncing.md create mode 100644 resources/boost/skills/tenancy/references/rls.md create mode 100644 resources/boost/skills/tenancy/references/routing-assets.md create mode 100644 resources/boost/skills/tenancy/references/testing.md diff --git a/resources/boost/guidelines/core.blade.php b/resources/boost/guidelines/core.blade.php new file mode 100644 index 00000000..878494ba --- /dev/null +++ b/resources/boost/guidelines/core.blade.php @@ -0,0 +1,901 @@ + +=== core rules === + +# Stancl Tenancy Guidelines + +These guidelines are for Laravel applications using `stancl/tenancy`. They are based on this package's source, installer, config, stubs, routes, migrations, service provider, commands, bootstrappers, middleware, models, and tests. + +## Package Context + +- Composer package: `stancl/tenancy` +- Purpose: automatic multi-tenancy for Laravel applications +- Service provider: `Stancl\Tenancy\TenancyServiceProvider` +- Facades: `Tenancy`, `GlobalCache` +- Core singleton: `Stancl\Tenancy\Tenancy` +- Database manager singleton: `Stancl\Tenancy\Database\DatabaseManager` +- Current tenant contract binding: `Stancl\Tenancy\Contracts\Tenant` +- Current domain contract binding: `Stancl\Tenancy\Contracts\Domain` +- Default tenant model: `Stancl\Tenancy\Database\Models\Tenant` +- Default domain model: `Stancl\Tenancy\Database\Models\Domain` +- Default impersonation token model: `Stancl\Tenancy\Database\Models\ImpersonationToken` +- Default tenant key relation column: `tenant_id` +- Reserved tenant database connection name: `tenant` +- Default central connection config: `tenancy.database.central_connection`, usually `env('DB_CONNECTION', 'central')` + +## Source Files To Inspect + +Before changing tenancy behavior, inspect the relevant local package files. Do not guess package behavior from memory. + +- `README.md` +- `composer.json` +- `src/TenancyServiceProvider.php` +- `src/Tenancy.php` +- `src/helpers.php` +- `assets/config.php` +- `assets/routes.php` +- `assets/tenant_routes.stub.php` +- `assets/TenancyServiceProvider.stub.php` +- `assets/migrations/*` +- `assets/impersonation-migrations/*` +- `assets/resource-syncing-migrations/*` +- `src/Middleware/*` +- `src/Resolvers/*` +- `src/Bootstrappers/*` +- `src/Commands/*` +- `src/Database/Models/*` +- `src/Database/Concerns/*` +- `src/Database/TenantDatabaseManagers/*` +- `src/Features/*` +- `src/Jobs/*` +- `resources/boost/skills/tenancy/references/package.md` +- `tests/*` for expected behavior + +Use Laravel documentation for framework-level behavior such as service providers, vendor publishing, routes, middleware, migrations, queues, cache, filesystem, database, and testing. + +## Installation Steps + +Follow every installation step. Do not skip setup files or migrations. + +1. Install the package with Composer. + +```bash +composer require stancl/tenancy +``` + +2. Run the package installer. + +```bash +php artisan tenancy:install --no-interaction +``` + +3. Confirm the installer published the config. + +```text +config/tenancy.php +``` + +4. Confirm the installer published tenant routes. + +```text +routes/tenant.php +``` + +5. Confirm the installer published the application tenancy service provider. + +```text +app/Providers/TenancyServiceProvider.php +``` + +6. Confirm the installer published central migrations. + +```text +database/migrations/2019_09_15_000010_create_tenants_table.php +database/migrations/2019_09_15_000020_create_domains_table.php +``` + +7. Confirm the installer created the tenant migration directory. + +```text +database/migrations/tenant +``` + +8. Review and adjust `config/tenancy.php` before running migrations. Decide identification, bootstrappers, database isolation, central domains, route mode, and tenant migration parameters first. + +9. Run central migrations for the main application database. + +```bash +php artisan migrate +``` + +10. Add tenant-specific migrations under `database/migrations/tenant`. + +11. Create tenants using the configured tenant model and attach domains when using domain, subdomain, or domain-or-subdomain identification. + +12. Run tenant migrations after tenants exist. + +```bash +php artisan tenants:migrate +``` + +13. Seed tenant databases only when needed. + +```bash +php artisan tenants:seed +``` + +14. If tenant-aware local public storage URLs are enabled, create tenant symlinks. + +```bash +php artisan tenants:link +``` + +15. Test central routes and tenant routes separately before shipping. + +## Manual Publish Commands + +Prefer `tenancy:install`. Use manual publishing only when intentionally publishing a specific group. + +```bash +php artisan vendor:publish --provider="Stancl\Tenancy\TenancyServiceProvider" --tag=config +php artisan vendor:publish --provider="Stancl\Tenancy\TenancyServiceProvider" --tag=routes +php artisan vendor:publish --provider="Stancl\Tenancy\TenancyServiceProvider" --tag=providers +php artisan vendor:publish --provider="Stancl\Tenancy\TenancyServiceProvider" --tag=migrations +php artisan vendor:publish --provider="Stancl\Tenancy\TenancyServiceProvider" --tag=impersonation-migrations +php artisan vendor:publish --provider="Stancl\Tenancy\TenancyServiceProvider" --tag=resource-syncing-migrations +``` + +## Published Files + +The package publishes these files and directories: + +- `assets/config.php` to `config/tenancy.php` +- `assets/tenant_routes.stub.php` to `routes/tenant.php` +- `assets/TenancyServiceProvider.stub.php` to `app/Providers/TenancyServiceProvider.php` +- `assets/migrations/2019_09_15_000010_create_tenants_table.php` to central migrations +- `assets/migrations/2019_09_15_000020_create_domains_table.php` to central migrations +- `assets/impersonation-migrations/2020_05_15_000010_create_tenant_user_impersonation_tokens_table.php` when user impersonation is used +- `assets/resource-syncing-migrations/2020_05_11_000002_create_tenant_resources_table.php` when resource syncing is used +- `database/migrations/tenant` is created by `tenancy:install` for tenant migrations + +## Installer Behavior + +`php artisan tenancy:install` performs these package-defined steps: + +- Publishes config using tag `config` +- Publishes routes using tag `routes` +- Publishes provider using tag `providers` +- Publishes tenant and domain migrations using tag `migrations` +- Creates `database/migrations/tenant` +- Skips existing files and warns instead of overwriting them +- Shows an interactive GitHub support prompt unless `--no-interaction` is used + +Use `--no-interaction` in automation and agent workflows. + +## Core Config Checklist + +Always review these `config/tenancy.php` sections before implementation: + +- `models.tenant` +- `models.domain` +- `models.impersonation_token` +- `models.tenant_key_column` +- `models.id_generator` +- `identification.central_domains` +- `identification.default_middleware` +- `identification.middleware` +- `identification.domain_identification_middleware` +- `identification.path_identification_middleware` +- `identification.resolvers` +- `bootstrappers` +- `database.central_connection` +- `database.template_tenant_connection` +- `database.tenant_host_connection_name` +- `database.prefix` +- `database.suffix` +- `database.managers` +- `database.drop_tenant_databases_on_migrate_fresh` +- `rls.manager` +- `rls.user.username` +- `rls.user.password` +- `rls.session_variable_name` +- `cache.prefix` +- `cache.stores` +- `cache.scope_sessions` +- `cache.tag_base` +- `filesystem.suffix_base` +- `filesystem.disks` +- `filesystem.root_override` +- `filesystem.url_override` +- `filesystem.scope_cache` +- `filesystem.scope_sessions` +- `filesystem.suffix_storage_path` +- `filesystem.asset_helper_override` +- `redis.prefix` +- `redis.prefixed_connections` +- `features` +- `routes` +- `default_route_mode` +- `pending.include_in_queries` +- `pending.count` +- `migration_parameters` +- `seeder_parameters` + +## Tenant Identification + +Decide the identification strategy before writing routes, middleware, model logic, URLs, tests, or tenant creation flows. + +Built-in identification middleware: + +- `Stancl\Tenancy\Middleware\InitializeTenancyByDomain` +- `Stancl\Tenancy\Middleware\InitializeTenancyBySubdomain` +- `Stancl\Tenancy\Middleware\InitializeTenancyByDomainOrSubdomain` +- `Stancl\Tenancy\Middleware\InitializeTenancyByPath` +- `Stancl\Tenancy\Middleware\InitializeTenancyByRequestData` +- `Stancl\Tenancy\Middleware\InitializeTenancyByOriginHeader` + +Related middleware: + +- `Stancl\Tenancy\Middleware\PreventAccessFromUnwantedDomains` +- `Stancl\Tenancy\Middleware\CheckTenantForMaintenanceMode` +- `Stancl\Tenancy\Middleware\ScopeSessions` + +Rules: + +- Configure `identification.central_domains` correctly for domain and subdomain identification. +- Use `PreventAccessFromUnwantedDomains` only with domain-oriented identification middleware listed in `identification.domain_identification_middleware`. +- For path identification, check `PathTenantResolver::tenantParameterName()` and `identification.resolvers[PathTenantResolver::class]` before changing route parameters. +- For request data identification, configure header, cookie, and query parameter names in `RequestDataTenantResolver` config. +- For origin header identification, verify trusted frontend/origin behavior and failure handling. +- Failed identification throws package exceptions unless an `onFail` callback is registered. +- If custom middleware is added, also add it to the matching config array when the package needs to recognize its category. + +## Tenant Resolvers + +Built-in resolvers: + +- `Stancl\Tenancy\Resolvers\DomainTenantResolver` +- `Stancl\Tenancy\Resolvers\PathTenantResolver` +- `Stancl\Tenancy\Resolvers\RequestDataTenantResolver` + +Resolver guidance: + +- Enable resolver cache only deliberately and invalidate it when domain or tenant lookup data changes. +- Use `cache_ttl` and `cache_store` when resolver caching is enabled. +- For path resolver custom binding fields, configure `allowed_extra_model_columns`. +- For request data resolver, set unused identification channels to `null`. +- Use `tenant_model_column` when lookup should use a custom tenant column instead of the tenant key. + +## Route Setup + +The published `routes/tenant.php` stub uses: + +```php +Route::middleware([ + 'web', + Middleware\InitializeTenancyByDomain::class, + Middleware\PreventAccessFromUnwantedDomains::class, + Middleware\ScopeSessions::class, +])->group(function () { + // Tenant routes... +}); +``` + +The published application `TenancyServiceProvider` loads tenant routes like this: + +- Waits until the app is booted +- Checks `base_path('routes/tenant.php')` +- Applies middleware group `tenant` +- Uses `static::$controllerNamespace` +- Can clone routes as tenant routes through `CloneRoutesAsTenant` + +The package service provider registers empty route middleware groups: + +- `clone` +- `universal` +- `tenant` +- `central` + +Route mode rules: + +- `tenancy.default_route_mode` defaults to `RouteMode::CENTRAL`. +- Override default route mode by applying `central`, `tenant`, or `universal` middleware. +- Keep central and tenant routes explicit. +- Use `routes/tenant.php` for tenant application routes when the published stub is used. +- Use `universal` only for routes that intentionally work in both contexts. +- Do not use ad hoc request host checks when package middleware/route modes cover the behavior. + +## Tenant Asset Routes + +When `tenancy.routes` is true, the package loads `assets/routes.php` and registers: + +- `/tenancy/assets/{path?}` named `stancl.tenancy.asset` +- `/{tenant}/tenancy/assets/{path?}` named `tenant.stancl.tenancy.asset` for path identification, behind `tenant` middleware + +Guidance: + +- Disable `tenancy.routes` only if using external storage or a custom asset controller. +- If `filesystem.url_override` is used for local disks, run `php artisan tenants:link`. +- For global assets, use global asset helpers when `filesystem.asset_helper_override` is enabled. +- Prefer explicit `tenant_asset()` calls for tenant-specific assets when global packages call `asset()` internally. + +## Tenant Context API + +Use package APIs for context switching. Do not manually mutate Laravel globals. + +```php +tenancy()->initialize($tenant); + +tenancy()->end(); + +tenancy()->reinitialize(); + +$tenant->run(function () { + // Code runs in tenant context. +}); + +tenancy()->central(function () { + // Code runs in central context and then safely reverts. +}); +``` + +Important runtime behavior: + +- `initialize()` accepts a tenant model, tenant ID, or tenant key string. +- `initialize()` ends the previous tenant context before switching to a different tenant. +- `run()` is atomic and reverts to the previous tenant or central context in `finally`. +- `central()` is atomic and restores the previous tenant context when finished. +- `reinitialize()` is useful when tenant attributes used by bootstrappers changed during a request. +- `bootstrapFeatures()` is idempotent for features already bootstrapped, but feature bootstrapping is irreversible. +- `tenancy()->find($id, $column = null, $withRelations = false)` uses the configured tenant model. +- `Tenancy::tenantKeyColumn()` reads `tenancy.models.tenant_key_column` and defaults to `tenant_id`. + +## Helpers And Facades + +Use package helpers and facades where appropriate: + +- `tenancy()` for the `Tenancy` singleton +- `tenant()` for current tenant access and tenant attribute lookup +- `central()` for central-context execution +- `globalCache()` or `GlobalCache` for cache that should remain central +- `global_asset()` when asset helper tenancy is enabled and the asset should remain global +- `tenant_asset()` for tenant-specific local assets +- `Tenancy` facade for the tenancy manager +- `GlobalCache` facade for central cache access + +## Bootstrappers + +Default bootstrappers in `assets/config.php`: + +- `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 rules: + +- Configure bootstrappers before writing application workarounds. +- Do not manually change DB connections, cache prefixes, filesystem roots, queue payloads, Redis prefixes, URL roots, or mail/broadcasting config when a bootstrapper owns it. +- `DatabaseCacheBootstrapper` must run after `DatabaseTenancyBootstrapper`. +- `RedisTenancyBootstrapper` needs phpredis and is for direct Redis calls, not normal cache-only Redis usage. +- `TenantConfigBootstrapper` should be preferred over the deprecated `TenantConfig` feature. +- `RootUrlBootstrapper` affects CLI URL generation in tenant context. +- `UrlGeneratorBootstrapper` is important for path/query-string route generation. +- If tenant state appears partially applied, inspect `tenancy()->getBootstrappers()` and `tenancy.bootstrappers`. + +## Database Tenancy + +Database config supports: + +- separate tenant databases +- PostgreSQL schema isolation +- permission-controlled tenant database users +- SQLite tenant database management +- MySQL/MariaDB tenant database management +- PostgreSQL tenant database management +- SQL Server tenant database management +- PostgreSQL RLS for single-database tenancy + +Rules: + +- `tenant` is a reserved dynamic connection name; do not use it as the template tenant connection name. +- Use `database.template_tenant_connection` for the tenant connection template. +- Use `database.tenant_host_connection_name` for temporary creation/deletion connection behavior. +- Tenant database names are generated as `prefix + tenant_id + suffix`. +- Use permission-controlled managers only when tenant-specific DB users are required. +- For PostgreSQL schemas, swap the pgsql manager to a schema manager instead of a database manager. +- `database.drop_tenant_databases_on_migrate_fresh` controls package behavior for `migrate:fresh` through the package override. + +## Central Migrations + +The base central migrations create: + +- `tenants` table with string primary `id`, timestamps, and nullable JSON `data` +- `domains` table with integer `id`, unique `domain`, tenant key column, timestamps, and foreign key to `tenants.id` + +Guidance: + +- Add custom tenant columns to the `tenants` migration before running it. +- If using auto-increment tenant IDs, set `models.id_generator` to `null` and update the tenants migration primary key accordingly. +- Keep domain values unique and lowercase behavior in mind; the default domain model converts domains to lowercase. +- The domains migration uses `Tenancy::tenantKeyColumn()` for the tenant foreign key. + +## Tenant Migrations And Seeders + +Tenant migrations are configured by `tenancy.migration_parameters`: + +- `--force` defaults to true +- `--path` defaults to `database/migrations/tenant` +- `--schema-path` defaults to `database/schema/tenant-schema.dump` +- `--realpath` defaults to true + +Tenant seeders are configured by `tenancy.seeder_parameters`: + +- `--class` defaults to `Database\Seeders\DatabaseSeeder` + +Rules: + +- Put tenant database migrations in `database/migrations/tenant` by default. +- Use `php artisan tenants:migrate` for tenant migrations. +- Use `php artisan tenants:rollback` for tenant rollback. +- Use `php artisan tenants:migrate-fresh` for tenant migrate fresh behavior. +- Use `php artisan tenants:seed` for tenant seeders. +- Do not run normal Laravel migrations expecting them to apply to tenant databases. +- Review `migration_parameters` and `seeder_parameters` before changing command calls. +- Use `--tenants=*` options when only specific tenants should be affected. +- Use `--skip-failing` deliberately when tenant migration failures should not stop the whole command. +- Use `--processes` only after confirming database and application code are safe for concurrent tenant operations. + +## Tenant Models + +Default tenant model traits include: + +- `VirtualColumn` +- `CentralConnection` +- `GeneratesIds` +- `HasInternalKeys` +- `TenantRun` +- `InitializationHelpers` +- `InvalidatesResolverCache` + +Default tenant model behavior: + +- table: `tenants` +- primary key: `id` +- guarded: empty array +- dispatches creating, created, saving, saved, updating, updated, deleting, deleted tenant events +- `Tenant::current()` returns current tenant +- `Tenant::currentOrFail()` throws if tenancy is not initialized +- tenant collection class: `Stancl\Tenancy\Database\TenantCollection` + +Guidance: + +- Use the configured tenant model from `config('tenancy.models.tenant')`. +- If replacing the tenant model, implement `Stancl\Tenancy\Contracts\Tenant`. +- Preserve package traits unless there is a specific tested reason to replace them. +- Use tenant model events and the published application service provider's pipelines for provisioning. + +## Domain Models + +Default domain model traits include: + +- `CentralConnection` +- `EnsuresDomainIsNotOccupied` +- `ConvertsDomainsToLowercase` +- `InvalidatesTenantsResolverCache` + +Default domain model behavior: + +- guarded: empty array +- belongs to the configured tenant model using `Tenancy::tenantKeyColumn()` +- dispatches creating, created, saving, saved, updating, updated, deleting, deleted domain events + +Guidance: + +- Use domains for domain/subdomain/domain-or-subdomain identification. +- Do not bypass domain uniqueness checks. +- Ensure domain cache invalidates when domain or tenant lookup data changes. + +## Single-Database Tenancy + +For single-database tenancy, use package traits and scopes instead of hand-written tenant filters. + +Relevant concerns: + +- `BelongsToTenant` +- `FillsCurrentTenant` +- `TenantConnection` +- `CentralConnection` +- `TenantScope` +- `HasScopedValidationRules` +- `RLSModel` when PostgreSQL RLS is used + +Rules: + +- Apply tenant scoping consistently to tenant-owned models. +- Make tenant-owned models fill the current tenant key automatically where appropriate. +- Test central resources and tenant resources separately. +- For PostgreSQL RLS, configure `rls.user`, `rls.manager`, and `rls.session_variable_name`, then use package RLS commands/policies. + +## Resource Syncing + +Resource syncing assets include: + +- migration: `tenant_resources` +- events in `Stancl\Tenancy\ResourceSyncing\Events` +- listeners in `Stancl\Tenancy\ResourceSyncing\Listeners` +- traits/classes such as `ResourceSyncing`, `SyncMaster`, `Syncable`, `TenantPivot`, `TenantMorphPivot` + +Guidance: + +- Publish `resource-syncing-migrations` before using resource syncing. +- Keep central resource and tenant resource lifecycles explicit. +- Use package events/listeners from the published provider instead of custom sync loops. +- If soft-deleted synced resources are needed, configure the listener query scope in the application `TenancyServiceProvider` as shown in the stub. + +## User Impersonation + +User impersonation uses: + +- feature: `Stancl\Tenancy\Features\UserImpersonation` +- model: `Stancl\Tenancy\Database\Models\ImpersonationToken` +- migration: `tenant_user_impersonation_tokens` +- command: `tenants:purge-impersonation-tokens` + +Guidance: + +- Publish `impersonation-migrations` before enabling impersonation. +- Enable the `UserImpersonation` feature in `tenancy.features`. +- Run central migrations after publishing the impersonation migration. +- Purge expired tokens with `php artisan tenants:purge-impersonation-tokens`. +- Verify guard, redirect URL, remember flag, tenant match, and token TTL in tests. + +## Pending Tenants + +Pending tenant config: + +- `pending.include_in_queries` +- `pending.count`, defaulting to `TENANCY_PENDING_COUNT` or 5 + +Commands: + +- `php artisan tenants:pending-create` +- `php artisan tenants:pending-create --count=10` +- `php artisan tenants:pending-clear` +- `php artisan tenants:pending-clear --older-than-days=7` +- `php artisan tenants:pending-clear --older-than-hours=12` + +Rules: + +- If `pending.include_in_queries` is false, pending tenants are excluded from tenant queries and tenant commands. +- Use `withPending()`, `withoutPending()`, and `onlyPending()` intentionally when querying pending tenants. +- Do not assume pending tenants are included in migrations or seeds when config excludes them. + +## Tenant Lifecycle And Jobs + +The published application `TenancyServiceProvider` wires lifecycle events to job pipelines. + +Default `TenantCreated` pipeline: + +- `CreateDatabase` +- `MigrateDatabase` +- optional `SeedDatabase` +- optional `CreateStorageSymlinks` +- custom provisioning jobs + +Default deleting/deleted tenant pipelines: + +- `DeleteDomains` during `DeletingTenant` +- optional `DeleteTenantStorage` +- optional `RemoveStorageSymlinks` +- `DeleteDatabase` during `TenantDeleted` +- optional resource-syncing cleanup + +Rules: + +- Add tenant provisioning logic to the event pipeline rather than scattering it through controllers. +- Decide whether pipelines should be queued using `shouldBeQueued()`. +- Keep database creation, migration, seeding, storage, and domain deletion order explicit. +- Test tenant creation and deletion side effects. + +## Filesystem, Storage, And Assets + +Filesystem config controls: + +- tenant storage suffix base +- scoped disks +- local root overrides +- URL overrides +- file cache scoping +- file session scoping +- `storage_path()` suffixing +- `asset()` helper override + +Rules: + +- Keep `suffix_storage_path` enabled for local disk tenancy unless using external storage like S3 and the app is tested without it. +- Add local disks to both `filesystem.disks` and `filesystem.root_override` when root override is needed. +- Use `tenants:link` when `filesystem.url_override` maps local public disks. +- Use `tenants:link --remove` when removing tenant symlinks. +- Use `tenants:link --relative` only when relative symlinks are required by deployment. +- Use `tenants:link --force` when recreating existing symlinks deliberately. +- Be careful with `asset_helper_override`; packages that call `asset()` may unexpectedly become tenant-aware. + +## Cache, Global Cache, Sessions, And Redis + +Cache rules: + +- `CacheTenancyBootstrapper` scopes cache by changing `cache.prefix`. +- `CacheTagsBootstrapper` scopes using tags and is an alternative pattern. +- `DatabaseCacheBootstrapper` scopes database cache by tenant DB connection and must run after database tenancy. +- Use `GlobalCache`/`globalCache()` for cache that must remain central. +- If session driver is cache-based, `cache.scope_sessions` may add the session store to prefixed stores. + +Filesystem session rules: + +- `filesystem.scope_sessions` scopes file sessions under tenant storage. +- Use `ScopeSessions` middleware on tenant routes when session scoping is required. + +Redis rules: + +- `RedisTenancyBootstrapper` is for direct Redis facade/injected Redis usage. +- phpredis is required for Redis tenancy. +- Redis cache alone usually does not need `RedisTenancyBootstrapper`; cache scoping covers cache usage. + +## Queue Behavior + +Queue bootstrappers: + +- `QueueTenancyBootstrapper` +- `PersistentQueueTenancyBootstrapper` + +Rules: + +- Use the queue bootstrapper for tenant-aware queued jobs. +- Do not manually inject tenant IDs into every job if the package bootstrapper already handles payload/context. +- Test queued jobs from central context and tenant context. +- Use the persistent queue bootstrapper only when worker processes intentionally stay tenant-aware across jobs. + +## URL, Routes, Mail, Broadcasting, Fortify, Scout + +Use optional bootstrappers for integration-specific runtime config: + +- `RootUrlBootstrapper` for tenant root URL in CLI/context URL generation +- `UrlGeneratorBootstrapper` for tenant-aware route generation and tenant parameters +- `MailConfigBootstrapper` for tenant mail configuration +- `BroadcastingConfigBootstrapper` for tenant broadcaster credentials +- `BroadcastChannelPrefixBootstrapper` for tenant-prefixed broadcast channel names +- `FortifyRouteBootstrapper` for tenant Fortify route/redirect behavior +- `ScoutPrefixBootstrapper` for tenant-specific Scout prefixes + +Rules: + +- Configure these bootstrappers instead of writing custom service-provider mutations. +- Use the `overrideUrlInTenantContext()` hook in the published application provider for CLI root URL customization. +- For Livewire v3, follow the provider stub pattern to make the Livewire update route universal when needed. + +## Optional Features + +Features are bootstrapped independently from tenant initialization and are enabled via `tenancy.features`. + +Available features: + +- `Stancl\Tenancy\Features\UserImpersonation` +- `Stancl\Tenancy\Features\TelescopeTags` +- `Stancl\Tenancy\Features\CrossDomainRedirect` +- `Stancl\Tenancy\Features\ViteBundler` +- `Stancl\Tenancy\Features\DisallowSqliteAttach` +- `Stancl\Tenancy\Features\TenantConfig` + +Rules: + +- Inspect the feature class before assuming it affects tenant initialization. +- Prefer `TenantConfigBootstrapper` over deprecated `TenantConfig` feature for mapping tenant attributes into config. +- `DisallowSqliteAttach` protects SQLite use by blocking `ATTACH`; verify PHP/version-specific behavior in tests. +- `CrossDomainRedirect` adds redirect domain behavior. +- `TelescopeTags` adds tenant tags when tenancy is initialized. +- `ViteBundler` affects tenant-aware bundling behavior. + +## Artisan Commands + +Use package commands instead of ad hoc loops. + +Installation: + +```bash +php artisan tenancy:install --no-interaction +``` + +Tenant migrations and seeds: + +```bash +php artisan tenants:migrate +php artisan tenants:migrate --tenants=tenant-id +php artisan tenants:migrate --skip-failing +php artisan tenants:rollback +php artisan tenants:migrate-fresh +php artisan tenants:seed +``` + +Run commands in tenant context: + +```bash +php artisan tenants:run cache:clear +php artisan tenants:run "your:command" --tenants=tenant-id +php artisan tenant:tinker +``` + +Tenant maintenance: + +```bash +php artisan tenants:down +php artisan tenants:down --redirect=/maintenance --retry=60 --refresh=60 --secret=secret --status=503 +php artisan tenants:up +``` + +Tenant storage symlinks: + +```bash +php artisan tenants:link +php artisan tenants:link --tenants=tenant-id +php artisan tenants:link --relative +php artisan tenants:link --force +php artisan tenants:link --remove +``` + +Pending tenants: + +```bash +php artisan tenants:pending-create +php artisan tenants:pending-create --count=10 +php artisan tenants:pending-clear +php artisan tenants:pending-clear --older-than-days=7 +php artisan tenants:pending-clear --older-than-hours=12 +``` + +Other package commands: + +```bash +php artisan tenants:list +php artisan tenant:dump +php artisan tenants:purge-impersonation-tokens +php artisan tenants:rls +php artisan tenants:rls --force +``` + +Command rules: + +- Use `php artisan list` or `php artisan help ` to confirm available options in the installed app. +- Use `--tenants=*` when affecting only selected tenants. +- Use tenant commands for tenant databases, not central Laravel migration commands. +- Use `tenants:run` for existing Artisan commands that need tenant context. + +## Maintenance Mode + +Maintenance commands: + +- `tenants:down` +- `tenants:up` + +Related middleware: + +- `CheckTenantForMaintenanceMode` + +Rules: + +- Use tenant maintenance mode when only tenant apps should be unavailable. +- Test bypass secret, redirect, retry, refresh, and status code behavior when configured. +- Do not confuse tenant maintenance with Laravel global maintenance mode. + +## PostgreSQL RLS + +RLS config and classes: + +- `rls.manager` +- `rls.user.username` +- `rls.user.password` +- `rls.session_variable_name` +- `PostgresRLSBootstrapper` +- `RLSModel` +- `TableRLSManager` +- `TraitRLSManager` +- `tenants:rls` + +Rules: + +- Use PostgreSQL and single-database tenancy for RLS. +- Set a namespaced session variable name such as `my.current_tenant`. +- Configure one tenant database user used for all tenants, not one user per tenant. +- Run `php artisan tenants:rls` to create policies/user. +- Use `--force` only when policies should be recreated even if they already exist. +- Test policy coverage on every tenant-owned table. + +## Testing Guidelines + +Every tenancy behavior change must be tested programmatically. + +Test at minimum: + +- installation artifacts exist when testing installer behavior +- central routes remain central +- tenant routes initialize tenancy +- wrong central/tenant access is rejected +- domain, subdomain, path, request-data, or origin-header identification resolves the expected tenant +- identification failure throws or handles the expected package exception +- current tenant is available through `tenant()`, facade, and contract binding when expected +- database connection switches and reverts +- cache keys are scoped or global as intended +- filesystem roots, URLs, and storage paths are scoped as intended +- queues reinitialize tenant context around jobs +- sessions are scoped when configured +- URL generation uses tenant route names and parameters correctly +- tenant migrations, rollbacks, and seeds affect the expected tenants +- tenant creation pipelines create DBs, migrate DBs, seed DBs, create storage, and attach domains as configured +- tenant deletion pipelines delete domains, database, storage, symlinks, and resource mappings as configured +- optional features behave only when enabled +- central context is restored after `run()` and `central()` callbacks + +Use existing package tests as examples: + +- `tests/AutomaticModeTest.php` +- `tests/ManualModeTest.php` +- `tests/RouteMiddlewareTest.php` +- `tests/PathIdentificationTest.php` +- `tests/RequestDataIdentificationTest.php` +- `tests/OriginHeaderIdentificationTest.php` +- `tests/TenantAssetTest.php` +- `tests/CommandsTest.php` +- `tests/QueueTest.php` +- `tests/SingleDatabaseTenancyTest.php` +- `tests/RLS/*` +- `tests/ResourceSyncingTest.php` +- `tests/TenantUserImpersonationTest.php` + +## Implementation Rules + +- Decide identification first. +- Decide database isolation before creating application models. +- Decide bootstrappers before writing workaround code. +- Keep central and tenant routes explicit. +- Use package commands for tenant-aware operations. +- Use package context APIs instead of manual context mutation. +- Use package models, contracts, traits, events, and jobs before adding custom abstractions. +- Keep provisioning in the application `TenancyServiceProvider` event pipelines. +- Review config before changing application code. +- Test both central and tenant behavior for every change. + +## Common Pitfalls + +- Running normal `php artisan migrate` and expecting tenant DBs to migrate +- Forgetting to run `php artisan tenants:migrate` after tenants exist +- Skipping `routes/tenant.php` or the application `TenancyServiceProvider` +- Using the reserved connection name `tenant` as a template connection +- Mixing central and tenant routes without route modes or middleware +- Using `PreventAccessFromUnwantedDomains` with unsupported non-domain identification +- Forgetting `central_domains` for domain/subdomain apps +- Manually changing DB/cache/filesystem/queue/session/url state instead of using bootstrappers +- Enabling `asset_helper_override` without checking third-party packages that call `asset()` +- Enabling resolver caching without invalidation coverage +- Forgetting to publish impersonation or resource-syncing migrations before enabling those features +- Assuming pending tenants are included when `pending.include_in_queries` excludes them +- Using auto-increment tenant IDs without considering enumeration risk +- Adding tenant-owned models in single-database tenancy without tenant scoping +- Not verifying central context after tenant context work + + diff --git a/resources/boost/skills/tenancy/SKILL.md b/resources/boost/skills/tenancy/SKILL.md index 673795d4..b60bcdbb 100644 --- a/resources/boost/skills/tenancy/SKILL.md +++ b/resources/boost/skills/tenancy/SKILL.md @@ -3,7 +3,7 @@ name: tenancy description: "Activate when the user is building or debugging multi-tenant Laravel behavior with stancl/tenancy. Use for tenancy:install, tenant identification middleware, central and tenant routes, tenant model and domain model setup, multi-database or single-database tenancy, tenant-aware bootstrappers for database/cache/filesystem/queue/session/Redis, tenant context switching with tenancy()->initialize() or tenant()->run(), tenant migrations and seeders, tenant asset routes, pending tenants, resource syncing, user impersonation, RLS, Vite bundling, or testing tenant-aware behavior." license: MIT metadata: - author: laravel + author: Samuel Štancl --- # Tenancy For Laravel @@ -28,6 +28,29 @@ Use `search-docs` first when it is available for Laravel integration patterns. F Load `references/package.md` when the task needs package-specific detail beyond the core workflow in this file. +## Feature References + +Load focused references when the task matches a specific package area: + +- `references/installation.md` for install, publishing, and setup checks +- `references/configuration.md` for `config/tenancy.php` sections +- `references/identification.md` for middleware and resolvers +- `references/routing-assets.md` for tenant routes, route modes, cloned routes, and asset routes +- `references/context-api.md` for `tenancy()`, `tenant()`, `run()`, and `central()` behavior +- `references/bootstrappers.md` for tenant-aware Laravel service scoping +- `references/database-tenancy.md` for database isolation and tenant database managers +- `references/migrations-commands.md` for tenant Artisan commands +- `references/models-domains.md` for tenant/domain models and single-database traits +- `references/filesystem-cache-queue.md` for storage, cache, sessions, Redis, and queues +- `references/lifecycle-jobs.md` for events, provisioning, and cleanup pipelines +- `references/resource-syncing.md` for synced central and tenant resources +- `references/impersonation.md` for tenant user impersonation +- `references/pending-tenants.md` for pending tenant pools +- `references/rls.md` for PostgreSQL row-level security +- `references/features.md` for optional package features +- `references/integrations.md` for URL, mail, broadcasting, Fortify, Scout, Livewire, Telescope, and Vite +- `references/testing.md` for test coverage guidance + ## Package Surface The package auto-discovers: diff --git a/resources/boost/skills/tenancy/references/bootstrappers.md b/resources/boost/skills/tenancy/references/bootstrappers.md new file mode 100644 index 00000000..0333b822 --- /dev/null +++ b/resources/boost/skills/tenancy/references/bootstrappers.md @@ -0,0 +1,42 @@ +# Bootstrappers Reference + +Use this when tenant context should affect Laravel services. + +## Source Files + +- `src/Bootstrappers/*` +- `assets/config.php` + +## Defaults + +- `DatabaseTenancyBootstrapper` +- `CacheTenancyBootstrapper` +- `FilesystemTenancyBootstrapper` +- `QueueTenancyBootstrapper` +- `DatabaseSessionBootstrapper` + +## Optional Bootstrappers + +- `CacheTagsBootstrapper` +- `DatabaseCacheBootstrapper` +- `RedisTenancyBootstrapper` +- `TenantConfigBootstrapper` +- `RootUrlBootstrapper` +- `UrlGeneratorBootstrapper` +- `MailConfigBootstrapper` +- `BroadcastingConfigBootstrapper` +- `BroadcastChannelPrefixBootstrapper` +- `FortifyRouteBootstrapper` +- `ScoutPrefixBootstrapper` +- `PostgresRLSBootstrapper` +- `PersistentQueueTenancyBootstrapper` + +## Rules + +- Configure bootstrappers before writing app-level workarounds. +- `DatabaseCacheBootstrapper` must run after `DatabaseTenancyBootstrapper`. +- `RedisTenancyBootstrapper` needs phpredis and is for direct Redis calls. +- Prefer `TenantConfigBootstrapper` over deprecated `TenantConfig` feature. +- Use `RootUrlBootstrapper` for CLI URL root behavior. +- Use `UrlGeneratorBootstrapper` for tenant-aware route generation. +- Inspect `tenancy()->getBootstrappers()` when context looks partially applied. diff --git a/resources/boost/skills/tenancy/references/configuration.md b/resources/boost/skills/tenancy/references/configuration.md new file mode 100644 index 00000000..99deb1aa --- /dev/null +++ b/resources/boost/skills/tenancy/references/configuration.md @@ -0,0 +1,34 @@ +# Configuration Reference + +Use this when changing `config/tenancy.php`. + +## Source Files + +- `assets/config.php` +- `src/TenancyServiceProvider.php` + +## Must-Review Sections + +- `models`: tenant, domain, impersonation token, tenant key column, ID generator. +- `identification`: central domains, default middleware, resolver settings. +- `bootstrappers`: runtime Laravel feature scoping. +- `database`: central connection, template tenant connection, DB managers, prefixes. +- `rls`: PostgreSQL RLS manager, user, and session variable. +- `cache`: prefix, stores, session scoping, tag base. +- `filesystem`: disks, root overrides, URL overrides, storage suffixing, asset override. +- `redis`: direct Redis connection prefixing. +- `features`: optional package features. +- `routes`: package asset route registration toggle. +- `default_route_mode`: central, tenant, or universal default route behavior. +- `pending`: pending tenant query inclusion and pool count. +- `migration_parameters`: tenant migration defaults. +- `seeder_parameters`: tenant seeder defaults. + +## Rules + +- Decide identification, database isolation, and bootstrappers before writing app code. +- Never use `tenant` as the template tenant connection name; it is reserved by the package. +- Set `models.id_generator` to `null` only when using auto-increment tenant IDs intentionally. +- Keep resolver caching disabled until invalidation behavior is tested. +- Keep `database.drop_tenant_databases_on_migrate_fresh` false unless local/dev destructive behavior is intended. +- Enable `filesystem.asset_helper_override` only after checking third-party package asset calls. diff --git a/resources/boost/skills/tenancy/references/context-api.md b/resources/boost/skills/tenancy/references/context-api.md new file mode 100644 index 00000000..d07bcc2f --- /dev/null +++ b/resources/boost/skills/tenancy/references/context-api.md @@ -0,0 +1,45 @@ +# Context API Reference + +Use this when switching between tenant and central contexts. + +## Source Files + +- `src/Tenancy.php` +- `src/helpers.php` +- `src/Database/Concerns/TenantRun.php` +- `src/Database/Concerns/InitializationHelpers.php` + +## Core API + +```php +tenancy()->initialize($tenant); +tenancy()->end(); +tenancy()->reinitialize(); +tenancy()->central(fn () => null); +$tenant->run(fn () => null); +``` + +## Behavior + +- `initialize()` accepts a tenant model, ID, or string key. +- Switching tenants ends the previous context first. +- `run()` restores the previous tenant or central context in `finally`. +- `central()` temporarily ends tenancy and restores prior tenant context. +- `reinitialize()` re-runs bootstrappers for the current tenant. +- `bootstrapFeatures()` is idempotent per feature, but feature bootstrapping is irreversible. +- `find()` resolves tenants through the configured tenant model. + +## Helpers + +- `tenancy()` returns the tenancy singleton. +- `tenant()` returns current tenant or tenant attribute. +- `central()` executes a callback in central context. +- `globalCache()` resolves central cache. +- `tenant_asset()` returns tenant asset URLs. +- `global_asset()` returns global asset URLs. + +## Rules + +- Do not manually mutate DB connections, cache prefixes, filesystem roots, queue payloads, sessions, or URL roots. +- Use atomic `run()` and `central()` when context must be restored safely. +- Test context restoration after exceptions. diff --git a/resources/boost/skills/tenancy/references/database-tenancy.md b/resources/boost/skills/tenancy/references/database-tenancy.md new file mode 100644 index 00000000..13b3c680 --- /dev/null +++ b/resources/boost/skills/tenancy/references/database-tenancy.md @@ -0,0 +1,36 @@ +# Database Tenancy Reference + +Use this when changing tenant database isolation or managers. + +## Source Files + +- `src/Database/DatabaseManager.php` +- `src/Database/DatabaseConfig.php` +- `src/Database/TenantDatabaseManagers/*` +- `src/Bootstrappers/DatabaseTenancyBootstrapper.php` +- `assets/config.php` + +## Supported Isolation + +- Separate tenant databases. +- PostgreSQL schema isolation. +- Permission-controlled tenant database users. +- PostgreSQL RLS for single-database tenancy. + +## Managers + +- SQLite: `SQLiteDatabaseManager` +- MySQL/MariaDB: `MySQLDatabaseManager` +- PostgreSQL: `PostgreSQLDatabaseManager` +- SQL Server: `MicrosoftSQLDatabaseManager` +- Permission-controlled variants for MySQL, PostgreSQL, SQL Server. +- PostgreSQL schema managers for schema isolation. + +## Rules + +- `tenant` is a reserved dynamic connection name. +- Use `database.template_tenant_connection` for the tenant connection template. +- Use `database.tenant_host_connection_name` for database creation/deletion host connection. +- Tenant DB names are `prefix + tenant_id + suffix`. +- Use schema managers only when PostgreSQL schema isolation is intended. +- Test creation, migration, rollback, deletion, and connection restoration. diff --git a/resources/boost/skills/tenancy/references/features.md b/resources/boost/skills/tenancy/references/features.md new file mode 100644 index 00000000..06c70a7c --- /dev/null +++ b/resources/boost/skills/tenancy/references/features.md @@ -0,0 +1,30 @@ +# Optional Features Reference + +Use this when enabling or debugging classes in `tenancy.features`. + +## Source Files + +- `src/Features/*` +- `src/Tenancy.php` + +## Features + +- `UserImpersonation` +- `TelescopeTags` +- `CrossDomainRedirect` +- `ViteBundler` +- `DisallowSqliteAttach` +- `TenantConfig` + +## Behavior + +- Features are bootstrapped independently from tenant initialization. +- `tenancy()->bootstrapFeatures()` is idempotent per feature. +- Feature bootstrapping is irreversible during the request lifecycle. +- `TenantConfig` is deprecated in favor of `TenantConfigBootstrapper`. + +## Rules + +- Inspect the feature class before assuming behavior. +- Enable only the needed features. +- Test each enabled feature in central and tenant contexts where relevant. diff --git a/resources/boost/skills/tenancy/references/filesystem-cache-queue.md b/resources/boost/skills/tenancy/references/filesystem-cache-queue.md new file mode 100644 index 00000000..ae688932 --- /dev/null +++ b/resources/boost/skills/tenancy/references/filesystem-cache-queue.md @@ -0,0 +1,41 @@ +# Filesystem Cache Queue Reference + +Use this when tenant context affects storage, cache, sessions, Redis, or queues. + +## Source Files + +- `src/Bootstrappers/FilesystemTenancyBootstrapper.php` +- `src/Bootstrappers/CacheTenancyBootstrapper.php` +- `src/Bootstrappers/CacheTagsBootstrapper.php` +- `src/Bootstrappers/DatabaseCacheBootstrapper.php` +- `src/Bootstrappers/RedisTenancyBootstrapper.php` +- `src/Bootstrappers/QueueTenancyBootstrapper.php` +- `src/Bootstrappers/PersistentQueueTenancyBootstrapper.php` +- `src/Bootstrappers/DatabaseSessionBootstrapper.php` +- `src/Middleware/ScopeSessions.php` + +## Filesystem + +- `filesystem.disks` controls scoped disks. +- `filesystem.root_override` rewrites local disk roots. +- `filesystem.url_override` enables tenant-aware local public URLs. +- `filesystem.suffix_storage_path` controls `storage_path()` suffixing. +- `filesystem.asset_helper_override` makes `asset()` tenant-aware. + +## Cache And Redis + +- Cache tenancy prefixes configured stores through `cache.prefix`. +- Global central cache is available through `GlobalCache`/`globalCache()`. +- Redis tenancy is for direct Redis usage and requires phpredis. + +## Queue + +- Queue bootstrapper carries tenant context into queued jobs. +- Persistent queue bootstrapper is for workers intentionally staying tenant-aware. + +## Rules + +- Run `php artisan tenants:link` when tenant public local storage URLs are enabled. +- Be careful with `asset_helper_override`; third-party package assets may become tenant-aware. +- Scope sessions through config and `ScopeSessions` middleware where required. +- Test queued jobs in central and tenant contexts. diff --git a/resources/boost/skills/tenancy/references/identification.md b/resources/boost/skills/tenancy/references/identification.md new file mode 100644 index 00000000..787c944e --- /dev/null +++ b/resources/boost/skills/tenancy/references/identification.md @@ -0,0 +1,43 @@ +# Tenant Identification Reference + +Use this when resolving tenants from requests. + +## Source Files + +- `src/Middleware/IdentificationMiddleware.php` +- `src/Middleware/InitializeTenancyByDomain.php` +- `src/Middleware/InitializeTenancyBySubdomain.php` +- `src/Middleware/InitializeTenancyByDomainOrSubdomain.php` +- `src/Middleware/InitializeTenancyByPath.php` +- `src/Middleware/InitializeTenancyByRequestData.php` +- `src/Middleware/InitializeTenancyByOriginHeader.php` +- `src/Middleware/PreventAccessFromUnwantedDomains.php` +- `src/Middleware/ScopeSessions.php` +- `src/Resolvers/*` + +## Middleware + +- `InitializeTenancyByDomain` +- `InitializeTenancyBySubdomain` +- `InitializeTenancyByDomainOrSubdomain` +- `InitializeTenancyByPath` +- `InitializeTenancyByRequestData` +- `InitializeTenancyByOriginHeader` +- `PreventAccessFromUnwantedDomains` +- `CheckTenantForMaintenanceMode` +- `ScopeSessions` + +## Resolver Config + +- `DomainTenantResolver`: cache, TTL, cache store. +- `PathTenantResolver`: tenant route parameter, route name prefix, tenant model column, allowed extra columns, cache. +- `RequestDataTenantResolver`: header, cookie, query parameter, tenant model column, cache. + +## Rules + +- Configure `identification.central_domains` for domain/subdomain strategies. +- Use `PreventAccessFromUnwantedDomains` only with configured domain identification middleware. +- For path identification, confirm the tenant parameter name before defining URLs. +- For request-data identification, set unused channels to `null`. +- If custom middleware is introduced, add it to the appropriate config category. +- Test success and failure identification paths. diff --git a/resources/boost/skills/tenancy/references/impersonation.md b/resources/boost/skills/tenancy/references/impersonation.md new file mode 100644 index 00000000..9d6f70bc --- /dev/null +++ b/resources/boost/skills/tenancy/references/impersonation.md @@ -0,0 +1,36 @@ +# User Impersonation Reference + +Use this when implementing tenant user impersonation. + +## Source Files + +- `src/Features/UserImpersonation.php` +- `src/Database/Models/ImpersonationToken.php` +- `assets/impersonation-migrations/*` + +## Setup + +```bash +php artisan vendor:publish --provider="Stancl\Tenancy\TenancyServiceProvider" --tag=impersonation-migrations +php artisan migrate +``` + +Enable feature: + +```php +'features' => [ + Stancl\Tenancy\Features\UserImpersonation::class, +], +``` + +## Command + +```bash +php artisan tenants:purge-impersonation-tokens +``` + +## Rules + +- Verify tenant match before logging in impersonated users. +- Test guard, redirect URL, remember flag, token TTL, and invalid token behavior. +- Purge expired tokens routinely. diff --git a/resources/boost/skills/tenancy/references/installation.md b/resources/boost/skills/tenancy/references/installation.md new file mode 100644 index 00000000..1165fdb1 --- /dev/null +++ b/resources/boost/skills/tenancy/references/installation.md @@ -0,0 +1,73 @@ +# Installation Reference + +Use this when installing or auditing `stancl/tenancy` setup. + +## Source Files + +- `src/Commands/Install.php` +- `src/TenancyServiceProvider.php` +- `assets/config.php` +- `assets/tenant_routes.stub.php` +- `assets/TenancyServiceProvider.stub.php` +- `assets/migrations/*` + +## Required Steps + +1. Install the package. + +```bash +composer require stancl/tenancy +``` + +2. Run the installer non-interactively. + +```bash +php artisan tenancy:install --no-interaction +``` + +3. Confirm these files exist: + +- `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` +- `database/migrations/tenant` + +4. Review `config/tenancy.php` before running migrations. + +5. Run central migrations. + +```bash +php artisan migrate +``` + +6. Add tenant migrations to `database/migrations/tenant`. + +7. Create tenants and domains according to the identification strategy. + +8. Run tenant migrations. + +```bash +php artisan tenants:migrate +``` + +## Manual Publish Commands + +Prefer `tenancy:install`. Use these only for targeted publishing: + +```bash +php artisan vendor:publish --provider="Stancl\Tenancy\TenancyServiceProvider" --tag=config +php artisan vendor:publish --provider="Stancl\Tenancy\TenancyServiceProvider" --tag=routes +php artisan vendor:publish --provider="Stancl\Tenancy\TenancyServiceProvider" --tag=providers +php artisan vendor:publish --provider="Stancl\Tenancy\TenancyServiceProvider" --tag=migrations +php artisan vendor:publish --provider="Stancl\Tenancy\TenancyServiceProvider" --tag=impersonation-migrations +php artisan vendor:publish --provider="Stancl\Tenancy\TenancyServiceProvider" --tag=resource-syncing-migrations +``` + +## Installer Behavior + +- Publishes config, routes, provider, and base migrations. +- Creates `database/migrations/tenant`. +- Skips files that already exist and warns instead of overwriting. +- Shows an interactive support prompt unless `--no-interaction` is used. diff --git a/resources/boost/skills/tenancy/references/integrations.md b/resources/boost/skills/tenancy/references/integrations.md new file mode 100644 index 00000000..89a31cbf --- /dev/null +++ b/resources/boost/skills/tenancy/references/integrations.md @@ -0,0 +1,44 @@ +# Integrations Reference + +Use this when tenancy integrates with URL generation, mail, broadcasting, Fortify, Scout, Livewire, Telescope, or Vite. + +## Source Files + +- `src/Bootstrappers/RootUrlBootstrapper.php` +- `src/Bootstrappers/UrlGeneratorBootstrapper.php` +- `src/Bootstrappers/MailConfigBootstrapper.php` +- `src/Bootstrappers/BroadcastingConfigBootstrapper.php` +- `src/Bootstrappers/BroadcastChannelPrefixBootstrapper.php` +- `src/Bootstrappers/Integrations/FortifyRouteBootstrapper.php` +- `src/Bootstrappers/Integrations/ScoutPrefixBootstrapper.php` +- `src/Features/TelescopeTags.php` +- `src/Features/ViteBundler.php` +- `assets/TenancyServiceProvider.stub.php` + +## Bootstrappers + +- `RootUrlBootstrapper`: tenant root URL for CLI/context URL generation. +- `UrlGeneratorBootstrapper`: tenant-aware route names and tenant parameters. +- `MailConfigBootstrapper`: tenant-specific mail config. +- `BroadcastingConfigBootstrapper`: tenant broadcaster config and manager. +- `BroadcastChannelPrefixBootstrapper`: tenant-prefixed broadcast channel names. +- `FortifyRouteBootstrapper`: tenant auth route/redirect integration. +- `ScoutPrefixBootstrapper`: tenant-specific Scout prefix. + +## Features + +- `TelescopeTags`: adds tenant tags when tenancy is initialized. +- `ViteBundler`: tenant-aware bundling behavior. + +## Stub Hooks + +- `overrideUrlInTenantContext()` shows how to set `RootUrlBootstrapper::$rootUrlOverride`. +- The Livewire v3 comment shows how to make the Livewire update route universal. +- `cloneRoutes()` shows the package route-cloning integration point. + +## Rules + +- Prefer bootstrappers over ad hoc service-provider config mutation. +- Test generated URLs in HTTP and CLI contexts. +- Test broadcast channel names and tenant-specific broadcaster credentials. +- Make third-party package routes universal or cloned only when intentionally accessible in tenant context. diff --git a/resources/boost/skills/tenancy/references/lifecycle-jobs.md b/resources/boost/skills/tenancy/references/lifecycle-jobs.md new file mode 100644 index 00000000..f8715982 --- /dev/null +++ b/resources/boost/skills/tenancy/references/lifecycle-jobs.md @@ -0,0 +1,46 @@ +# Lifecycle Jobs Reference + +Use this when provisioning or deleting tenant resources through events and job pipelines. + +## Source Files + +- `assets/TenancyServiceProvider.stub.php` +- `src/Events/*` +- `src/Jobs/*` +- `src/Listeners/*` +- `src/Database/Models/Tenant.php` +- `src/Database/Models/Domain.php` + +## Tenant Created Pipeline + +The published application provider wires `TenantCreated` to a `JobPipeline` containing: + +- `CreateDatabase` +- `MigrateDatabase` +- optional `SeedDatabase` +- optional `CreateStorageSymlinks` +- custom provisioning jobs + +## Tenant Deletion Pipelines + +The stub wires: + +- `DeletingTenant` to `DeleteDomains`, optional `DeleteTenantStorage`, optional `RemoveStorageSymlinks`. +- `TenantDeleted` to `DeleteDatabase`, optional resource-syncing cleanup. + +## Event Groups + +- Tenant lifecycle events. +- Domain lifecycle events. +- Database lifecycle events. +- Tenancy initialization/end/bootstrap events. +- Pending tenant events. +- Resource syncing events. +- Storage symlink events. + +## Rules + +- Put provisioning and cleanup in event pipelines rather than controllers. +- Keep database, migration, seeding, storage, domain, and sync cleanup order explicit. +- Decide whether pipelines should be queued using `shouldBeQueued()`. +- Test tenant creation and deletion side effects. diff --git a/resources/boost/skills/tenancy/references/migrations-commands.md b/resources/boost/skills/tenancy/references/migrations-commands.md new file mode 100644 index 00000000..7df8c465 --- /dev/null +++ b/resources/boost/skills/tenancy/references/migrations-commands.md @@ -0,0 +1,56 @@ +# Migrations And Commands Reference + +Use this for tenant-aware Artisan operations. + +## Source Files + +- `src/Commands/*` +- `src/Concerns/HasTenantOptions.php` +- `src/Concerns/ExtendsLaravelCommand.php` +- `src/Concerns/DealsWithMigrations.php` +- `assets/config.php` + +## Tenant Migrations + +Defaults from `tenancy.migration_parameters`: + +- `--force` true +- `--path` `database/migrations/tenant` +- `--schema-path` `database/schema/tenant-schema.dump` +- `--realpath` true + +Commands: + +```bash +php artisan tenants:migrate +php artisan tenants:migrate --tenants=tenant-id +php artisan tenants:migrate --skip-failing +php artisan tenants:rollback +php artisan tenants:migrate-fresh +php artisan tenants:seed +``` + +## Tenant Operations + +```bash +php artisan tenants:run cache:clear +php artisan tenant:tinker +php artisan tenants:list +php artisan tenant:dump +``` + +## Maintenance And Storage + +```bash +php artisan tenants:down +php artisan tenants:up +php artisan tenants:link +php artisan tenants:link --remove +``` + +## Rules + +- Use tenant commands for tenant DBs; normal `migrate` is central. +- Use `--tenants=*` to scope commands to selected tenants. +- Use `--skip-failing` only when failures should not stop execution. +- Use concurrent process options only after verifying tenant operations are safe in parallel. diff --git a/resources/boost/skills/tenancy/references/models-domains.md b/resources/boost/skills/tenancy/references/models-domains.md new file mode 100644 index 00000000..eec8fbdf --- /dev/null +++ b/resources/boost/skills/tenancy/references/models-domains.md @@ -0,0 +1,42 @@ +# Models And Domains Reference + +Use this when changing tenant/domain models or tenant-owned models. + +## Source Files + +- `src/Database/Models/Tenant.php` +- `src/Database/Models/Domain.php` +- `src/Contracts/Tenant.php` +- `src/Contracts/Domain.php` +- `src/Database/Concerns/*` +- `assets/migrations/*` + +## Default Tenant Model + +- Table: `tenants` +- Primary key: `id` +- Uses `VirtualColumn`, `CentralConnection`, `GeneratesIds`, `HasInternalKeys`, `TenantRun`, `InitializationHelpers`, `InvalidatesResolverCache`. +- Dispatches tenant lifecycle events. + +## Default Domain Model + +- Unique `domain` column. +- Belongs to configured tenant model using `Tenancy::tenantKeyColumn()`. +- Uses `CentralConnection`, `EnsuresDomainIsNotOccupied`, `ConvertsDomainsToLowercase`, `InvalidatesTenantsResolverCache`. + +## Single-Database Traits + +- `BelongsToTenant` +- `FillsCurrentTenant` +- `TenantConnection` +- `CentralConnection` +- `HasScopedValidationRules` +- `RLSModel` + +## Rules + +- Custom tenant models must implement `Stancl\Tenancy\Contracts\Tenant`. +- Custom domain models must implement `Stancl\Tenancy\Contracts\Domain`. +- Preserve resolver cache invalidation behavior when replacing models. +- Use tenant scoping traits consistently for single-database tenancy. +- If auto-increment tenant IDs are used, update config and migrations together. diff --git a/resources/boost/skills/tenancy/references/package.md b/resources/boost/skills/tenancy/references/package.md index 9b00b92a..75503683 100644 --- a/resources/boost/skills/tenancy/references/package.md +++ b/resources/boost/skills/tenancy/references/package.md @@ -2,6 +2,30 @@ 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` diff --git a/resources/boost/skills/tenancy/references/pending-tenants.md b/resources/boost/skills/tenancy/references/pending-tenants.md new file mode 100644 index 00000000..28c2ca1a --- /dev/null +++ b/resources/boost/skills/tenancy/references/pending-tenants.md @@ -0,0 +1,33 @@ +# Pending Tenants Reference + +Use this when maintaining a pool of prepared tenants. + +## Source Files + +- `src/Commands/CreatePendingTenants.php` +- `src/Commands/ClearPendingTenants.php` +- `src/Database/Concerns/HasPending.php` +- `src/Database/Concerns/PendingScope.php` +- `src/Jobs/CreatePendingTenants.php` +- `src/Jobs/ClearPendingTenants.php` + +## Config + +- `pending.include_in_queries` +- `pending.count`, defaulting to `TENANCY_PENDING_COUNT` or 5 + +## Commands + +```bash +php artisan tenants:pending-create +php artisan tenants:pending-create --count=10 +php artisan tenants:pending-clear +php artisan tenants:pending-clear --older-than-days=7 +php artisan tenants:pending-clear --older-than-hours=12 +``` + +## Rules + +- When `include_in_queries` is false, pending tenants are excluded from tenant queries and tenant commands. +- Use `withPending()`, `withoutPending()`, and `onlyPending()` intentionally. +- Test command behavior with and without pending tenants included in queries. diff --git a/resources/boost/skills/tenancy/references/resource-syncing.md b/resources/boost/skills/tenancy/references/resource-syncing.md new file mode 100644 index 00000000..fba5c217 --- /dev/null +++ b/resources/boost/skills/tenancy/references/resource-syncing.md @@ -0,0 +1,32 @@ +# Resource Syncing Reference + +Use this when syncing central resources into tenant contexts. + +## Source Files + +- `src/ResourceSyncing/*` +- `assets/resource-syncing-migrations/*` +- `assets/TenancyServiceProvider.stub.php` + +## Setup + +Publish resource syncing migration: + +```bash +php artisan vendor:publish --provider="Stancl\Tenancy\TenancyServiceProvider" --tag=resource-syncing-migrations +php artisan migrate +``` + +## Main Pieces + +- `tenant_resources` table. +- `ResourceSyncing` classes and listeners. +- `SyncMaster`, `Syncable`, `TenantPivot`, `TenantMorphPivot`. +- Events such as `SyncedResourceSaved`, `SyncedResourceDeleted`, `CentralResourceAttachedToTenant`. + +## Rules + +- Use package events/listeners instead of custom tenant loops. +- Keep central and tenant resource lifecycles explicit. +- Configure soft-delete query behavior in the application `TenancyServiceProvider` when needed. +- Test create, update, delete, restore, attach, and detach behavior. diff --git a/resources/boost/skills/tenancy/references/rls.md b/resources/boost/skills/tenancy/references/rls.md new file mode 100644 index 00000000..64eef412 --- /dev/null +++ b/resources/boost/skills/tenancy/references/rls.md @@ -0,0 +1,33 @@ +# PostgreSQL RLS Reference + +Use this when implementing single-database PostgreSQL row-level security. + +## Source Files + +- `src/Bootstrappers/PostgresRLSBootstrapper.php` +- `src/RLS/*` +- `src/Database/Concerns/RLSModel.php` +- `src/Commands/CreateUserWithRLSPolicies.php` +- `tests/RLS/*` + +## Config + +- `rls.manager` +- `rls.user.username` +- `rls.user.password` +- `rls.session_variable_name` +- `PostgresRLSBootstrapper` in `bootstrappers` + +## Command + +```bash +php artisan tenants:rls +php artisan tenants:rls --force +``` + +## Rules + +- Use PostgreSQL and single-database tenancy. +- Session variable name must be namespaced, for example `my.current_tenant`. +- RLS user is one tenant database user for all tenants, not one user per tenant. +- Test policies on every tenant-owned table. diff --git a/resources/boost/skills/tenancy/references/routing-assets.md b/resources/boost/skills/tenancy/references/routing-assets.md new file mode 100644 index 00000000..45b29074 --- /dev/null +++ b/resources/boost/skills/tenancy/references/routing-assets.md @@ -0,0 +1,49 @@ +# Routing And Assets Reference + +Use this when working with tenant routes, route modes, cloned routes, or tenant assets. + +## Source Files + +- `assets/tenant_routes.stub.php` +- `assets/TenancyServiceProvider.stub.php` +- `assets/routes.php` +- `src/Actions/CloneRoutesAsTenant.php` +- `src/Enums/RouteMode.php` +- `src/Controllers/TenantAssetController.php` + +## Published Tenant Routes + +The stub groups tenant routes with: + +- `web` +- `InitializeTenancyByDomain` +- `PreventAccessFromUnwantedDomains` +- `ScopeSessions` + +The application `TenancyServiceProvider` loads `routes/tenant.php` under the `tenant` middleware group. + +## Route Modes + +The package registers these middleware groups: + +- `clone` +- `universal` +- `tenant` +- `central` + +`tenancy.default_route_mode` defaults to central. Override per route using route mode middleware. + +## Asset Routes + +When `tenancy.routes` is true, the package registers: + +- `/tenancy/assets/{path?}` named `stancl.tenancy.asset` +- `/{tenant}/tenancy/assets/{path?}` named `tenant.stancl.tenancy.asset` for path identification + +## Rules + +- Keep central and tenant routes explicit. +- Use `routes/tenant.php` for tenant application routes when using the stub. +- Use `universal` only for routes intended to work in both contexts. +- Use `CloneRoutesAsTenant` for package route integration instead of manually duplicating route definitions. +- Disable package routes only if using external storage or a custom asset controller. diff --git a/resources/boost/skills/tenancy/references/testing.md b/resources/boost/skills/tenancy/references/testing.md new file mode 100644 index 00000000..6a72cb16 --- /dev/null +++ b/resources/boost/skills/tenancy/references/testing.md @@ -0,0 +1,43 @@ +# Testing Reference + +Use this when adding or reviewing tenancy behavior tests. + +## Source Files + +- `tests/TestCase.php` +- `tests/Pest.php` +- `tests/*` + +## High-Value Test Areas + +- Installation and published files. +- Central route access. +- Tenant route access. +- Domain, subdomain, path, request data, and origin header identification. +- Identification failures. +- Tenant context API restoration after success and exceptions. +- Database connection switching and reverting. +- Cache, Redis, filesystem, session, queue, URL, mail, and broadcasting scoping. +- Tenant migrations, rollbacks, seeds, and tenant command options. +- Tenant lifecycle jobs and event pipelines. +- Resource syncing. +- User impersonation. +- Pending tenants. +- RLS policies. +- Optional features. + +## Useful Existing Tests + +- `tests/AutomaticModeTest.php` +- `tests/ManualModeTest.php` +- `tests/RouteMiddlewareTest.php` +- `tests/PathIdentificationTest.php` +- `tests/RequestDataIdentificationTest.php` +- `tests/OriginHeaderIdentificationTest.php` +- `tests/TenantAssetTest.php` +- `tests/CommandsTest.php` +- `tests/QueueTest.php` +- `tests/SingleDatabaseTenancyTest.php` +- `tests/RLS/*` +- `tests/ResourceSyncingTest.php` +- `tests/TenantUserImpersonationTest.php`