### setup()

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-transport.md

Creates the required database table schema if it does not exist.

```APIDOC
## setup()

### Description
Creates the `messenger_messages` table with all required columns and indexes. This is typically called automatically during initialization.

### Returns
- **void**

### Throws
- TransportException: If schema creation fails
```

--------------------------------

### setup()

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/connection.md

Creates or updates the database schema for message storage.

```APIDOC
## setup()

### Description
Introspects the database schema and creates the `messenger_messages` table if it doesn't exist, with all required columns and indexes.

### Returns
- **void**

### Throws
- Exception (if schema modifications fail)
```

--------------------------------

### Supports method examples

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-transport-factory.md

Demonstrates how the supports method validates DSN strings starting with doctrine://.

```php
$factory = new DoctrineTransportFactory($connectionRegistry);

// Returns true
$factory->supports('doctrine://default', []);
$factory->supports('doctrine://default?table_name=msgs', []);

// Returns false
$factory->supports('amqp://localhost', []);
$factory->supports('redis://localhost', []);
```

--------------------------------

### Manual Schema Setup

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/README.md

Configures the database schema and creates the necessary transport table.

```php
// In migration
$transport->configureSchema($schema, $connection, fn() => true);
$connection->setup(); // Create table
```

--------------------------------

### Configuring Serializers for DoctrineSender

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-sender.md

Examples of initializing DoctrineSender with different serializer implementations.

```php
// With default PHP serializer
$sender = new DoctrineSender($connection);

// With JSON serializer (if installed)
$sender = new DoctrineSender($connection, new JsonSerializer());

// With custom serializer
$sender = new DoctrineSender($connection, new CustomSerializer());
```

--------------------------------

### Handle TableNotFoundException

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/errors.md

Demonstrates the difference between automatic setup and manual recovery when the messenger table is missing.

```php
// With auto_setup=true (default)
$transport->send($envelope); // Table doesn't exist yet
// Internally: TableNotFoundException caught → setup() → retry → success

// With auto_setup=false
try {
    $transport->send($envelope); // Table doesn't exist
} catch (TableNotFoundException $e) {
    // Must call setup() manually
    $transport->setup();
    $transport->send($envelope); // Now succeeds
}
```

--------------------------------

### Create transport examples

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-transport-factory.md

Demonstrates basic transport creation, usage with PostgreSQL optimizations, and disabling LISTEN/NOTIFY.

```php
$factory = new DoctrineTransportFactory($connectionRegistry);

$transport = $factory->createTransport(
    'doctrine://default?table_name=messages',
    [],
    $serializer
);
```

```php
$listener = new PostgreSqlNotifyOnIdleListener($logger);
$factory = new DoctrineTransportFactory($connectionRegistry, $listener);

// LISTEN/NOTIFY will be enabled automatically for PostgreSQL
$transport = $factory->createTransport(
    'doctrine://default?use_notify=true',
    ['transport_name' => 'async_transport'],
    $serializer
);
```

```php
$transport = $factory->createTransport(
    'doctrine://default',
    ['use_notify' => false],
    $serializer
);
```

--------------------------------

### Basic Single-Queue Messenger Setup

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/configuration.md

Standard configuration for a single transport and multiple buses.

```yaml
framework:
  messenger:
    transports:
      async:
        dsn: 'doctrine://default'
    
    buses:
      command_bus:
        middleware:
          - routing_handlers
      
      event_bus:
        default_middleware: 'allow_no_handlers'
    
    routing:
      'App\Message\UserCreatedEvent': event_bus
      'App\Message\SendEmailCommand': command_bus
```

--------------------------------

### Setup database schema in PHP

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-transport.md

Ensures the required messenger table exists in the database.

```php
$transport = new DoctrineTransport($connection, $serializer);
$transport->setup(); // Ensure table exists
```

--------------------------------

### Example of invalid connection configuration

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-notify-listener.md

Demonstrates a configuration that triggers a LogicException due to mismatched DBAL connections.

```php
// This would fail validation
$listener->addConnection('async', $postgresConnection1); // DBAL conn A, table 'messages'
$listener->addConnection('events', $postgresConnection2); // DBAL conn B, table 'messages'

// onWorkerStarted() would throw:
// "PostgreSQL transports "async" and "events" use different DBAL connections..."
```

--------------------------------

### Production Setup with Manual Schema Management

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/configuration.md

Disable auto_setup for production and define the schema manually via migrations.

```yaml
doctrine:
  dbal:
    connections:
      messenger:
        url: '%env(resolve:MESSENGER_DATABASE_URL)%'

framework:
  messenger:
    transports:
      async:
        dsn: 'doctrine://messenger?auto_setup=false&table_name=app_messages'
    
    buses:
      command_bus:
        middleware:
          - routing_handlers
```

```php
// migrations/Version20240101000000.php
public function up(Schema $schema): void
{
    $table = $schema->createTable('app_messages');
    $table->addColumn('id', 'bigint', ['autoincrement' => true, 'notnull' => true]);
    $table->addColumn('body', 'text', ['notnull' => true]);
    $table->addColumn('headers', 'text', ['notnull' => true]);
    $table->addColumn('queue_name', 'string', ['length' => 190, 'notnull' => true]);
    $table->addColumn('created_at', 'datetime_immutable', ['notnull' => true]);
    $table->addColumn('available_at', 'datetime_immutable', ['notnull' => true]);
    $table->addColumn('delivered_at', 'datetime_immutable', ['notnull' => false]);
    $table->setPrimaryKey(['id']);
    $table->addIndex(['queue_name', 'available_at', 'delivered_at', 'id']);
}
```

--------------------------------

### Instantiating DoctrineTransportFactory

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-transport-factory.md

Example showing the manual instantiation of the factory using a connection registry and an optional listener.

