Version 3.4.0 - Minor Release

A consolidated release that lands twenty features from the roadmap across
retry/DLQ, delayed/typed/schema messaging, production infrastructure,
workflows/testing, and scale/interop -- all fully backwards-compatible and
verified on PHP 7.3 through 8.5.

No migration required. Every new feature is opt-in; existing publish/consume
code, handler signatures, and config layouts continue to work unchanged.

Compatibility

• PHP: 7.3 through 8.5
• Laravel: 8.x through 13.x (Lumen 8.x+)
• PHPUnit: ^9.6 on PHP 7.3/7.4; ^10.5|^11.5|^12.0 on PHP 8.0+
• New scripts/check-php73-compat.php (curated) and
  scripts/check-php73-compat-all-src.php (entire src/) using
  nikic/php-parser — every file under src/ parses as PHP 7.3.

Retry, Delayed, Typed & Schema Messaging

1. Advanced retry & dead-letter abstractions

   • Bschmitt\Amqp\Support\RetryPolicy value object with
     fixed() / exponential() / immediate() / none() factories and
     configurable maxDelayMs cap + jitterMs.
   • DeadLetterTopology builder generates property bags for the work
     queue, DLQ, and per-delay retry queues ({queue}.retry.{ms}).
   • RetryHandler decorator wraps any callable with the full
     republish-or-reject pipeline (tracks x-retry-attempt,
     x-first-failed-at, and x-last-error headers).
   • Amqp::declareRetryTopology(), retryHandler(),
     consumeWithRetry(), topology().
   • amqp:work gains --retry, --retry-backoff, --retry-delay,
     --retry-multiplier, --retry-max-delay, --retry-jitter,
     --dlq, and --declare-topology.

2. Delayed messaging & publisher backoff

   • Bschmitt\Amqp\Support\DelayedPublisher with two strategies:
     ttl (default, TTL+DLX per-delay queue — works on stock RabbitMQ)
     and plugin (rabbitmq-delayed-message-exchange).
   • Amqp::publishLater(), publishTypedLater(),
     delayedPublisher().
   • PublishBackoff wraps any publish closure with a RetryPolicy,
     exposed via Amqp::withPublishBackoff().
   • amqp:publish gains --delay-ms and --delay-strategy=ttl|plugin.

3. Typed message contracts & DTO serialization

   • Bschmitt\Amqp\Contracts\MessageContractInterface and the
     optional TypedMessage base class (reflection-driven defaults plus
     routingKey(), exchange(), schema() hooks).
   • MessageSerializerInterface strategy; default is
     JsonMessageSerializer (JSON_THROW_ON_ERROR, unicode/slash-safe).
   • Amqp::publishTyped(), publishTypedLater(), consumeTyped(),
     setSerializer(), getSerializer().
   • amqp:work --contract= deserializes inbound bodies and passes the
     DTO as a third handler argument (the existing two-argument signature
     keeps working — the new arg defaults to null).

4. JSON Schema validation for messages

   • Zero-dependency Bschmitt\Amqp\Support\SchemaValidator
     implementing a Draft 7 subset (types, required, properties,
     additionalProperties, string/number/array constraints, enum,
     const, oneOf/anyOf/allOf/not, common formats).
   • SchemaValidationException carries errors() with JSON-pointer
     paths.
   • Schema validation runs automatically on publish/consume whenever a
     contract exposes a non-null schema().
   • amqp:work --validate-schema enforces in long-running workers.

Production Infrastructure

1. Exchange & topology builders

   • ExchangeTopology fluent builder for exchange + multi-queue bindings.
   • Amqp::declareExchangeTopology(), exchangeTopology() shortcut.

2. Quorum & priority queue profiles

   • QueueProfile presets: classic(), quorum(), priority(),
     quorumWithPriority() with mergeInto() for property bags.

3. Auto reconnect & heartbeat monitoring

   • ResilientConnectionManager decorator with connect retries and
     heartbeat staleness detection.
   • Amqp::resilientConnection() factory helper.

4. Connection pooling & persistent channels

   • ConnectionPool singleton via Amqp::connectionPool() with
     persistent key support and optional resilient wrapping.

5. Distributed tracing (W3C, OTel-ready)

   • TraceContext, TracePropagatorInterface, W3cTracePropagator,
     NullTracePropagator, CallbackTracePropagator for APM bridges.
   • propagate_trace flag on publish/consume; Amqp::setTracePropagator().

6. Correlation ID propagation

   • CorrelationContext with propagate_correlation integration on
     publish and consumeWithLifecycle().

