PHPackages                             friendsofhyperf/amqp-job - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Queues & Workers](/categories/queues)
4. /
5. friendsofhyperf/amqp-job

ActiveLibrary[Queues & Workers](/categories/queues)

friendsofhyperf/amqp-job
========================

The amqp job for Hyperf.

v3.2.1(3w ago)28.0k↓59.8%1MITPHP

Since Jul 28Pushed 3w ago2 watchersCompare

[ Source](https://github.com/friendsofhyperf/amqp-job)[ Packagist](https://packagist.org/packages/friendsofhyperf/amqp-job)[ Fund](https://hdj.me/sponsors/)[ GitHub Sponsors](https://github.com/huangdijia)[ RSS](/packages/friendsofhyperf-amqp-job/feed)WikiDiscussions main Synced 2d ago

READMEChangelog (10)Dependencies (20)Versions (38)Used By (0)

Amqp Job
========

[](#amqp-job)

[中文说明](README_CN.md)

Introduction
------------

[](#introduction)

`friendsofhyperf/amqp-job` dispatches PHP job objects through `hyperf/amqp`. A job declares its AMQP binding with the `AmqpJob` attribute, and the component automatically registers a consumer for each enabled attributed job when the server starts.

The component uses PHP serialization by default, so only dispatch trusted job objects and keep their classes available to consumers.

Installation
------------

[](#installation)

```
composer require friendsofhyperf/amqp-job
```

The package's `ConfigProvider` is discovered by Hyperf. It registers the consumer listener and binds the retry-attempt store to Redis and the message packer to `PhpSerializerPacker`. Configure `hyperf/amqp` and its selected AMQP pool before dispatching jobs. Setting `amqp.enable` to `false` skips all automatic job-consumer registration.

Define And Dispatch A Job
-------------------------

[](#define-and-dispatch-a-job)

```
use FriendsOfHyperf\AmqpJob\Annotation\AmqpJob;
use FriendsOfHyperf\AmqpJob\Job;
use FriendsOfHyperf\AmqpJob\JobMessage;
use Hyperf\Amqp\Result;
use Hyperf\Amqp\Producer;

#[AmqpJob(
    exchange: 'hyperf.exchange',
    routingKey: 'hyperf.routing.key',
    pool: 'default',
    queue: 'hyperf.queue',
    maxAttempts: 3,
    confirm: true,
    nums: 2,
)]
class FooJob extends Job
{
    public function __construct(private readonly int $id)
    {
    }

    public function handle(): Result
    {
        // Process $this->id.
        return Result::ACK;
    }
}

function dispatchFoo(Producer $producer, int $id): bool
{
    $message = (new JobMessage(new FooJob($id)))
        ->setExchange('hyperf.exchange')
        ->setRoutingKey('hyperf.routing.key')
        ->setPoolName('default');

    return $producer->produce($message, confirm: true, timeout: 5);
}
```

`dispatch(JobInterface $payload, ?bool $confirm = null, ?int $timeout = null): bool`is a convenience function that creates and publishes a `JobMessage`. It assigns a unique job ID when the job does not already have one. The optional `confirm` and `timeout`arguments override the job's values for that dispatch.

Currently, `dispatch()` does not copy the job's exchange, routing key, or pool into the `JobMessage`. The resulting producer message therefore uses an empty exchange, an empty routing key, and Hyperf's `default` AMQP pool. To publish to the binding declared by `AmqpJob`, create a `JobMessage`, set its destination as shown above, and pass it to `Hyperf\Amqp\Producer`.

Attribute Options
-----------------

[](#attribute-options)

OptionTypeDefaultBehavior`exchange``string`requiredExchange used by the automatic consumer and returned by `Job::getExchange()`.`routingKey``string`requiredRouting key used by the automatic consumer and returned by `Job::getRoutingKey()`.`pool``?string``null`Automatic consumer pool and value returned by `Job::getPoolName()`.`queue``?string``null`Consumer queue; left unset when omitted.`maxAttempts``int``0`Maximum failed handling attempts; `0` disables retries.`maxConsumption``int``0`Maximum messages consumed before the consumer exits.`confirm``bool``false`Value returned by `Job::getConfirm()` and used by `dispatch()`.`enable``bool``true`Controls automatic consumer registration.`nums``int``1`Number of consumer processes.`name``?string``null`Consumer process name.If a job does not use the attribute, its getters fall back to exchange `hyperf`, routing key `hyperf.job`, no explicit pool, publisher confirmation disabled, a publish timeout of 5 seconds, and no retries. A subclass may provide protected properties such as `$exchange`, `$routingKey`, `$poolName`, `$confirm`, `$timeout`, or `$maxAttempts` to override those getter values. As noted above, `dispatch()` only consumes the confirm and timeout getters.

Consumption And Retries
-----------------------

[](#consumption-and-retries)

`JobConsumer` acknowledges a job when `handle()` returns nothing or an unrecognized string. Returning a `Hyperf\Amqp\Result` or its string value controls the result directly.

When `handle()` throws, the consumer logs the exception when a compatible logger is available. With `maxAttempts > 0`, the Redis-backed attempt counter requeues the job until the configured total attempt count is reached. It then calls `fail(Throwable $e)` and drops the message. The default `fail()` method does nothing and can be overridden:

```
use Throwable;

public function fail(Throwable $e): void
{
    // Report or persist the terminal failure.
}
```

The default Redis attempt keys use the `hyperf:amqp-job:attempts:` prefix and expire after 86,400 seconds. Redis is therefore required when retries are enabled. Bind `FriendsOfHyperf\AmqpJob\Contract\Attempt` or `FriendsOfHyperf\AmqpJob\Contract\Packer` to replace the default implementations. For exception logging, the consumer first resolves `FriendsOfHyperf\AmqpJob\Contract\LoggerInterface`, then `Hyperf\Contract\StdoutLoggerInterface`; logging is skipped when neither is available.

Register A Custom Consumer
--------------------------

[](#register-a-custom-consumer)

Automatic consumers are normally sufficient. To consume compatible serialized jobs with a manually declared consumer, extend `JobConsumer` and use Hyperf's `Consumer` attribute:

```
namespace App\Amqp\Consumer;

use FriendsOfHyperf\AmqpJob\JobConsumer;
use Hyperf\Amqp\Annotation\Consumer;

#[Consumer(
    exchange: 'hyperf.exchange',
    routingKey: 'hyperf.routing.key',
    queue: 'hyperf.queue',
    name: 'MyConsumer',
    nums: 4,
)]
class MyConsumer extends JobConsumer
{
}
```

###  Health Score

51

—

FairBetter than 95% of packages

Maintenance95

Actively maintained with recent releases

Popularity28

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 93.8% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~29 days

Recently: every ~48 days

Total

37

Last Release

24d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/8337659?v=4)[Deeka Wong](/maintainers/huangdijia)[@huangdijia](https://github.com/huangdijia)

---

Top Contributors

[![huangdijia](https://avatars.githubusercontent.com/u/8337659?v=4)](https://github.com/huangdijia "huangdijia (45 commits)")[![xuanyanwow](https://avatars.githubusercontent.com/u/28777109?v=4)](https://github.com/xuanyanwow "xuanyanwow (3 commits)")

---

Tags

hyperfv3.2

### Embed Badge

![Health badge](/badges/friendsofhyperf-amqp-job/health.svg)

```
[![Health](https://phpackages.com/badges/friendsofhyperf-amqp-job/health.svg)](https://phpackages.com/packages/friendsofhyperf-amqp-job)
```

###  Alternatives

[hyperf/amqp

A amqplib for hyperf.

231.3M72](/packages/hyperf-amqp)[hyperf/database

A flexible database library.

192.9M322](/packages/hyperf-database)[hyperf/http-server

A HTTP Server for Hyperf.

103.0M372](/packages/hyperf-http-server)[hyperf/validation

hyperf validation

122.2M199](/packages/hyperf-validation)[friendsofhyperf/sentry

The sentry component for Hyperf.

1974.5k](/packages/friendsofhyperf-sentry)[hyperf/socketio-server

Socket.io implementation for hyperf

26140.9k7](/packages/hyperf-socketio-server)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)