PHPackages hyperf/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. [Queues & Workers](/categories/queues) 4. / 5. hyperf/xxl-job-incubator ActiveLibrary[Queues & Workers](/categories/queues) hyperf/xxl-job-incubator ======================== php hyperf xxljob v0.9.0(3w ago)4837.8k↓11%9[2 issues](https://github.com/hyperf/xxl-job-incubator/issues)3MITPHPPHP >=8.1CI passing Since Oct 1Pushed 3w ago2 watchersCompare [ Source](https://github.com/hyperf/xxl-job-incubator)[ Packagist](https://packagist.org/packages/hyperf/xxl-job-incubator)[ Docs](https://hyperf.io)[ Fund](https://hyperf.wiki/#/zh-cn/donate)[ Fund](https://opencollective.com/hyperf)[ RSS](/packages/hyperf-xxl-job-incubator/feed)WikiDiscussions master Synced today READMEChangelog (10)Dependencies (32)Versions (35)Used By (3) 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.3.1版本) [](#安装xxl-job-admin331版本) #### 初始化“调度数据库” [](#初始化调度数据库) [初始化SQL脚本](https://github.com/xuxueli/xxl-job/blob/3.3.1/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.3.1 ``` > 替换:数据库地址/账号/密码和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 58 — FairBetter than 98% of packages Maintenance94 Actively maintained with recent releases Popularity42 Moderate usage in the ecosystem Community27 Small or concentrated contributor base Maturity61 Established project with proven stability Bus Factor1 Top contributor holds 67.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 Every ~54 days Recently: every ~19 days Total 33 Last Release 4d ago Major Versions v0.2.9 → 2.2.x-dev2026-07-01 PHP version history (3 changes)v0.1.0PHP >=7.3 v0.1.1PHP >=8.0 v0.7.0PHP >=8.1 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/44228082?v=4)[Hyperf Community](/maintainers/hyperf)[@hyperf](https://github.com/hyperf) --- Top Contributors [![tw2066](https://avatars.githubusercontent.com/u/24579418?v=4)](https://github.com/tw2066 "tw2066 (88 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/hyperf-xxl-job-incubator/health.svg) ``` [![Health](https://phpackages.com/badges/hyperf-xxl-job-incubator/health.svg)](https://phpackages.com/packages/hyperf-xxl-job-incubator) ``` ### Alternatives [tempest/framework The PHP framework that gets out of your way. 2.2k34.4k15](/packages/tempest-framework)[drupal/core Drupal is an open source content management platform powering millions of websites and applications. 21866.0M1.7k](/packages/drupal-core)[spatie/laravel-export Create a static site bundle from a Laravel app 674146.0k6](/packages/spatie-laravel-export)[open-dxp/opendxp Content & Product Management Framework (CMS/PIM) 9421.6k61](/packages/open-dxp-opendxp)[whatsdiff/whatsdiff See what's changed in your project's dependencies 771.2k](/packages/whatsdiff-whatsdiff)[eslazarev/wildberries-sdk Wildberries OpenAPI clients (generated). 273.0k](/packages/eslazarev-wildberries-sdk) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)