## Getting Started

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

Enable the bundle in config/bundles.php:

return [
    // ...
    CodeMeme\IronMqBundle\CodeMemeIronMqBundle::class => ['all' => true],
];

Configuration: Add IronMQ credentials to .env:

IRON_MQ_PROJECT_ID=your_project_id
IRON_MQ_TOKEN=your_token
IRON_MQ_HOST=https://mq-aws.us-east-1.iron.io  # Adjust region as needed

Publish the default config (optional):

php bin/console config:dump-reference CodeMemeIronMqBundle

First Use Case: Enqueue a job via a service:

use CodeMeme\IronMqBundle\Service\IronMqService;

class MyJobService
{
    private $ironMq;

    public function __construct(IronMqService $ironMq)
    {
        $this->ironMq = $ironMq;
    }

    public function dispatchJob()
    {
        $this->ironMq->enqueue('my_queue', [
            'data' => 'Hello, IronMQ!',
            'priority' => 1,
        ]);
    }
}

Implementation Patterns

Core Workflows

Queue Operations:

Enqueue: Use enqueue() with a queue name and payload (array or JSON-serializable object).
```
$this->ironMq->enqueue('orders', ['order_id' => 123, 'status' => 'pending']);
```

Dequeue: Fetch jobs with dequeue() and process them in a loop.

while (($job = $this->ironMq->dequeue('orders')) !== null) {
    $data = json_decode($job->body, true);
    // Process $data...
    $this->ironMq->release($job); // Or $this->ironMq->delete($job);
}

Batch Processing: Use peek() to inspect jobs without removing them.
```
$jobs = $this->ironMq->peek('orders', 5); // Get 5 jobs
```

Event-Driven Architecture:

Consumers: Create a Symfony command to run a consumer loop:

use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

class ProcessOrdersCommand extends Command
{
    protected function execute(InputInterface $input, OutputInterface $output)
    {
        $ironMq = $this->getIronMqService();
        while (($job = $ironMq->dequeue('orders')) !== null) {
            try {
                $this->processOrder($job);
                $ironMq->delete($job);
            } catch (\Exception $e) {
                $ironMq->release($job); // Retry later
            }
        }
    }
}

Retry Logic:

Implement exponential backoff for failed jobs:

$attempts = 0;
$maxAttempts = 3;
$delay = 1; // seconds

while ($attempts < $maxAttempts) {
    try {
        $this->processJob($job);
        $ironMq->delete($job);
        break;
    } catch (\Exception $e) {
        $attempts++;
        $ironMq->release($job, $delay * $attempts);
        sleep($delay * $attempts);
    }
}

Delayed Jobs:

Schedule jobs to run later using delay:

$this->ironMq->enqueue('delayed', ['task' => 'send_email'], [
    'delay' => 3600, // 1 hour in seconds
]);

Integration Tips

Dependency Injection: Always inject IronMqService into your services/controllers.
Error Handling: Wrap IronMQ calls in try-catch blocks to handle network issues or rate limits.

Logging: Log job IDs and payloads for debugging:

$this->logger->info('Processing job', ['job_id' => $job->id, 'payload' => $job->body]);

Configuration: Override default settings in config/packages/codememe_iron_mq.yaml:
```
codememe_iron_mq:
    default_queue: 'default'
    timeout: 30
    retries: 3
```

Gotchas and Tips

Common Pitfalls

Connection Issues:
- Symptom: Jobs enqueue but never appear in the queue or consumers fail silently.
- Fix: Verify .env credentials and network connectivity. IronMQ requires outbound HTTPS.
```
curl -v https://mq-aws.us-east-1.iron.io/1/projects
```
- Debug: Enable debug mode in config/packages/codememe_iron_mq.yaml:
```
debug: true
```
Rate Limiting:
- Symptom: 429 Too Many Requests errors when enqueuing/dequeuing rapidly.
- Fix: Implement retry logic with exponential backoff (see Implementation Patterns).
- Tip: Monitor your IronMQ dashboard for rate limit alerts.
Job Visibility Timeout:
- Symptom: Jobs stuck in "in-flight" state if not deleted/released within the timeout (default: 30s).
- Fix: Ensure your consumer loop runs frequently and handles failures gracefully.
- Config: Adjust timeout in config/packages/codememe_iron_mq.yaml:
```
timeout: 60 # Increase to 60 seconds if processing is slow
```
Payload Size Limits:
- Symptom: Large payloads (>256KB) fail silently or are truncated.
- Fix: Offload large data to a database or S3 and store only references in the queue.
- Tip: Compress payloads if necessary:
```
$compressed = gzcompress(json_encode($data));
$this->ironMq->enqueue('queue', $compressed, ['compression' => 'gzip']);
```
Queue Naming:
- Symptom: Case-sensitive queue names may cause issues across environments.
- Fix: Use consistent naming (e.g., snake_case) and validate in tests:
```
$this->assertEquals(
    $this->ironMq->queue('orders')->name(),
    'orders' // Not 'ORDERS' or 'Orders'
);
```

Debugging Tips

Check Job Metadata:

$job = $this->ironMq->dequeue('queue');
$this->logger->debug('Job metadata', [
    'id' => $job->id,
    'queue' => $job->queue,
    'delay' => $job->delay,
    'timestamp' => $job->timestamp,
]);

Simulate Failures: Use release() with a delay to test retry logic:
```
$this->ironMq->release($job, 10); // Retry after 10 seconds
```

Monitor with CLI: List queues and jobs:

php bin/console debug:ironmq:list-queues
php bin/console debug:ironmq:list-jobs orders

Extension Points

Custom Job Processors: Create a decorator for IronMqService to add pre/post-processing:

use CodeMeme\IronMqBundle\Service\IronMqServiceInterface;

class CustomIronMqService implements IronMqServiceInterface
{
    private $decorated;

    public function __construct(IronMqServiceInterface $decorated)
    {
        $this->decorated = $decorated;
    }

    public function enqueue($queue, $payload, array $options = [])
    {
        $options['metadata'] = ['processed_at' => now()->toIso8601String()];
        return $this->decorated->enqueue($queue, $payload, $options);
    }

    // Delegate other methods to $this->decorated
}

services:
    CodeMeme\IronMqBundle\Service\IronMqServiceInterface: '@custom_iron_mq_service'
    custom_iron_mq_service:
        class: App\Service\CustomIronMqService
        decorates: 'codememe_iron_mq.service'

Event Listeners: Trigger events for job lifecycle (e.g., `

Ironmq Bundle Laravel Package