```php
$factory = new DoctrineTransportFactory(
    $connectionRegistry,
    $notifyOnIdleListener
);
```

--------------------------------

### Handle worker start event

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-notify-listener.md

Initializes the LISTEN/NOTIFY mechanism when a worker starts. Validates that all transports share the same database connection and table.

```php
public function onWorkerStarted(WorkerStartedEvent $event): void
```

--------------------------------

### Send Messages with DoctrineSender

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-sender.md

Examples demonstrating immediate, delayed, and multi-stamp message dispatching using the send method.

```php
$sender = new DoctrineSender($connection);

$message = new MyMessage('content');
$envelope = new Envelope($message);

$sentEnvelope = $sender->send($envelope);
$messageId = $sentEnvelope->last(TransportMessageIdStamp::class)->getId();

echo "Message sent with ID: $messageId";
```

```php
$message = new MyMessage('content');
$envelope = new Envelope($message);

// Delay message for 1 minute (60,000 milliseconds)
$envelope = $envelope->with(new DelayStamp(60000));

$sentEnvelope = $sender->send($envelope);
echo "Message will be available in 60 seconds";
```

```php
$message = new EmailMessage('user@example.com', 'Hello');
$envelope = new Envelope($message);

// Add multiple stamps
$envelope = $envelope
    ->with(new DelayStamp(30000))
    ->with(new BusNameStamp('async_bus'));

$sentEnvelope = $sender->send($envelope);
```

--------------------------------

### get(int $fetchSize)

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-connection.md

Retrieves messages from the queue with PostgreSQL LISTEN/NOTIFY optimization.

```APIDOC
## get(int $fetchSize)

### Description
Retrieves messages from the queue. Optimizes retrieval for PostgreSQL LISTEN/NOTIFY. If an external listener handles LISTEN/NOTIFY, it uses getNotify() to wait for notifications without blocking; otherwise, it delegates to the parent get() method.

### Method
public function get(int $fetchSize = 1): ?array

### Parameters
- **fetchSize** (int) - Optional - Number of messages to retrieve (Default: 1)

### Returns
- ?array - Array of message rows, or null if queue empty and not notified
```

--------------------------------

### Configure auto_setup for Doctrine Messenger

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/configuration.md

Control whether the database table is automatically created. Use manual setup for production environments.

```yaml
transports:
  # Auto-create (default)
  async:
    dsn: 'doctrine://default'
  
  # Manual setup only
  production:
    dsn: 'doctrine://prod?auto_setup=false'
```

```php
// In console command or migration
$transport->setup();
```

```php
// migrations/Version20240101000000.php
public function up(Schema $schema): void
{
    $transport = new DoctrineTransport($connection, $serializer);
    $transport->configureSchema($schema, $dbalConnection, function() { return true; });
}
```

--------------------------------

### Retrieve messages with PostgreSQL LISTEN/NOTIFY

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-connection.md

Demonstrates using the get() method within a worker loop, configured with an external listener.

```php
$connection = new PostgreSqlConnection($config, $dbal);

// Use with external listener
$connection->listen(false);

// Worker loop
while (true) {
    $messages = $connection->get(5);
    if (null === $messages) {
        // Queue is empty or waiting for notification
        sleep(1);
        continue;
    }
    
    foreach ($messages as $msg) {
        process($msg);
    }
}
```

--------------------------------

### Configure PostgreSQL Multi-Queue Transport

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-transport-factory.md

Example configuration for enabling LISTEN/NOTIFY on multiple queues sharing the same Doctrine DBAL connection.

```yaml
framework:
  messenger:
    transports:
      notifications:
        dsn: 'doctrine://default?queue_name=notifications&use_notify=true'
      emails:
        dsn: 'doctrine://default?queue_name=emails&use_notify=true'
    
    buses:
      command_bus:
        middleware:
          - routing_handlers
      
      event_bus:
        default_middleware: 'allow_no_handlers'
```

--------------------------------

### Retrieve messages with get()

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-receiver.md

Retrieves and deserializes messages from the database queue, supporting an optional fetch size.

```php
public function get(/* int $fetchSize = 1 */): iterable
```

```php
$receiver = new DoctrineReceiver($connection);

foreach ($receiver->get(5) as $envelope) {
    /** @var MyMessage $message */
    $message = $envelope->getMessage();
    echo "Processing: " . $message->getContent();
}
```

--------------------------------

### onWorkerStarted(WorkerStartedEvent $event)

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-notify-listener.md

Initializes the LISTEN/NOTIFY session when a worker starts.

```APIDOC
## onWorkerStarted(WorkerStartedEvent $event)

### Description
Event handler for when a worker starts processing messages. It performs connection validation and registers LISTEN on the database connections.

### Parameters
- **event** (WorkerStartedEvent) - Required - Event containing worker metadata

### Returns
- **void**

### Throws
- **LogicException** - If multiple transports use different DBAL connections or table names.
```

--------------------------------

### Retrieving messages with get()

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-transport.md

Fetches a specified number of messages from the queue, locking them for processing.

```php
public function get(/* int $fetchSize = 1 */): iterable
```

```php
$transport = new DoctrineTransport($connection, $serializer);

foreach ($transport->get(5) as $envelope) {
    // Process message
    $message = $envelope->getMessage();
    echo $message->content;
}
```

--------------------------------

### DoctrineTransportFactory implementation

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-notify-listener.md

Example of how the transport factory handles the use_notify option to register connections with the listener.

```php
class DoctrineTransportFactory implements TransportFactoryInterface {
    public function createTransport(string $dsn, array $options, SerializerInterface $serializer): TransportInterface {
        $useNotify = $options['use_notify'] ?? true;
        $transportName = $options['transport_name'] ?? null;
        
        if ($useNotify && $isPostgreSQL) {
            $connection = new PostgreSqlConnection($config, $dbalConnection);
            
            if (null !== $transportName) {
                $this->notifyOnIdleListener?->addConnection($transportName, $connection);
            }
        }
        
        return new DoctrineTransport($connection, $serializer);
    }
}
```

