README

php-resque（发音为“rescue”）是一个基于 Redis 的库，用于创建后台任务，将这些任务放入多个队列，并在稍后处理它们。

内容

• 背景
• 要求
• 入门
• 任务
  • 定义任务
  • 排队任务
  • 延迟任务
  • 任务状态
• 工作者
  • 信号
  • 分叉
  • 进程标题
  • 自动加载任务类
• 命令与选项
• 日志记录
• 事件/钩子系统
• 配置选项
• Redis
• 贡献者

背景

这个版本的 php-resque 是基于最初由 chrisboulton 完成的作品，他移植了由 GitHub 创建的同名 ruby 版本。

重写先前工作的原因是为了提供更好的对工作者服务器水平扩展的支持，并提高任务故障容忍度，以创建一个非常高可用性的系统。与 Monolog 的集成意味着可以实现非常详细的日志记录，这使得解决分布式系统中的错误变得容易得多。广泛的事件/钩子系统使得更深层次的集成和统计收集成为可能。

此版本提供以下功能：

• 工作者可以分布在多台机器之间。
• 对内存泄漏具有弹性（任务在分叉进程中运行）。
• 预期并记录失败。
• 日志使用 Monolog。
• 可以将闭包推送到队列中。
• 跟踪任务状态和输出。
• 如果超出内存或最大执行时间，任务将干净地失败。
• 如果运行任务的分叉子进程不以状态码 0 退出，则将任务标记为失败。
• 具有内置的事件系统，以便启用钩子进行深层集成。
• 支持优先级（队列）。

这个版本不是 GitHub 的 Resque 的直接移植，因此与它不兼容，也不与它们的 Web 界面兼容。 此版本的 Web 界面目前正在开发中，如果您想了解更多或提供帮助，请与我联系。

要求

您必须安装以下内容才能运行 php-resque

• Redis
• PHP 5.3+
• PCNTL PHP 扩展
• Composer

可选，但推荐

• Phpiredis 1.0+
• proctitle PECL 包

入门

