README

PHP 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-resque-scheduler，它是resque-scheduler的PHP端口，为Resque添加了对未来安排项目的支持。它已被设计为与Ruby插件几乎完全相同

目前，php-resque-scheduler仅支持延迟作业，这是将作业推送到队列并在特定时间戳或秒数后运行的能力。计划在未来的版本中支持周期性作业（类似于CRON）。

此端口最初由Chris Boulton创建，并由社区维护。有关更多历史信息，请参阅https://github.com/chrisboulton/php-resque。

需求

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

入门指南

当php-resque作为您项目中的Composer包安装时，与php-resque一起工作最容易。Composer不是强制性的，但会使生活变得更加简单。

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

运行composer require resque/php-resque。
如果您还没有，请将Composer自动加载添加到项目初始化文件中。（示例）

require 'vendor/autoload.php';

作业

排队作业

作业如下排队

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

$args = array(
          'name' => 'Chris'
        );
Resque\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\Resque::dequeue('default', ['My_Job']);

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

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

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

如果没有提供任务，此方法将移除所有匹配提供的队列的任务。

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

跟踪任务状态

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

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

$token = Resque\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() 方法强制状态过期。

获取任务 PID

您可以通过 Resque\Job\PID 获取实际执行工作的进程的 PID。在分叉操作系统中，这将是分叉进程的 PID。

注意：在非分叉操作系统中，返回的 PID 将是工作进程自身的 PID。

echo Resque\Job\PID::get($token);

如果 perform 尚未开始，或者已经结束，函数返回 0。

延迟任务

以下引用 Ruby resque-scheduler 的文档

延迟任务是您希望在未来的某个时间点放入队列的单次任务。经典示例是发送电子邮件

require 'Resque.php';
require 'Scheduler.php';

$in = 3600;
$args = array('id' => $user->id);
Resque\Scheduler::enqueueIn($in, 'email', 'SendFollowUpEmail', $args);

以上代码将任务存储在延迟队列中 1 小时，然后一旦有可用的工人，立即从队列中取出并提交到 Resque 的 email 队列进行处理。

您也可以将时间戳作为 DateTime 对象或包含 UNIX 时间戳的整数传递给 enqueueAt 方法，而不是传递以秒为单位的相对时间

require 'Resque.php';
require 'Scheduler.php';

$time = 1332067214;
Resque\Scheduler::enqueueAt($time, 'email', 'SendFollowUpEmail', $args);

$datetime = new DateTime('2012-03-18 13:21:49');
Resque\Scheduler::enqueueAt($datetime, 'email', 'SendFollowUpEmail', $args);

注意：resque-scheduler 不保证任务将在指定的时间触发。在指定的时间，resque-scheduler 将从延迟队列中取出任务并将其推送到 Resque 中的适当队列。您的下一个可用的 Resque 工人将获取任务。为了尽可能快地处理，请保持队列尽可能空。

工人

工人的工作方式与 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

在检查 warm_cache 队列之前，将始终在每个迭代中检查 file_serve 队列以寻找新工作。

运行所有队列

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

$ QUEUE='*' bin/resque

运行多个工作者

可以通过提供 COUNT 环境变量来同时启动多个工作者

$ COUNT=5 bin/resque

然而，请注意，每个工作者都是其自己的进程，并且原始进程将在创建 COUNT 个进程之后立即关闭。如果您需要使用像 monit 这样的外部应用程序来跟踪您的工作者，您将需要解决这个限制。

自定义前缀

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

$ PREFIX=my-app-name bin/resque

设置Redis后端

当Redis数据库位于工作者运行的不同的主机上时，您必须设置 REDIS_BACKEND 环境变量

$ REDIS_BACKEND=my-redis-ip:my-redis-port bin/resque

分支

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

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

信号

在支持的平台上的信号也正好像在Resque的Ruby版本中一样工作

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将自动检测并使用它。

Resque调度器

resque-scheduler需要一个特殊的后台运行的工人。这个工人负责从调度/延迟队列中提取项并将其添加到Resque的队列中。这意味着为了执行延迟或计划的作业，该工人需要正在运行。

包含设置运行工人环境的“基本启动”bin/resque-scheduler 文件（通过composer安装时为 vendor/bin/resque-scheduler）。它接受与php-resque的主要工作者相同的许多环境变量

REDIS_BACKEND - 要连接的Redis服务器
LOGGING - 启用向STDOUT的日志记录
VERBOSE - 启用详细日志记录
VVERBOSE - 启用非常详细的日志记录
INTERVAL - 在检查计划/延迟队列之前休眠这么长时间
APP_INCLUDE - 启动时包含此文件（用于启动您的应用程序）
PIDFILE - 将工作进程的PID写入此文件

使用bin/resque-scheduler启动resque-scheduler工作进程非常简单：$ php bin/resque-scheduler

事件/钩子系统

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\ResqueWorker实例。

beforeFork

在工作进程准备运行作业之前调用。传递的参数包含即将运行的作业的Resque\JobHandler实例。

beforeFork在父进程中触发。所做的任何更改将永久适用于整个工作进程生命周期。

afterFork

在工作进程在运行作业之前（但在运行作业之前）调用。传递的参数包含即将运行的作业的Resque\JobHandler实例。

afterFork在工作进程在为完成作业而进行分叉后的子进程中触发。所做的任何更改只会持续到作业被处理。

beforePerform

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

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

afterPerform

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

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

onFailure

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

异常 - 当作业失败时抛出的异常
Resque\JobHandler - 失败的作业

beforeEnqueue

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

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

您可以通过抛出 Resque\Exceptions\DoNotCreateException 异常来防止作业入队。

afterEnqueue

在调用 Resque\Resque::enqueue 方法将作业入队后调用。按顺序传递的参数包括

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

afterSchedule

在作业被添加到调度后调用。传递的参数包括作业的时间戳、队列、作业的类名和作业的参数。

beforeDelayedEnqueue

在作业从延迟队列中取出并添加到resque队列之前立即调用。传递的参数包括作业的队列、作业的类名和作业的参数。

逐步说明

要深入了解php-resque在底层做了什么（无需直接查看代码），请参阅 HOWITWORKS.md。

贡献者

项目负责人

@chrisboulton

项目负责人

@danhunsaker
@rajibahmed
@steveklabnik

其他人

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

nazmulislam / resque-background-job

维护者

详细信息

README

背景

需求

入门指南

作业

排队作业

定义作业

出队作业

跟踪任务状态

获取任务 PID

延迟任务

工人

日志记录

优先级和队列列表

运行所有队列

运行多个工作者

自定义前缀

设置Redis后端

分支

信号

进程标题/状态

Resque调度器

事件/钩子系统

事件

beforeFirstFork

beforeFork

afterFork

beforePerform

afterPerform

onFailure

beforeEnqueue

afterEnqueue

afterSchedule

beforeDelayedEnqueue

逐步说明

贡献者

项目负责人

项目负责人

其他人