Replace SynchronousAdapter with SynchronousPushHandler

.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/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/console-commands.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/message-status.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/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,38 @@
+# 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, create the queue instance 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()` logs an info message and returns without listening.
+- `status()` always returns `MessageStatus::NOT_FOUND` — there is no message storage to track IDs.

src/Adapter/AdapterInterface.php

@@ -4,7 +4,6 @@
 
 namespace Yiisoft\Queue\Adapter;
 
-use InvalidArgumentException;
 use Yiisoft\Queue\MessageStatus;
 use Yiisoft\Queue\Message\MessageInterface;
 
@@ -18,11 +17,10 @@ interface AdapterInterface
  public function runExisting(callable $handlerCallback): void;
 
  /**
- * Returns status code of a message with the given id.
+ * Returns status code of a message with the given ID.
+ * Returns {@see MessageStatus::NOT_FOUND} when status tracking is not supported or there is no such id.
  *
  * @param int|string $id ID of a message.
- *
- * @throws InvalidArgumentException When there is no such id in the adapter.
  */
  public function status(string|int $id): MessageStatus;
 

src/MessageStatus.php

@@ -6,13 +6,15 @@
 
 enum MessageStatus: int
 {
+ case NOT_FOUND = 0;
  case WAITING = 1;
  case RESERVED = 2;
  case DONE = 3;
 
  public function key(): string
  {
  return match ($this) {
+ self::NOT_FOUND => 'not-found',
  self::WAITING => 'waiting',
  self::RESERVED => 'reserved',
  self::DONE => 'done',

src/Middleware/Push/MiddlewarePushStack.php

@@ -19,8 +19,7 @@ final class MiddlewarePushStack implements MessageHandlerPushInterface
 
  /**
  * @param Closure[] $middlewares Middlewares.
- * @param MessageHandlerPushInterface $finishHandler Fallback handler
- * events.
+ * @param MessageHandlerPushInterface $finishHandler Final handler invoked after all middlewares are processed.
  */
  public function __construct(
  private readonly array $middlewares,

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;
+ }
+}