Getting Started

Minimal Setup

Install the Bundle:

composer require autobus-php/autobus-bus-bundle

Choose a queue system (e.g., AWS SQS or Google PubSub) and install its bundle:

composer require enqueue/sqs  # or enqueue/gps

Configure .env:

ENQUEUE_DSN=sqs:  # or gps:
AWS_REGION=your-region
AWS_ACCESS_KEY_ID=your-key
AWS_SECRET_ACCESS_KEY=your-secret

Run Migrations (if applicable) and clear cache:

php bin/console doctrine:migrations:migrate
php bin/console cache:clear

First Job Creation:

Create a job class implementing RunnerInterface (or extending AbstractRunner):

namespace App\Bus\Jobs;

use Autobus\Bundle\BusBundle\Runner\AbstractRunner;

class SendEmailJob extends AbstractRunner
{
    public function run(): void
    {
        // Your job logic here
        $this->logger->info('Email sent!');
    }
}

services:
    App\Bus\Jobs\SendEmailJob:
        tags: ['bus.runner']

Trigger the Job:
- Via Cron: Add to crontab:
```
* * * * * php bin/console autobus:cron:run
```
- Via Queue: Start the consumer (e.g., for SQS):
```
php bin/console autobus:sqs:consume
```

Implementation Patterns

Workflow: Job Lifecycle

Define Jobs:
- Extend AbstractRunner for boilerplate (e.g., logging, retries).
- Implement run() for job logic. Use dependency injection for services:
```
public function __construct(private Mailer $mailer) {}
```
Configure Jobs via UI:
- Use the web UI to create job instances (e.g., schedule, payload, retries).
- Example payload (JSON):
```
{
    "email": "user@example.com",
    "subject": "Hello"
}
```

Trigger Mechanisms:

Cron Jobs: Schedule via autobus:cron:run (e.g., hourly/daily).

# config/packages/autobus.yaml
autobus:
    cron:
        jobs:
            send_emails:
                job: App\Bus\Jobs\SendEmailJob
                schedule: "0 * * * *"  # Every hour

Queue Jobs: Publish via BusPublisher:

$publisher = $this->container->get('autobus.bus.publisher');
$publisher->publish(new SendEmailJob(), ['email' => 'user@example.com']);

Webhooks/APIs: Use autobus:api:trigger to fire jobs externally.

Error Handling:

Implement onFailure() in AbstractRunner for custom retries:

public function onFailure(\Throwable $e): void
{
    $this->logger->error('Failed: ' . $e->getMessage());
    // Requeue or notify
}

Monitoring:
- Use Symfony’s profiler or integrate with tools like Sentry to track job execution.
- Log job metadata (e.g., start/end time, payload) in run().

Integration Tips

Laravel-Specific:

Replace Symfony’s container with Laravel’s app() helper:
```
$publisher = app('autobus.bus.publisher');
```

Use Laravel’s Artisan facade for CLI commands:

use Illuminate\Support\Facades\Artisan;
Artisan::call('autobus:cron:run');

Queue Systems:
- For AWS SQS, ensure IAM roles have sqs:ReceiveMessage, sqs:DeleteMessage, and sqs:ChangeMessageVisibility permissions.
- For Google PubSub, set up a service account with pubsub.subscriber role.
Testing:
- Mock the BusPublisher in unit tests:
```
$this->mock(BusPublisher::class)
     ->shouldReceive('publish')
     ->once();
```
- Use autobus:test:run to simulate job execution in tests.

Gotchas and Tips

Pitfalls

Queue Consumer Stuck:
- Cause: Missing or incorrect ENQUEUE_DSN in .env.
- Fix: Verify DSN format (e.g., sqs://access_key:secret@?queue=your_queue) and credentials.
Jobs Not Triggering:
- Cause: Cron job not added to crontab or supervisor.
- Fix: Check logs (php bin/console autobus:cron:run --verbose) and ensure the command is scheduled.
Payload Serialization Issues:
- Cause: Complex objects (e.g., DateTime, resources) not serializable to JSON.
- Fix: Use json_encode($payload, JSON_THROW_ON_ERROR) or implement __serialize().
Permission Denied (AWS SQS):
- Cause: IAM user lacks SQS permissions.
- Fix: Attach AmazonSQSFullAccess policy (temporarily for testing) or refine permissions.
Duplicate Jobs:
- Cause: Consumer processes messages slower than they arrive.
- Fix: Adjust batch size in consumer config or scale consumers horizontally.

Debugging

Logs:
- Enable debug mode in config/packages/dev/autobus.yaml:
```
autobus:
    debug: true
```
- Check var/log/dev.log for job execution traces.

Command-Line Flags:

Run consumers with --verbose:

php bin/console autobus:sqs:consume --verbose

Simulate job execution:

php bin/console autobus:test:run App\Bus\Jobs\SendEmailJob

Database Inspection:
- Query the autobus_job table to verify job statuses:
```
SELECT * FROM autobus_job WHERE status = 'pending';
```

Extension Points

Custom Job Storage:
- Override the default Doctrine repository by binding a custom JobRepositoryInterface:
```
services:
    App\Bus\Repositories\CustomJobRepository:
        tags: ['autobus.job.repository']
```

Middleware:

Add pre/post-processing to jobs via middleware:

namespace App\Bus\Middleware;

use Autobus\Bundle\BusBundle\Runner\RunnerInterface;
use Autobus\Bundle\BusBundle\Runner\RunnerMiddlewareInterface;

class LoggingMiddleware implements RunnerMiddlewareInterface
{
    public function handle(RunnerInterface $runner): void
    {
        $runner->getLogger()->info('Job started: ' . $runner::class);
    }
}

Event Listeners:

Listen to job events (e.g., JobStarted, JobFailed) via Symfony’s event dispatcher:

$dispatcher->addListener(JobEvents::JOB_STARTED, function (JobStartedEvent $event) {
    // Log or notify
});

Dynamic Job Configuration:

Use environment variables or config files to parameterize jobs:

# config/packages/autobus.yaml
autobus:
    jobs:
        send_email:
            retry_count: 3
            timeout: 300

Autobus Bus Bundle Laravel Package