README

Resque是一个基于Redis的后端库，用于创建后台任务，将这些任务放入一个或多个队列中，并在稍后处理。

背景

Resque是由GitHub（是的，我是一个马屁精）的出色人员开创和开发的，并使用Ruby编写。你在这里看到的是Resque工作器和入队系统直接移植到PHP的几乎直接版本。

有关Resque的更多信息，请访问官方GitHub项目：https://github.com/resque/resque

有关更多信息，请参阅GitHub博客上的启动帖子：http://github.com/blog/542-introducing-resque

PHP端口不包括自己的Web界面来查看队列状态，因为数据存储的格式与Resque的Ruby版本完全相同。

PHP端口提供了与Ruby版本几乎相同的特性

• 工作器可以在多台机器之间分布式
• 包括对优先级（队列）的支持
• 对内存泄露具有弹性（分叉）
• 预期会失败

它还支持以下附加功能

• 能够跟踪作业的状态
• 如果一个分叉子进程在运行作业时没有以状态码0退出，则将其标记为失败
• 内置了对setUp和tearDown方法的支持，这些方法分别在作业前后调用

要求

• PHP 5.3+
• Redis 2.2+
• 可选但推荐：Composer

入门

使用php-resque的最简单方法是将其作为您的项目中的Composer包安装。Composer不是必需的，但它会使生活变得更加容易。

如果您不熟悉Composer，请参阅https://getcomposer.org.cn/。

1. 将php-resque添加到您的应用程序的composer.json文件中。

{
    // ...
    "require": {
        "chrisboulton/php-resque": "1.2.x"	// Most recent tagged version
    },
    // ...
}

1. 运行composer install。

2. 如果您还没有这样做，请将Composer自动加载添加到您的项目初始化文件中。（示例）

require 'vendor/autoload.php';

作业

队列作业

作业如下排队

// Required if redis is located elsewhere
Resque::setBackend('localhost:6379');

$args = array(
        'name' => 'Chris'
        );
Resque::enqueue('default', 'My_Job', $args);

定义作业

每个作业应该在其自己的类中，并包含一个perform方法。

class My_Job
{
    public function perform()
    {
        // Work work work
        echo $this->args['name'];
    }
}

当作业运行时，类将被实例化，任何参数都将作为数组设置在实例化的对象上，并通过$this->args访问。

作业抛出的任何异常都会导致作业失败 - 这里要小心，确保处理那些不会导致作业失败的异常。

作业还可以有 setUp 和 tearDown 方法。如果定义了 setUp 方法，它将在 perform 方法运行之前被调用。如果定义了 tearDown 方法，它将在作业完成后被调用。

class My_Job
{
    public function setUp()
    {
        // ... Set up environment for this job
    }

    public function perform()
    {
        // .. Run job
    }

    public function tearDown()
    {
        // ... Remove environment for this job
    }
}

出队作业

此方法可以方便地从队列中删除作业。

// Removes job class 'My_Job' of queue 'default'
Resque::dequeue('default', ['My_Job']);

// Removes job class 'My_Job' with Job ID '087df5819a790ac666c9608e2234b21e' of queue 'default'
Resuque::dequeue('default', ['My_Job' => '087df5819a790ac666c9608e2234b21e']);

// Removes job class 'My_Job' with arguments of queue 'default'
Resque::dequeue('default', ['My_Job' => array('foo' => 1, 'bar' => 2)]);

// Removes multiple jobs
Resque::dequeue('default', ['My_Job', 'My_Job2']);

如果没有提供作业，此方法将出队所有与提供的队列匹配的作业。

// Removes all jobs of queue 'default'
Resque::dequeue('default');

跟踪作业状态

php-resque 能够执行队列作业的基本状态跟踪。状态信息将允许您检查作业是否在队列中，是否正在运行，是否已完成或已失败。

要跟踪作业状态，将 true 作为 Resque::enqueue 的第四个参数传递。将返回用于跟踪作业状态的令牌。

$token = Resque::enqueue('default', 'My_Job', $args, true);
echo $token;

要获取作业的状态

$status = new Resque_Job_Status($token);
echo $status->get(); // Outputs the status

作业状态定义为 Resque_Job_Status 类中的常量。有效的状态包括

