Download the PHP package tomaj/hermes without Composer

Hermes

Background job processing PHP library

Documentation: https://tomaj.github.io/hermes/

Getting started · API reference · Changelog

What is Hermes?

Hermes is a lightweight PHP library for background job processing. When you need to handle time-consuming tasks outside of HTTP requests—such as sending emails, calling external APIs, or processing data—Hermes provides a clean, efficient solution.

Key features:

• Multiple queue backends: Support for Redis, RabbitMQ, Amazon SQS, and more
• Simple integration: Easy to add to existing projects with minimal setup
• Extensible architecture: Create custom drivers and handlers for your specific needs
• Production-ready: Built-in support for priorities, retries, and graceful shutdown

Installation

This library requires PHP 8.4 or later.

The recommended installation method is via Composer:

Library is compliant with PSR-1, PER Coding Style, PSR-3 and PSR-4.

Optional Dependencies

Hermes supports logging through any PSR-3 compatible logger. For more information, see psr/log.

While the library works without logging, we recommend installing monolog for production environments to track message processing and debugging.

Supported Drivers

Hermes includes built-in support for multiple queue backends:

• Redis - Two implementations available: phpredis (native extension) or Predis (pure PHP)
• Amazon SQS - AWS Simple Queue Service integration
• RabbitMQ - Industry-standard message broker
• ZeroMQ - Available as a separate package: tomaj/hermes-zmq-driver

Note: You need to install the corresponding client libraries for your chosen driver. For example, to use Redis with Predis, add predis/predis to your composer.json and configure your Redis connection.

Concept - How Hermes Works

Hermes acts as a message broker between your web application and background workers. Here's the flow:

Implementation steps:

1. Choose a driver: Select a queue backend (Redis, RabbitMQ, etc.) and register it with the Dispatcher and Emitter
2. Emit messages: Send messages to the queue when you need background processing
3. Create handlers: Write handler classes to process your messages
4. Run the worker: Create a PHP CLI script that runs continuously to process messages from the queue

How to Use

This example demonstrates using the Redis driver to send emails in the background.

Emitting Messages

Emit messages from anywhere in your application—it's quick and straightforward:

Processing Messages

To process messages, create a PHP CLI script that runs continuously. Here's a simple implementation with a handler:

To keep the worker running continuously on your server, use a process manager like supervisord, upstart, monit, or god.

Logging

Hermes supports any PSR-3 compliant logger. Set a logger for the Dispatcher or Emitter to track message flow and handler execution.

To enable logging in your handlers, add the Psr\Log\LoggerAwareTrait trait (or implement Psr\Log\LoggerAwareInterface)—the Dispatcher and Emitter will automatically inject the logger.

Example using monolog:

To add logging within your handlers:

Retry

If your handler fails, it can be retried automatically: implement RetryableHandlerInterface and add RetryTrait. Override maxRetry() to control the number of retry attempts (default is 25), and canRetry($message, $exception) to skip retries for permanent errors.

Note: Retry functionality requires a driver that supports delayed execution (the $executeAt message parameter).

Priorities

You can configure multiple queues with different priority levels to ensure high-priority messages are processed first.

Example with Redis driver:

Key points about priorities:

• Priority is the second argument of Emitter::emit(). The third argument of Message is the message id, not a priority
• Use Dispatcher::DEFAULT_PRIORITY (100) or any integer you registered with setupPriorityQueue()
• Higher numbers indicate higher priority
• You can pass a list of priorities to Dispatcher::handle(), for example handle([Dispatcher::DEFAULT_PRIORITY + 10]), to create workers that process only those queues

Graceful Shutdown

Hermes workers can be gracefully stopped without losing messages.

When you provide an implementation of Tomaj\Hermes\Shutdown\ShutdownInterface to the Dispatcher, Hermes checks ShutdownInterface::shouldShutdown() after each message. If it returns true, the worker shuts down cleanly.

Important: Hermes handles shutdown, but automatic restart must be managed by your process controller (e.g., supervisord, systemd, or Docker).

Two shutdown implementations are available:

SharedFileShutdown

Trigger shutdown by creating or touching a specific file:

RedisShutdown

Trigger shutdown by setting a Redis key:

Scaling Hermes

Hermes can easily scale to handle high message volumes. Simply run multiple worker instances—either on the same machine or distributed across multiple servers.

Requirements for scaling:

1. Network-capable driver: Your driver must support remote connections (Redis, RabbitMQ, and Amazon SQS all support this)
2. At-most-once delivery: Each message should be delivered to only one worker

Both Redis and RabbitMQ drivers satisfy these requirements and are designed for high-throughput scenarios.

Extending Hermes

Hermes uses interface-based architecture, making it easy to extend. You can create custom drivers, use different loggers, or implement your own message serialization.

Creating a Custom Driver

Each driver must implement Tomaj\Hermes\Driver\DriverInterface with two methods: send() and wait().

Here's an example driver using Gearman:

Creating a Custom Serializer

To use custom serialization, create a class that implements Tomaj\Hermes\SerializerInterface. Add the Tomaj\Hermes\Driver\SerializerAwareTrait to your driver to enable the setSerializer() method.

Example using jms/serializer:

Scheduled Execution

Since version 2.0, you can schedule messages for future execution by passing a timestamp as the fourth parameter to the Message constructor. Currently supported by RedisSetDriver and PredisSetDriver.

Upgrade Guide

From v5 to v6

See UPGRADE-6.0.md.

From v3 to v4

Breaking Changes:

• Renamed Restart → Shutdown to better reflect functionality. Hermes can gracefully stop its own process, but restarting must be handled by an external process manager.
  • RestartInterface → ShutdownInterface
  • All implementation classes and namespaces have been updated accordingly

Changelog

See CHANGELOG for a detailed list of changes and version history.

Testing

Code Coverage

To generate code coverage reports:

The coverage reports will be generated in:

• HTML report: build/coverage/index.html (open in browser to see line-by-line coverage)
• Clover XML: build/logs/clover.xml (for CI/CD integration)

Online Coverage Reports: Coverage reports are published with the documentation site after each successful test run on master, at https://tomaj.github.io/hermes/coverage/.

Documentation

• Documentation
• Getting started
• Concepts
• Drivers
• API reference
• Changelog
• Coverage report

Contributing

Please see Code of Conduct for details.

Security

Please report vulnerabilities privately. See SECURITY.md for supported versions and how to disclose an issue.

License

The MIT License (MIT). Please see License File for more information.