Download the PHP package hirale/queue without Composer

Hirale Queue

A queue module for OpenMage and Maho, built on Symfony Messenger. Backend-agnostic by design: Redis Streams ships in v3.0, with Doctrine / AMQP / SQS as drop-in transports later.

Which version do I need?

One codebase serves both platforms: the module uses OpenMage-era class names that Maho aliases natively, and the only platform difference you will notice is the worker entry point (Maho CLI vs shell/ scripts).

v3 was previously published as hirale/openmage-redis-queue; the rename to hirale/queue reflects the rewrite. Upgrading a v1 install is a breaking change — see Migrating from v1.x below.

What's new in v3

• Symfony Messenger as the bus. v2's custom Worker / Backoff / DeadLetter / HandlerRegistry / QueueRouter are gone. v3 plugs into Messenger's middleware pipeline, retry strategy interface, and transport abstraction.
• Backend-agnostic. Admin picks Redis / Doctrine / AMQP / SQS from a dropdown; the module assembles the DSN. v3.0 ships Redis; the other transports are wired in v3.x as composer require symfony/<backend>-messenger adds the needed factory.
• Dual-platform. One codebase for OpenMage 20.17+ and Maho 26.5+ (PHP 8.3+); composer conflicts reject older platforms with a clear error.

• Producer API is typed. Downstream code dispatches typed message classes:

  Handlers implement __invoke(MessageClass $message): void.

• Per-store retry policy. Captured at dispatch from the dispatching store's config and travels with the envelope so a worker serving many stores doesn't have to look up live config per message.
• Save-time validation. Saving a bad backend config refuses to persist — connection is probed in the admin form's predispatch event and a clear error banner appears.

Requirements

• Maho 26.5+ or OpenMage 20.17+
• PHP 8.3+
• ext-json, ext-redis (for the Redis backend)
• A Redis server reachable from the workers (TCP or Unix socket)

Install

OpenMage: one-time composer adjustments

Two stock-OpenMage facts need one-time tweaks. The pinned magento-hackathon/magento-composer-installer cannot serve a project that uses Symfony Messenger: its 3.x/4.x releases require symfony/console ≤5 (Messenger 7/8 conflicts with console <7.2), and its only console-free release (1.3.2) is a Composer 1 plugin that deploys while Composer 2 is still extracting archives, aborting every dist install. OpenMage also locks dependency resolution to PHP 8.1 via config.platform, which would reject this package's PHP 8.3 floor.

In your project root:

hirale/magento-module-installer is a zero-dependency Composer 2 plugin that deploys extra.map and modman modules after extraction completes. It replaces the legacy installer, so the stock root requirement keeps resolving — nothing to remove — and existing modman-based packages (openmage_ignition, the Cm redis modules, …) keep deploying. It copies this module into app/, including the five shell/hirale_queue_*.php entry points; composer magento-module-deploy re-deploys everything idempotently.

Create the four queue tables (hirale_queue_job, hirale_queue_job_event, hirale_queue_job_archive, hirale_queue_audit):

• Maho: ./maho migrate
• OpenMage: setup scripts run on the next request, as usual

Configure

Open System → Configuration → Hirale → Queue in admin.

Backend connection is global (infrastructure does not vary by store). Operational and retention values can be overridden per-website using the native admin scope selector.

When you click Save Config, the module assembles the DSN and tries to connect to the backend. If the probe fails, the form refuses to persist and shows the error — your previous values stay intact.

Producer API

Downstream modules dispatch typed messages:

Variants:

The current store context is captured automatically. Don't pass store_id in the message — Bus attaches a StoreScopeStamp for you, and the per-store retry policy is read at dispatch time.

Handler registration

In your downstream module's etc/config.xml, under <global>:

The element name is the MessageClass FQCN (use underscored class names — XML element names cannot contain backslashes, so PSR-4 namespaced messages are not supported on the routing side; declare them as legacy Vendor_Module_* classes).

Handler:

Unmapped messages route to the default queue.

Consumer

Long-running worker — Maho:

OpenMage (same engine, shell entry point):

With options (Maho shown; the shell worker takes the same options as --queues a,b --time-limit ... --limit ... --sleep ... --memory-limit ...):

Run under systemd or Supervisor so the process restarts after --time-limit or --limit.

systemd example

Cron / Ofelia example

Without systemd, run the worker from cron with flock (or Ofelia's no-overlap) guaranteeing a single instance; the worker exits after --time-limit and is relaunched on the next tick:

Maho's own cron (./maho cron:run default / always) must also be scheduled — it runs the nightly hirale_queue_archive job (archive move + retention purges, including the event and audit tables).

CLI commands

Admin operations

System → Tools → Hirale Queue shows:

• Status tiles per state (queued, running, retry_wait, succeeded, failed, canceled).
• A grid of recent jobs with job_id, message class, queue, status, attempt counters, last error excerpt, timestamps.
• Page-level buttons: Test Connection (probes the backend), Purge Finished (applies retention to the archive).
• Per-row actions: View, Retry (reconstructs the message and re-dispatches as a new job; a failed source row is marked superseded), Cancel (cooperative for running jobs; immediate for queued / retry_wait).
• Clicking a row opens the job detail page: full field list, the payload pretty-printed with configured fields redacted, metadata, and the complete state-transition timeline from hirale_queue_job_event.

A Test Connection button also sits below the backend fields in System → Configuration → Hirale → Queue — it probes the values currently entered in the form, before saving.

All admin actions are recorded in hirale_queue_audit when audit logging is enabled; audit rows are purged by the nightly cron after audit_retention_days (default 90).

Migrating from v1.x

v3 intentionally breaks API compatibility with the v1 line (hirale/openmage-redis-queue ^1.0):

• v1.x producer: Mage::getModel('hirale_queue/task')->addTask($handler, $data, ...)
• v3 producer: \Hirale\Queue\Bus::dispatch(new YourMessage(...))

The handler interface, payload format, DB schema, and config paths all changed. Upgrading an existing OpenMage install:

1. Apply the one-time composer adjustments from Install → OpenMage, then composer remove hirale/openmage-redis-queue && composer require hirale/queue
2. Setup scripts create the v3 tables automatically (v1 tables are left untouched; drop them once you no longer need the history).
3. Reconfigure the backend once under System → Configuration → Hirale → Queue (config paths changed; save-time validation checks the connection).
4. Migrate every producer and handler to typed messages and __invoke handlers (see Producer API and Handler registration above), or update the consuming modules to their v3-compatible releases.
5. Run the self-test: php shell/hirale_queue_test.php.

Development

The unit suite covers DSN assembly per backend, message routing (SendersLocator), retry strategy semantics (including the unrecoverable/recoverable exception markers), message reconstruction, and stamp construction. For a live end-to-end check against a real install, use ./maho hirale:queue:test.

License

Open Software License v. 3.0 (OSL-3.0). See LICENSE.md.