ahfeel / php-resque
基于 Redis 的库,用于创建后台任务并在稍后处理它们。基于 Ruby 的 Resque。
Requires
- php: >=8.0
- ext-pcntl: *
- colinmollenhour/credis: ^1.2
- psr/log: ^1.0 || ^2.0 || ^3.0
Requires (Dev)
- phpunit/phpunit: 3.7.*
Suggests
- ext-proctitle: Allows php-resque to rename the title of UNIX processes to show the status of a worker.
- ext-redis: Native PHP extension for Redis connectivity. Credis will automatically utilize when available.
README
Resque 是一个基于 Redis 的库,用于创建后台任务,将这些任务放入一个或多个队列中,并在稍后处理它们。
背景
Resque 由 GitHub 的优秀团队(是的,我在拍马屁)首创并开发,是用 Ruby 编写的。你在这里看到的是 Resque 工作器和入队系统几乎直接移植到 PHP 的结果。
有关 Resque 的更多信息,请访问官方 GitHub 项目:https://github.com/resque/resque
有关更多信息,请参阅 GitHub 博客上的启动帖子:http://github.com/blog/542-introducing-resque
PHP 版本不包括用于查看队列统计信息的自有网络界面,因为数据以与 Resque 的 Ruby 版本完全相同的预期格式存储。
PHP 版本提供了与 Ruby 版本几乎相同的特性
- 工作器可以在多台机器之间分配
- 包括对优先级(队列)的支持
- 具有防止内存泄漏(分叉)的弹性
- 期望失败
它还支持以下附加功能
- 具有跟踪作业状态的能力
- 如果执行作业的分叉子进程没有以状态码 0 退出,则将作业标记为失败
- 具有内置对
setUp
和tearDown
方法的支持,这些方法分别在作业前后调用
要求
- PHP 5.3+
- Redis 2.2+
- 建议但不是必需的:Composer
入门
使用 php-resque 的最简单方法是在你的项目中将其作为 Composer 包安装。Composer 不是必需的,但它会使生活更加容易。
如果你不熟悉 Composer,请参阅 https://getcomposer.org.cn/。
- 将 php-resque 添加到应用程序的 composer.json。
{ // ... "require": { "chrisboulton/php-resque": "1.2.x" // Most recent tagged version }, // ... }
-
运行
composer install
。 -
如果你还没有这样做,请将 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
在检查warm_cache
队列之前,将始终在每个迭代中检查file_serve
队列是否有新作业。
运行所有队列
所有队列都支持相同的方式,并按字母顺序处理
$ 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
- 恢复工作进程。
处理进程标题/状态
Ruby 版本的 Resque 有一个巧妙的功能,即更新工作进程的进程标题以显示工作进程正在做什么,并且任何分叉的子进程也会设置其进程标题,以运行任务。这有助于识别服务器上运行的进程及其 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