• Resque_Job_Status::STATUS_WAITING - 作业仍在队列中
• Resque_Job_Status::STATUS_RUNNING - 作业正在运行
• Resque_Job_Status::STATUS_FAILED - 作业已失败
• Resque_Job_Status::STATUS_COMPLETE - 作业已完成
• false - 获取状态失败 - 令牌有效吗？

状态在作业完成或失败后最多可保留24小时，然后自动过期。也可以通过在状态类上调用 stop() 方法强制状态过期。

工作进程

工作进程的工作方式与 Ruby 工作进程完全相同。有关工作进程的完整文档，请参阅原始文档。

包含一个基本的“启动并运行”的 bin/resque 文件，该文件设置了一个运行工作进程的环境。（通过 Composer 安装时为 vendor/bin/resque）

与 Ruby 版本的 resque 相似的一个例外是工作进程的初始设置。为了在所有环境中工作（不像 Ruby 那样只有一个环境），PHP 端口 不 做任何假设。

要启动工作进程，它与 Ruby 版本非常相似

$ QUEUE=file_serve php bin/resque

您的责任是告诉工作进程要包含哪个文件以启动应用程序。您通过设置 APP_INCLUDE 环境变量来做到这一点。

$ QUEUE=file_serve APP_INCLUDE=../application/init.php php bin/resque

提示：使用 Composer？很可能是您不需要担心 APP_INCLUDE，因为希望 Composer 也负责自动加载您的应用程序！

启动应用程序还包括通过自动加载器或包含它们来告诉工作进程您的作业类。

或者，您始终可以从应用程序中 include('bin/resque') 并完全跳过设置 APP_INCLUDE。只是确保在这样做之前设置各种环境变量（setenv）。

日志记录

端口支持用于将日志记录到 STDOUT 的相同环境变量。设置 VERBOSE 将打印基本的调试信息，而 VVERBOSE 将打印详细信息。

$ VERBOSE=1 QUEUE=file_serve bin/resque
$ VVERBOSE=1 QUEUE=file_serve bin/resque

优先级和队列列表

同样，优先级和队列列表功能与 Ruby 工作进程完全相同。多个队列应以逗号分隔，并且它们提供的顺序是它们被检查的顺序。

根据原始示例

$ QUEUE=file_serve,warm_cache bin/resque

file_serve 队列将在每次迭代中始终被检查是否有新的工作，然后再检查 warm_cache 队列。

运行所有队列

所有队列以相同的方式支持，并按字母顺序处理。

$ QUEUE='*' bin/resque

运行多个工作进程

可以通过提供 COUNT 环境变量同时启动多个工作进程。

$ COUNT=5 bin/resque

然而，请注意，每个工作进程都是一个独立的进程，并且原始进程将在创建了 COUNT 个进程分支后立即关闭。如果您需要使用 monit 等外部应用程序跟踪工作进程，则需要解决这个问题。

自定义前缀

当您有多个应用程序使用相同的 Redis 数据库时，最好使用自定义前缀来区分 Resque 数据。

$ PREFIX=my-app-name bin/resque

分支

与 Ruby 版本类似，支持的平台在拾取工作后会立即分支。分支的子进程将在工作完成时退出。

与 php-resque 的不同之处在于，如果分支的子进程没有优雅地退出（PHP 错误等），php-resque 将自动失败该工作。

信号

信号在支持的平台上工作，与 Ruby 版本的 Resque 完全一样。

• QUIT - 等待工作完成处理然后退出
• TERM / INT - 立即终止工作然后退出
• USR1 - 立即终止工作但不退出
• USR2 - 暂停工作进程，不处理新工作
• CONT - 恢复工作进程。

进程标题/状态

Resque 的 Ruby 版本有一个巧妙的功能，即更新工作进程的进程标题以指示工作进程正在做什么，任何分支的子进程也会设置其进程标题以运行工作。这有助于识别服务器上正在运行的过程及其 Resque 状态。

PHP 默认情况下没有这个功能，直到 5.5。

存在一个 PECL 模块（http://pecl.php.net/package/proctitle），在 5.5 之前将此功能添加到 PHP 中，因此如果您想更新进程标题，也需要安装此 PECL 模块。php-resque 将自动检测并使用它。

