Laravel Multidomain Laravel Package

Technical Evaluation

Architecture Fit

• Multi-Tenant Isolation: The package excels at database, storage, and configuration isolation per domain, making it ideal for multi-tenant SaaS architectures where tenants share code but require separate environments.
• Laravel-Centric Design: Deeply integrates with Laravel’s core (e.g., Application, QueueServiceProvider), ensuring compatibility with Laravel’s ecosystem (e.g., Horizon, queues, caching).
• Environment-Based Routing: Leverages .env files and domain-specific configs, aligning with Laravel’s convention-over-configuration philosophy.
• Limitations:
  • No Route/Controller Isolation: All domains share the same codebase; tenant-specific logic must be manually implemented (e.g., middleware, feature flags).
  • Storage Link Workarounds: Requires manual storage:link management for per-domain public storage (a known gap).

Integration Feasibility

• Low-Coupling: Minimal changes to Laravel’s core (only bootstrap/app.php and config/app.php modifications).
• Backward Compatibility: Supports Laravel 5.x–13.x, but Laravel 10+ versions require version alignment (e.g., 13.* for Laravel 13).
• Dependency Risks:
  • Horizon Compatibility: Requires manual HorizonServiceProvider override.
  • Queue Drivers: Database/sync drivers need explicit queue separation (e.g., QUEUE_DEFAULT per domain).
  • Custom Domain Detection: May need overrides for non-standard environments (e.g., CLI, Docker, or reverse proxies).

Technical Risk

Key Questions

1. Tenant Logic: How will tenant-specific routes/controllers be isolated? (e.g., middleware, subdomains, or feature flags?)
2. Deployment Complexity: How will domains be added/removed in production? (e.g., CI/CD pipelines for domain:add/domain:remove?)
3. Performance: Will per-domain storage/config caching (config:cache --domain) impact startup time?
4. Monitoring: How will logs/metrics distinguish between domains? (e.g., Sentry tags, Laravel Debugbar customization?)
5. Rollback Plan: What’s the strategy if a domain’s .env or config breaks the app? (e.g., fallback to default .env?)

Integration Approach

Stack Fit

• Core Stack: Optimized for Laravel 10+ (recommended) with PHP 8.1+. Avoid Laravel 5.x due to EOL risks.
• Extensions:
  • Queues: Works with database, redis, beanstalkd (requires manual queue separation).
  • Caching: Supports config:cache --domain for per-domain cached configs.
  • Filesystems: Manual storage:link management needed for public storage.
• Non-Fit:
  • Octane: Untested; may require custom domain detection in Swoole/RoadRunner.
  • Livewire/Inertia: No built-in tenant context; requires manual integration (e.g., middleware).

Migration Path

1. Pre-Integration:
   • Audit existing .env for domain-specific variables (e.g., DB_DATABASE, APP_URL).
   • Plan for queue isolation (e.g., separate QUEUE_CONNECTION per domain).
2. Installation:
   • Replace bootstrap/app.php and config/app.php as per docs.
   • Publish config: php artisan vendor:publish --provider="Gecche\Multidomain\MultidomainServiceProvider".
3. Testing:
   • Validate domain detection with php artisan domain:list.
   • Test config:cache --domain for each tenant.
   • Verify queue workers: php artisan queue:work --domain=tenant1.com.
4. Production Rollout:
   • Add domains via CI/CD (e.g., GitHub Actions with domain:add).
   • Monitor storage paths and config merges.

Compatibility

Sequencing

1. Phase 1: Sandbox integration with 1–2 domains in staging.
2. Phase 2: Automate domain management (e.g., Terraform + domain:add).
3. Phase 3: Implement tenant-specific logic (e.g., middleware, feature flags).
4. Phase 4: Optimize storage/config caching and monitoring.

Operational Impact

Maintenance

• Pros:
  • Centralized Configs: All domain settings in .env files and config/domains/.
  • CLI Tools: domain:add/remove/update_env simplify tenant management.
• Cons:
  • Manual Overrides: Custom domain detection or storage links require dev ops effort.
  • Config Conflicts: Merged configs may cause issues if keys overlap (e.g., app.name).
• Best Practices:
  • Use feature flags for tenant-specific features.
  • Document .env variables per domain in a shared wiki.
  • Implement pre-commit hooks to validate .env files.

Support

• Common Issues:
  • Domain Detection Failures: Debug $_SERVER variables in custom environments.
  • Queue Stuck Jobs: Monitor per-domain queues separately.
  • Storage Permissions: Ensure storage/ has correct ownership (e.g., www-data).
• Troubleshooting:
  • Use app('domain') in Tinker to verify current domain.
  • Check config/domains.php for registered domains.
  • Log domain-specific errors with Sentry or Monolog tags.

Scaling

• Performance:
  • Config Caching: Use config:cache --domain in production to reduce I/O.
  • Storage: Avoid per-domain storage for large files; use shared S3 with tenant prefixes.
  • Databases: Consider read replicas per domain for high-traffic tenants.
• Horizontal Scaling:
  • Stateless Workers: Queue workers should be stateless; use shared Redis for queue connections.
  • Load Balancers: Ensure SERVER_NAME is correctly forwarded (e.g., via X-Forwarded-Host).

Failure Modes

Ramp-Up

• Onboarding New Tenants:
  1. Run php artisan domain:add tenant.example.com.
  2. Configure .env.tenant_example_com and config/domains/tenant_example_com.php.
  3. Test with php artisan config:cache --domain=tenant.example.com.
• Training:
  • Document domain-specific CLI flags (e.g., --domain).
  • Train devs on debugging domain context (e.g., app('domain')).
• Tooling:
  • CI/CD: Automate domain creation/updates (e.g., GitHub Actions).
  • Monitoring: Tag metrics/logs with tenant_id (e.g., Sentry tags).