7. Consumer lifecycle management

   • ConsumerLifecycle hooks (starting/stopping/message/error), signal
     handlers, and Amqp::consumeWithLifecycle().

Workflows, Events, Middleware & Testing

1. SAGA workflow helpers

   • Saga builder with step($name, $action, $compensation) and
     reverse-order compensations on failure.
   • SagaResult reports succeeded/failed status, per-step results, the
     failing step, exception, and which steps were compensated.
   • Amqp::saga($name) shortcut.

2. Laravel events

   • New events under Bschmitt\Amqp\Events\: MessagePublishing,
     MessagePublished, MessageReceived, MessageHandled,
     MessageFailed.
   • Dispatched via Illuminate\Support\Facades\Event when available;
     fallback singleton EventDispatcher for non-Laravel contexts.

3. Consume middleware pipeline

   • ConsumeMiddlewareInterface and ConsumePipeline.
   • Amqp::consumeWithMiddleware($queue, $handler, $middlewares, $properties).

4. Fake AMQP test driver

   • Bschmitt\Amqp\Testing\FakeAmqp extends Amqp with null
     publisher/consumer/factory stubs.
   • Laravel-style assertions: assertPublished(), assertNotPublished(),
     assertNothingPublished(), assertPublishedCount().
   • Amqp::fake() swaps the bound singleton (or returns a standalone fake
     when no Laravel app is active).

5. Publisher confirms & async publishing

   • AsyncPublisher with persistent channel, confirm_select,
     onAck() / onNack() callbacks, and flush() / stats().
   • Amqp::asyncPublisher($properties) shortcut.
   • Leverages existing Publisher confirms (publisher_confirms,
     wait_for_confirms, waitForConfirms()).

Scale & Interop

1. RPC abstraction helpers

   • RpcClient + RpcCallResult with JSON mode and configurable
     timeouts.
   • RpcServer auto-reply consumer wrapper.
   • Amqp::rpcClient(), rpcServer().

2. Cross-service / polyglot messaging

   • InteropEnvelope / InteropMessage with standard headers
     (x-message-type, x-schema-version, x-source-service).
   • Amqp::publishInterop(), consumeInterop().

3. Enhanced observability & queue metrics

   • MetricsCollector with Amqp::metrics() (auto-increment on
     publish / consume).
   • QueueMetrics normalized view of Management API stats.
   • Amqp::queueMetrics(), getQueueStats() alias.

4. High-performance worker optimizations

   • WorkerOptions presets (throughput, lowLatency).
   • HighPerformanceWorker, Amqp::consumeOptimized().
   • amqp:work --optimized (prefetch=50 when not overridden).

Tests

• ~130 new unit tests; total 395 unit tests (906 assertions).
• Full suite passes on PHP 8.3 and 8.4; deprecation warnings on 8.4 come
  exclusively from the vendored Mockery library and predate this release.

New & Updated Documentation

• New pages:
  • docs/content/delayed-messaging.md
  • docs/content/typed-messaging.md
  • docs/content/schema-validation.md
  • docs/content/production-features.md
  • docs/content/workflow-events-testing.md
  • docs/content/scale-and-interop.md
• Updated docs/content/advanced.md, publishing.md, consuming.md,
  artisan-commands.md, best-practices.md, faq.md,
  getting-started.md, guide.md, USER_MANUAL.md, README.md.
• New sidebar entries and feature cards in docs/index.html; new
  "Typed Messages" quick-start tab on the home page.

Migration

No migration required. All new features are opt-in:

• Existing handlers keep their two-argument signature; the typed third
  argument defaults to null when --contract is not used.
• MessageHandlerInterface::handle() gains an optional $typed = null
  parameter; implementations written against the old signature continue
  to work because the new argument has a default value.
• The default MessageSerializerInterface is lazily resolved as
  JsonMessageSerializer — existing publish/consume calls that send raw
  bodies are unaffected.

Version 3.3.0 - Minor Release

This release broadens framework and PHP compatibility, improves configuration resolution, and expands CI coverage.

Compatibility

• PHP: 7.3 through 8.5 (composer.json: ^7.3|^8.0)
• Laravel: 7.x through 13.x in dev dependencies; CI matrix covers Laravel 8–13 across supported PHP versions
• Laravel 8: supports PHP 7.3 and 7.4 (Laravel 9+ requires PHP 8.0.2+)
• Laravel 9: requires PHP ^8.0.2; CI/local installs use platform.php 8.0.2 (see scripts/ci-platform-php.sh)
• PHPUnit: ^9.6 on PHP 7.3/7.4; ^10.5|^11.5|^12.0 on PHP 8.0+ (resolved automatically by Composer)