使用 php-resque 的最简单方法是将其作为 Composer 包 安装到您的项目中。虽然 Composer (https://getcomposer.org.cn/) 不是必需的，但它会使事情变得容易得多。

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

{
    "require": {
        "francislavoie/php-resque": "1.3.x"
    }
}

转到您的项目根目录并运行

$ php composer.phar install

如果您尚未添加，请将 Composer 自动加载器添加到项目引导中

require 'vendor/autoload.php';

工作

定义工作

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

class MyJob {

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

	public function perform($args) {
        // Perform some job
    }

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

}

当运行工作的时候，类将被实例化，任何参数都将作为参数传递给 perform 方法。

工作抛出的任何异常都将导致工作失败 - 这里要小心，确保处理那些不应该导致工作失败异常。如果你想取消一个工作（而不是让它失败），则可以抛出 Resque\Exception\Cancel 异常，工作将被标记为已取消。

工作也可以有 setUp 和 tearDown 方法。如果定义了 setUp 方法，它将在运行 perform 方法之前被调用。如果定义了 tearDown 方法，它将在工作完成后被调用。如果在 setUp 方法中抛出异常，perform 方法将不会运行。这在有不同工作需要相同的引导程序的情况下很有用，例如数据库连接。

排队工作

要向队列中添加一个新工作，请使用 Resque::push 方法。

$job = Resque::push('MyJob', array('arg1', 'arg2'));

第一个参数是你工作类的完全解析的类名（如果你想知道 php-resque 如何了解你的工作类，请参阅 自动加载工作类）。第二个参数是要传递给工作类的任何参数的数组。

也可以将闭包推送到队列中。这对于快速、简单的需要排队任务来说非常方便。当将闭包推送到队列中时，不应使用 __DIR__ 和 __FILE__ 常量。

$job = Resque::push(function($job) {
    echo 'This is a inline job #'.$job->getId().'!';
});

也可以通过将队列名称作为第三个参数传递给 Resque::push 方法，将工作推送到另一个队列（默认队列名为 default）。

$job = Resque::push('SendEmail', array(), 'email');

延迟工作

可以使用 Resque::later 方法安排工作在未来的指定时间运行。你可以通过传递一个 int 或一个 DateTime 对象来实现。

$job = Resque::later(60, 'MyJob', array());
$job = Resque::later(1398643990, 'MyJob', array());
$job = Resque::later(new \DateTime('+2 mins'), 'MyJob', array());
$job = Resque::later(new \DateTime('2014-07-08 11:14:15'), 'MyJob', array());

如果你传递一个整数并且它小于 94608000 秒（3年），php-resque 将假设你想要一个相对于当前时间的时间（毕竟，谁会延迟超过3年的工作呢？？）。注意，你必须有一个在工作指定时间运行的工人，以便工作能够运行。

工作状态

php-resque 跟踪工作的状态。状态信息将允许你检查工作是否在队列中、正在运行、失败等。要跟踪工作的状态，你必须捕获推送到队列的工作的 job id。

$job = Resque::push('MyJob');
$jobId = $job->getId();

要获取工作的状态

$job = Resque\Job::load($jobId);
$status = $job->getStatus();

工作状态是在 Resque\Job 类中定义的常量。有效状态如下

• Resque\Job::STATUS_WAITING - 工作仍在队列中
• Resque\Job::STATUS_DELAYED - 工作被延迟
• Resque\Job::STATUS_RUNNING - 工作正在运行
• Resque\Job::STATUS_COMPLETE - 工作已完成
• Resque\Job::STATUS_CANCELLED - 工作已被取消
• Resque\Job::STATUS_FAILED - 工作已失败
• false - 无法获取状态 - id 是否有效？

状态在完成或失败后7天内可用，然后自动过期。此超时时间可以在配置文件中更改。

工作者

要启动工作者，请导航到您的项目根目录并运行

$ bin/resque worker:start

请注意，一旦这个工作者启动，它将继续运行，直到手动停止。您可以使用进程监控工具，如 Supervisor 将工作者作为后台进程运行，并确保工作者不会停止运行。

如果工作者是后台任务，您可以使用以下命令停止、暂停和重启工作者

$ bin/resque worker:stop
$ bin/resque worker:pause
$ bin/resque worker:resume

这些命令接受内联配置选项，同时也会从 配置文件 中读取。

例如，要指定工作者只处理名为 high 和 low 的队列中的作业，并且为作业允许最多 30MB 的内存，您可以运行以下命令

$ bin/resque worker:start --queue=high,low --memory=30 -vvv

请注意，这将首先检查 high 队列，然后是 low 队列，因此可以使用此方法来方便地使用作业队列优先级。要运行所有队列，请使用 * - 这是默认值。使用 -vvv 启用非常详细的日志记录。要禁用所有日志记录，请使用 -q 标志。

有关更多命令和完整选项列表，请参阅 命令文档。

信号

信号在受支持的平台上工作。发送给工作者的信号将产生以下效果

• QUIT - 等待子进程完成处理然后退出
• TERM / INT - 立即杀死子进程然后退出
• USR1 - 立即杀死子进程但不退出
• USR2 - 暂停工作者，不会处理新的作业
• CONT - 继续工作者

分叉

当 php-resque 运行作业时，它首先将进程分叉到子进程中。这样做是为了如果作业失败，工作者可以检测到作业失败并继续运行。分叉的子进程将在作业完成后立即退出。

必须安装 PECL 模块 (https://php.ac.cn/manual/en/book.pcntl.php) 才能使用 php-resque。

进程标题

更新工作者的进程标题很有用，因为它可以指示工作者正在做什么，任何分叉的子进程也会使用正在运行的作业来设置其进程标题。这有助于识别服务器上运行的进程及其 php-resque 状态。

不幸的是，PHP 默认没有安装能够更新进程标题的功能。

存在一个 PECL 模块 (http://pecl.php.net/package/proctitle)，它向 PHP 添加了此功能，因此如果您想更新进程标题，还需要安装此 PECL 模块。php-resque 将检测并使用它。

自动加载作业类

让您的应用程序开始运行还需要告诉工作者您的作业类，通过自动加载器或包含它们来实现。如果您使用的是 Composer，那么在那里添加您的作业类将会相对简单。

或者您可以在 config.yml 文件中这样做，或者通过设置 include 参数

$ bin/resque worker:start --include=/path/to/your/include/file.php

本项目 examples/ 文件夹中有一个如何实现此功能的示例。

命令 & 选项

有关 php-resque 命令及其相关参数的完整列表，请参阅 命令文档。

日志记录

php-resque 与 Monolog 集成，提供了强大的日志记录功能。有关完整文档，请参阅日志记录文档。

事件/钩子系统

php-resque 拥有一个广泛的事件/钩子系统，允许开发者无需修改任何核心文件即可深度集成库。有关完整文档和事件列表，请参阅钩子文档。

配置选项

有关所有配置选项的完整列表，请参阅配置文档。

Redis

您可以在行内或配置文件中设置 Redis 连接详情。在运行命令时设置

$ bin/resque [command] --host=<hostname> --port=<port>

贡献者

为该项目做出贡献将极大地帮助维护和扩展脚本。如果您有兴趣贡献，请在 Github 上发起拉取请求。

• mjphaynes
• chrisboulton (原始端口)