--------------------------------

### Create Envelope with DoctrineReceivedStamp

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-received-stamp.md

Example of adding the stamp during envelope creation within a receiver.

```php
class DoctrineReceiver {
    private function createEnvelopeFromData(array $data): Envelope {
        $stamps = [
            new DoctrineReceivedStamp($data['id']),
            new TransportMessageIdStamp($data['id']),
        ];
        
        return $this->serializer->decode($data)->with(...$stamps);
    }
}
```

--------------------------------

### Doctrine Messenger DSN Examples

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/types.md

Various configurations for Doctrine transport using different connection names and query parameters.

```text
doctrine://default
doctrine://default?table_name=app_messages
doctrine://events?queue_name=events&redeliver_timeout=7200
doctrine://default?table_name=messages&auto_setup=false&use_notify=false
```

--------------------------------

### PostgreSQL Multi-Transport Configuration Errors

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/errors.md

Examples showing incorrect PHP configuration for PostgreSQL transports and the correct YAML configuration approach.

```php
// WRONG: Different connections
$listener = new PostgreSqlNotifyOnIdleListener();
$listener->addConnection('async', $postgresConnection1);  // DBAL A
$listener->addConnection('events', $postgresConnection2); // DBAL B

// When worker starts consuming both:
// Throws LogicException:
// "PostgreSQL transports "async" and "events" use different DBAL connections..."
```

```yaml
# Both should use same connection
async:
  dsn: 'doctrine://default?queue_name=async'   # Same 'default' connection
events:
  dsn: 'doctrine://default?queue_name=events'  # Same 'default' connection
```

--------------------------------

### Logging Worker Status

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-notify-listener.md

Example of triggering a worker running event and the resulting debug log output.

```php
$listener->onWorkerRunning($event);
// Logs: "Worker waiting for PostgreSQL LISTEN/NOTIFY wake-up." with timeout_ms
```

```text
[2024-01-01 10:00:00] DEBUG: Worker waiting for PostgreSQL LISTEN/NOTIFY wake-up. {"timeout_ms": 45000}
```

--------------------------------

### Query Impact of Queue Filtering

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/configuration.md

Example SQL query demonstrating how the transport filters messages by queue name and availability.

```sql
SELECT * FROM messenger_messages 
WHERE queue_name = 'emails' 
  AND available_at <= NOW() 
  AND (delivered_at IS NULL OR delivered_at < NOW() - INTERVAL 3600 SECOND)
```

--------------------------------

### get(int $fetchSize = 1)

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-transport.md

Retrieves a collection of message envelopes from the database queue. Messages are locked upon retrieval.

```APIDOC
## get(int $fetchSize = 1)

### Description
Retrieves messages from the database queue. Returns an iterable collection of message envelopes ready for processing.

### Parameters
- **fetchSize** (int) - Optional - Number of messages to retrieve in a single call (default: 1)

### Returns
- iterable (Envelope objects)

### Example
```php
$transport = new DoctrineTransport($connection, $serializer);
foreach ($transport->get(5) as $envelope) {
    $message = $envelope->getMessage();
}
```
```

--------------------------------

### Common Doctrine Messenger Configuration Errors

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/configuration.md

Examples of invalid DSN configurations that trigger specific exceptions during application startup or transport initialization.

```yaml
# ERROR: Unknown parameter
transports:
  async:
    dsn: 'doctrine://default?invalid_param=true'
# Throws: InvalidArgumentException - Unknown option found

# ERROR: Invalid DSN format
transports:
  async:
    dsn: 'doctrine://invalid://dsn'
# Throws: InvalidArgumentException - The given Doctrine Messenger DSN is invalid

# ERROR: Non-existent connection
transports:
  async:
    dsn: 'doctrine://nonexistent'
# Throws: TransportException - Could not find Doctrine connection
```

--------------------------------

### Instantiate Connection with Configuration

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/connection.md

Demonstrates how to define configuration options and instantiate the Connection class.

```php
$configuration = [
    'table_name' => 'app_messages',
    'queue_name' => 'default',
    'redeliver_timeout' => 7200,
    'auto_setup' => true,
    'connection' => 'default',
];

$connection = new Connection($configuration, $dbalConnection);
```

--------------------------------

### Get subscribed events

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-notify-listener.md

Returns the mapping of event classes to listener methods.

```php
public static function getSubscribedEvents(): array
```

```php
$events = PostgreSqlNotifyOnIdleListener::getSubscribedEvents();
// [
//     WorkerStartedEvent::class => 'onWorkerStarted',
//     WorkerRunningEvent::class => 'onWorkerRunning',
// ]
```

--------------------------------

### Initialize PostgreSqlConnection with configuration

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-connection.md

Use buildConfiguration to parse the DSN string before instantiating the connection.

```php
$config = PostgreSqlConnection::buildConfiguration(
    'doctrine://default?check_delayed_interval=30000&get_notify_timeout=120000'
);
$connection = new PostgreSqlConnection($config, $dbalConnection);
```

--------------------------------

### Dispatching messages with DoctrineSender

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-sender.md

Demonstrates initializing the sender and dispatching an envelope with a delay stamp.

```php
// In a Messenger transport factory
$sender = new DoctrineSender($connection, $serializer);

// Message dispatch
$envelope = new Envelope($myMessage);
$envelope = $envelope->with(new DelayStamp(5000)); // 5 second delay

// Send returns envelope with ID
$sentEnvelope = $sender->send($envelope);

// Get the message ID for tracking
$stamp = $sentEnvelope->last(TransportMessageIdStamp::class);
$messageId = $stamp->getId();
```

--------------------------------

### Initialize Connection Constructor

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/connection.md

