Replace SynchronousAdapter with SynchronousPushHandler (#270)

Co-authored-by: Alexander Makarov <sam@rmcreative.ru>

Author: vjik

.github/workflows/rector-cs.yml

@@ -1,7 +1,7 @@
 name: Rector + PHP CS Fixer
 
 on:
-  pull_request_target:
+  pull_request:
     paths:
       - 'config/**'
       - 'src/**'
@@ -12,7 +12,7 @@ on:
       - '.php-cs-fixer.dist.php'
 
 permissions:
-  contents: read
+  contents: write
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -21,8 +21,6 @@ concurrency:
 jobs:
   rector:
     uses: yiisoft/actions/.github/workflows/rector-cs.yml@master
-    secrets:
-      token: ${{ secrets.YIISOFT_GITHUB_TOKEN }}
     with:
       repository: ${{ github.event.pull_request.head.repo.full_name }}
       php: '8.1'

README.md

@@ -36,9 +36,11 @@ composer require yiisoft/queue
 For production use, you should install an adapter package that matches your message broker ([AMQP](https://github.com/yiisoft/queue-amqp), [Kafka](https://github.com/g41797/queue-kafka), [NATS](https://github.com/g41797/queue-nats), and [others](docs/guide/en/adapter-list.md)).
 See the [adapter list](docs/guide/en/adapter-list.md) and follow the adapter-specific documentation for installation and configuration details.
 
-> For development and testing, you can start without an external broker using the built-in [`SynchronousAdapter`](docs/guide/en/adapter-sync.md).
-> This adapter processes messages immediately in the same process, so it won't provide true async execution,
-> but it's useful for getting started and writing tests.
+> If you don't have an external broker — whether for development, testing, or because you want to
+> design around `QueueInterface` from day one and add a real broker later — you can run the queue
+> in [synchronous mode](docs/guide/en/synchronous-mode.md) (the adapter argument is optional).
+> In this mode messages are processed immediately in the same process, so it won't provide true
+> async execution, but the code stays the same when you switch to a real adapter.
 
 ### 2. Configure the queue
 
@@ -127,7 +129,7 @@ By default, Yii Framework uses [yiisoft/yii-console](https://github.com/yiisoft/
 
 See [Console commands](docs/guide/en/console-commands.md) for more details.
 
-> In case you're using the `SynchronousAdapter` for development purposes, you should not use these commands, as you have no asynchronous processing available. The messages are processed immediately when pushed.
+> In case you're running the queue in synchronous mode (no adapter), `queue:listen` logs an info message and exits. The messages are processed immediately when pushed.
 
 ## Documentation
 

docs/guide/en/README.md

@@ -5,7 +5,7 @@
 - [Prerequisites and installation](prerequisites-and-installation.md)
 - [Configuration with yiisoft/config](configuration-with-config.md)
 - [Adapter list](adapter-list.md)
-- [Synchronous adapter](adapter-sync.md)
+- [Synchronous mode](synchronous-mode.md)
 - [Queue names](queue-names.md)
 
 ## Build and handle messages

docs/guide/en/adapter-list.md

@@ -1,9 +1,11 @@
-Queue Adapters
--------------
+# Queue Adapters
 
-* [Synchronous](adapter-sync.md) - adapter for development and test environments
-* [AMQP](https://github.com/yiisoft/queue-amqp) - adapter over AMQP protocol via [amqplib](https://github.com/php-amqplib/php-amqplib)
+If you don't need (or don't yet have) a real broker, the queue can be used in
+[synchronous mode](synchronous-mode.md) — no adapter is required.
+
+For asynchronous processing pick one of the adapters below.
 
+* [AMQP](https://github.com/yiisoft/queue-amqp) - adapter over AMQP protocol via [amqplib](https://github.com/php-amqplib/php-amqplib)
 
 There are other queue adapters contributed and maintained by the community and available on GitHub, such as:
 * [NATS](https://github.com/g41797/queue-nats) - [NATS](https://nats.io/) JetStream adapter

docs/guide/en/adapter-sync.md

@@ -16,7 +16,6 @@ To use the queue, you need to create instances of the following classes:
 use Psr\Container\ContainerInterface;
 use Psr\Log\NullLogger;
 use Yiisoft\Injector\Injector;
-use Yiisoft\Queue\Adapter\SynchronousAdapter;
 use Yiisoft\Queue\Cli\SimpleLoop;
 use Yiisoft\Queue\Middleware\CallableFactory;
 use Yiisoft\Queue\Middleware\Consume\ConsumeMiddlewareDispatcher;
@@ -70,49 +69,23 @@ $worker = new Worker(
 // Create loop (SignalLoop requires ext-pcntl; SimpleLoop works without it)
 $loop = new SimpleLoop();
 
-// Create queue (adapter is wired in a second step due to mutual dependency)
+// Create queue. Without an adapter the queue runs in synchronous mode (messages are processed
+// immediately on push). Pass an adapter (e.g., AMQP, Redis) for asynchronous processing.
 $queue = new Queue(
     $worker,
     $loop,
     $logger,
     $pushMiddlewareDispatcher,
 );
 
-// SynchronousAdapter needs a queue reference — create it after the queue
-$adapter = new SynchronousAdapter($worker, $queue);
-
-// Attach the adapter to the queue (returns a new Queue instance)
-$queue = $queue->withAdapter($adapter);
-
 // Now you can push messages
 $message = new \Yiisoft\Queue\Message\Message('file-download', ['url' => 'https://example.com/file.pdf']);
 $queue->push($message);
 ```
 
 ## Using Queue Provider
 
-For multiple queue names, use `AdapterFactoryQueueProvider` (maps queue names to adapter definitions) or `PredefinedQueueProvider` (maps queue names to pre-built queue instances):
-
-```php
-use Yiisoft\Queue\Provider\AdapterFactoryQueueProvider;
-use Yiisoft\Queue\Adapter\SynchronousAdapter;
-
-// AdapterFactoryQueueProvider: each queue name maps to an adapter definition.
-// The provider wraps each adapter in a Queue with the given name.
-$definitions = [
-    'queue1' => new SynchronousAdapter($worker, $queue),
-    'queue2' => SynchronousAdapter::class,
-];
-
-$provider = new AdapterFactoryQueueProvider(
-    $queue,
-    $definitions,
-    $container,
-);
-
-$queueForQueue1 = $provider->get('queue1');
-$queueForQueue2 = $provider->get('queue2');
-```
+For multiple queue names, use `PredefinedQueueProvider` (maps queue names to pre-built queue instances):
 
 ```php
 use Yiisoft\Queue\Provider\PredefinedQueueProvider;

docs/guide/en/configuration-manual.md

@@ -15,5 +15,6 @@ Advanced applications eventually need the following tweaks:
 - **Named handlers or callable definitions** — map a short message type to a callable in [`yiisoft/queue.handlers` config](message-handler-advanced.md) when another application is the message producer and you cannot use FQCN as message type.
 - **Middleware pipelines** — adjust push/consume/failure behavior: collect metrics, modify messages, and so on. See [Middleware pipelines](middleware-pipelines.md) for details.
 
-For development and testing you can start with the synchronous adapter.
-For production you have to use a [real backend adapter](adapter-list.md) (AMQP, Kafka, SQS, etc.). If you do not have any preference, it's simpler to start with [yiisoft/queue-amqp](https://github.com/yiisoft/queue-amqp) and [RabbitMQ](https://www.rabbitmq.com/).
+If you don't have a broker yet (for development, testing, or as a stepping stone before introducing
+async processing), you can run the queue in [synchronous mode](synchronous-mode.md).
+For real asynchronous processing pick a [backend adapter](adapter-list.md) (AMQP, Kafka, SQS, etc.). If you do not have any preference, it's simpler to start with [yiisoft/queue-amqp](https://github.com/yiisoft/queue-amqp) and [RabbitMQ](https://www.rabbitmq.com/).

docs/guide/en/configuration-with-config.md

@@ -33,6 +33,8 @@ The following command launches a daemon, which infinitely consumes messages from
 yii queue:listen [queueName]
 ```
 
+> **Note:** If the queue is not configured with an adapter (synchronous mode), the command logs an info message and exits gracefully.
+
 ## 3. Listen to multiple queues
 
 The following command iterates through multiple queues and is meant to be used in development environment only, as it consumes a lot of CPU for iterating through queues. You can pass to it:

docs/guide/en/console-commands.md

@@ -7,7 +7,7 @@ The API surface is:
 - `QueueInterface::status(string|int $id): MessageStatus`
 - `AdapterInterface::status(string|int $id): MessageStatus`
 
-Status tracking support depends on the adapter. If an adapter doesn't keep status history, calling `status()` with that ID will throw `InvalidArgumentException`.
+Status tracking support depends on the adapter. If an adapter doesn't support status tracking or can't find the message by ID, it returns `MessageStatus::NOT_FOUND`.
 
 ## Getting a message ID
 
@@ -30,6 +30,9 @@ The ID type (`string` or `int`) and how long it stays queryable are adapter-spec
 
 Statuses are represented by the `Yiisoft\Queue\MessageStatus` enum:
 
+- `MessageStatus::NOT_FOUND`
+  The message is not known to the queue, or the adapter doesn't support status tracking.
+
 - `MessageStatus::WAITING`
   The message is in the queue and has not been picked up yet.
 
@@ -42,7 +45,7 @@ Statuses are represented by the `Yiisoft\Queue\MessageStatus` enum:
 In addition to enum cases, `MessageStatus` provides a string key via `MessageStatus::key()`:
 
 ```php
-$statusKey = $status->key(); // "waiting", "reserved" or "done"
+$statusKey = $status->key(); // "not-found", "waiting", "reserved" or "done"
 ```
 
 ## Querying a status
@@ -73,10 +76,10 @@ if ($status === MessageStatus::DONE) {
 }
 ```
 
-## Errors and edge cases
+## Edge cases
 
-- **Unknown ID**
-  If an adapter can't find the message by ID, it must throw `InvalidArgumentException`.
+- **Unknown ID or unsupported tracking**
+  If an adapter doesn't support status tracking or can't find the message by ID, it returns `MessageStatus::NOT_FOUND`.
 
 - **Timing**
   `RESERVED` can be short-lived and difficult to observe: depending on the adapter, a message may move from `WAITING` to `RESERVED` and then to `DONE` quickly.

docs/guide/en/message-status.md

@@ -58,7 +58,7 @@ $provider = new QueueFactoryProvider(
     [
         'emails' => [
             'class' => Queue::class,
-            '__construct()' => [$worker, $pushDispatcher, $eventDispatcher, $adapter],
+            '__construct()' => [$worker, $loop, $logger, $pushDispatcher, $adapter],
         ],
     ],
     $container,