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的子类。为了更好的安全性，强烈建议使用DatabaseConnection实例化时，传递一个期望处理的Job子类列表。

您可以通过在设置数据库连接时传递一个包含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';
} );

贡献

欢迎通过Pull Requests进行贡献，但请在开始工作之前提出一个问题，以讨论更改，如果尚未提出问题。如果有已批准的问题，您想解决，请在它上面发表评论，让人们知道您将尝试解决它，以免造成重复工作。

单元测试和样式测试

在开发库时，请将单元测试添加到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 许可证。