Promise Laravel Package

Technical Evaluation

Architecture Fit

• Event-Driven & Async Workflows: Perfect fit for Laravel’s queue workers, HTTP clients, and real-time features (e.g., WebSockets, database listeners). Aligns with Laravel’s growing async ecosystem (e.g., spatie/async).
• Promise/A Compatibility: Enables composable async chains (e.g., Promise.all() for parallel API calls) without callback hell, reducing cognitive complexity.
• Laravel Integration Points:
  • Queues: Replace queue:work callbacks with Deferred promises for chained async tasks.
  • HTTP Clients: Use Promise.race() to implement timeouts for external APIs.
  • Middleware: Leverage finally() for cleanup (e.g., logging, resource release).
• Type Safety: PHP 8.4+ strict types (e.g., resolve(T $value)) catch bugs early, improving maintainability.

Integration Feasibility

• Low Friction: Replaces reactphp/promise with 1:1 API parity (same methods: then(), catch(), all(), etc.).
• Laravel Ecosystem Compatibility:
  • Works with Guzzle HTTP Client, Laravel Queues, and Laravel Echo (WebSockets).
  • Can integrate with Laravel’s Illuminate\Support\Facades via custom facades (e.g., Promise::resolve()).
• Dependency Graph: Lightweight (~1MB) with no external PHP extensions required.

Technical Risk

Key Questions

1. Async Strategy:
   • Will this replace Laravel Queues entirely, or supplement them (e.g., for in-memory async)?
   • How will we handle long-running Promises (e.g., timeouts, cancellation)?
2. Error Observability:
   • Should we extend set_rejection_handler() to integrate with Laravel’s logging (e.g., Log::error())?
3. Testing:
   • How will we mock Promises in PHPUnit (e.g., for unit tests of async services)?
4. Adoption Path:
   • Start with non-critical paths (e.g., API clients) before migrating queues.
   • Train devs on Promise patterns (e.g., all() vs. race()).

Integration Approach

Stack Fit

• Laravel Core: Compatible with PHP 8.1+, Composer, and PSR-15 middleware.
• Async Libraries:
  • Guzzle HTTP Client: Wrap Guzzle\Promise calls in internal/promise for unified error handling.
  • Laravel Queues: Use Deferred to chain jobs (e.g., dispatch()->then(fn() => dispatchNext())).
  • Laravel Echo: Handle WebSocket events as Promises (e.g., socket.on('message')->then(...)).
• Database:
  • Eloquent: Replace DB::select() callbacks with Promise.resolve(DB::select(...)).
  • Query Builders: Chain async queries (e.g., User::where(...)->get()->then(...)).

Migration Path

Compatibility

• Backward Compatibility:
  • v3.x drops deprecated APIs (e.g., otherwise()), but provides BC aliases (e.g., catch() replaces otherwise()).
  • v2.x still supported for gradual migration.
• Laravel-Specific:
  • Service Providers: Register Promise as a singleton in AppServiceProvider.
  • Facades: Create Promise facade for resolve(), reject(), etc.
  • Testing: Use Mockery to stub Promises in unit tests.

Sequencing

1. Phase 1 (Week 1-2):
   • Add internal/promise to composer.json.
   • Replace Guzzle callbacks with Promises in API services.
   • Write integration tests for Promise chains.
2. Phase 2 (Week 3-4):
   • Migrate queue jobs to use Deferred.
   • Add Promise facade and global rejection handler.
3. Phase 3 (Week 5+):
   • Replace Eloquent callbacks with Promises.
   • Optimize parallel operations (e.g., Promise.all() for batch processing).

Operational Impact

Maintenance

• Pros:
  • Production-Ready: Backed by ReactPHP’s battle-tested codebase.
  • Active Development: Regular updates (e.g., PHP 8.4 support, type safety).
  • Low Boilerplate: No need to maintain custom Promise logic.
• Cons:
  • Dependency Risk: Relies on ReactPHP’s ecosystem (though internal/promise is standalone).
  • Learning Curve: Team must adopt Promise patterns (e.g., then/catch/finally).
• Tooling:
  • PHPStan: Enforce type safety (already used by the package).
  • PestPHP: Test async workflows with expectPending().

Support

• Debugging:
  • Unhandled Rejections: Logged by default (configurable via set_rejection_handler()).
  • Stack Traces: Include previous exceptions for nested Promise failures.
• Monitoring:
  • Integrate with Laravel Horizon to track Promise-based queue jobs.
  • Add Sentry integration for error reporting.
• Documentation:
  • Create internal docs for Laravel-specific Promise patterns (e.g., "How to chain queue jobs").
  • Example: Promise::race([$job1, $job2]) for timeout logic.

Scaling

• Performance:
  • I/O-Bound: Near-zero overhead for async operations (e.g., HTTP, DB).
  • CPU-Bound: Avoid Promises for synchronous tasks (use native PHP).
• Concurrency:
  • Parallelism: Promise.all() scales horizontally (e.g., batch API calls).
  • Cancellation: Use cancel() for long-running Promises (e.g., user-initiated timeouts).
• Resource Usage:
  • Memory: Lightweight (no global state; Promises are immutable).
  • Threads: Single-threaded; safe for Laravel’s request lifecycle.

Failure Modes

Ramp-Up

• Training:
  • Workshops: Teach Promise patterns (e.g., then/catch, all/race).
  • Code Reviews: Enforce Promise usage in async services.
• **On