Replace SynchronousAdapter with SynchronousPushHandler

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 call sites stay 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) for development purposes, you should not use these commands, as you have no asynchronous processing available. 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/configuration-manual.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-with-config.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/queue-names-advanced.md

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

docs/guide/en/queue-names.md

@@ -30,19 +30,22 @@ If you use only a single queue, you can inject `QueueInterface` directly.
 
 #### 1.1 Configure an Adapter
 
-Adapter is what actually sends messages to a queue broker.
-
-Minimal DI configuration example:
+An adapter is what actually delivers messages to a queue broker. Pick one from the
+[adapter list](adapter-list.md), install it, and bind it in DI:
 
 ```php
-use Yiisoft\Queue\Adapter\SynchronousAdapter;
 use Yiisoft\Queue\Adapter\AdapterInterface;
 
 return [
-    AdapterInterface::class => SynchronousAdapter::class,
+    AdapterInterface::class => YourBrokerAdapter::class,
 ];
 ```
-> `SynchronousAdapter` is for learning/testing only. For production, install a real adapter, see adapter list: [adapter-list](adapter-list.md).
+
+Refer to the chosen adapter's documentation for connection settings and any additional bindings.
+
+If you don't have a broker yet, you can skip this step — the queue will run in
+[synchronous mode](synchronous-mode.md) and process messages immediately on `push()`. You can
+plug in a real adapter later without changing any call sites.
 
 #### 1.2. Configure a default queue name
 

docs/guide/en/synchronous-mode.md

@@ -0,0 +1,39 @@
+Synchronous Mode
+================
+
+Run tasks synchronously in the same process. Useful for:
+
+- developing and debugging an application;
+- writing tests;
+- production setups where the application is built around `QueueInterface` from day one but
+  doesn't have an external broker yet — you can switch to a real adapter later without touching
+  the call sites.
+
+To enable it, construct the queue without an adapter (the `adapter` argument defaults to `null`):
+
+```php
+$logger = $DIContainer->get(\Psr\Log\LoggerInterface::class);
+
+$worker = $DIContainer->get(\Yiisoft\Queue\Worker\WorkerInterface::class);
+$loop = $DIContainer->get(\Yiisoft\Queue\Cli\LoopInterface::class);
+$pushMiddlewareDispatcher = $DIContainer->get(
+    \Yiisoft\Queue\Middleware\Push\PushMiddlewareDispatcher::class
+);
+
+$queue = new Yiisoft\Queue\Queue(
+    $worker,
+    $loop,
+    $logger,
+    $pushMiddlewareDispatcher,
+);
+```
+
+In synchronous mode every message passed to `push()` is processed immediately by the worker.
+The value returned from `push()` is the message after push-middlewares — without an `IdEnvelope`,
+since no adapter is involved to assign an ID.
+
+Limitations:
+
+- `run()` does nothing and returns `0`.
+- `listen()` throws `BadMethodCallException`.
+- `status()` throws `BadMethodCallException` — there is no message storage to track IDs.

src/Middleware/Push/SynchronousPushHandler.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Queue\Middleware\Push;
+
+use Yiisoft\Queue\Message\MessageInterface;
+use Yiisoft\Queue\QueueInterface;
+use Yiisoft\Queue\Worker\WorkerInterface;
+
+/**
+ * @internal
+ */
+final class SynchronousPushHandler implements MessageHandlerPushInterface
+{
+    public function __construct(
+        private readonly WorkerInterface $worker,
+        private readonly QueueInterface $queue,
+    ) {}
+
+    public function handlePush(MessageInterface $message): MessageInterface
+    {
+        $this->worker->process($message, $this->queue);
+
+        return $message;
+    }
+}

src/Queue.php

@@ -5,6 +5,7 @@
 namespace Yiisoft\Queue;
 
 use BackedEnum;
+use BadMethodCallException;
 use Psr\Log\LoggerInterface;
 use Yiisoft\Queue\Adapter\AdapterInterface;
 use Yiisoft\Queue\Cli\LoopInterface;
@@ -13,6 +14,7 @@
 use Yiisoft\Queue\Middleware\Push\MessageHandlerPushInterface;
 use Yiisoft\Queue\Middleware\Push\MiddlewarePushInterface;
 use Yiisoft\Queue\Middleware\Push\PushMiddlewareDispatcher;
