PHPackages westmoon/xxl-job-incubator - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. westmoon/xxl-job-incubator ActiveLibrary westmoon/xxl-job-incubator ========================== php hyperf xxljob 1.0.10(6mo ago)08MITPHPPHP >=8.1 Since Oct 23Pushed 5mo agoCompare [ Source](https://github.com/sanzhangshitou/xxl-job-incubator)[ Packagist](https://packagist.org/packages/westmoon/xxl-job-incubator)[ Docs](https://hyperf.io)[ RSS](/packages/westmoon-xxl-job-incubator/feed)WikiDiscussions master Synced 1mo ago READMEChangelogDependencies (16)Versions (2)Used By (0) xxl-job-incubator ================= [](#xxl-job-incubator) 此为 xxl-job 的 PHP 版本的任务执行器(Job Executor)，特别适配于 Hyperf 框架，其余框架尚未验证适配性 ### 优点 [](#优点) - 分布式任务调度平台 - 任务可以随时关闭与开启 - 日志可通过服务端查看 使用须知 ---- [](#使用须知) > 1. xxl-job 服务端版本需 >= 2.2.0 > 2. 阻塞处理策略:已全部适配 > 3. 建议优先使用进程模式执行任务，终止任务完善且安全 > 4. swoole版本不小于6.1版本，协程模式执行任务时，终止任务通过`cancel`方法停止 安装 -- [](#安装) ``` composer require hyperf/xxl-job-incubator ``` 使用 -- [](#使用) ### 配置 [](#配置) 配置文件: `config/autoload/xxl_job.php` ``` use function Hyperf\Support\env; return [ // 是否启动 xxl-job 'enable' => env('XXL_JOB_ENABLE', true), // xxl-job admin 地址 'admin_address' => env('XXL_JOB_ADMIN_ADDRESS', 'http://127.0.0.1:8080/xxl-job-admin'), // xxl-job app_name 'app_name' => env('XXL_JOB_APP_NAME', 'xxl-job-demo'), // xxl-job access_token 'access_token' => env('XXL_JOB_ACCESS_TOKEN', ''), // xxl-job 心跳时间 'heartbeat' => env('XXL_JOB_HEARTBEAT', 30), // xxl-job 日志保留天数 'log_retention_days' => 30, // xxl-job 执行器配置 'executor_server' => [ // executor host (no Settings, automatically obtained) 'host' => env('XXL_JOB_EXECUTOR_HOST'), // executor port 'port' => env('XXL_JOB_EXECUTOR_PORT'), // executor prefix 'prefix_url' => env('XXL_JOB_EXECUTOR_PREFIX_URL', 'php-xxl-job') ], 'guzzle_config' => [ 'headers' => [ 'charset' => 'UTF-8', ], 'timeout' => 10, ], 'file_logger' => [ 'dir' => BASE_PATH . '/runtime/xxl_job/logs/', ], ]; ``` 如文件不存在可通过以下命令发布配置文件 ``` php bin/hyperf.php vendor:publish hyperf/xxl-job-incubator ``` ### Bean 模式(类形式) [](#bean-模式类形式) Bean 模式任务，支持基于类的开发方式，每个任务对应一个 PHP 类 优点：与 Hyperf 整合性好，易于管理 缺点：任务运行于单独的，协程任务代码不能存在阻塞 IO，每个 Job 需占用一个类文件，Job 逻辑简单但数量过多时过于累赘 > swoole默认使用命令行模式执行，swow默认使用协程模式执行 如需要手动指定模式，通过注解XxlJob指定运行模式 swoole使用协程模式，无法使用:`关闭终止任务`|`以及阻塞处理策略`|`任务超时` #### 编写 Job 类 [](#编写-job-类) 编写一个实现 `Hyperf\XxlJob\Handler\JobHandlerInterface` 的 Job 类，并为 Job 类添加注解 `#[XxlJob('value')]`，注解的 value 值对应的是调度中心新建任务的 JobHandler 属性的值，如下所示： > Tips: 可直接继承 `Hyperf\XxlJob\Handler\AbstractJobHandler` 得到对应的实现 ``` namespace App\Job; use Hyperf\Di\Annotation\Inject; use Hyperf\XxlJob\Annotation\XxlJob; use Hyperf\XxlJob\Handler\AbstractJobHandler; use Hyperf\XxlJob\Logger\JobExecutorLoggerInterface; use Hyperf\XxlJob\Requests\RunRequest; #[XxlJob("demoJobClassHandler")] class DemoJobClass extends AbstractJobHandler { #[Inject] protected JobExecutorLoggerInterface $jobExecutorLogger; /** * 执行任务 */ public function execute(RunRequest $request): void { // 获取参数 $params = $request->getExecutorParams(); // 获取 LogId $logId = $request->getLogId(); $this->jobExecutorLogger->info('demoJobClassHandler...'); $this->jobExecutorLogger->info('params:' . $params); for ($i = 1; $i < 5; ++$i) { sleep(2); $this->jobExecutorLogger->info($i); $this->jobExecutorLogger->info('logId:' . $logId); $this->jobExecutorLogger->info('params:' . $params); } } } ``` #### 在调度中心新建调度任务 [](#在调度中心新建调度任务) 对新建的任务进行参数配置，运行模式选中 `BEAN模式`，JobHandler 属性填写注解 `#[XxlJob]`中定义 value 值 [![hMvJnQ](https://camo.githubusercontent.com/2364e20974be44f80de877b9e5e6913eb40c01825a21590768ed64a5f6e08c91/68747470733a2f2f7777772e78757875656c692e636f6d2f646f632f7374617469632f78786c2d6a6f622f696d616765732f696d675f5a41737a2e706e67)](https://camo.githubusercontent.com/2364e20974be44f80de877b9e5e6913eb40c01825a21590768ed64a5f6e08c91/68747470733a2f2f7777772e78757875656c692e636f6d2f646f632f7374617469632f78786c2d6a6f622f696d616765732f696d675f5a41737a2e706e67) ### Bean 模式(方法形式) [](#bean-模式方法形式) 基于方法的开发方式，每个任务对应一个方法 优点：相对比 `Bean(类形式)` 更加灵活 缺点：数量多时更难管理，代码复杂度高时多个任务间容易造成耦合度过高 #### 编写 Job 方法 [](#编写-job-方法) 对任意类中的 Public 方法增加 `#[XxlJob('value')]` 注解，注解的 value 值对应的是调度中心新建任务的 JobHandler 属性的值 ``` use Hyperf\XxlJob\Annotation\XxlJob; class Foo { #[XxlJob('demoJobHandler')] public function demoJobHandler(){} } ``` #### 在调度中心新建调度任务 [](#在调度中心新建调度任务-1) 对新建的任务进行参数配置，运行模式选中 `BEAN模式`，JobHandler 属性填写注解 `#[XxlJob]`中定义 value 值 [![hMvJnQ](https://camo.githubusercontent.com/2364e20974be44f80de877b9e5e6913eb40c01825a21590768ed64a5f6e08c91/68747470733a2f2f7777772e78757875656c692e636f6d2f646f632f7374617469632f78786c2d6a6f622f696d616765732f696d675f5a41737a2e706e67)](https://camo.githubusercontent.com/2364e20974be44f80de877b9e5e6913eb40c01825a21590768ed64a5f6e08c91/68747470733a2f2f7777772e78757875656c692e636f6d2f646f632f7374617469632f78786c2d6a6f622f696d616765732f696d675f5a41737a2e706e67) #### 使用案例 [](#使用案例) ``` namespace App\Job; use Hyperf\Di\Annotation\Inject; use Hyperf\XxlJob\Annotation\XxlJob; use Hyperf\XxlJob\Logger\JobExecutorLoggerInterface; use Hyperf\XxlJob\Requests\RunRequest; class DemoJob { #[Inject] protected JobExecutorLoggerInterface $jobExecutorLogger; /** * 1.任务示例. */ #[XxlJob('demoJobHandler')] public function demoJobHandler(RunRequest $request) { //获取参数 $params = $request->getExecutorParams(); //获取logId $logId = $request->getLogId(); $this->jobExecutorLogger->info('params:' . $params); for ($i = 1; $i < 5; ++$i) { sleep(2); $this->jobExecutorLogger->info($i); $this->jobExecutorLogger->info('logId:' . $logId); $this->jobExecutorLogger->info('params:' . $params); } } /** * 2、分片广播任务 */ #[XxlJob('shardingJobHandler')] public function shardingJobHandler(RunRequest $request) { // 分片参数 $shardIndex = $request->getBroadcastIndex(); $shardTotal = $request->getBroadcastTotal(); $this->jobExecutorLogger->info(sprintf('分片参数：当前分片序号 = %d, 总分片数 = %d', $shardIndex, $shardTotal)); // 业务逻辑 for ($i = 0; $i < $shardTotal; ++$i) { if ($i == $shardIndex) { $this->jobExecutorLogger->info('第 %d 片, 命中分片开始处理', $i); } else { $this->jobExecutorLogger->info('第 %d 片, 忽略', $i); } } } /** * 3、执行命令. */ #[XxlJob('commandJobHandler')] public function commandJobHandler(RunRequest $request) { //获取参数 //例子:php -v $command = $request->getExecutorParams(); var_dump($command); $result = System::exec($command); $message = str_replace("\n", '', $result['output']); $this->jobExecutorLogger->info($message); } /** * 4、param任务 * 参数示例： * "url: http://www.baidu.com\n" + * "method: get". */ #[XxlJob('paramJobHandler')] public function paramJobHandler(RunRequest $request) { $param = $request->getExecutorParams(); $array = explode(PHP_EOL, $param); /** array(2) { [0]=> string(25) "url: http://www.baidu.com" [1]=> string(11) "method: get" } */ var_dump($param, $array); } /** * 5、任务示例：任务初始化与销毁时，支持自定义相关逻辑. */ #[XxlJob(value: 'demoJob', init: 'initMethod', destroy: 'destroyMethod')] public function demoJob() { $this->jobExecutorLogger->info('demoJob run...'); } public function initMethod() { $this->jobExecutorLogger->info('initMethod'); } public function destroyMethod() { $this->jobExecutorLogger->info('destroyMethod'); } } ``` ### Glue 脚本模式 [](#glue-脚本模式) 该模式下，可支持任务以将源码方式维护在调度中心，支持通过 XXL-JOB 提供的 Web IDE 在线编写代码和在线更新，因此不需要指定固定的 `JobHandler` 脚本模式支持多种脚本语言编写 Job 代码，包括 PHP、Python、NodeJs、Shell、PowerShell，在 XXL-JOB 新建任务时选择对应的模式即可，例如 `GLUE(PHP)` 即代表 PHP 语言的脚本模式，所有脚本模式的任务会以一个独立的进程来运行，故在 PHP 下也可支持编写存在 IO 阻塞的代码 > 要使用 `Glue 脚本模式` 必须配置 Access Token 方可启用 优点：极度灵活，可以实现不重启新增和修改 Job 代码，支持多种脚本语言，独立进程 缺点：大批量任务时容易造成进程数过多，脚本代码由 XXL-JOB 远程编辑发放容易导致安全问题，Job 代码可对 Executor 所在服务器环境进行与启动 Hyperf 应用的权限相同的操作 ### 安装xxl-job-admin(3.0.0版本) [](#安装xxl-job-admin300版本) #### 初始化“调度数据库” [](#初始化调度数据库) [初始化SQL脚本](https://github.com/xuxueli/xxl-job/blob/3.0.0/doc/db/tables_xxl_job.sql) #### docker安装 [](#docker安装) ``` docker run -d \ -e PARAMS="--spring.datasource.url=jdbc:mysql://127.0.0.1:3306/xxl_job?Unicode=true&characterEncoding=UTF-8&autoReconnect=true&serverTimezone=Asia/Shanghai --spring.datasource.username=root --spring.datasource.password=123456 --xxl.job.accessToken=123456" \ -p 8080:8080 --name xxl-job --restart=always xuxueli/xxl-job-admin:3.0.0 ``` > 替换:数据库地址/账号/密码和accessToken ### 引用 [](#引用) 关于 XXL-JOB 更多的使用细节可参考 [XXL-JOB 官方文档](https://www.xuxueli.com/xxl-job/#%E3%80%8A%E5%88%86%E5%B8%83%E5%BC%8F%E4%BB%BB%E5%8A%A1%E8%B0%83%E5%BA%A6%E5%B9%B3%E5%8F%B0XXL-JOB%E3%80%8B) ### Health Score 33 — LowBetter than 75% of packages Maintenance68 Regular maintenance activity Popularity4 Limited adoption so far Community12 Small or concentrated contributor base Maturity44 Maturing project, gaining track record Bus Factor1 Top contributor holds 64.7% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 202d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/1eba87c5a322cea2b426f2983f9af4fadb14ebbd2fa6cd39cfee3d2e80bfef58?d=identicon)[sanzhangshitou](/maintainers/sanzhangshitou) --- Top Contributors [![tw2066](https://avatars.githubusercontent.com/u/24579418?v=4)](https://github.com/tw2066 "tw2066 (77 commits)")[![huangzhhui](https://avatars.githubusercontent.com/u/12077148?v=4)](https://github.com/huangzhhui "huangzhhui (24 commits)")[![limingxinleo](https://avatars.githubusercontent.com/u/16648551?v=4)](https://github.com/limingxinleo "limingxinleo (14 commits)")[![SparkLee](https://avatars.githubusercontent.com/u/7686363?v=4)](https://github.com/SparkLee "SparkLee (2 commits)")[![jatyPeng](https://avatars.githubusercontent.com/u/92199761?v=4)](https://github.com/jatyPeng "jatyPeng (1 commits)")[![xuchuandi](https://avatars.githubusercontent.com/u/51897937?v=4)](https://github.com/xuchuandi "xuchuandi (1 commits)") --- Tags xxljobhyperf xxljobphp xxljobxxljob executor ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/westmoon-xxl-job-incubator/health.svg) ``` [![Health](https://phpackages.com/badges/westmoon-xxl-job-incubator/health.svg)](https://phpackages.com/packages/westmoon-xxl-job-incubator) ``` ### Alternatives [hyperf/xxl-job-incubator php hyperf xxljob 4632.2k5](/packages/hyperf-xxl-job-incubator)[mineadmin/mineadmin Quickly build a background management system for web applications 1.2k2.0k](/packages/mineadmin-mineadmin)[hyperf/odin 425.9k](/packages/hyperf-odin)[hyperf/swow-skeleton A coroutine framework that focuses on hyperspeed and flexible, specifically use for build microservices and middlewares. 514.5k](/packages/hyperf-swow-skeleton) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)