Pact Messenger Bundle Laravel Package

Getting Started

This is a Symfony Messenger bundle, not a Laravel package — tienvx/pact-messenger-bundle wires pact-php consumer contract testing into the Messenger middleware stack. As a Laravel dev you'll mostly use it when integrating with Symfony services over a shared broker (RabbitMQ/SQS/AMQP), so treat it as a reference implementation and a test harness you run alongside, not something you composer require into an app/.

Minimal steps:

1. composer require --dev tienvx/pact-messenger-bundle (needs PHP 8.x, Symfony 5.4/6.x, symfony/messenger, and phpspec/php-pact).
2. Register the bundle in config/bundles.php and create config/packages/pact_messenger.yaml.
3. Point the config at your Pact mock provider base URL and pick the transport(s) to record.
4. Write a first test: start the mock provider, dispatch a message through MessageBusInterface, and assert the recorded interaction matches your contract JSON.

Look first at:

• EnvelopeCollector — the service that snapshots dispatched Envelopes. This is the heart of the package; everything else is plumbing around it.
• SendMessageToTransportsEventListener — hooks SendMessageToTransportsEvent so messages leaving the bus are captured at exactly the right point.
• README example usage (rewritten in PR #9) — the only end-to-end sample that currently exists.

First real use case: you publish App\Message\UserCreated to a queue and a Symfony consumer owns the contract. Use this bundle (or copy its pattern into a Laravel test) to assert your outgoing envelope's body and headers satisfy the consumer's expectations before you ship.

Implementation Patterns

Consumer test with the mock provider. Boot the Pact mock server in setUpBeforeClass, dispatch via MessageBusInterface, then let EnvelopeCollector hand you the captured Envelope for assertion against the mock's expectations. Verify in tearDownAfterClass.

Transport-scoped recording (new in v1.0.0, PR #2). Allow filter envelope by transport is the most practically important change in this release. Configure an allowlist of transport names so only messages routed to the contracted queue are recorded. Without this, every message on every bus — sync, async, failed, retry — lands in the interaction set and your contract drifts.

Assert on the envelope, not the payload. The value of this bundle over hand-rolled HTTP assertions is that it captures the full Envelope: serialized body, Content-Type, type header, and Messenger stamps. Assert the headers your consumer actually keys off.

Provider-side verification. Run the handler against the published pact to prove your Symfony consumer can deserialize what's produced. Pair with pact-broker publish + can-i-deploy in CI.

Mirror the package's own test layout. v1.0.0 added tests for EnvelopeCollector, SendMessageToTransportsEventListener, and a UserController — copy that structure for your own integration tests; the listener unit test in particular shows the exact event shape you need to fake.

Laravel-side adapter. If you're the producer, don't fight the Symfony dependency tree. Either (a) use phpspec/php-pact directly with a small MessageSending/JobProcessing event listener, or (b) run this bundle in a tiny Symfony sidecar whose only job is producing contract interactions. The EnvelopeCollector logic is ~100 lines and easy to port to a Laravel listener.

Gotchas and Tips

• No service provider, no config/pact.php. Bundle registration and YAML config only. In Laravel you must wire the collector yourself or skip the bundle entirely.
• Default collection is broad. Envelope filtering by transport is opt-in; if you don't configure it you'll capture failed/retried envelopes with RedeliveryStamp, DelayStamp, and error stamps in the headers — noise that will break a strict contract.
• Version churn is real. PR #1 is literally "Fix wrong arguments" and PRs #3–#7 are all dependency bumps and test additions. v1.0.0 is the first tag; pin exact versions and expect the config schema to move.
• Serializer symmetry. Messenger's Serializer must match the consumer's expectations (application/json vs PHP-serialize, type header alias mapping). Serializer mismatches are the #1 cause of "the contract passes locally but the consumer can't deserialize it."
• Use in-memory:// for tests. Hitting a real broker makes the suite slow and non-deterministic; the collector only cares about the envelope leaving the bus, not delivery.
• Stale type headers after refactors. Renaming a message class silently changes the type header — a breaking contract change that no PHPStan rule will catch.
• Docs lag code. PR #8 is a "Add todo" commit to the docs, so the README is still catching up with v1.0.0 behaviour. Read EnvelopeCollector and the config tree directly when the README is ambiguous.
• Extension points: decorate EnvelopeCollector (it's a normal service) to redact or normalize headers, and override/replace SendMessageToTransportsEventListener if you need custom capture timing. Both are tested as of this release, so overriding is reasonably safe.
• Mock server lifecycle is on you. There's no PHPUnit extension shipped here — start/stop the pact-php mock server in your base test case or you'll get port collisions between parallel CI jobs.