Php Amqp Client Bundle Laravel Package

Getting Started

• Install with composer require sigbits/php-amqp-client-bundle:^0.7. The baseline now pulls sigbits/php-amqp-client:^1.4, requires PHP ^8.3, and targets Symfony ^6.4 || ^7.4 || ^8.1.
• Read this first: this is a Symfony bundle, not a Laravel package. There is no service provider, no facade, and no config/amqp.php. If your app is Laravel, the bundle's autoconfiguration will never run — the day-to-day value you get is from the underlying sigbits/php-amqp-client 1.4 APIs plus whatever you wire yourself. If you are on Symfony, register the bundle in bundles.php and start with the DI extension to see what services it exposes.
• The two classes worth opening on day one are OpenReceiverEndpoint (consuming) and TerminusFactoryInterface (producing / settling). In 0.7.0 these gained deliveries() and modified() respectively, and those are exactly the APIs you will touch most.
• First use case: publish one message, consume it in a loop, and settle it explicitly (ack vs. reject/requeue vs. modified). Do that end-to-end against a real broker before touching anything else — connection and channel lifecycle is where most of the friction lives.

Implementation Patterns

Consuming with deliveries(). The new iterator is the idiomatic consume loop in 0.7.0:

$endpoint = $container->get(OpenReceiverEndpoint::class);

foreach ($endpoint->deliveries() as $delivery) {
    try {
        $this->handle($delivery->message());
        $endpoint->accept($delivery);
    } catch (RetryableException $e) {
        $endpoint->release($delivery);
    } catch (\Throwable $e) {
        $endpoint->reject($delivery);
    }
}

Treat the iterator as infinite — it is a long-running loop, not a finite collection. Wrap it in a worker command with signal handling so SIGTERM breaks out cleanly.

Settling with modified(). TerminusFactoryInterface::modified() lets you return a modified outcome instead of a hard reject. This is the right tool when you want to release a message back to the broker without counting it as a failure — for example "this consumer cannot handle this routing key right now" or "dependency unavailable, put it back". Use it deliberately:

• accept — processed, drop it.
• reject — permanent failure, dead-letter it.
• release — transient failure, redeliver.
• modified — "not my message / not now", with delivery-failure and requeue flags.

Laravel wiring. Since bundling doesn't apply, bind the client in a service provider as a singleton connection, and expose the endpoint via the container. Keep the connection out of the request lifecycle and instead resolve it inside a queued job or a custom Artisan worker command — that mirrors what the Symfony bundle does with its long-lived services.

Producing. Resolve the terminus factory from the container rather than constructing it inline; you want one factory per connection so delivery-state values and the connection's session stay consistent.

Testing. The endpoint/factory pair is interface-driven (TerminusFactoryInterface), so fake the factory in unit tests and use a real broker (Testcontainers / a compose service) for a thin integration suite. Do not try to unit-test the iterator.

Gotchas and Tips

• Pre-1.0 semver. 0.7.x is a minor bump that raised a hard dependency floor and added APIs. Expect 0.x minors to break things — pin to ^0.7 and read every changelog, or pin exactly. The 0.7-dev branch alias means dev-* constraints will now resolve differently in CI.
• The ^1.4 floor is a conflict source. If anything else in the tree pins sigbits/php-amqp-client to 1.3.*, Composer will fail the whole install. Check composer why sigbits/php-amqp-client before upgrading rather than after.
• PHP 8.3 minimum. Your CI matrix, Docker base image, and any platform config in composer.json must agree, or you get a confusing resolution failure that looks like a package problem.
• Bundle ≠ Laravel. The most common early mistake is assuming the bundle's DI config, tagged services, or services.yaml conventions apply. They don't. Everything is manual wiring: connection, factory, endpoints.
• Delivery-state semantics are broker-dependent. modified is not universally supported the way accept/reject are. Verify against your actual broker version in staging; a modified that the broker downgrades to a requeue can silently produce a hot redelivery loop.
• Unacked deliveries die with the connection. If deliveries() yields ten messages and your worker crashes on the third, everything unacked is requeued — which is correct, but makes non-idempotent handlers dangerous. Make handlers idempotent before you enable prefetch above 1.
• Long-running workers and heartbeats. Connections idle out or get killed by the broker during slow processing. Set a heartbeat on the connection and reconnect on failure rather than assuming the iterator survives a dropped socket.
• Debugging. Enable the client's own logging first — the bundle gives you very little diagnostic surface on its own. When messages vanish, check settlement order (are you settling before the work commits?) and whether you are reusing a channel across concurrent coroutines.