Promise Laravel Package

Technical Evaluation

Architecture Fit

• Async Workflow Abstraction: Fits well in Laravel applications where async operations (e.g., API calls, queue jobs, external service integrations) require structured chaining. Avoids "callback hell" and promotes composable, declarative async logic.
• Event Loop Agnostic: Since it doesn’t tie to a specific event loop (unlike ReactPHP), it integrates cleanly with Laravel’s synchronous-by-default architecture while enabling async patterns where needed (e.g., in custom queue workers or background jobs).
• Library vs. Framework Use Case: Ideal for internal libraries (e.g., a service layer) or third-party integrations where async orchestration is required but a full event loop (e.g., Swoole, ReactPHP) is overkill.

Integration Feasibility

• Laravel Compatibility:
  • Works seamlessly with Laravel’s Queues (e.g., wrapping dispatch() calls in Promises for chaining).
  • Can augment HTTP clients (e.g., Guzzle) by converting async requests into Promises for sequential/parallel execution.
  • Useful in custom command handlers or event listeners where async dependencies exist.
• Dependency Lightweightness: No heavy dependencies (unlike Amp or ReactPHP), reducing bloat in monolithic apps.
• PHP Version Support: Assumes modern PHP (likely 8.1+), aligning with Laravel’s LTS support.

Technical Risk

• No Event Loop: Requires manual handling of async execution (e.g., Promises must be resolved via callbacks or coroutines). Not a drop-in replacement for async frameworks.
• Error Handling Nuances: PHP’s lack of native async/await means catch blocks must still use callbacks, which could lead to inconsistent error surfaces if not disciplined.
• Testing Complexity: Async flows require mocking/resolving Promises in tests (e.g., using Mockery or custom test doubles).
• Performance Overhead: Micro-optimizations may be needed for high-throughput scenarios (e.g., batch Promise resolution).

Key Questions

1. Async Execution Strategy:
   • How will Promises be resolved? (e.g., via Laravel Queues, custom event loop, or synchronous callbacks?)
   • Will this require a hybrid sync/async architecture (e.g., Promises for orchestration + Queues for execution)?
2. Error Resilience:
   • How will global Promise rejections be handled (e.g., logging, Sentry integration)?
   • Are there fallback mechanisms for unhandled rejections?
3. Adoption Scope:
   • Will this be used in core application logic (risky for monoliths) or bounded contexts (e.g., API clients, background jobs)?
4. Tooling Support:
   • Are there plans to integrate with Laravel’s Horizon (for queue monitoring) or Telescope (for Promise debugging)?
5. Alternatives:
   • Could Laravel’s built-in Illuminate\Support\Facades\Bus or Illuminate\Queue suffice, or is a Promise layer necessary for composability?

Integration Approach

Stack Fit

• Primary Use Cases:
  • API Clients: Chain multiple HTTP requests (e.g., fetch user → fetch user’s orders → aggregate data).
  • Queue Workers: Orchestrate dependent jobs (e.g., Promise::all([job1(), job2()])).
  • Event-Driven Logic: Compose async event handlers (e.g., event1.then(() => event2)).
• Laravel Synergy:
  • Service Providers: Register a Promise facade for global access.
  • Macros/Helpers: Extend Laravel’s Bus or Queue to return Promises natively.
  • Testing: Use Mockery to stub Promise resolutions in unit tests.

Migration Path

1. Pilot Phase:
   • Start with a single bounded context (e.g., a feature requiring async API calls).
   • Replace nested callbacks with Promise chains (e.g., Guzzle requests → Promise::all → process responses).
2. Core Integration:
   • Create a Promise-aware facade (e.g., Promise::dispatch($job)) to wrap Laravel Queues.
   • Add combinator helpers (e.g., Promise::race(), Promise::any()) for common patterns.
3. Tooling:
   • Build a Telescope channel to log Promise states/rejections.
   • Add Laravel Forge/Envoyer hooks for Promise-heavy deployments (e.g., warm-up async workers).

Compatibility

• Laravel Ecosystem:
  • Queues: Promises can wrap dispatch() calls but won’t replace the queue system.
  • HTTP Clients: Works with Guzzle/PestHTTP via custom adapters (e.g., GuzzlePromise::send($request)).
  • Events: Can bridge Event::dispatch() with Promises for async listeners.
• Third-Party Packages:
  • Spatie Async: Could complement this for event-loop integration.
  • Amp/PReact: Avoid unless migrating to full async PHP (this library is lighter).

Sequencing

1. Phase 1 (0–2 weeks):
   • Implement Promise wrappers for critical async paths (e.g., API integrations).
   • Add basic error handling and logging.
2. Phase 2 (2–4 weeks):
   • Extend to queue workers and event listeners.
   • Build combinator utilities (e.g., Promise::allSettled()).
3. Phase 3 (4+ weeks):
   • Integrate with monitoring (Telescope/Sentry).
   • Document patterns for team adoption (e.g., "How to avoid Promise leaks").

Operational Impact

Maintenance

• Pros:
  • Minimal Boilerplate: Lightweight core means less maintenance overhead.
  • Isolated Scope: If scoped to libraries/services, changes won’t disrupt the entire app.
• Cons:
  • Async Debugging: Harder to trace Promise chains in production (tools like Telescope or Xdebug async support needed).
  • Team Familiarity: Requires upskilling on Promise patterns (e.g., avoiding "unhandled rejection" pitfalls).

Support

• Developer Experience:
  • Readability: Reduces callback nesting but introduces new concepts (e.g., .then() chaining).
  • Onboarding: Need clear docs/examples for:
    • Resolving Promises in Laravel’s sync context.
    • Handling edge cases (e.g., circular dependencies, memory leaks).
• Production Issues:
  • Common Failure Modes:
    • Unhandled rejections crashing workers (mitigate with global handlers).
    • Memory leaks from unresolved Promises (use finally for cleanup).
  • Rollback Plan: If adoption stalls, revert to callbacks or use Laravel’s native async tools.

Scaling

• Performance:
  • Not a Silver Bullet: Promises alone don’t parallelize work (still need Queues/Workers).
  • Bottlenecks: Inefficient combinators (e.g., Promise::all() with many slow operations) may need batching.
• Horizontal Scaling:
  • Works well with Laravel’s queue workers (e.g., scale Promises across pods).
  • Avoid global Promise state (e.g., shared resolvers) in distributed setups.

Failure Modes

Ramp-Up

• Training:
  • Workshops: Hands-on sessions converting callback-heavy code to Promises.
  • Code Reviews: Enforce Promise best practices (e.g., no nested .then() chains).
• Documentation:
  • Cheat Sheet: Common patterns (e.g., "How to retry a failed Promise").
  • Decision Records: Justify why Promises were chosen over alternatives (e.g., Queues alone).
• Tooling:
  • IDE Support: PHPStorm/Xdebug for Promise debugging.
  • Testing: Example test cases for Promise mocking (e.g., Promise::resolve() stubs).