Tenancy Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Multi-tenancy paradigm: The bundle aligns perfectly with Symfony’s ecosystem, offering database-per-tenant and shared-database modes, both critical for SaaS architectures. The event-driven kernel extension approach (via kernel.request listener) ensures seamless integration without requiring manual tenant context propagation in controllers or services.
• Zero-boilerplate design: Eliminates common anti-patterns (e.g., manual $tenantId parameters, leaked queries) by automating tenant resolution and subsystem reconfiguration (DB, cache, mailer, messenger). This reduces cognitive load for developers and minimizes risk of tenant isolation failures.
• Strict-by-default security: Default strict mode (explicit opt-out) enforces tenant resolution, preventing silent data leaks—a critical requirement for compliance-heavy applications (e.g., healthcare, finance).
• Symfony-first philosophy: Unlike Laravel’s stancl/tenancy, this bundle is Symfony-native, with deep integration into Doctrine, Messenger, Cache, and Mailer. The tag-based bootstrapper system (tenancy.bootstrapper) allows for extensibility without modifying core logic.

Integration Feasibility

• Minimal setup: One-liner installation (composer require) + tenancy:install command handles bundle registration and config scaffolding. No manual DI wiring or complex migrations required for basic use cases.
• Backward compatibility: Supports Symfony 7.4/8.0 and PHP 8.2/8.3/8.4. Optional dependencies (Doctrine, Messenger) are guarded with class_exists checks, enabling use in non-Doctrine Symfony apps.
• Laravel-like features: Offers 5 built-in resolvers (Host, Origin header, CLI flag, etc.), mirroring Laravel’s stancl/tenancy but with Symfony-specific optimizations (e.g., Origin resolver for SPAs).
• Testing support: InteractsWithTenancy trait provides real SQLite tenant isolation per test, reducing flakiness in CI/CD pipelines.

Technical Risk

• Low-risk core: The bundle’s small surface area (559 tests, PHPStan level 9) and modular design (bootstrappers as tagged services) minimize integration risks. The demo-smoke CI gate (end-to-end tenant isolation testing) validates stability.
• Shared-DB mode risks: While the #[TenantAware] attribute simplifies query scoping, performance overhead (SQL filters) and edge cases (nested transactions, complex joins) may require tuning. The bundle’s strict mode mitigates this by failing fast on misconfigured queries.
• Messenger/Mailer dependencies: Async workflows (e.g., delayed jobs) require tenant context propagation, which the bundle handles via TenantStamp. However, custom transports may need additional bootstrappers.
• Database-per-tenant limitations:
  • Connection pooling: DBAL’s wrapperClass may not optimize connections as effectively as dedicated tools (e.g., PgBouncer, ProxySQL).
  • Schema migrations: The tenancy:migrate command runs migrations per tenant, but large-scale deployments (10K+ tenants) may need parallelization or batch processing.
  • Landlord vs. tenant schemas: The dual landlord/tenant EntityManager setup could conflict with legacy Symfony apps using custom connection logic.

Key Questions

1. Performance:
   • For database-per-tenant, how will connection switching impact latency under high concurrency? Are there plans to support connection pooling (e.g., PgBouncer)?
   • For shared-DB, what’s the query plan overhead of the TenantAwareFilter? Are there optimizations for read-heavy workloads?
2. Scaling:
   • How does the bundle handle tenant creation/deletion at scale (e.g., 10K+ tenants)? Are there bulk operations for DB-per-tenant setups?
   • What’s the recommended architecture for multi-region deployments (e.g., tenant data locality)?
3. Extensibility:
   • Can custom bootstrappers (e.g., for Redis, Elasticsearch) be added without modifying the bundle?
   • How does the bundle handle tenant-specific middleware (e.g., rate limiting, feature flags)?
4. Observability:
   • The Profiler tab is useful, but are there metrics (e.g., tenant resolution latency, bootstrapper failures) for monitoring?
   • How are tenant resolution failures logged/alerted (e.g., missing tenant, resolver conflicts)?
5. Migration Path:
   • If switching from a manual tenancy solution, how can existing tenant data (e.g., schemas, tables) be seamlessly migrated to the bundle’s structure?
   • Are there deprecation warnings for Symfony 6.x or PHP 8.1 support?

Integration Approach

Stack Fit

• Symfony 7.4/8.0: Native support with zero breaking changes to existing Symfony services. The bundle’s compiler passes and tag-based bootstrappers ensure compatibility.
• Doctrine ORM: Deep integration via #[TenantAware] attribute and SQL filters. Works with Doctrine Migrations and custom entity listeners.
• Messenger: Automatic TenantStamp propagation for async jobs. Supports sync/async transports and retries.
• Cache: Per-tenant namespace isolation via cache pool prefixing. Compatible with Redis, APCu, and filesystem caches.
• Mailer: Per-tenant SMTP/DSN configuration. Supports sync/async sending and custom transports.
• CLI: tenancy:run command wraps any Symfony CLI tool (e.g., make:migration) with tenant context.
• Testing: InteractsWithTenancy trait integrates with PHPUnit, enabling real tenant isolation in tests.

Migration Path

1. Assessment Phase:
   • Audit existing tenancy logic (e.g., manual $tenantId parameters, custom query scopes).
   • Identify tenant resolution sources (e.g., subdomains, API headers) to map to the bundle’s resolvers.
   • Review database schema for compatibility with database-per-tenant or shared-DB mode.
2. Pilot Migration:
   • Start with a non-critical tenant (e.g., sandbox environment).
   • Use tenancy:install for one-shot setup and configure tenancy.yaml.
   • Replace manual tenant logic with attribute-based scoping (#[TenantAware]).
   • Test cache isolation, mailer bootstrapping, and Messenger jobs.
3. Incremental Rollout:
   • Phase 1: Migrate tenant resolution and database isolation.
   • Phase 2: Replace custom query scopes with #[TenantAware].
   • Phase 3: Integrate Messenger/Mailer bootstrappers.
   • Phase 4: Update CLI tools and tests to use tenancy:run and InteractsWithTenancy.
4. Cutover:
   • Deploy the bundle in parallel with legacy logic (if needed).
   • Use feature flags to toggle tenancy mode.
   • Monitor tenant resolution failures and performance metrics.

Compatibility

• Doctrine: Fully compatible with Doctrine 3.x. Supports custom entity inheritance and migrations.
• Symfony Components: Works with Cache, Messenger, Mailer, and HTTP Client out of the box.
• Third-Party Bundles:
  • API Platform: Requires custom resolver for tenant-aware routes (e.g., Origin header).
  • EasyAdmin: May need tenant-aware CRUD adjustments (e.g., filtering by #[TenantAware]).
  • LexikJWTAuthentication: Supports tenant-aware tokens via custom resolver.
• Legacy Code:
  • Manual tenant IDs: Replace with dependency injection (e.g., TenantContext service).
  • Static tenant references: Refactor to use resolver chain or context propagation.

Sequencing

1. Configure Tenant Resolution:
   • Set up resolvers in tenancy.yaml (e.g., Host, Header, QueryParam).
   • Test with tenancy:run CLI command.
2. Database Isolation:
   • Choose database-per-tenant (recommended for strict isolation) or shared-DB (for simplicity).
   • Run tenancy:migrate for schema setup.
3. Entity Scoping:
   • Add #[TenantAware] to entities in shared-DB mode.
   • For database-per-tenant, ensure landlord/tenant EntityManager separation.
4. Infrastructure Bootstrappers:
   • Enable cache isolation, mailer, and Messenger via config.
   • Test async jobs and email sending per tenant.
5. Testing:
   • Replace mocks with InteractsWithTenancy