Defines the constructor signature for the Connection class, requiring configuration and a DBAL connection instance.

```php
public function __construct(
    protected array $configuration,
    protected DBALConnection $driverConnection,
): void
```

--------------------------------

### listen()

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-connection.md

Registers a LISTEN on the PostgreSQL connection for the configured table.

```APIDOC
## listen()

### Description
Enables LISTEN on the PostgreSQL connection for the configured table name. Can be called multiple times safely.

### Signature
`public function listen(bool $registerOnDatabase = true): void`

### Parameters
- **registerOnDatabase** (bool) - Optional - Default: true - If true, executes SQL LISTEN command; if false, only marks as externally handled.
```

--------------------------------

### Register LISTEN on PostgreSQL connection

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-connection.md

Enable notification listening. Use registerOnDatabase=true for direct listening and false for external handling scenarios.

```php
$connection->listen(true);
// Connection now listens for notifications on the table
if ($connection->waitForNotify(5000)) {
    $messages = $connection->get();
}
```

```php
// First connection actually listens
$connection1->listen(true);

// Other connections mark as externally handled
$connection2->listen(false);
$connection3->listen(false);

// Only connection1 executes LISTEN; others know it's being handled
```

--------------------------------

### Register PostgreSqlNotifyOnIdleListener in services.yaml

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-notify-listener.md

Configure the listener as a service with optional logger and clock dependencies.

```yaml
services:
  Symfony\Component\Messenger\Bridge\Doctrine\EventListener\PostgreSqlNotifyOnIdleListener:
    arguments:
      - '@?logger'
      - '@?psr.clock'
    tags:
      - messenger.event_subscriber
```

--------------------------------

### Connection::buildConfiguration()

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/connection.md

Parses a Messenger DSN string and returns a configuration array ready for the Connection constructor.

```APIDOC
## Connection::buildConfiguration()

### Description
Parses a Messenger DSN string and returns a configuration array. The DSN format is `doctrine://connection_name?table_name=...`.

### Parameters
- **dsn** (string) - Required - Messenger DSN in format `doctrine://connection_name?table_name=...`
- **options** (array) - Optional - Override configuration options

### Returns
- **array** - Configuration array ready for constructor

### Throws
- `InvalidArgumentException` if DSN is invalid or contains unknown options
```

--------------------------------

### Instantiate DoctrineSender

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-sender.md

Create a new instance of the sender with a database connection and an optional serializer.

```php
$sender = new DoctrineSender($connection, new JsonSerializer());
```

--------------------------------

### Get earliest delayed message time signature

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-notify-listener.md

Defines the signature for retrieving the earliest available time for delayed messages.

```php
private function getEarliestDelayedMessageTime(): ?\DateTimeImmutable
```

--------------------------------

### Registering PostgreSqlNotifyOnIdleListener with EventDispatcher

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-notify-listener.md

Instantiates the listener and registers it with a Symfony EventDispatcher.

```php
$listener = new PostgreSqlNotifyOnIdleListener(
    $logger,
    $clock
);

$dispatcher = new EventDispatcher();
$dispatcher->addSubscriber($listener);
```

--------------------------------

### Configure PostgreSQL Optimization

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-transport-factory.md

Register a connection with the PostgreSQL notify listener to enable efficient idle detection.

```php
$listener->addConnection('async_transport', $postgresConnection);
```

--------------------------------

### Constructor definition for PostgreSqlNotifyOnIdleListener

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-notify-listener.md

Defines the constructor for the listener, accepting optional PSR-3 logger and PSR-20 clock instances.

```php
public function __construct(
    private ?LoggerInterface $logger = null,
    private ?ClockInterface $clock = null,
): void
```

--------------------------------

### Configure Environment Variables for Doctrine Messenger

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/configuration.md

Define database and transport DSNs in the .env.local file to keep sensitive credentials externalized.

```bash
# .env.local
MESSENGER_DATABASE_URL=postgresql://user:pass@localhost/app
MESSENGER_TRANSPORT_ASYNC_DSN=doctrine://default?queue_name=async
MESSENGER_TRANSPORT_EVENTS_DSN=doctrine://default?queue_name=events
```

--------------------------------

### reset()

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-connection.md

Clears internal state and LISTEN registration.

```APIDOC
## reset()

### Description
Clears the internal state, including the LISTEN registration. It calls the parent reset() method to clear queueEmptiedAt and executes UNLISTEN to clear the LISTEN state.

### Method
public function reset(): void

### Returns
- void
```

--------------------------------

### Basic Transport Usage

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/README.md

Demonstrates creating a transport, sending an envelope, and retrieving/acknowledging messages.

```php
$transport = $busFactory->createTransport('doctrine://default', [], $serializer);

// Send message
$envelope = new Envelope($message);
$transport->send($envelope);

// Retrieve messages
foreach ($transport->get(5) as $envelope) {
    // Process message
    handleMessage($envelope->getMessage());
    
    // Acknowledge (delete from queue)
    $transport->ack($envelope);
}
```

--------------------------------

### Instantiate DoctrineReceivedStamp

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-received-stamp.md

Create a new stamp instance and attach it to an envelope.

```php
$stamp = new DoctrineReceivedStamp('42');
$envelope = new Envelope($message);
$envelope = $envelope->with($stamp);
```

--------------------------------

### Connection::getConfiguration()

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/connection.md

Returns the current connection configuration.

```APIDOC
## Connection::getConfiguration()

### Description
Returns the current connection configuration array.

### Returns
- **array** - The configuration array
```

--------------------------------

### supports(string $dsn, array $options)

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-transport-factory.md

Checks if the factory can handle a given DSN.

```APIDOC
## supports(string $dsn, array $options)

### Description
Checks if this factory can handle a given DSN. Returns true if the DSN starts with `doctrine://`.

