Refactor: Introduce fluent API for dispatch() helper function

[huangdijia]

Summary

This PR refactors the dispatch() helper function to introduce a fluent API pattern, making it more flexible and intuitive to use. Instead of immediately executing dispatch operations, the function now returns pending dispatch objects that can be configured using method chaining before execution.

Changes

New Classes

• PendingAsyncQueueDispatch: Handles JobInterface dispatching with chainable configuration methods

  • onPool(string $pool): Specify which queue pool to use
  • delay(int $delay): Set delay in seconds before job execution
  • setMaxAttempts(int $maxAttempts): Configure maximum retry attempts

• PendingAmqpProducerMessageDispatch: Handles AMQP message dispatching with chainable configuration

  • onPool(string $pool): Specify which connection pool to use
  • setConfirm(bool $confirm): Enable/disable producer confirmation
  • setTimeout(int $timeout): Set operation timeout

• PendingKafkaProducerMessageDispatch: Handles Kafka message dispatching with chainable configuration

  • onPool(string $pool): Specify which producer pool to use
  • withHeader(string $key, string $value): Add custom headers to messages

Modified Files

• Functions.php: Refactored the dispatch() function to return Pending dispatch objects instead of immediately dispatching
  • Removed direct dependencies on DriverFactory, Producer, and ProducerManager
  • Improved type safety with enhanced PHPDoc annotations
  • Simplified function signature

API Examples

Before (positional parameters)

// AsyncQueue
dispatch($job, 'custom-pool', 10, 3); // pool, delay, maxAttempts

// AMQP
dispatch($message, true, 10); // confirm, timeout

After (fluent API)

// AsyncQueue - cleaner and more readable
dispatch($job)
    ->onPool('custom-pool')
    ->delay(10)
    ->setMaxAttempts(3);

// AMQP - explicit configuration
dispatch($message)
    ->setConfirm(true)
    ->setTimeout(10);

// Kafka - with custom headers
dispatch($kafkaMessage)
    ->onPool('analytics')
    ->withHeader('trace-id', '123456');

// Basic usage remains unchanged
dispatch($job); // Still works!

Benefits

1. Improved Readability: Method names clearly indicate what's being configured
2. Better IDE Support: Type hints and autocomplete work better with object methods
3. Flexible Configuration: Only specify the options you need
4. Laravel-like API: Familiar pattern for developers coming from Laravel
5. Backward Compatible: Basic dispatch($job) usage still works exactly the same
6. Deferred Execution: Configuration happens before dispatch via __destruct()
7. Better Separation of Concerns: Dispatch logic moved to dedicated classes

Breaking Changes

None. The basic usage dispatch($job) remains unchanged. Advanced configurations that used positional parameters should migrate to the fluent API.

Test Plan

• Verify basic dispatch still works: dispatch($job)
• Test fluent API for AsyncQueue with pool, delay, and maxAttempts
• Test fluent API for AMQP with confirm and timeout settings
• Test fluent API for Kafka with custom headers
• Verify Conditionable trait works with when() and unless() methods
• Ensure backward compatibility with existing code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review (1)

• main

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/fluent-dispatch-api

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}