Weave Code
Pigeon Laravel Package
convenia/pigeon
Convenia Pigeon is a Laravel/PHP package for adding message-based communication to your application. It offers a simple, configurable API for publishing and consuming messages, helping teams build decoupled services and reliable workflows with minimal boilerplate.
Laravel package for dealing with AMQP messaging with easy syntax on top of php-amqplib.
Frequently asked questions about Pigeon
- What is convenia/pigeon and how does it differ from using php-amqplib directly?
- Pigeon is a Laravel package that wraps php-amqplib in a fluent, Laravel-native API so you can publish and consume AMQP messages without hand-writing channel, exchange, and queue plumbing. Instead of managing connections and declarations yourself, you call methods such as dispatch(), queue(), exchange(), routing(), and hook into events. It keeps the underlying php-amqplib primitives available but removes most of the boilerplate for typical publish/consume workflows.
- How do I install convenia/pigeon in a Laravel application?
- Install it with Composer using composer require convenia/pigeon, then publish the package configuration so Pigeon has the connection and topology settings it needs. Laravel's package auto-discovery registers the service provider, so no manual provider entry is normally required. After publishing, set your AMQP host, port, credentials, and any exchange or queue names in the config file or matching environment variables.
- How do I upgrade to Pigeon 3.2.0 without breaking existing message flows?
- The 3.2.0 release adds only an opt-in configuration gate, pigeon.skip_auto_declaration, which defaults to false, so a plain composer update preserves the existing declare-on-first-use behavior. The one thing to verify is your published config/pigeon.php: if it predates the release and lacks the new key, confirm the package reads the value with a false fallback rather than throwing on a missing key. Re-publish or manually add the key if you want to opt in.
- What does pigeon.skip_auto_declaration do and when should I enable it?
- It stops Pigeon from creating exchanges, queues, and bindings on the broker, turning the application into a pure AMQP client. Enable it when your topology is already managed as infrastructure-as-code through tools such as Terraform, Helm, RabbitMQ definitions JSON, or the RabbitMQ Operator. Leave it disabled if you rely on Pigeon to self-provision topology in development or in small deployments.
- Why does PIGEON_SKIP_AUTO_DECLARATION=false still behave as true?
- This is the classic env-to-boolean pitfall: environment values arrive as strings, and a naive (bool) cast turns the non-empty string "false" into true. Make sure the value is normalized with filter_var($value, FILTER_VALIDATE_BOOLEAN) or that the config file casts it before Pigeon validates the flag. The same issue has historically affected queue connection flags, so it is worth asserting in a test that "false" resolves to false.
- Which Laravel and PHP versions does convenia/pigeon support?
- Pigeon is a Laravel package built on php-amqplib, and supported Laravel and PHP ranges are declared in the package's composer.json constraints. Check that file and the repository's release notes before upgrading your framework, since PHP version bumps and Laravel major releases can change those constraints. If your application pins an older Laravel version, confirm the installed Pigeon release still allows it.
- How do I publish and consume messages with Pigeon?
- Publishing uses the fluent entry points such as dispatch() along with exchange() and routing() to target a destination, while consuming is done through queue() and the package's event hooks. The API is intentionally small so producer code reads like a normal Laravel service call rather than raw AMQP channel manipulation. Wrap publishing in your own job or service class so retries and failure handling stay under application control.
- What happens if the exchange or queue does not exist when skip_auto_declaration is enabled?
- With auto-declaration disabled, Pigeon no longer creates missing topology, so the broker itself returns an error instead of the package silently provisioning it. Expect 404 NOT_FOUND for a missing queue or exchange and 406 PRECONDITION_FAILED when an existing entity has mismatched parameters. Make sure those errors surface in your logs and alerting, because they now indicate an infrastructure drift rather than a recoverable first-run condition.
- How should I test AMQP publishing and consuming in a Laravel app using Pigeon?
- The most reliable approach is to run a real RabbitMQ broker in CI, for example via Docker, so topology, routing, and error codes are exercised end to end. For fast unit tests you can mock or fake the Pigeon driver and assert that dispatch, queue, exchange, and routing are called with the expected arguments. Also add a test covering the skip_auto_declaration flag in both states, including the string "false" case, so the env coercion behavior is locked in.
- Is convenia/pigeon actively maintained and what are the alternatives?
- Maintenance activity is best judged from the GitHub repository's release history, commit cadence, and open issue responses, so check those before committing to it. If you need framework-agnostic control or features beyond Pigeon's abstraction, php-amqplib directly, Laravel's queue system with an AMQP driver, or a dedicated AMQP client library are common alternatives. Pigeon's advantage remains its small, Laravel-native surface for teams that want straightforward publish and consume semantics.
Weaver
How can I help you explore Laravel packages today?