README

本项目是从 webman-tech/components-monorepo 自动 split 出来的，请勿直接修改

简介

webman 定时任务管理插件，基于 workerman/crontab 实现，提供更加便捷的定时任务管理方式。

该插件解决了 webman 默认定时任务配置的一些问题：

默认的单进程下起多个定时任务会存在阻塞问题
缺乏统一的日志记录机制
定时任务的管理不够灵活

功能特性

灵活的进程管理：支持单进程单个定时任务和单进程多个定时任务的配置
完善的日志支持：提供定时任务开始、结束、异常等常规日志记录
事件机制：支持任务执行前后的事件处理
内存管理：支持任务执行后自动释放内存
命令行工具：提供查看和创建定时任务的命令
异常处理：完善的异常处理机制，防止任务异常影响整个进程

安装

composer require webman-tech/crontab-task

快速开始

1. 创建定时任务

创建一个继承 BaseTask 的定时任务类：

<?php

namespace app\crontab\tasks;

use WebmanTech\CrontabTask\BaseTask;

class SampleTask extends BaseTask 
{
    /**
     * @inheritDoc
     */
    public function handle()
    {   
        // 实际业务逻辑
        echo date('Y-m-d H:i:s') . PHP_EOL;
    }
}

2. 配置定时任务进程

在 config/plugin/webman-tech/crontab-task/process.php 中配置：

<?php

use WebmanTech\CrontabTask\Schedule;

return (new Schedule())
    // 添加单个定时任务，独立进程
    ->addTask('task1', '*/1 * * * * *', \app\crontab\tasks\SampleTask::class)
    // 添加多个定时任务，在同个进程中（注意会存在阻塞）
    ->addTasks('task2', [
        ['*/1 * * * * *', \app\crontab\tasks\SampleTask::class],
        ['*/2 * * * * *', \app\crontab\tasks\SampleTask::class],
    ])
    ->buildProcesses();

3. 启动服务

php start.php start

核心组件

BaseTask 基础任务类

BaseTask 是所有定时任务的基类，提供了任务执行的完整生命周期管理：

taskExec(): 任务执行入口，处理异常和日志记录
handle(): 抽象方法，由子类实现具体业务逻辑
集成日志、事件、内存管理等特性

Schedule 调度器

Schedule 用于配置和管理定时任务进程：

addTask(): 添加单个定时任务（独立进程）
addTasks(): 添加多个定时任务（同一进程）
buildProcesses(): 构建进程配置数组

TaskProcess 任务进程

TaskProcess 是实际的任务进程类：

验证任务配置的正确性
在进程启动时注册定时任务
管理任务的执行

特性详解

日志记录

通过 LogTrait 提供日志记录功能：

class MyTask extends BaseTask
{
    public function handle()
    {
        $this->log('这是一条信息日志');
        $this->log('这是一条警告日志', 'warning');
        $this->log('这是一条错误日志', 'error');
    }
}

事件机制

通过 TaskEventTrait 提供任务执行前后的事件处理：

class MyTask extends BaseTask
{
    protected function initEvents()
    {
        parent::initEvents();
        
        $this->addBeforeEvent(function() {
            // 任务执行前的操作
        });
        
        $this->addAfterEvent(function() {
            // 任务执行后的操作
        });
    }
}

内存管理

通过 TaskAutoFreeMemoryTrait 提供自动内存释放功能：

class MyTask extends BaseTask
{
    // 启用自动内存释放（也可通过配置文件全局启用）
    protected ?bool $isAutoFreeMemory = true;
}

异常处理

定时任务中的异常分为两类：

TaskException: 业务异常，记录为 warning 级别日志
其他异常: 系统异常，记录为 error 级别日志

class MyTask extends BaseTask
{
    public function handle()
    {
        if ($someCondition) {
            // 业务异常
            throw new \WebmanTech\CrontabTask\Exceptions\TaskException('业务异常信息');
        }
        
        if ($otherCondition) {
            // 系统异常
            throw new \Exception('系统异常信息');
        }
    }
}

命令行工具

查看定时任务列表

php webman crontab-task:list

创建定时任务

php webman make:crontab-task MyTask

配置说明

进程配置