Features

1. Configuration layouts

   • ConfigurationProvider accepts current use/properties, legacy default/connections, and flat single-connection configs.

2. CI and local testing

   • GitHub Actions matrix for PHP 7.3–8.5 and Laravel 8–13.
   • scripts/ci-platform-php.sh and scripts/ci-composer-install.sh for correct Composer platform constraints.
   • test-ci.sh for running the CI matrix locally.

Fixes

PHP 8.4+ and 8.5 compatibility fixes contributed by @dlpro in PR #136 (merged May 18, 2026):

1. PHP 8.4+ implicitly nullable parameters

   • Added explicit ? to nullable constructor parameters in ConsumerFactory, PublisherFactory, Consumer, and Publisher (avoids deprecation warnings on PHP 8.4 and fatal errors in PHP 9).
   • Fixed the same pattern in DeadLetterExchangeIntegrationTest::createConfig().

2. PHP 8.5 deprecations

   • Removed curl_close() from ManagementApiClient (no-op since PHP 8.0, removed in PHP 8.5).
   • Dropped ReflectionProperty::setAccessible() calls in unit/integration tests (deprecated in PHP 8.5; no-op since PHP 8.1).
   • ReflectionTestTrait still calls setAccessible(true) on PHP 7.3/7.4 where reflection access requires it.

Migration

No migration required. Existing config/amqp.php layouts continue to work.

v3.2.0

This release includes Laravel 13 readiness updates, RPC reliability fixes, CI modernization, and a major documentation portal refresh.

Highlights

• Added compatibility guidance for Laravel 10.x, 11.x, 12.x, and 13.x.
• Improved RPC reply reliability by fixing correlation ID handling in Consumer::reply().
• Updated CI to test modern Laravel/PHP combinations.
• Added and standardized contributor/project health documentation.

What’s New

Fixes

• Fixed RPC response matching by publishing correlation_id as a proper AMQP message property.
• Updated integration test logic around reply handling and consumer timeout/persistence behavior.

CI/CD

• Refreshed GitHub Actions workflow matrix for current PHP/Laravel targets.
• Improved CI runtime reliability with updated workflow configuration.

Documentation

• Introduced a new docs portal with richer structure and content.
• Added comprehensive documentation sections (installation, configuration, publishing, consuming, RPC, management API, troubleshooting, best practices, and more).
• Updated README badges and release references.

Community / Maintenance

• Added CONTRIBUTING.md guidance.
• Improved repository hygiene and maintainability updates.

Compatibility

• PHP: modern supported versions (including PHP 8.3 in CI)
• Laravel: 10.x, 11.x, 12.x, 13.x
• RabbitMQ: 3.x (tested with rabbitmq:3-management)

Testing

• Unit test suite passing.
• Integration test suite passing (with expected environment-dependent skips/warnings).

Notes

• This is a minor release (3.2.0) due to cumulative feature/documentation expansion plus fixes.
• No intentional breaking API changes are introduced in this release.

What's Changed

• Solves #127,#128 Issues - Remove Amqp, Consumer, and Publisher classes; update integration test… by @zfhassaan in #129

Full Changelog: v3.1.0...v3.1.1

Release Notes

Version 3.1.0 - Major Release

This release introduces significant new features, improvements, and bug fixes to the Laravel AMQP package. The package now provides comprehensive support for RabbitMQ management operations, RPC patterns, message properties, and enhanced testing capabilities.

Major New Features

1. RPC (Request-Response) Pattern Support

The package now includes built-in support for RPC patterns, making it easy to implement request-response communication between services.

New Methods

• $amqp->rpc() - Make RPC calls with automatic correlation ID and reply queue management

  $amqp = app('Amqp');
  $response = $amqp->rpc('rpc-queue', 'request-data', [], 30);

• Consumer::reply() - Send RPC responses from consumer callbacks

  $amqp = app('Amqp');
  $amqp->consume('rpc-queue', function ($message, $resolver) {
      $result = processRequest($message->body);
      $resolver->reply($message, $result);
      $resolver->acknowledge($message);
  });

• $amqp->listen() - Convenience method to auto-create queues and bind to multiple routing keys

  $amqp = app('Amqp');
  $amqp->listen(['key1', 'key2'], function ($message, $resolver) {
      // Handle message
  });

Benefits

• Simplified RPC implementation
• Automatic correlation ID management
• Built-in timeout handling
• Support for request-response patterns in microservices

