Expression.php

<?php

declare(strict_types=1);

/*
 * This file is part of the PHP-CRON-EXPR package.
 *
 * (c) Jitendra Adhikari <jiten.adhikary@gmail.com>
 *     <https://github.com/adhocore>
 *
 * Licensed under MIT license.
 */

namespace Ahc\Cron;

use DateTime;

/**
 * Cron Expression Parser.
 *
 * This class checks if a cron expression is due to run on given timestamp (or default now).
 * Acknowledgement: The initial idea came from {@link http://stackoverflow.com/a/5727346}.
 *
 * @author Jitendra Adhikari <jiten.adhikary@gmail.com>
 */
class Expression
{
    /** @var Expression */
    protected static $instance;

    /** @var SegmentChecker */
    protected $checker;

    /** @var Normalizer */
    protected $normalizer;

    /** @var Ticks */
    protected $ticks;

    public function __construct(SegmentChecker $checker = null, Normalizer $normalizer = null)
    {
        $this->checker    = $checker ?: new SegmentChecker;
        $this->normalizer = $normalizer ?: new Normalizer;
        $this->ticks      = new Ticks($this);

        if (null === static::$instance) {
            static::$instance = $this;
        }
    }

    public static function instance(): self
    {
        if (null === static::$instance) {
            static::$instance = new static;
        }

        return static::$instance;
    }

    /**
     * Parse cron expression to decide if it can be run on given time (or default now).
     *
     * @param string $expr The cron expression.
     * @param mixed  $time The timestamp to validate the cron expr against. Defaults to now.
     *
     * @return bool
     */
    public static function isDue(string $expr, $time = null): bool
    {
        return static::instance()->isCronDue($expr, $time);
    }

    /**
     * Next DateTime when the expr would be due again.
     *
     * @param string $expr The cron expression.
     * @param mixed  $time The timestamp to validate the cron expr against. Defaults to now.
     *
     * @throws \RuntimeException
     * @throws \UnexpectedValueException
     *
     * @return \DateTime
     */
    public function nextTick(string $expr, $time = null): DateTime
    {
        return $this->ticks->next($expr, $time);
    }

    /**
     * Next DateTime when the expr would be due again.
     *
     * @param string $expr The cron expression.
     * @param mixed  $time The timestamp to validate the cron expr against. Defaults to now.
     *
     * @throws \RuntimeException
     * @throws \UnexpectedValueException
     *
     * @return \DateTime
     */
    public static function next(string $expr, $time = null): DateTime
    {
        return static::instance()->nextTick($expr, $time);
    }

    /**
     * Next date time as formatted string when the expr would be due again.
     *
     * @param string $expr The cron expression.
     * @param mixed  $time The timestamp to validate the cron expr against. Defaults to now.
     * @param string $fmt  The format
     *
     * @throws \RuntimeException
     * @throws \UnexpectedValueException
     *
     * @return \DateTime
     */
    public static function nextf(string $expr, $time = null, string $fmt = 'Y-m-d H:i:s'): string
    {
        return static::next($expr, $time)->format($fmt);
    }

    /**
     * Filter only the jobs that are due.
     *
     * @param array $jobs Jobs with cron exprs. [job1 => cron-expr1, job2 => cron-expr2, ...]
     * @param mixed $time The timestamp to validate the cron expr against. Defaults to now.
     *
     * @return array Due job names: [job1name, ...];
     */
    public static function getDues(array $jobs, $time = null): array
    {
        return static::instance()->filter($jobs, $time);
    }

    /**
     * Instance call.
     *
     * Parse cron expression to decide if it can be run on given time (or default now).
     *
     * @param string $expr The cron expression.
     * @param mixed  $time The timestamp to validate the cron expr against. Defaults to now.
     *
     * @return bool
     */
    public function isCronDue(string $expr, $time = null): bool
    {
        return $this->segmentsDue($this->segments($expr), $time);
    }

    public function segmentsDue(array $segments, $time = null): bool
    {
        $this->checker->setReference(new ReferenceTime($time));

        foreach ($segments as $pos => $segment) {
            if ($segment === '*' || $segment === '?') {
                continue;
            }

            if (!$this->checker->checkDue($segment, $pos)) {
                return false;
            }
        }

        return true;
    }

    public function segments(string $expr): array
    {
        return \explode(' ', $this->normalizer->normalizeExpr($expr));
    }

    public function segmentChecker(): SegmentChecker
    {
        return $this->checker;
    }

    /**
     * Filter only the jobs that are due.
     *
     * @param array $jobs Jobs with cron exprs. [job1 => cron-expr1, job2 => cron-expr2, ...]
     * @param mixed $time The timestamp to validate the cron expr against. Defaults to now.
     *
     * @return array Due job names: [job1name, ...];
     */
    public function filter(array $jobs, $time = null): array
    {
        $dues = $cache = [];

        foreach ($jobs as $name => $expr) {
            $expr = $this->normalizer->normalizeExpr($expr);

            if (!isset($cache[$expr])) {
                $cache[$expr] = $this->isCronDue($expr, $time);
            }

            if ($cache[$expr]) {
                $dues[] = $name;
            }
        }

        return $dues;
    }
}