Laravel Multidomain Laravel Package

Product Decisions This Supports

• Multi-Tenancy Strategy: Enables subdomain-based multi-tenancy (shared code, isolated data/config/storage per tenant) without complex middleware or database sharding. Ideal for SaaS platforms, agency clients, or franchise models where each tenant needs a distinct environment.
• Cost Efficiency: Reduces infrastructure costs by consolidating a single Laravel instance across multiple domains instead of deploying separate instances per tenant.
• Scalability Roadmap: Supports phased scaling—start with subdomains (e.g., client1.app.com) and later migrate to database-per-tenant or full isolation if needed.
• Build vs. Buy: Buy (avoid custom development of tenant isolation logic) unless requiring advanced features like dynamic DNS or wildcard subdomains.
• Use Cases:
  • Agencies: Host multiple client sites under one codebase (e.g., client1.agency.com).
  • SaaS Platforms: Isolate tenant configurations (e.g., tenant1.app.com with its own DB/cache).
  • Franchises: Centralized app with localized storage/config (e.g., franchise-ny.app.com).
  • Legacy Migration: Consolidate disparate Laravel 5.x/6.x apps into a single multi-domain instance.

When to Consider This Package

Adopt This Package If:

• You need subdomain-based multi-tenancy with minimal code changes (shared code, isolated .env, storage, and DB per tenant).
• Your tenants require independent configurations (e.g., different DBs, caches, queues) but share the same application logic.
• You’re using Laravel 5.x–13.x and want to avoid reinventing tenant isolation.
• You prioritize simplicity over granular control (e.g., no need for dynamic subdomains or wildcard support).
• Your infrastructure supports static subdomains (e.g., *.app.com configured in DNS).

Look Elsewhere If:

• You need database-per-tenant (use Laravel’s built-in multi-tenancy or packages like stancl/tenancy).
• You require wildcard subdomains without manual DNS setup (this package needs explicit domain entries).
• You’re using Laravel 14+ (compatibility untested; check for updates).
• You need advanced tenant routing (e.g., path-based tenancy like /tenant1/).
• Your tenants share nothing (e.g., completely separate apps; use separate Laravel instances).
• You’re on a shared hosting environment where $_SERVER['SERVER_NAME'] is unreliable (requires custom domain detection).

How to Pitch It (Stakeholders)

For Executives:

"This package lets us run multiple independent client sites—like a SaaS platform or agency—under one Laravel instance, cutting server costs by 70%+ while keeping each client’s data/config isolated. For example, client1.ourapp.com and client2.ourapp.com can share the same code but have their own databases, storage, and settings. It’s like having a ‘white-label’ factory for our software, with zero extra dev work. We avoid the complexity of custom multi-tenancy builds and can scale by adding domains in minutes via php artisan domain:add."

Key Benefits:

• Cost Savings: One server for all tenants (vs. separate instances).
• Speed to Market: Add a new tenant in 5 minutes (vs. weeks for custom builds).
• Risk Reduction: Isolated configs/storage prevent one tenant’s issues from affecting others.
• Future-Proof: Start with subdomains, then migrate to database-per-tenant later if needed.

For Engineering:

**"This is a battle-tested Laravel package that handles subdomain-based multi-tenancy with minimal boilerplate. Here’s how we’d use it:

1. Installation: Replace Laravel’s Application class and override QueueServiceProvider (10-minute setup).
2. Tenant Onboarding: Add a domain with php artisan domain:add client1.com—it auto-generates .env.client1.com, a storage/client1_com/ folder, and updates config.
3. Isolation: Each subdomain loads its own .env and storage path at runtime. Queues, caches, and DBs are tenant-specific.
4. CLI Support: Run Artisan commands for a tenant with --domain=client1.com (e.g., php artisan queue:work --domain=client1.com).

Trade-offs:

• No Wildcards: Must manually add subdomains to DNS (e.g., client1.ourapp.com).
• Storage Links: Need manual ln -s for public storage per tenant (or use .htaccess for SPAs).
• Queue Management: Requires separate queue workers per tenant if using database queues.

Alternatives Considered:

• Custom middleware: More maintenance.
• stancl/tenancy: Overkill for subdomain-only needs.
• Separate instances: Higher ops overhead.

Recommendation: Use this for subdomain-based multi-tenancy where tenants share code but need isolated configs. For database-per-tenant, pair with stancl/tenancy later."**