Download the PHP package glueful/tenancy without Composer

glueful/tenancy

Shared-database, row-level multi-tenancy for the Glueful framework.

What it is

glueful/tenancy gives a single application the ability to serve many tenants out of one shared database, isolating their data at the row level: tenant-owned tables carry a tenant_uuid column, and every read/write against those tables is automatically scoped to the active tenant.

The data model is many-tenants-per-user: a (global) user is granted a role inside a tenant through a tenant_memberships bridge row, so one user can belong to several tenants and one tenant can have many members. This is logical isolation, not hard isolation — see Security posture.

Install / enable

Tenancy uses two providers with intentionally different lifecycles:

Add the control-plane provider to the application's static provider list:

Then run the migrations. The control-plane provider registers the migrations that create the central tenant, membership, domain, and released-host tables.

When the application is ready to enforce tenancy, enable the extension provider:

Enabling adds Glueful\Extensions\Tenancy\TenancyServiceProvider to config/extensions.php. Its presence means enforcement is active: it registers the resolver, middleware, scoping hooks, stamper, and query guard. Disabling the extension removes that provider and therefore removes enforcement on the next application boot. The control plane remains available while enforcement is disabled.

extensions:enable and extensions:disable manage only the manifest provider. They cannot add or remove TenancyControlPlaneProvider in config/serviceproviders.php.

Upgrading from the single-provider release

Before deploying the provider-split release:

1. Add Glueful\Extensions\Tenancy\TenancyControlPlaneProvider to config/serviceproviders.php.
2. Keep Glueful\Extensions\Tenancy\TenancyServiceProvider in config/extensions.php if tenancy enforcement is currently active; remove it if enforcement should remain off.
3. Deploy the package update, rebuild the extension/container cache as required by the host, and run php glueful migrate:run.
4. Verify tenant administration and resolution before accepting traffic.

Do not upgrade without the control-plane registration. The enforcement provider no longer owns migrations, default configuration, commands, or administration bindings, so loading it alone is an invalid deployment.

The old config('tenancy.enabled') switch no longer suppresses enforcement while TenancyServiceProvider is loaded. Applications that previously kept the provider enabled and set tenancy.enabled=false must instead remove/disable the enforcement provider. Provider presence is the engine-level enforcement switch; a host application may maintain a separate persisted lifecycle state for transition orchestration.

Custom membership-role authority

The control plane validates membership roles through MembershipRoleAuthority. By default, ConfigRoleAuthority preserves the static tenancy.membership.roles allow-list. A host that owns per-tenant role definitions may configure an implementation class:

Register that concrete class in the host container. The engine factory resolves it while retaining the config allow-list as a safe default. Membership assignment and role changes validate inside a transaction while holding canonical per-tenant role advisory locks; concurrent conflicts surface as MembershipRoleConflictException rather than proceeding with an unprotected role.

Framework requirement: glueful/framework ^1.67.0. The extension relies on the chainable Connection::addTableHook() / QueryExecutor::addQueryInterceptor() seams (so tenancy hooks compose with host interceptors instead of replacing them) and the Connection::class container binding. Earlier framework versions are not supported.

The data model

Two registry tables ship with the extension (both are central / never tenant-scoped):

tenants — the tenant directory.

tenant_memberships — grants a global user a role in a tenant.

Glueful\Extensions\Tenancy\Models\Tenant and Glueful\Extensions\Tenancy\Models\TenantMembership model these. Their consumer-side counterpart is your own tenant-owned model — any model that opts in via BelongsToTenant.

Making a consumer table tenant-owned

Add a tenant_uuid column to the table and the trait to the model:

Also list every tenant-owned table in config/tenancy.php under tables — that list is the authoritative registry the raw-query backstop reads at boot (the trait also self-registers, but the config list is what protects a table before its model is booted):

⚠ The composite-unique pitfall

A per-tenant-unique business key (a slug, an order number, an email-within-tenant) must be a composite unique on (tenant_uuid, key) — never a global unique on the key alone:

A global unique('slug') leaks across the tenant boundary: as soon as tenant A creates a project with slug flagship, tenant B is permanently blocked from using it — and the failure surfaces as a confusing database constraint violation, not a tenancy error. Always scope uniqueness by tenant_uuid.

Request flow

Register the tenant middleware on tenant-scoped routes. It must run after authentication (it reads auth.user.uuid to check membership):

On each request the middleware: resolve the tenant candidate (resolver chain) → validate it exists, is active, and that the user is a member (or holds a bypass permission) → set the request tenant context → run the handler → clear the context in a finally (state never leaks to a later request, even on success).

Responses:

Resolver chain

Resolvers run in the configured order; the first non-null candidate wins. Configure order and each resolver's input in config/tenancy.php:

Trim the list to only the resolvers you use; unknown names are skipped rather than erroring. Keep client-controlled resolvers (header, query, path) after trusted resolvers when more than one source may be present; resolver order is security-relevant because the first candidate wins.

Automatic scoping

Adding BelongsToTenant to a model wires three behaviors against the model's request-scoped tenant context:

• Reads are scoped. A global scope appends where tenant_uuid = <current tenant> to every query. With no active tenant and enforcement.required_by_default on, the scope fails closed — MissingTenantContextException rather than ever returning unscoped rows.
• Creates are force-stamped. A creating hook sets tenant_uuid from the active tenant via setAttribute(), which bypasses $fillable. The stamped value unconditionally overwrites any caller-supplied tenant_uuid (e.g. from a mass-assigned request body), so a model can never plant a row in another tenant — even if it lists tenant_uuid in $fillable or is unguarded.
• tenant_uuid is immutable. An updating hook rejects any change to tenant_uuid on a model save.

