Message Broker Amqp Laravel Package

Getting Started

• Start with the package README and CHANGELOG.md; v0.3.0 is a breaking release, so read the upgrade notes before touching code.
• Confirm the installed versions of freyr/message-broker-contracts (^0.3) and freyr/identity (^1.0). The identity upgrade changes generated IDs from UUID v7 to ULID.
• Look first for the package service provider, publishable config, and the broker contract interfaces. Typical integration points are a config file under config/, a broker/publisher service, and consumer/handler contracts.
• First useful use case: publish a small domain event after a database commit and consume it asynchronously through a Laravel queue worker. Keep the first message simple and assert the published payload in a test before wiring real consumers.
• If you are upgrading, do the dependency bump first, then run the test suite with deprecations visible. v0.3.0 enables PHPUnit failOnDeprecation, so existing deprecation notices can fail CI immediately.

Implementation Patterns

• Define messages as small immutable DTOs implementing the broker contract. Keep payloads explicit and versionable rather than passing Eloquent models directly.
• Publish after commit. Use DB::afterCommit() or the queue afterCommit option so consumers do not receive messages for rolled-back transactions.
• Treat the message ID as the idempotency key. With ULIDs, store the ID as char(26) or Laravel’s ulid column type, and enforce a unique constraint in consumer-side deduplication tables.
• Use Laravel queues for asynchronous consumption. Run workers with supervision, restart workers on deploy, and configure retry/backoff and dead-letter handling deliberately.
• Keep a stable message envelope: message ID, type/name, occurred-at timestamp, schema version, correlation ID, and payload. This makes tracing and contract evolution much easier.
• For contract upgrades, implement the new ^0.3 interfaces fully and use static analysis to catch signature drift. Since this is a 0.x contracts package, minor bumps can still be breaking.
• Test publishing and consumption with the package’s fake/test doubles where available. Assert message type, payload shape, and ULID format rather than exact generated IDs.
• Use ULIDs in logs and traces for correlation. They are lexicographically sortable, which is useful for debugging and rough chronological ordering, but do not treat them as strict distributed sequence guarantees.
• For integration with existing systems, centralize ID conversion. Keep ULIDs as strings at boundaries and avoid leaking package-specific ID objects into APIs or database casts unless the package explicitly supports it.

Gotchas and Tips

• v0.3.0 is breaking. Upgrade freyr/message-broker-contracts to ^0.3 and freyr/identity to ^1.0 together, then update all implementations of changed contracts. Do not assume a 0.x minor bump is backward compatible.
• UUID v7 to ULID is not just a format change. ULIDs are 26-character Crockford base32 strings. Update database columns, validation rules, API response expectations, URL/route constraints, casts, fixtures, and any external consumers that expect UUID-shaped IDs.
• Existing UUID v7 records will not automatically become valid ULIDs. Plan a migration or dual-read strategy if stored message IDs or deduplication keys must remain resolvable. Backfill or keep a legacy-ID column rather than rewriting identifiers in place.
• If you use Laravel’s uuid column type for message IDs, switch to ulid/char(26) and verify indexes and unique constraints still fit. Check any JSON columns or encrypted payloads that embed IDs.
• PHPUnit failOnDeprecation is enabled. Deprecations from your code or transitive dependencies will fail the suite. Run PHPUnit with deprecation display, fix your own deprecated calls first, and pin or isolate vendor deprecations rather than disabling the flag globally.
• Contract interfaces may have added methods or changed return types. Grep for implementations, run composer update, and use PHPStan/Psalm before deploying. Missing methods often surface only when the container resolves the handler.
• ULID objects can serialize differently from strings. Explicitly cast to string in message payloads, logs, and API resources to avoid inconsistent JSON.
• Config caching can hide new v0.3.0 config keys. Run php artisan config:clear locally and php artisan config:cache in deploy after publishing/updating config.
• Restart queue workers after upgrading. Long-running workers can hold old contract classes in memory and fail on newly published message versions.
• Do not rely on ULID ordering as a strict global sequence. It is sortable and useful for correlation, but concurrent producers can still produce interleaved timestamps.
• Extension points to inspect: custom identity/ID generators, message serializers, broker middleware, and handler resolution. If the package exposes an ID generator contract, bind your own only if you can keep ULID compatibility across the ecosystem.
• When debugging, start at the published message envelope and the consumer’s idempotency record. Most day-to-day failures are serialization mismatches, missing handler bindings, stale workers, or duplicate delivery rather than broker transport issues.