README

A PHP library providing async messaging interfaces for domain-driven design (DDD) applications.

Overview

This package offers a set of standardized interfaces for implementing message-based communication patterns in PHP applications. It provides abstractions for publishers, consumers, message handlers, and connections to message brokers, allowing you to build decoupled, event-driven architectures.

Requirements

PHP >= 8.2

Installation

Install via Composer:

composer require jardispsr/messaging

Interfaces

Core Interfaces

MessagingServiceInterface

Unified interface combining both publisher and consumer functionality in one service.

public function publish(string $topic, string|object|array $message, array $options = []): bool;
public function consume(string $topic, MessageHandlerInterface $handler, array $options = []): void;
public function getPublisher(): MessagePublisherInterface;
public function getConsumer(): MessageConsumerInterface;

ConnectionInterface

Manages connections to message brokers.

public function connect(): void;
public function disconnect(): void;
public function isConnected(): bool;

Publishing Interfaces

PublisherInterface

Low-level interface for publishing messages to topics, channels, or queues.

public function publish(string $topic, string $message, array $options = []): bool;

MessagePublisherInterface

High-level interface for application-specific message publishing.

public function publish(string|object|array $message): bool;

Consumption Interfaces

ConsumerInterface

Low-level interface for consuming messages from topics, channels, or queues.

public function consume(string $topic, callable $callback, array $options = []): void;
public function stop(): void;

MessageConsumerInterface

High-level interface for application-specific message consumption.

public function consume(MessageHandlerInterface $handler): void;

MessageHandlerInterface

Handles received messages with acknowledgment control.

public function handle(string|array $message, array $metadata): bool;

Exceptions

The library provides specific exceptions for different error scenarios:

ConnectionException - Connection-related errors
PublishException - Publishing failures
ConsumerException - Consumption errors
MessageException - Message handling errors

Usage Examples

Using MessagingServiceInterface (Recommended)

The unified service interface simplifies implementation by combining publisher and consumer:

use JardisPsr\Messaging\MessagingServiceInterface;
use JardisPsr\Messaging\MessageHandlerInterface;

class MyMessagingService implements MessagingServiceInterface {
    public function publish(string $topic, string|object|array $message, array $options = []): bool {
        // Publish message to your broker
        return true;
    }

    public function consume(string $topic, MessageHandlerInterface $handler, array $options = []): void {
        // Start consuming messages
    }

    public function getPublisher(): MessagePublisherInterface {
        // Return publisher instance
    }

    public function getConsumer(): MessageConsumerInterface {
        // Return consumer instance
    }
}

// Usage
$service = new MyMessagingService();
$service->publish('orders', ['order_id' => 123, 'status' => 'created']);
$service->consume('orders', new MyMessageHandler());

Using Individual Interfaces

For more granular control, implement the interfaces separately:

use JardisPsr\Messaging\PublisherInterface;
use JardisPsr\Messaging\ConsumerInterface;
use JardisPsr\Messaging\MessageHandlerInterface;

class MyPublisher implements PublisherInterface {
    public function publish(string $topic, string $message, array $options = []): bool {
        // Implementation for your message broker
        return true;
    }
}

class MyMessageHandler implements MessageHandlerInterface {
    public function handle(string|array $message, array $metadata): bool {
        // Process the message
        // Return true to acknowledge, false to reject/requeue
        return true;
    }
}

class MyConsumer implements ConsumerInterface {
    public function consume(string $topic, callable $callback, array $options = []): void {
        // Implementation for your message broker
    }

    public function stop(): void {
        // Stop consuming
    }
}

Development

Code Quality Tools

The project includes PHPStan and PHP_CodeSniffer for maintaining code quality:

# Run PHPStan
composer exec phpstan analyse

# Run PHP_CodeSniffer
composer exec phpcs

Git Hooks

A pre-commit hook is automatically installed via Composer to ensure code quality before commits.

License

MIT License - see LICENSE file for details.

Support

Issues: GitHub Issues
Email: jardisCore@headgent.dev

Authors

Jardis Core Development - jardisCore@headgent.dev

Keywords

messaging, interfaces, JardisPsr, Headgent, DDD

jardispsr / messaging

Maintainers

Details