### Parameters
- **dsn** (string) - Required - The DSN to check.
- **options** (array) - Required - Configuration options.

### Returns
- **bool** - True if supported, false otherwise.

### Example
```php
$factory = new DoctrineTransportFactory($connectionRegistry);
$isSupported = $factory->supports('doctrine://default', []);
```
```

--------------------------------

### PostgreSQL LISTEN/NOTIFY Optimization

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/configuration.md

Configure Messenger to use PostgreSQL's LISTEN/NOTIFY for improved performance.

```yaml
doctrine:
  dbal:
    connections:
      messenger:
        url: '%env(MESSENGER_DATABASE_URL)%'
        driver: 'pdo_pgsql'

framework:
  messenger:
    transports:
      async:
        dsn: 'doctrine://messenger?use_notify=true&get_notify_timeout=30000&check_delayed_interval=30000'
      
      events:
        dsn: 'doctrine://messenger?queue_name=events&use_notify=true'
    
    buses:
      command_bus:
        middleware:
          - routing_handlers
      
      event_bus:
        default_middleware: 'allow_no_handlers'
```

--------------------------------

### Instantiate Transport Manually

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-transport-factory.md

Use the transport registry to create a transport instance programmatically.

```php
$busFactory->createTransport(
    'doctrine://default',
    ['transport_name' => 'async'],
    $serializer
)
```

--------------------------------

### PostgreSQL LISTEN/NOTIFY Configuration

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/README.md

Enables PostgreSQL-specific optimization for the Doctrine transport.

```yaml
framework:
  messenger:
    transports:
      async:
        dsn: 'doctrine://pg?use_notify=true&get_notify_timeout=30000'
```

--------------------------------

### Configure schema for management in PHP

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-transport.md

Integrates the messenger table into the application's DBAL schema management system.

```php
$schema = new Schema();
$schema = $transport->configureSchema($schema, $dbalConnection, function($stmt) {
    // Check if this connection is for the same database
    return true;
});
```

--------------------------------

### Multi-Queue Configuration with Timeouts

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/configuration.md

Configure multiple transports with distinct queue names and redelivery timeouts.

```yaml
framework:
  messenger:
    transports:
      urgent:
        dsn: 'doctrine://default?queue_name=urgent&redeliver_timeout=300'
      
      default:
        dsn: 'doctrine://default?queue_name=default&redeliver_timeout=3600'
      
      batch:
        dsn: 'doctrine://default?queue_name=batch&redeliver_timeout=14400'
    
    routing:
      'App\Message\UrgentAlert': urgent
      'App\Message\SendEmail': default
      'App\Message\GenerateReport': batch
```

--------------------------------

### Handle Different DBAL Connections Error

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-notify-listener.md

Demonstrates the LogicException thrown when multiple transports use different DBAL connections.

```php
$listener->addConnection('async', $postgresConn1);  // DBAL A
$listener->addConnection('events', $postgresConn2); // DBAL B

// onWorkerStarted() throws LogicException:
// 'PostgreSQL transports "async" and "events" use different DBAL connections...'
```

--------------------------------

### Connection::send()

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/connection.md

Inserts a message into the queue.

```APIDOC
## Connection::send()

### Description
Inserts a message into the queue with the current timestamp and calculates availability time based on delay. The message is immediately committed to the database.

### Parameters
- **body** (string) - Required - Serialized message body
- **headers** (array) - Required - Message headers (merged and JSON-encoded)
- **delay** (int) - Optional - Delay in milliseconds before message is available

### Returns
- **string** - The database ID of the inserted message

### Throws
- `DBALException` if database insert fails
```

--------------------------------

### Handle Different Table Names Error

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-notify-listener.md

Demonstrates the LogicException thrown when multiple transports use different table names.

```php
$listener->addConnection('async', $conn1);   // table: 'messenger_messages'
$listener->addConnection('events', $conn2);  // table: 'events_queue'

// onWorkerStarted() throws LogicException:
// 'PostgreSQL transports "async" and "events" use different table_name values...'
```

--------------------------------

### Define PostgreSQL connection default options

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-connection.md

Extends parent connection defaults with PostgreSQL-specific settings for delayed message checks and notification timeouts.

```php
protected const DEFAULT_OPTIONS = parent::DEFAULT_OPTIONS + [
    'check_delayed_interval' => 60000,
    'get_notify_timeout' => 60000,
];
```

--------------------------------

### Retrieve Connection Configuration

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/connection.md

Fetches the current configuration array for an active connection instance.

```php
$config = $connection->getConfiguration();
echo "Table: " . $config['table_name'];
echo "Queue: " . $config['queue_name'];
echo "Timeout: " . $config['redeliver_timeout'];
```

--------------------------------

### Handle TransportException for Connection Failures

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/errors.md

Demonstrates catching a TransportException and inspecting the previous DBAL exception for logging or retry logic.

```php
try {
    $transport->send($envelope);
} catch (TransportException $e) {
    echo "Failed to send message: " . $e->getMessage();
    // Message: Likely DBAL connection error
    
    if ($e->getPrevious() instanceof DBALException) {
        // Can retry, log, or propagate
        $this->logger->error("Transport error", ['previous' => $e->getPrevious()]);
    }
}
```

--------------------------------

### Instantiate DoctrineReceiver

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-receiver.md

Constructor for the DoctrineReceiver, requiring a database connection and an optional serializer.

```php
public function __construct(
    private Connection $connection,
    ?SerializerInterface $serializer = null,
): void
```

```php
$receiver = new DoctrineReceiver($connection, new JsonSerializer());
```

--------------------------------

### Configuring schema via migrations

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/errors.md

Use the configureSchema method within a migration file to ensure the transport table exists in production environments.

```php
// migrations/Version20240101000000.php
$transport->configureSchema($schema, $connection, function() { return true; });
// Creates table schema via DBAL
```

--------------------------------

### Connection::get()

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/connection.md

Retrieves available messages from the queue.

```APIDOC
## Connection::get()