事件/钩子系统

php-resque 有一个基本的事件系统，可以由您的应用程序使用来自定义一些 php-resque 内部行为。

您可以通过向 Resque_Event 注册并提供一个回调来监听事件（如下所示）。

Resque_Event::listen('eventName', [callback]);

[回调] 可以是 PHP 中任何可以通过 call_user_func_array 调用的内容。

• 一个包含函数名称的字符串
• 包含要调用对象和方法的数组
• 包含要调用对象和静态方法的数组
• 闭包（PHP 5.3+）

事件可以传递参数（如下所示），因此您的回调应接受这些参数。

您可以通过调用 Resque_Event::stopListening 并提供与 Resque_Event::listen 提供的相同参数来停止监听事件。

注册事件监听器是您应用程序的责任。当在您的应用程序中排队事件时，应该像确保php-resque已加载并调用Resque_Event::listen一样简单。

当运行工作进程时，如果您通过默认的bin/resque脚本来运行工作进程，则您的APP_INCLUDE脚本应初始化并注册操作所需的任何监听器。如果您自己开发了工作进程管理器，那么注册监听器也是您的责任。

示例插件包含在extras目录中。

事件

beforeFirstFork

在工作进程初始化时调用一次。传递的参数是刚刚初始化的Resque_Worker实例。

beforeFork

在php-resque进行作业前调用。传递的参数包含即将运行的作业的Resque_Job实例。

beforeFork在父进程中触发。所做的任何更改将对工作进程的生命周期保持永久。

afterFork

在php-resque进行作业分叉后调用（但在运行作业之前）。传递的参数包含即将运行的作业的Resque_Job实例。

afterFork在分叉出去完成作业的子进程后触发。所做的任何更改将只存在于作业处理期间。

beforePerform

在运行作业的setUp和perform方法之前调用。传递的参数包含即将运行的作业的Resque_Job实例。

您可以通过抛出Resque_Job_DontPerform异常来防止作业的执行。抛出的任何其他异常都将被视为在作业中抛出，导致作业失败。

afterPerform

在运行作业的perform和tearDown方法之后调用。传递的参数包含刚刚运行的作业的Resque_Job实例。

抛出的任何异常都将被视为在作业中抛出，导致作业被标记为失败。

onFailure

每当作业失败时调用。传递的参数（按此顺序）包括：

• 异常 - 作业失败时抛出的异常
• Resque_Job - 失败的作业

beforeEnqueue

在通过Resque::enqueue方法将作业入队之前立即调用。传递的参数（按此顺序）包括：

• 类 - 包含要入队的作业名称的字符串
• 参数 - 作业的参数数组
• 队列 - 包含作业将入队的队列名称的字符串
• ID - 包含要入队作业令牌的字符串

您可以通过抛出Resque_Job_DontCreate异常来防止作业的入队。

afterEnqueue

在通过Resque::enqueue方法将作业排队之后调用。传递的参数（按此顺序）包括：

• 类 - 包含计划作业名称的字符串
• 参数 - 传递给作业的参数数组
• 队列 - 包含已添加作业的队列名称的字符串
• ID - 包含已入队作业的新令牌的字符串

逐步操作

要深入了解php-resque在内部是如何工作的（无需直接查看代码），请参阅HOWITWORKS.md。

贡献者

项目负责人

• @chrisboulton

其他人

• @acinader
• @ajbonner
• @andrewjshults
• @atorres757
• @benjisg
• @cballou
• @chaitanyakuber
• @charly22
• @CyrilMazur
• @d11wtq
• @danhunsaker
• @dceballos
• @ebernhardson
• @hlegius
• @hobodave
• @humancopy
• @iskandar
• @JesseObrien
• @jjfrey
• @jmathai
• @joshhawthorne
• @KevBurnsJr
• @lboynton
• @maetl
• @matteosister
• @MattHeath
• @mickhrmweb
• @Olden
• @patrickbajao
• @pedroarnal
• @ptrofimov
• @rajibahmed
• @richardkmiller
• @Rockstar04
• @ruudk
• @salimane
• @scragg0x
• @scraton
• @thedotedge
• @tonypiper
• @trimbletodd
• @warezthebeef