Raw / non-ORM access

The ORM scope only covers Model-path queries. For hand-written query-builder code, two backstops apply:

1. Auto-injection table hook — a Connection table hook injects where tenant_uuid = <current> into any query against a registered tenant-owned table while a tenant is active and no bypass is set.
2. Pre-execution guard — TenantQueryGuard inspects the final SQL just before execution and, if it sees unscoped access to a tenant-owned table, throws in dev/test (guard.dev = throw) or emits a metric/log in prod (guard.prod = metric). It is conservative (prefers letting a query through over a false-positive outage) and is a no-op outside a tenant request or under a bypass.

For deliberate raw access, use the provided helper, which asserts the table is registered and returns the already-scoped builder:

Rule of thumb: use models or TenantQuery; the guard catches the rest.

Bypass APIs (noisy on purpose)

Glueful\Extensions\Tenancy\Bypass\Tenancy is the only sanctioned way to step outside the per-request scope. The names are intentionally explicit — there is no generic withoutScope() — so a bypass is always obvious in a diff and in a security review. Each method saves, sets, and restores tenancy state in a finally, so they nest and unwind cleanly even on exception.

forAnyTenant is permission-gated on request paths. By default it checks whether the current user holds any of config('tenancy.bypass_permissions') (default tenancy.access_any, tenancy.manage) and throws TenantAccessDeniedException if not — failing closed when authorization cannot be evaluated. Trusted CLI / system callers pass $requirePermission = false to skip the check.

The check honors your app's active permission provider first (PermissionManager::can() — the same authority the rest of the app uses), then falls back to the framework Gate's voters when no provider is active. So an RBAC extension like glueful/aegis governs bypass directly: grant a role tenancy.access_any / tenancy.manage in aegis and it unlocks cross-tenant access. With no provider installed, a configured super_roles user (or a config/permissions.php policy) grants it via the Gate.

Context propagation

The tenant middleware only sets the tenant for HTTP requests. Outside the request lifecycle, propagate the tenant explicitly:

Jobs — opt in per job with PropagatesTenant. Capture the tenant at dispatch (it is stored in the job's serialization-surviving payload) and restore it on the worker (where it is re-loaded and re-validated as active; a missing/inactive tenant throws rather than running unscoped):

No captured tenant ⇒ the job runs system-scoped (no tenant, no implicit bypass).

CLI — add the --tenant switch with RunsInTenantContext:

--tenant=<uuid|slug> resolves + active-validates a single tenant; no flag = trusted system context (no tenant, enforcement suspended).

Scheduler — fan a scheduled callback out over every active tenant with ForEachTenant:

One tenant failure does not abort the remaining tenants. Inspect $result->failed and $result->errors after the run to decide whether the scheduler job should alert or retry.

Console commands

tenant:diagnose reports three sections:

• Registered tenant-owned tables — every table in the registry (config tables + trait-registered).
• Schema drift — each registered table is checked for a tenant_uuid column; any missing column (or a registered table that does not exist) is flagged.
• Membership integrity — counts orphan tenant_memberships rows whose tenant_uuid has no matching tenants.uuid.

It is a report, not a gate — it always exits success, but renders warnings prominently. Run it after adding tenant-owned tables.

Security posture

This is logical isolation, not hard isolation. All tenants share one database; isolation is enforced in the application layer by three cooperating mechanisms — the ORM scope, the create-time force-stamp, and the raw-query guard.

Threat model — be honest about what it does and does not cover:

• ✅ Protects against application-level cross-tenant access — the common SaaS need. Model queries are scoped, raw builder queries are auto-injected and guarded, writes are force-stamped to the active tenant, and tenant_uuid is immutable.
• ❌ Does NOT protect a SQL path that bypasses the framework query layer. A hand-written PDO statement, a query the guard's conservative heuristic does not recognize, or anything executed outside the builder is not scoped. The guard is a safety net, not a wall.
• ❌ Does NOT defend against a compromised database credential. Anyone with direct DB access sees every tenant's rows — there is no per-tenant database, schema, or encryption boundary here. If you need isolation against that, you need a different (physical) tenancy model.

Fail-closed defaults:

• enforcement.required_by_default = true — a tenant-owned model with no active tenant throws rather than returning unscoped rows.
• Writes are force-stamped to the active tenant, overriding any caller-supplied tenant_uuid.
• The guard throws in dev/test so leaks are caught loudly during development.
• forAnyTenant on a request is permission-gated and fails closed when authorization is unavailable.

Recommendations:

• Make every per-tenant-unique key a composite unique on (tenant_uuid, …) (see the pitfall above).
• List every tenant-owned table in config/tenancy.php tables so the backstop protects it from boot.
• Run php glueful tenant:diagnose after schema changes to catch drift and orphaned memberships.
• Keep enforcement.guard.prod at metric (or log) so prod leaks are observable without risking an outage; keep guard.dev at throw.
• Enable enforcement.hide_existence if even tenant membership must not be probable.

Configuration reference

config/tenancy.php (merged from the extension; override per app):

Enforcement activation is intentionally not a configuration key. It is controlled by whether Glueful\Extensions\Tenancy\TenancyServiceProvider is present in the application's enabled-extension list. TenancyControlPlaneProvider remains statically registered regardless of that state.