### Description
Retrieves messages in FIFO order (sorted by `available_at`). Marks retrieved messages as delivered using a pessimistic write lock.

### Parameters
- **fetchSize** (int) - Optional - Number of messages to retrieve

### Returns
- **?array** - Array of message rows, or `null` if queue is empty

### Throws
- `DBALException` if database query fails
- `TableNotFoundException` (auto-setup if enabled)
```

--------------------------------

### Check DSN support

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-transport-factory.md

Defines the signature for checking if the factory supports a specific DSN.

```php
public function supports(#["SensitiveParameter"] string $dsn, array $options): bool
```

--------------------------------

### Configure Doctrine Connections

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/configuration.md

Define multiple Doctrine connections in the doctrine.yaml file to be used by Messenger transports.

```yaml
# config/packages/doctrine.yaml
doctrine:
  dbal:
    default_connection: default
    connections:
      default:
        url: '%env(DATABASE_URL)%'
      
      legacy:
        url: '%env(LEGACY_DATABASE_URL)%'
      
      replica:
        url: '%env(REPLICA_DATABASE_URL)%'
```

--------------------------------

### Resolve Doctrine Connection

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-transport-factory.md

Demonstrates how the factory resolves connection names from DSN strings using the ConnectionRegistry.

```php
// From DSN 'doctrine://my_connection?...'
$connection = $registry->getConnection('my_connection');

// Throws InvalidArgumentException if not found
// Wrapped as TransportException by the factory
```

--------------------------------

### Build Connection Configuration

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/connection.md

Parses a DSN string into a configuration array. Throws an InvalidArgumentException if the DSN is malformed or contains unknown options.

```php
$config = Connection::buildConfiguration(
    'doctrine://default?table_name=app_messages&queue_name=async',
    ['redeliver_timeout' => 7200]
);

// Result:
// [
//     'connection' => 'default',
//     'table_name' => 'app_messages',
//     'queue_name' => 'async',
//     'redeliver_timeout' => 7200,
//     'auto_setup' => true,
// ]
```

--------------------------------

### Configure PostgreSQL Messenger Transport

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-connection.md

Set the DSN parameters to balance message latency and database load using LISTEN/NOTIFY.

```yaml
framework:
  messenger:
    transports:
      async:
        dsn: 'doctrine://default?check_delayed_interval=60000&get_notify_timeout=60000'
```

--------------------------------

### configureSchema(Schema $schema, DbalConnection $forConnection, \Closure $isSameDatabase)

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-transport.md

Adds the messenger table to a DBAL schema for schema management purposes.

```APIDOC
## configureSchema(Schema $schema, DbalConnection $forConnection, \Closure $isSameDatabase)

### Description
Used internally by Symfony's schema management system to properly track the messenger table alongside other application tables.

### Parameters
- **schema** (Schema) - Required - The DBAL schema to add the table to
- **forConnection** (DbalConnection) - Required - The DBAL connection to check against
- **isSameDatabase** (\Closure) - Required - Callback to verify if connections use same database

### Returns
- **Schema** - The modified schema with messenger table included
```

--------------------------------

### Define Connection Configuration Array

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/types.md

Structure for the configuration array used in Connection constructor and buildConfiguration methods.

```php
array{
    table_name: string,
    queue_name: string,
    redeliver_timeout: int,
    auto_setup: bool,
    connection: string,
    check_delayed_interval?: int,           // Only for PostgreSqlConnection
    get_notify_timeout?: int,               // Only for PostgreSqlConnection
}
```

--------------------------------

### PostgreSqlNotifyOnIdleListener usage

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-connection.md

Coordinates multiple PostgreSqlConnection instances during worker lifecycle events.

```php
$listener = new PostgreSqlNotifyOnIdleListener($logger);

// Register connections
$listener->addConnection('notifications', $postgresConnection1);
$listener->addConnection('emails', $postgresConnection2);

// When worker starts
$worker->addEventListener(WorkerStartedEvent::class, function($event) use ($listener) {
    $listener->onWorkerStarted($event);
    // Sets up LISTEN on first connection only
    // Marks others as externally handled
});

// When worker is idle
$worker->addEventListener(WorkerRunningEvent::class, function($event) use ($listener) {
    $listener->onWorkerRunning($event);
    // Calls waitForNotify() on active connection
});
```

--------------------------------

### Handling BadMethodCallException for PostgreSqlConnection

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/errors.md

Demonstrates catching the exception thrown when attempting to serialize a PostgreSqlConnection, which is not supported.

```php
$connection = new PostgreSqlConnection($config, $dbal);

try {
    $serialized = serialize($connection);
} catch (BadMethodCallException $e) {
    echo $e->getMessage(); // "Cannot serialize..."
    // Cannot use this connection in caching or sessions
}
```

--------------------------------

### isListening()

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-connection.md

Checks if the connection is currently listening for PostgreSQL notifications.

```APIDOC
## isListening()

### Description
Checks if the connection is currently listening for PostgreSQL notifications.

### Signature
`public function isListening(): bool`

### Returns
- **bool** - True if LISTEN has been executed, false otherwise.
```

--------------------------------

### Configure get_notify_timeout for PostgreSQL

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/configuration.md

Define the maximum time in milliseconds to wait for a notification when the worker is idle.

```yaml
transports:
  # Short timeout for responsive systems
  highspeed:
    dsn: 'doctrine://default?get_notify_timeout=10000'
  
  # Standard timeout
  async:
    dsn: 'doctrine://default?get_notify_timeout=60000'
  
  # Long timeout for batch systems
  batch:
    dsn: 'doctrine://default?get_notify_timeout=300000'
```

```bash
# Worker has 1-hour time limit
php bin/console messenger:consume async --time-limit=3600

# With get_notify_timeout=60000:
# Actual wait = min(60000ms, time_until_deadline)
# If already 58 minutes into run, waits only 2 minutes
```

--------------------------------

### findAll(?int $limit)

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/connection.md

Retrieves all available messages from the queue.

```APIDOC
## findAll(?int $limit)

### Description
Retrieves all available messages from the queue.

### Parameters
- **limit** (int|null) - Optional - Maximum number of messages

### Returns
- **array** - Array of message rows
```

--------------------------------

### Validate PostgreSQL connections for LISTEN/NOTIFY

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-notify-listener.md

Defines the signature for validating connection compatibility.

```php
private function validateConnections(array $connections): void
```

--------------------------------

### Create DoctrineTransport instance

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-transport-factory.md

Defines the signature for creating a transport instance from a DSN string, options array, and serializer.

```php
public function createTransport(
    #["SensitiveParameter"] string $dsn,
    array $options,
    SerializerInterface $serializer
): TransportInterface
```

--------------------------------

### SQL query for earliest delayed message

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-notify-listener.md

Retrieves the minimum available_at timestamp for messages across specified queues that are not yet delivered.

```sql
SELECT MIN(available_at) 
FROM messenger_messages 
WHERE queue_name IN (?, ?, ...) 
  AND available_at > ? 
  AND delivered_at IS NULL
```

--------------------------------

### DoctrineTransportFactory Constructor Signature

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-transport-factory.md

The constructor requires a ConnectionRegistry and accepts an optional PostgreSqlNotifyOnIdleListener.

```php
public function __construct(
    private ConnectionRegistry $registry,
    private ?PostgreSqlNotifyOnIdleListener $notifyOnIdleListener = null,
): void
```

--------------------------------

### Internal unlisten method

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-connection.md

Executes UNLISTEN on the PostgreSQL connection and updates the internal listening state.

```php
private function unlisten(): void
```

--------------------------------

### Configuring PostgreSQL transports to use the same connection

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/errors.md

Ensure all PostgreSQL transports share the same DBAL connection to avoid issues with LISTEN/NOTIFY.

```yaml
# Use same connection for all PostgreSQL transports
framework:
  messenger:
    transports:
      async:
        dsn: 'doctrine://messaging?queue_name=async'    # Both use 'messaging'
      events:
        dsn: 'doctrine://messaging?queue_name=events'   # connection
```

--------------------------------

### Configure check_delayed_interval for PostgreSQL

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/configuration.md

Set the interval in milliseconds for checking delayed messages when using LISTEN/NOTIFY.

```yaml
transports:
  # Check every 30 seconds (low latency)
  realtime:
    dsn: 'doctrine://default?check_delayed_interval=30000'
  
  # Check every 5 minutes (batch processing)
  batch:
    dsn: 'doctrine://default?check_delayed_interval=300000'
  
  # Disable checking (only NOTIFY)
  notify_only:
    dsn: 'doctrine://default?check_delayed_interval=0'
```

--------------------------------

### Multi-queue transport configuration

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-notify-listener.md

Configure multiple transports on the same table to share the listener notification mechanism.

```yaml
transports:
  notifications:
    dsn: 'doctrine://default?queue_name=notifications&use_notify=true'
  emails:
    dsn: 'doctrine://default?queue_name=emails&use_notify=true'
```

--------------------------------

### Define InvalidArgumentException Class

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/types.md

Exception thrown for invalid DSN or configuration settings.

```php
class InvalidArgumentException extends RuntimeException { }
```

--------------------------------

### Consume Queues via Console

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/configuration.md

Commands to process specific queues or multiple queues simultaneously.

```bash
# Process default queue
php bin/console messenger:consume async

# Process priority queue only
php bin/console messenger:consume priority

# Process multiple queues
php bin/console messenger:consume async priority emails
```

--------------------------------

### Configure Custom Table Names

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/configuration.md

Specify a custom database table name for message storage using the table_name DSN parameter.

```yaml
transports:
  async:
    dsn: 'doctrine://default?table_name=app_messages'
  
  events:
    dsn: 'doctrine://default?table_name=events_queue'
```

--------------------------------

### Configure Doctrine Messenger Transports via PHP

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/configuration.md

Define transport configurations programmatically using the Symfony PHP configuration format.

```php
// config/packages/messenger.php
$config->extension('framework', [
    'messenger' => [
        'transports' => [
            'async' => [
                'dsn' => 'doctrine://default',
            ],
            'events' => [
                'dsn' => 'doctrine://events?queue_name=events',
            ],
        ],
    ],
]);
```

--------------------------------

### Check connection listening status

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-connection.md

Verify if the connection is currently registered to listen for PostgreSQL notifications.

```php
if ($connection->isListening()) {
    echo "Connection is listening for notifications";
}
```

--------------------------------

### Integrating DoctrineSender in DoctrineTransport

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-sender.md

Shows how DoctrineTransport lazily initializes and utilizes DoctrineSender for message dispatching.

```php
class DoctrineTransport implements TransportInterface {
    private ?DoctrineSender $sender = null;

    public function send(Envelope $envelope): Envelope {
        return $this->getSender()->send($envelope);
    }

    private function getSender(): DoctrineSender {
        return $this->sender ??= new DoctrineSender($this->connection, $this->serializer);
    }
}
```

--------------------------------

### Constructing DoctrineTransport

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-transport.md

The constructor requires a Doctrine connection wrapper and a serializer instance.

```php
public function __construct(
    private Connection $connection,
    private SerializerInterface $serializer,
): void
```

--------------------------------

### Register a PostgreSQL connection

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-notify-listener.md

Registers a connection for LISTEN/NOTIFY management. This is typically invoked by the DoctrineTransportFactory.

```php
public function addConnection(
    string $transportName,
    PostgreSqlConnection $connection
): void
```

```php
$listener = new PostgreSqlNotifyOnIdleListener($logger);

// Called by DoctrineTransportFactory
$listener->addConnection('async', $postgresConnection1);
$listener->addConnection('events', $postgresConnection2);
```

--------------------------------

### Implement standard error handling in a message handler

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/errors.md

Wrap message processing in a try-catch block to log errors before re-throwing the exception to trigger the Messenger failure transport.

```php
class MyMessageHandler
{
    public function __invoke(MyMessage $message)
    {
        try {
            // Process message
            $this->process($message);
        } catch (Exception $e) {
            // Log error
            $this->logger->error("Failed to process message", ['error' => $e]);
            
            // Throw to let Messenger handle (will reject by default)
            throw $e;
        }
    }
}
```

--------------------------------

### all(?int $limit = null)

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-transport.md

Retrieves all available messages from the queue, optionally limited by count.

```APIDOC
## all(?int $limit = null)

### Description
Returns all available messages, optionally limited by count. Useful for administrative or debugging purposes.

### Parameters
- **limit** (int|null) - Optional - Maximum number of messages to return

### Returns
- **iterable** - An iterable of Envelope objects
```

--------------------------------

### Define Database Permissions

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/configuration.md

Required SQL permissions for the database user to manage Messenger tables and utilize PostgreSQL LISTEN/NOTIFY.

```sql
-- Connection user needs:
CREATE TABLE           -- For auto_setup
INSERT INTO           
SELECT FROM
UPDATE
DELETE
LOCK IN SHARE MODE    -- Or equivalent pessimistic lock
LISTEN/NOTIFY         -- For PostgreSQL

-- Minimum permissions:
GRANT CREATE ON database TO messenger_user;
GRANT SELECT, INSERT, UPDATE, DELETE ON TABLE messenger_messages TO messenger_user;
GRANT REFERENCES ON TABLE messenger_messages TO messenger_user;
```

--------------------------------

### Retrieve Messages from Queue

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/connection.md

Fetches messages in FIFO order using a pessimistic write lock. Returns null if the queue is empty.

```php
$messages = $connection->get(5);
if (null !== $messages) {
    foreach ($messages as $msg) {
        echo "Message ID: " . $msg['id'] . "\n";
        echo "Body: " . $msg['body'] . "\n";
        echo "Created at: " . $msg['created_at']->format('Y-m-d H:i:s') . "\n";
    }
} else {
    echo "Queue is empty\n";
}
```

--------------------------------

### send(Envelope $envelope)

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/doctrine-transport.md

Sends a message to the queue.

```APIDOC
## send(Envelope $envelope)

### Description
Sends a message to the queue. Returns the envelope with an added TransportMessageIdStamp.

### Parameters
- **envelope** (Envelope) - Required - The message envelope to send

### Returns
- Envelope (with added TransportMessageIdStamp)

### Throws
- TransportException: If the database operation fails
```

--------------------------------

### Implement Deadlock Retry Logic

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/errors.md

Shows a manual retry loop with random backoff when a deadlock is detected in the TransportException message.

```php
$retryCount = 0;
$maxRetries = 5;

while ($retryCount < $maxRetries) {
    try {
        $messages = $receiver->get(10);
        break; // Success
    } catch (TransportException $e) {
        if (str_contains($e->getMessage(), 'Deadlock')) {
            $retryCount++;
            usleep(rand(100000, 500000)); // 100-500ms random backoff
            continue;
        }
        throw; // Non-deadlock error, propagate
    }
}
```

--------------------------------

### Configure Multiple Queues

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/configuration.md

Use the queue_name parameter to isolate different message types into independent processing pipelines.

```yaml
transports:
  async:
    dsn: 'doctrine://default?queue_name=default'
  
  priority:
    dsn: 'doctrine://default?queue_name=priority&table_name=messenger_messages'
  
  emails:
    dsn: 'doctrine://default?queue_name=emails&table_name=messenger_messages'
  
  notifications:
    dsn: 'doctrine://default?queue_name=notifications&table_name=messenger_messages'
```

--------------------------------

### Send Message to Queue

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/connection.md

Inserts a serialized message into the database queue. Supports delayed delivery by specifying a delay in milliseconds.

```php
$body = serialize($message);
$headers = ['X-Message-Type' => 'MyMessage'];

// Send immediately
$id = $connection->send($body, $headers, 0);

// Send with 30-second delay
$id = $connection->send($body, $headers, 30000); // 30000 milliseconds
```

--------------------------------

### Define Transport Options Structure

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/types.md

Represents the configuration array passed to the transport factory for Doctrine-based message queues.

```php
array{
    use_notify?: bool,
    transport_name?: string|null,
    table_name?: string,
    queue_name?: string,
    redeliver_timeout?: int,
    auto_setup?: bool,
    check_delayed_interval?: int,
    get_notify_timeout?: int,
}
```

--------------------------------

### addConnection(string $transportName, PostgreSqlConnection $connection)

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/postgresql-notify-listener.md

Registers a PostgreSQL connection to be managed by the listener for LISTEN/NOTIFY operations.

```APIDOC
## addConnection(string $transportName, PostgreSqlConnection $connection)

### Description
Registers a PostgreSQL connection as a candidate for LISTEN/NOTIFY. This is typically called automatically by the DoctrineTransportFactory.

### Parameters
- **transportName** (string) - Required - Name identifying this transport (e.g., 'async')
- **connection** (PostgreSqlConnection) - Required - The PostgreSQL connection to manage

### Returns
- **void**
```

--------------------------------

### reset()

Source: https://github.com/symfony/doctrine-messenger/blob/8.2/_autodocs/api-reference/connection.md

Clears internal state.

```APIDOC
## reset()

### Description
Resets the `queueEmptiedAt` timestamp, clearing any cached state about queue emptiness.

### Returns
- **void**
```