2. Queue and Exchange Management Operations

Direct programmatic control over RabbitMQ queues and exchanges.

New Methods

• $amqp->queueUnbind() - Unbind a queue from an exchange
• $amqp->exchangeUnbind() - Unbind an exchange from another exchange
• $amqp->queuePurge() - Remove all messages from a queue
• $amqp->queueDelete() - Delete a queue
• $amqp->exchangeDelete() - Delete an exchange

Example Usage

// Get Amqp instance
$amqp = app('Amqp');

// Purge all messages from a queue
$amqp->queuePurge('my-queue', ['queue' => 'my-queue']);

// Delete a queue
$amqp->queueDelete('my-queue', ['queue' => 'my-queue']);

// Unbind a queue from an exchange
$amqp->queueUnbind('my-queue', 'my-exchange', 'routing-key', [
    'queue' => 'my-queue',
    'exchange' => 'my-exchange'
]);

3. RabbitMQ Management HTTP API Integration

Full integration with RabbitMQ's Management HTTP API for monitoring and statistics.

New Methods

• Amqp::getQueueStats() - Get queue statistics (message count, consumer count, etc.)
• Amqp::getConnections() - List all active connections
• Amqp::getChannels() - List all active channels
• Amqp::getNodes() - Get cluster node information
• Amqp::getPolicies() - List all policies
• Amqp::createPolicy() - Create a new policy
• Amqp::updatePolicy() - Update an existing policy
• Amqp::deletePolicy() - Delete a policy
• Amqp::listFeatureFlags() - List all feature flags
• Amqp::getFeatureFlag() - Get status of a specific feature flag

Configuration

Add to your config/amqp.php:

'management_api_url' => 'http://localhost:15672',
'management_api_user' => 'guest',
'management_api_password' => 'guest',

Example Usage

// Get Amqp instance
$amqp = app('Amqp');

// Get queue statistics
$stats = $amqp->getQueueStats('my-queue', '/');
// Returns: ['messages' => 10, 'consumers' => 2, ...]

// List all connections
$connections = $amqp->getConnections();

// Create a policy
$amqp->createPolicy('my-policy', '/', [
    'pattern' => '^my-queue$',
    'definition' => ['max-length' => 1000]
]);

4. Policy Management

Programmatic management of RabbitMQ policies for queue and exchange configuration.

Features

• Create, update, and delete policies
• Support for all policy definition options
• Integration with Management HTTP API

5. Feature Flags Support

Query RabbitMQ feature flags to determine available capabilities.

Methods

• Amqp::listFeatureFlags() - Get all feature flags and their status
• Amqp::getFeatureFlag() - Check if a specific feature flag is enabled

6. Enhanced Message Properties

Full support for standard AMQP message properties.

Supported Properties

• Priority - Message priority (0-255)
• Correlation ID - For RPC patterns
• Reply-To - For request-response patterns
• Message ID - Unique message identifier
• Timestamp - Message timestamp
• Type - Message type
• User ID - User identifier
• App ID - Application identifier
• Expiration - Message TTL
• Content Type - MIME type
• Content Encoding - Content encoding
• Delivery Mode - Persistent or transient
• Application Headers - Custom headers

Example Usage

// Get Amqp instance
$amqp = app('Amqp');

// Publish with message properties (using dynamic call)
$amqp->publish('routing-key', 'message', [
    'priority' => 10,
    'correlation_id' => 'unique-id',
    'reply_to' => 'reply-queue',
    'application_headers' => [
        'X-Custom-Header' => 'value'
    ]
]);

// Access properties in consumer (using dynamic call)
$amqp->consume('queue', function ($message, $resolver) {
    $priority = $message->getPriority();
    $correlationId = $message->getCorrelationId();
    $headers = $message->getHeaders();
});

7. Connection Configuration Helper

New method to retrieve connection configurations programmatically.

Method

• $amqp->getConnectionConfig() - Get configuration for a specific connection

Example Usage

$amqp = app('Amqp');
$config = $amqp->getConnectionConfig('production');
// Returns: ['host' => 'localhost', 'port' => 5672, ...]

Improvements

Consumer Prefetch (QoS)

• Enhanced prefetch configuration with dynamic adjustment
• Support for qos_prefetch_count, qos_prefetch_size, and qos_a_global
• Better control over message delivery rates

Publisher Confirms

• Full support for publisher confirms
• Configurable acknowledgment handlers
• Support for wait_for_confirms and publish_timeout
• Return message handling for unroutable messages

Queue Types

