Laravel Multitenancy Laravel Package

Product Decisions This Supports

• Multi-Tenant SaaS Platforms: Strengthens support for tenant-aware job queues, now including payload-based tenant resolution for job retries (critical for async workflows like invoicing, notifications, or background processing).
• Async Workflow Reliability: Enables fault-tolerant job retries by resolving tenant context from payload data (e.g., failed email sends, webhook retries), reducing race conditions in distributed systems.
• Build vs. Buy: Buy for core multitenancy and job queue isolation (saves 1–2 months of custom development for retry logic). Customize only tenant resolution and payload parsing.
• Roadmap Priorities:
  • Phase 1 (Updated): Launch MVP with domain-based tenant isolation + tenant-aware job retries (e.g., tenant1.app.com with resilient background tasks).
  • Phase 2: Add tenant-specific queues (e.g., tenant1-jobs:default) for granular control over job routing.
  • Phase 3: Implement tenant-aware Artisan commands with payload validation (e.g., bulk operations for failed jobs).
• Use Cases:
  • B2B Platforms: Isolate client data and ensure retries (e.g., failed API calls, payment processing) resolve to the correct tenant.
  • Marketplaces: Separate vendor data with reliable job retries (e.g., order confirmations, payouts).
  • Regulatory Compliance: GDPR/CCPA isolation plus audit-ready job retries (e.g., data deletion requests).

When to Consider This Package

Adopt This Package If:

• Your Laravel app requires multi-tenancy with resilient job retries (e.g., failed background tasks must resolve tenant context from payload data).
• You use Laravel queues (Redis, database, SQS) and need tenant-aware job retries without custom middleware.
• You’re on Laravel 11+ and PHP 8.2+ (no legacy support overhead).
• Your team lacks expertise in job payload parsing or tenant context propagation in async workflows.
• You want MIT-licensed, actively maintained open-source (1.3K+ stars, now with payload-based tenant resolution for retries).

Look Elsewhere If:

• You need schema-per-tenant (this package focuses on database-per-tenant or shared tables).
• Your tenants require complex billing/subscription logic (pair with spatie/laravel-billing).
• You’re using non-Laravel frameworks (e.g., Symfony, Django).
• You need real-time multi-tenancy (e.g., WebSockets with tenant isolation—consider beyondcode/laravel-websockets).
• Your app requires tenant-specific caching (extend with spatie/laravel-cache-queue).
• You’re building a highly customized tenant resolution system (e.g., IP-based, header-based) and need payload parsing for retries.

How to Pitch It (Stakeholders)

For Executives:

*"This update fixes a critical gap in multi-tenant SaaS reliability: job retries now resolve tenant context from payload data, ensuring failed background tasks (e.g., emails, payments) always run in the correct tenant. For example, if tenant1.app.com’s invoice generation fails, the retry will automatically target tenant1’s database/queue—no more race conditions or data leaks.

ROI Highlights (Updated):

• Dev Time Saved: ~1–2 months less custom retry logic for async workflows.
• Scalability: Handles 100+ tenants with resilient job retries.
• Cost: Free (MIT license) with optional Spatie sponsorship.
• Risk Reduction: Eliminates tenant context loss in failed jobs (e.g., GDPR compliance, financial transactions).

Trade-off: We’ll still need to define how tenant data is embedded in job payloads (e.g., tenant_id field), but the package handles the retry resolution."*

For Engineering Teams:

*"New in 4.1.3: Tenant resolution from payload context during job retries. Here’s how we’ll leverage it:

1. Job Payload Design: Ensure jobs include tenant_id or tenant_key in their payload (e.g., SendInvoiceJob with tenant_id).
2. Retry Safety: Failed jobs (e.g., SendInvoiceJob::failed()) will auto-resolve the tenant from the payload, preventing context loss.
3. Testing: Validate retries with:

   Tenant::forget(); // Simulate lost context
   $job->release(); // Retry should resolve tenant from payload
   

Why This Matters:

• No More Silent Failures: Retries now work even if tenant context is lost mid-execution.
• Audit Trail: Failed jobs log with correct tenant context (critical for compliance).
• Backward Compatible: Existing tenant resolution (domains, subdirectories) still works.

Next Steps:

• Audit job payloads to include tenant_id (e.g., SendEmailJob, ProcessPaymentJob).
• Test retry workflows with Tenant::forget() to simulate edge cases.
• Document payload requirements for new jobs (e.g., ‘All async jobs must include tenant_id’)."*

Key Trade-offs (Updated):