PHP Cron 表达式解析器技术文档

1. 安装指南

1.1 使用 Composer 安装

要安装 PHP Cron 表达式解析器，首先确保你已经安装了 Composer。然后在你的项目根目录下运行以下命令：

composer require mtdowling/cron-expression

1.2 手动安装

如果你不使用 Composer，也可以手动下载项目源码并将其包含在你的项目中。你需要将 src 目录中的文件复制到你的项目中，并确保能够正确加载这些文件。

2. 项目使用说明

2.1 基本用法

安装完成后，你可以使用以下代码来解析和计算 CRON 表达式的运行时间：

<?php

require_once '/vendor/autoload.php';

// 使用预定义的调度定义
$cron = Cron\CronExpression::factory('@daily');
$cron->isDue();
echo $cron->getNextRunDate()->format('Y-m-d H:i:s');
echo $cron->getPreviousRunDate()->format('Y-m-d H:i:s');

// 使用复杂的表达式
$cron = Cron\CronExpression::factory('3-59/15 2,6-12 */15 1 2-5');
echo $cron->getNextRunDate()->format('Y-m-d H:i:s');

// 计算未来两次运行的时间
$cron = Cron\CronExpression::factory('@daily');
echo $cron->getNextRunDate(null, 2)->format('Y-m-d H:i:s');

// 计算相对于特定时间的运行时间
$cron = Cron\CronExpression::factory('@monthly');
echo $cron->getNextRunDate('2010-01-12 00:00:00')->format('Y-m-d H:i:s');

2.2 CRON 表达式格式

一个 CRON 表达式是一个字符串，表示某个命令的执行计划。CRON 表达式的各个部分如下：

*    *    *    *    *
-    -    -    -    -
|    |    |    |    |
|    |    |    |    |
|    |    |    |    +----- 星期几 (0 - 7) (星期日=0 或 7)
|    |    |    +---------- 月份 (1 - 12)
|    |    +--------------- 日期 (1 - 31)
|    +-------------------- 小时 (0 - 23)
+------------------------- 分钟 (0 - 59)

3. 项目 API 使用文档

3.1 Cron\CronExpression::factory($expression)

• 描述: 创建一个 CRON 表达式解析器实例。
• 参数:
  • $expression (string): 要解析的 CRON 表达式。
• 返回值: Cron\CronExpression 实例。

3.2 isDue()

• 描述: 检查当前时间是否符合 CRON 表达式的执行条件。
• 返回值: 布尔值，true 表示当前时间符合条件，false 表示不符合。

3.3 getNextRunDate($currentTime = 'now', $nth = 0)

• 描述: 计算 CRON 表达式的下一次运行时间。
• 参数:
  • $currentTime (string|DateTime): 计算的基准时间，默认为当前时间。
  • $nth (int): 跳过的匹配次数，默认为 0。
• 返回值: DateTime 对象，表示下一次运行的时间。

3.4 getPreviousRunDate($currentTime = 'now', $nth = 0)

• 描述: 计算 CRON 表达式的上一次运行时间。
• 参数:
  • $currentTime (string|DateTime): 计算的基准时间，默认为当前时间。
  • $nth (int): 跳过的匹配次数，默认为 0。
• 返回值: DateTime 对象，表示上一次运行的时间。

4. 项目安装方式

4.1 通过 Composer 安装

推荐使用 Composer 进行安装，具体步骤如下：

1. 打开终端或命令行工具。
2. 进入你的项目目录。
3. 运行以下命令：

composer require mtdowling/cron-expression

4.2 手动安装

如果你不使用 Composer，可以手动下载项目源码并将其包含在你的项目中。你需要将 src 目录中的文件复制到你的项目中，并确保能够正确加载这些文件。

5. 项目要求

• PHP 7.0 及以上版本
• PHPUnit 用于运行单元测试
• Composer 用于管理依赖和运行单元测试

通过以上文档，你应该能够顺利安装和使用 PHP Cron 表达式解析器。如果有任何问题，请参考项目的 GitHub Wiki 或联系项目维护者。