## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require swarrot/swarrot-bundle

return [
    // ...
    Swarrot\SwarrotBundle\SwarrotBundle::class => ['all' => true],
];

Basic Configuration (config/packages/swarrot.yaml):

swarrot:
    provider: pecl  # or 'amqp_lib'
    default_connection: rabbitmq
    connections:
        rabbitmq:
            url: "amqp://guest:guest@localhost:5672/%2f"
    messages_types:
        default:
            connection: rabbitmq
            exchange: my_exchange
            routing_key: my_key

First Use Case: Publishing a Message Inject the publisher service in a controller/service:

use Swarrot\Broker\Message;

class MyController extends AbstractController
{
    public function publishMessage()
    {
        $publisher = $this->container->get('swarrot.publisher');
        $message = new Message('Hello Swarrot!');
        $publisher->publish('default', $message);
    }
}

Implementation Patterns

Core Workflows

1. Message Publishing

Standard Flow:

$publisher = $this->get('swarrot.publisher');
$message = new Message(json_encode(['data' => 'value']));
$publisher->publish('message_type_key', $message);

Dynamic Overrides:

$publisher->publish('message_type_key', $message, [
    'exchange' => 'dynamic_exchange',
    'routing_key' => 'dynamic_key',
]);

2. Message Consuming

Define a Consumer Service:

namespace App\Service;

use Swarrot\Processor\ProcessorInterface;
use Swarrot\Broker\Message;

class MyConsumer implements ProcessorInterface
{
    public function process(Message $message, array $options)
    {
        $data = json_decode($message->getBody(), true);
        // Process logic here
    }
}

Configure Consumer (config/packages/swarrot.yaml):

swarrot:
    consumers:
        my_consumer:
            processor: app.service.my_consumer
            middleware_stack:
                - configurator: swarrot.processor.ack
                - configurator: swarrot.processor.retry

Run Consumer:

php bin/console swarrot:consume:my_consumer my_queue [connection_name]

3. Middleware Stack

Order Matters: Middleware runs in the order defined. Example stack:

middleware_stack:
    - configurator: swarrot.processor.signal_handler
    - configurator: swarrot.processor.max_messages
    - configurator: swarrot.processor.doctrine_connection
    - configurator: swarrot.processor.ack

Custom Middleware: Implement ProcessorConfiguratorInterface and register as a service:

services:
    app.swarrot.custom_middleware:
        class: App\Middleware\CustomProcessorConfigurator
        tags:
            - { name: swarrot.processor_configurator }

4. Connection Management

Multiple Connections:

swarrot:
    connections:
        rabbitmq:
            url: "amqp://user:pass@rabbitmq:5672/%2f"
        redis:
            url: "redis://redis:6379"

Override Default Connection:

php bin/console swarrot:consume:my_consumer my_queue redis

Integration Tips

1. Doctrine Integration

Auto-Close Connection: Enable in middleware:

middleware_stack:
    - configurator: swarrot.processor.doctrine_connection
      extras:
          doctrine_close_master: true

2. Error Handling

Retry Mechanism:

middleware_stack:
    - configurator: swarrot.processor.retry
      extras:
          retry_attempts: 3
          retry_exchange: retry_exchange

Requeue on Error:

php bin/console swarrot:consume:my_consumer my_queue --requeue-on-error

3. Performance Tuning

Polling Interval:

consumers:
    my_consumer:
        extras:
            poll_interval: 100000  # 100ms

Max Messages:

php bin/console swarrot:consume:my_consumer my_queue --max-messages=50

4. Testing

Blackhole Publisher (for tests):

# config/packages/test/swarrot.yaml
parameters:
    swarrot.publisher.class: Swarrot\SwarrotBundle\Broker\BlackholePublisher

Gotchas and Tips

Pitfalls

1. Connection Issues

Symptom: Messages not being published/consumed.
Debugging:
- Verify url in connections is correct (use amqp:// for RabbitMQ).
- Check broker service (e.g., RabbitMQ) is running.
- Ensure credentials in .env match the broker configuration.

2. Middleware Order

Symptom: Unexpected behavior (e.g., retries not working).

Fix: Reorder middleware in middleware_stack. Example:

middleware_stack:
    - configurator: swarrot.processor.ack      # Must run after retry
    - configurator: swarrot.processor.retry

3. Doctrine Transactions

Symptom: Deadlocks or connection leaks.
Solution:
- Use doctrine_connection middleware with doctrine_ping: true.
- Avoid long-running transactions in processors.

4. Message Serialization

Symptom: Corrupted messages or errors during deserialization.

Tip: Always serialize messages explicitly:

$message = new Message(json_encode(['key' => 'value']));

5. Command Aliases

Symptom: Cannot find custom command alias.

Fix: Ensure command_alias is defined in consumers:

consumers:
    my_consumer:
        command_alias: app:my:custom:command

Then run:

php bin/console app:my:custom:command my_queue

Debugging Tips

1. Logging

Enable Debug Mode:

swarrot:
    logger: monolog.logger.debug

Log Levels: Use retry_log_levels_map in retry middleware for granular control.

2. CLI Options

Override Config:

php bin/console swarrot:consume:my_consumer my_queue --poll-interval=200000

Disable Catchers:

php bin/console swarrot:consume:my_consumer my_queue --no-catch

3. Environment-Specific Config

Test Environment:

# config/packages/test/swarrot.yaml
swarrot:
    connections:
        rabbitmq:
            url: "amqp://guest:guest@localhost:5672/%2f?connection_attempts=1"

4. Common Errors

Error	Cause	Solution
`Connection refused`	Broker unreachable	Check broker URL/credentials.
`No such exchange`	Exchange not declared	Declare exchange in broker (e.g., RabbitMQ).
`Message not acknowledged`	Missing `ack` middleware	Add `swarrot.processor.ack` to stack.
`Class not found`	Incorrect service ID	Verify `processor` service exists.

Extension Points

1. Custom Provider

Steps:

Implement Swarrot\SwarrotBundle\Broker\FactoryInterface.

Tag service with swarrot.provider_factory:

services:
    app.swarrot.redis_factory:
        class: App\Broker\RedisFactory
        tags:
            - { name: swarrot.provider_factory, alias: redis }

Configure in swarrot.yaml:
```
swarrot:
    provider: redis
```

2. Custom Processor