Laravel Multidomain Laravel Package

Technical Evaluation

Architecture Fit

• Multi-Tenancy Model: The package enables subdomain-based multi-tenancy (e.g., site1.example.com, site2.example.com), aligning with Laravel’s single-codebase, multi-database/environment paradigm. This is ideal for SaaS platforms, white-label solutions, or shared-code deployments where tenants require isolated configurations (DB, storage, queues).
• Isolation Scope: Supports per-tenant environment files (.env.<domain>), dedicated storage paths (storage/<domain>), and domain-specific configs (e.g., queues, caches). This avoids cross-contamination between tenants while sharing the same codebase.
• Laravel-Centric: Deeply integrates with Laravel’s core (e.g., overrides Application, QueueServiceProvider) to ensure seamless domain detection via $_SERVER['SERVER_NAME'] (customizable). This minimizes friction with existing Laravel patterns (e.g., service providers, middleware).
• Limitations:
  • No true database multi-tenancy: Requires separate databases per tenant (unlike packages like stancl/tenancy for schema-based isolation).
  • Storage isolation is manual: Symbolic links (storage:link) must be managed per-domain (workaround provided).
  • No built-in API/route isolation: Tenants share the same routes; isolation must be enforced via middleware or domain-specific logic.

Integration Feasibility

• Low-Coupling Design: The package modifies only bootstrap (app.php) and service providers (QueueServiceProvider), with minimal changes to existing code. The domain() helper method provides runtime access to the current tenant’s domain.
• Artisan Command Support: Extends Laravel’s CLI with --domain flags for commands (e.g., queue:work --domain=site1.com), enabling tenant-specific operations.
• Queue Support: Customizable queue drivers per tenant (critical for SaaS workloads). Requires explicit queue configuration in .env.<domain>.
• Compatibility:
  • Laravel 5.5–13.x: Broad support, but version alignment is strict (e.g., 13.* for Laravel 13). Downgrading may require manual adjustments.
  • Horizon: Requires a one-line override in HorizonServiceProvider (community-contributed).
  • SPA/Static Assets: Workarounds needed for domain-specific public storage (e.g., .htaccess rules or manual symlinks).

Technical Risk

• Bootstrap Override: Modifying bootstrap/app.php is non-standard and may conflict with:
  • Custom Laravel bootstrapping (e.g., Forge, Envoyer, or bespoke setups).
  • Future Laravel updates that alter app.php structure.
  • Mitigation: Document the change as a mandatory step and test with major Laravel versions.
• Domain Detection Edge Cases:
  • Non-standard environments: $_SERVER['SERVER_NAME'] may be missing (e.g., CLI, some load balancers). Custom detection functions are provided but require manual setup.
  • Wildcard subdomains: May clash with Laravel’s routing (e.g., *.example.com). Requires middleware to validate domains against config/domains.php.
• Storage Management:
  • Manual symlinks: No built-in support for storage:link per-domain. Workaround adds complexity (e.g., .htaccess hacks).
  • File permissions: Tenant storage paths must be writable by the web server (e.g., chown -R www-data:www-data storage/site1_com).
• Queue Isolation:
  • Database queues: Requires explicit queue names per tenant (e.g., QUEUE_DEFAULT=site1_jobs). Misconfiguration can lead to job mixing.
  • Redis/SQS: No built-in isolation; must be managed via queue names or separate instances.
• Performance:
  • Environment file loading: Each request loads a .env.<domain> file, which could introduce minor overhead. Cache configs with php artisan config:cache --domain=<domain>.
  • Storage path resolution: Dynamic path resolution (e.g., storage_path('app') → storage/site1_com/app) may impact filesystem operations.

Key Questions

1. Tenant Isolation Requirements:
   • Are tenants truly independent (separate DBs, queues, storage), or is this a shared-code use case (e.g., shared DB with tenant IDs)?
   • If shared DB, consider stancl/tenancy or middleware-based isolation instead.
2. Domain Management Workflow:
   • How will domains be provisioned (e.g., via CLI, API, or third-party tools like DNS providers)?
   • Is there a need for automated domain validation (e.g., reject non-whitelisted domains)?
3. Storage and Assets:
   • How will public assets (e.g., uploaded files) be served per-domain? Will you use:
     • Manual symlinks + .htaccess?
     • A CDN with domain-specific paths?
     • Laravel’s Storage facade with domain-aware URLs?
4. Queue Strategy:
   • Will tenants use shared queues (e.g., default) or dedicated queues (e.g., site1_jobs)?
   • How will failed jobs be handled per tenant?
5. CI/CD and Deployment:
   • How will .env.<domain> files be managed in Git (e.g., .gitignore, secrets management)?
   • Will domains be added/removed dynamically during deployment, or is this a static setup?
6. Monitoring and Logging:
   • How will logs/metrics be scoped to tenants (e.g., Sentry tags, Laravel Debugbar filters)?
   • Is there a need for tenant-aware error tracking?
7. Scaling Considerations:
   • Will tenants share a single Laravel instance (e.g., behind a load balancer), or will each have a dedicated instance?
   • If shared, how will horizontal scaling (e.g., queue workers, cron jobs) be managed per tenant?

Integration Approach

Stack Fit

• Laravel Versions: The package is version-locked to Laravel 5.5–13.x. For Laravel 11+, installation is simplified (no manual app.php edits required). For Laravel 10–, manual overrides are needed.
• PHP Requirements: No additional PHP extensions are required beyond Laravel’s defaults.
• Server/Hosting:
  • Shared Hosting: May struggle with $_SERVER['SERVER_NAME'] (e.g., some shared hosts use localhost). Custom detection functions are provided but require testing.
  • Cloud Providers (AWS, GCP, Azure): Works seamlessly with standard configurations. For serverless (e.g., Lambda), domain detection may need customization.
  • Docker/Kubernetes: Requires ensuring $_SERVER['SERVER_NAME'] is correctly passed (e.g., via nginx/traefik headers).
• Database: Assumes separate databases per tenant. No schema migration support (unlike stancl/tenancy).
• Caching: Supports per-tenant cache configs (e.g., CACHE_DRIVER=redis in .env.<domain>). Redis can be shared or tenant-specific.
• Queues: Supports database, redis, sqs, etc., but isolation must be configured manually (e.g., QUEUE_CONNECTION=redis_site1).

Migration Path

1. Assessment Phase:
   • Audit current Laravel setup for custom bootstrapping or service provider overrides.
   • Identify tenant isolation requirements (DB, storage, queues).
   • Test domain detection in staging (especially if using non-standard environments like CLI or serverless).
2. Proof of Concept (PoC):
   • Set up a single tenant with the package to validate:
     • Environment file loading (php artisan domain:add example.com).
     • Storage path isolation (storage/example_com).
     • Queue isolation (QUEUE_CONNECTION=redis_site1).
   • Test artisan commands with --domain flags.
3. Incremental Rollout:
   • Phase 1: Add the package to a non-production Laravel instance.
     • Override bootstrap/app.php and QueueServiceProvider.
     • Publish config (php artisan vendor:publish).
     • Add a test domain (php artisan domain:add test.example.com).
   • Phase 2: Migrate one tenant to the new setup.
     • Copy .env to .env.<domain>.
     • Update config/domains.php.
     • Test storage and queue isolation.
   • Phase 3: Roll out to remaining tenants via CI/CD.
4. Post-Migration:
   • Implement automated domain management (e.g., API endpoints to add/remove domains).
   • Set up monitoring for tenant-specific metrics (e.g., queue jobs, storage usage).

Compatibility

| Component | Compatibility | Workarounds