+use Yiisoft\Queue\Middleware\Push\SynchronousPushHandler;
 use Yiisoft\Queue\Worker\WorkerInterface;
 use Yiisoft\Queue\Message\IdEnvelope;
 use Yiisoft\Queue\Provider\QueueProviderInterface;
@@ -23,21 +25,23 @@ final class Queue implements QueueInterface
      * @var array|array[]|callable[]|MiddlewarePushInterface[]|string[]
      */
     private array $middlewareDefinitions;
-    private AdapterPushHandler $adapterPushHandler;
+    private MessageHandlerPushInterface $finalPushHandler;
     private string $name;
 
     public function __construct(
-        private readonly AdapterInterface $adapter,
         private readonly WorkerInterface $worker,
         private readonly LoopInterface $loop,
         private readonly LoggerInterface $logger,
         private readonly PushMiddlewareDispatcher $pushMiddlewareDispatcher,
+        private readonly ?AdapterInterface $adapter = null,
         string|BackedEnum $name = QueueProviderInterface::DEFAULT_QUEUE,
         MiddlewarePushInterface|callable|array|string ...$middlewareDefinitions,
     ) {
         $this->name = StringNormalizer::normalize($name);
         $this->middlewareDefinitions = $middlewareDefinitions;
-        $this->adapterPushHandler = new AdapterPushHandler($this->adapter);
+        $this->finalPushHandler = $adapter === null
+            ? new SynchronousPushHandler($worker, $this)
+            : new AdapterPushHandler($adapter);
     }
 
     public function getName(): string
@@ -59,6 +63,14 @@ public function push(
             $this->createPushHandler(...$middlewareDefinitions),
         );
 
+        if ($this->adapter === null) {
+            $this->logger->info(
+                'Processed message with message type "{messageType}" synchronously.',
+                ['messageType' => $message->getType()],
+            );
+            return $message;
+        }
+
         /** @var string $messageId */
         $messageId = $message->getMetadata()[IdEnvelope::MESSAGE_ID_KEY] ?? 'null';
         $this->logger->info(
@@ -71,6 +83,13 @@ public function push(
 
     public function run(int $max = 0): int
     {
+        if ($this->adapter === null) {
+            $this->logger->debug(
+                'Queue is in synchronous mode (no adapter). Messages are processed on push. run() does nothing.',
+            );
+            return 0;
+        }
+
         $this->logger->debug('Start processing queue messages.');
         $count = 0;
 
@@ -95,13 +114,25 @@ public function run(int $max = 0): int
 
     public function listen(): void
     {
+        if ($this->adapter === null) {
+            throw new BadMethodCallException(
+                'Cannot listen without an adapter. Queue is in synchronous mode.',
+            );
+        }
+
         $this->logger->info('Start listening to the queue.');
         $this->adapter->subscribe(fn(MessageInterface $message) => $this->handle($message));
         $this->logger->info('Finish listening to the queue.');
     }
 
     public function status(string|int $id): MessageStatus
     {
+        if ($this->adapter === null) {
+            throw new BadMethodCallException(
+                'Cannot get message status without an adapter. Queue is in synchronous mode.',
+            );
+        }
+
         return $this->adapter->status($id);
     }
 
@@ -131,12 +162,12 @@ private function handle(MessageInterface $message): bool
     private function createPushHandler(MiddlewarePushInterface|callable|array|string ...$middlewares): MessageHandlerPushInterface
     {
         return new class (
-            $this->adapterPushHandler,
+            $this->finalPushHandler,
             $this->pushMiddlewareDispatcher,
             array_merge($this->middlewareDefinitions, $middlewares),
         ) implements MessageHandlerPushInterface {
             public function __construct(
-                private readonly AdapterPushHandler $adapterPushHandler,
+                private readonly MessageHandlerPushInterface $finishHandler,
                 private readonly PushMiddlewareDispatcher $dispatcher,
                 /**
                  * @var array|array[]|callable[]|MiddlewarePushInterface[]|string[]
@@ -148,7 +179,7 @@ public function handlePush(MessageInterface $message): MessageInterface
             {
                 return $this->dispatcher
                     ->withMiddlewares($this->middlewares)
-                    ->dispatch($message, $this->adapterPushHandler);
+                    ->dispatch($message, $this->finishHandler);
             }
         };
     }