diff --git a/CHANGELOG.md b/CHANGELOG.md index 027dea7..15293e5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ### Added +- `ExplainCommand` + - explains cron expression syntax - `ListCommand` - adds `--explain` option to explain whole expression diff --git a/src/Command/ExplainCommand.php b/src/Command/ExplainCommand.php new file mode 100644 index 0000000..b07b468 --- /dev/null +++ b/src/Command/ExplainCommand.php @@ -0,0 +1,73 @@ +explainSyntax($output); + + return 0; + } + + private function explainSyntax(OutputInterface $output): void + { + $output->writeln( + <<<'CMD' +* * * * * +- - - - - +| | | | | +| | | | | +| | | | +----- day of week (0-7) (Sunday = 0 or 7) (or SUN-SAT) +| | | +--------- month (1-12) (or JAN-DEC) +| | +------------- day of month (1-31) +| +----------------- hour (0-23) ++--------------------- minute (0-59) + +Each part of expression can also use wildcard, lists, ranges and steps: + +- wildcard - match always + - e.g. * * * * * - At every minute. +- lists - match list of values, ranges and steps + - e.g. 15,30 * * * * - At minute 15 and 30. +- ranges - match values in range + - e.g. 1-9 * * * * - At every minute from 1 through 9. +- steps - match every nth value in range + - e.g. */5 * * * * - At every 5th minute. + - e.g. 0-30/5 * * * * - At every 5th minute from 0 through 30. +- combinations + - e.g. 0-14,30-44 * * * * - At every minute from 0 through 14 and every minute from 30 through 44. + +You can also use macro instead of an expression: + +- @yearly, @annually - Run once a year, midnight, Jan. 1 (same as 0 0 1 1 *) +- @monthly - Run once a month, midnight, first of month (same as 0 0 1 * *) +- @weekly - Run once a week, midnight on Sun (same as 0 0 * * 0) +- @daily, @midnight - Run once a day, midnight (same as 0 0 * * *) +- @hourly - Run once an hour, first minute (same as 0 * * * *) + +Although they are not part of cron expression syntax, you can also add to job: + +- seconds - repeat job every n seconds +- timezone - run only when cron expression matches within given timezone +CMD, + ); + } + +} diff --git a/tests/Unit/Command/ExplainCommandTest.php b/tests/Unit/Command/ExplainCommandTest.php new file mode 100644 index 0000000..b060d1f --- /dev/null +++ b/tests/Unit/Command/ExplainCommandTest.php @@ -0,0 +1,77 @@ +execute([]); + + self::assertSame( + <<<'MSG' +* * * * * +- - - - - +| | | | | +| | | | | +| | | | +----- day of week (0-7) (Sunday = 0 or 7) (or SUN-SAT) +| | | +--------- month (1-12) (or JAN-DEC) +| | +------------- day of month (1-31) +| +----------------- hour (0-23) ++--------------------- minute (0-59) + +Each part of expression can also use wildcard, lists, ranges and steps: + +- wildcard - match always + - e.g. * * * * * - At every minute. +- lists - match list of values, ranges and steps + - e.g. 15,30 * * * * - At minute 15 and 30. +- ranges - match values in range + - e.g. 1-9 * * * * - At every minute from 1 through 9. +- steps - match every nth value in range + - e.g. */5 * * * * - At every 5th minute. + - e.g. 0-30/5 * * * * - At every 5th minute from 0 through 30. +- combinations + - e.g. 0-14,30-44 * * * * - At every minute from 0 through 14 and every minute from 30 through 44. + +You can also use macro instead of an expression: + +- @yearly, @annually - Run once a year, midnight, Jan. 1 (same as 0 0 1 1 *) +- @monthly - Run once a month, midnight, first of month (same as 0 0 1 * *) +- @weekly - Run once a week, midnight on Sun (same as 0 0 * * 0) +- @daily, @midnight - Run once a day, midnight (same as 0 0 * * *) +- @hourly - Run once an hour, first minute (same as 0 * * * *) + +Although they are not part of cron expression syntax, you can also add to job: + +- seconds - repeat job every n seconds +- timezone - run only when cron expression matches within given timezone + +MSG, + implode( + PHP_EOL, + array_map( + static fn (string $s): string => rtrim($s), + explode(PHP_EOL, $tester->getDisplay()), + ), + ), + ); + self::assertSame($command::SUCCESS, $code); + } + +}