• Full support for Classic, Quorum, and Stream queue types
• Proper handling of queue type properties
• Validation and error handling

Exchange Types

• Enhanced validation for exchange types
• Support for custom exchange types (with validation override)
• Better error messages for invalid exchange types

Bug Fixes

Fixed Issues

1. Singleton Behavior - Fixed issue where Publisher and Consumer properties persisted between calls

   • Each call now creates a new instance with merged properties
   • Prevents unexpected routing behavior

2. Connection Management - Improved connection and channel cleanup

   • Proper shutdown of connections and channels
   • Better resource management

3. Configuration Handling - Enhanced configuration provider

   • Better handling of property merging
   • Improved test environment compatibility

4. Queue Declaration - Fixed PRECONDITION_FAILED errors

   • Better handling of existing queues with different properties
   • Support for passive queue/exchange declaration

5. Test Environment - Improved test reliability

   • Better handling of Laravel facade in test environments
   • Enhanced integration test setup

Documentation

New Documentation

• Comprehensive developer documentation in wiki format
• Module-by-module feature documentation
• FAQ section addressing common issues
• RPC pattern usage guide
• Testing guide with examples
• Architecture documentation

Updated Documentation

• Configuration guide with all new options
• Publishing and consuming examples
• Advanced features documentation
• Management API usage guide

Testing

Test Coverage

• 273 total tests with comprehensive coverage
• Unit tests for all new features
• Integration tests against real RabbitMQ instances
• Tested with rabbitmq:3-management Docker image

New Test Suites

• RPC method tests
• Management operation tests
• Management API integration tests
• Message properties tests
• Reply method tests

Test Improvements

• Better test isolation
• Improved cleanup procedures
• Enhanced error handling in tests
• More reliable integration test setup

Backward Compatibility

This release maintains full backward compatibility with previous versions:

• All existing methods continue to work as before
• Configuration file format remains compatible
• Existing code will work without modifications
• New features are opt-in

Dependencies

• PHP 8.1+ (tested with PHP 8.3)
• Laravel 8.x / 9.x / 10.x / 11.x
• php-amqplib/php-amqplib (latest)
• RabbitMQ 3.x (tested with 3-management)

Breaking Changes

None - This release is fully backward compatible.

Migration Guide

No migration required. All existing code will continue to work. To use new features:

1. Update your config/amqp.php if you want to use Management API features
2. Use new methods as needed in your code
3. Review new documentation for best practices

Important: Method Calling Convention

All methods should be called dynamically:

// Get Amqp instance from container
$amqp = app('Amqp');
// or
$amqp = resolve('Amqp');

// Publish messages (using dynamic call)
$amqp->publish('routing-key', 'message');

Dynamic Instance (required for all methods including consume(), rpc(), listen(), publish(), and management methods):

// Get Amqp instance from container
$amqp = app('Amqp');
// or
$amqp = resolve('Amqp');

// Use instance methods
$amqp->consume('queue', function ($message, $resolver) {
    // Handle message
});

$amqp->rpc('rpc-queue', 'request', [], 30);
$amqp->listen(['key1', 'key2'], function ($message, $resolver) {
    // Handle message
});

// Management methods
$amqp->queuePurge('my-queue', ['queue' => 'my-queue']);
$amqp->getQueueStats('my-queue', '/');

Note: All methods including publish(), consume(), rpc(), listen(), and all management methods must be called on an instance resolved from the container using $amqp = app('Amqp') or $amqp = resolve('Amqp').

What's Next

Future improvements planned:

• Enhanced RPC timeout handling
• Better error recovery mechanisms
• Additional queue management operations
• Performance optimizations

Acknowledgments

Special thanks to all contributors and the community for feedback and testing.

Changelog Summary

Added

• RPC pattern support (rpc(), reply(), listen())
• Queue and exchange management operations
• Management HTTP API integration
• Policy management
• Feature flags support
• Enhanced message properties
• Connection configuration helper
• Comprehensive test suite
• Developer documentation

Improved

• Consumer prefetch handling
• Publisher confirms support
• Queue type handling
• Exchange type validation
• Configuration management
• Test reliability
• Error messages

Fixed

• Singleton behavior issues
• Connection cleanup
• Configuration handling
• Queue declaration errors
• Test environment compatibility

Support

For issues, questions, or contributions, please visit:

• GitHub Issues: https://github.com/bschmitt/laravel-amqp/issues
• Documentation: See docs/ directory

Release Date: 2025
Version: 3.1.0
Status: Ready

Full Changelog: 2.1.2...v3.1.0