README

WordPress 任务队列。

安装

在项目中安装此库的推荐方式是通过Composer加载

composer require deliciousbrains/wp-queue

强烈建议使用PHP-Scoper对库的类文件进行前缀包装，以防止与其他使用此库的项目发生冲突。

先决条件

WP_Queue 需要 PHP 7.3+。

需要创建以下数据库表

CREATE TABLE {$wpdb->prefix}queue_jobs (
    id bigint(20) NOT NULL AUTO_INCREMENT,
    job longtext NOT NULL,
    attempts tinyint(3) NOT NULL DEFAULT 0,
    reserved_at datetime DEFAULT NULL,
    available_at datetime NOT NULL,
    created_at datetime NOT NULL,
    PRIMARY KEY (id)
);

CREATE TABLE {$wpdb->prefix}queue_failures (
    id bigint(20) NOT NULL AUTO_INCREMENT,
    job longtext NOT NULL,
    error text DEFAULT NULL,
    failed_at datetime NOT NULL,
    PRIMARY KEY (id)
);

或者，您可以通过调用辅助函数 wp_queue_install_tables() 来安装表。如果在使用WP_Queue的插件中，您可以选择在 register_activation_hook 中调用此辅助函数。

任务

任务类应扩展 WP_Queue\Job 类，通常只包含一个在任务被队列工作进程处理时调用的 handle 方法。任何任务所需的数据都应传递给构造函数并分配给公共属性。一旦任务从队列中检索出来，这些数据将保持可用。让我们看看一个示例任务类

<?php

use WP_Queue\Job;

class Subscribe_User_Job extends Job {

	/**
	 * @var int
	 */
	public $user_id;

	/**
	 * Subscribe_User_Job constructor.
	 *
	 * @param int $user_id
	 */
	public function __construct( $user_id ) {
		$this->user_id = $user_id;
	}

	/**
	 * Handle job logic.
	 */
	public function handle() {
		$user = get_user_by( 'ID', $this->user_id );

		// Process the user...
	}

}

分发任务

可以通过以下方式将任务推送到队列

wp_queue()->push( new Subscribe_User_Job( 12345 ) );

您可以通过向 push 方法传递可选的第二个参数来创建延迟任务。此任务将延迟60分钟

wp_queue()->push( new Subscribe_User_Job( 12345 ), 3600 );

Cron 工作进程

任务需要由队列工作进程处理。您可以像这样启动一个cron工作进程，该进程依赖于WP cron

wp_queue()->cron();

您还可以指定在将任务标记为失败之前应尝试执行任务的最大次数。

wp_queue()->cron( 3 );

限制允许的任务类

队列将处理任何 WP_Queue\Job 的子类。为了更好的安全性，强烈建议使用包含预期要处理的 Job 子类的列表来实例化 DatabaseConnection。

您可以在设置数据库连接时传递一个包含 Job 子类的数组，或者拥有只处理某些 Job 子类的数据库连接。

class Connection extends DatabaseConnection {
    public function __construct( $wpdb, array $allowed_job_classes = [] ) {
        // If a connection is always dealing with the same Jobs,
        // you could explicitly set the allowed job classes here
        // rather than pass them in.
        if ( empty( $allowed_job_classes ) ) {
            $allowed_job_classes = [ Subscribe_User_Job::class ];
        }

        parent::__construct( $wpdb, $allowed_job_classes );

        $this->jobs_table     = $wpdb->base_prefix . 'myplugin_subs_jobs';
        $this->failures_table = $wpdb->base_prefix . 'myplugin_subs_failures';
    }
}

class Subscribe_User_Queue extends Queue {
    public function __construct() {
        global $wpdb;

        // Set up custom database queue, with list of allowed job classes.
        parent::__construct( new Connection( $wpdb, [ Subscribe_User_Job::class ] ) );

        // Other set up stuff ...
    }
}

class MyPlugin {
    /**
     * @var Subscribe_User_Queue
     */
    private $queue;

    public function __construct() {
        // Part of bring-up ...
        $this->queue = new Subscribe_User_Queue();
        
        // Other stuff ...
    }

    protected function subscribe_user( $user_id ) {
        $this->queue->push( new Subscribe_User_Job( $user_id ) );
    }

    /**
     * Triggered by cron or background process etc.
     *
     * @return bool
     */
    protected function process_queue_job() {
        return $this->queue->worker()->process();
    }
}

本地开发

在本地开发时，您可能希望任务立即处理，而不是将其推送到队列。这可以用于通过Xdebug调试任务。添加以下筛选器以使用 sync 连接。

add_filter( 'wp_queue_default_connection', function() {
	return 'sync';
} );

贡献

欢迎通过拉取请求进行贡献，但请在开始任何工作之前提出一个问题，以便讨论更改，如果没有现有的问题。如果有您想解决的问题，请在其上发布评论，以告知人们您将尝试解决这个问题，以免造成重复工作。

单元测试和样式测试

在处理库时，请将单元测试添加到 tests 目录中适当的文件，以涵盖您的更改。

设置

我们使用标准的WordPress测试库来运行单元测试。

请运行以下命令来设置库

bin/install-wp-tests.sh db_name db_user db_pass

根据需要替换 db_name、db_user 和 db_pass。

请注意，运行单元测试是一个破坏性操作，数据库表将被清除，因此请使用专门用于运行单元测试的数据库名称。WordPress 社区通常使用的标准数据库名称是 wordpress_test，例如：

bin/install-wp-tests.sh wordpress_test root root

如果您在运行过程中遇到任何问题，请参考 WordPress 手册中的“在本地初始化测试环境”部分和“插件集成测试”条目。

运行单元测试

要运行单元测试，只需运行以下命令：

make test-unit

如果 composer 依赖项尚未安装，它们将被自动安装。

运行风格测试

库中的代码使用一致的风格对于快速理解代码和避免一些常见问题非常重要。PHP_Code_Sniffer 使用大多数标准 WordPress 规则来帮助检查一致性。

要运行风格测试，只需运行以下命令：

make test-style

如果 composer 依赖项尚未安装，它们将被自动安装。

运行所有测试

为了简化操作，只需运行以下命令即可运行所有测试：

make

如果 composer 依赖项尚未安装，它们将被自动安装。

创建 PR

在创建 PR 时，请确保在描述的开头提及要解决的 GitHub 问题的编号，例如：

解决 #123

单元测试和风格测试将被自动运行，除非它们通过，否则 PR 不得合并，并且分支需要与 master 保持同步。

许可

WP Queue 是开源软件，根据MIT 许可进行许可。