CronjobSchedule.class.php

<?php
// +---------------------------------------------------------------------------+
// This file is part of Stud.IP
// CronjobSchedule.class.php
//
// Copyright (C) 2013 Jan-Hendrik Willms <tleilax+studip@gmail.com>
// +---------------------------------------------------------------------------+
// This program is free software; you can redistribute it and/or
// modify it under the terms of the GNU General Public License
// as published by the Free Software Foundation; either version 2
// of the License, or any later version.
// +---------------------------------------------------------------------------+
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
// You should have received a copy of the GNU General Public License
// along with this program; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
// +---------------------------------------------------------------------------+

/**
 * CronjobSchedule - Model for the database table "cronjobs_schedules"
 *
 * @author      Jan-Hendrik Willms <tleilax+studip@gmail.com>
 * @license     http://www.gnu.org/licenses/gpl-2.0.html GPL version 2
 * @category    Stud.IP
 * @since       2.4
 *
 * @property string schedule_id database column
 * @property string id alias column for schedule_id
 * @property string task_id database column
 * @property string active database column
 * @property string title database column
 * @property string description database column
 * @property string parameters database column
 * @property string priority database column
 * @property string type database column
 * @property string minute database column
 * @property string hour database column
 * @property string day database column
 * @property string month database column
 * @property string day_of_week database column
 * @property string next_execution database column
 * @property string last_execution database column
 * @property string last_result database column
 * @property string execution_count database column
 * @property string mkdate database column
 * @property string chdate database column
 * @property SimpleORMapCollection logs has_many CronjobLog
 * @property CronjobTask task belongs_to CronjobTask
 */

class CronjobSchedule extends SimpleORMap
{
    const PRIORITY_LOW    = 'low';
    const PRIORITY_NORMAL = 'normal';
    const PRIORITY_HIGH   = 'high';

    protected static function configure($config = [])
    {
        $config['db_table'] = 'cronjobs_schedules';

        $config['belongs_to']['task'] = [
            'class_name'  => CronjobTask::class,
            'foreign_key' => 'task_id',
        ];
        $config['has_many']['logs'] = [
            'class_name' => CronjobLog::class,
            'on_delete'  => 'delete',
            'on_store'   => 'store',
        ];

        $config['registered_callbacks']['before_store'][]     = 'cbJsonifyParameters';
        $config['registered_callbacks']['after_store'][]      = 'cbJsonifyParameters';
        $config['registered_callbacks']['after_initialize'][] = 'cbJsonifyParameters';

        parent::configure($config);
    }

    /**
     * Returns a mapped version of the priorities (key = priority value,
     * value = localized priority label).
     *
     * @return Array The mapped priorities
     */
    public static function getPriorities()
    {
        $mapping = [];
        $mapping[self::PRIORITY_LOW]    = _('niedrig');
        $mapping[self::PRIORITY_NORMAL] = _('normal');
        $mapping[self::PRIORITY_HIGH]   = _('hoch');

        return $mapping;
    }

    /**
     * Maps a priority value to it's localized label.
     *
     * @param  String $priority Priority value
     * @return String The localized label
     * @throws RuntimeException when an unknown priority value is passed
     */
    public static function describePriority($priority)
    {
        $priority = $priority ?? 'normal';

        $mapping = self::getPriorities();
        if (!isset($mapping[$priority])) {
            throw new RuntimeException('Access to unknown priority "' . $priority . '"');
        }

        return $mapping[$priority];
    }

    /**
     * replaces title with task name if title is empty.
     *
     * @return string the title or the task name
     */
    public function getTitle()
    {
        return ($this->content['title'] ?: $this->task->name) ?? '';
    }

    protected function cbJsonifyParameters($type)
    {
        if ($type === 'before_store' && !is_string($this->parameters)) {
            $this->parameters = json_encode($this->parameters ?: null);
        }
        if (in_array($type, ['after_initialize', 'after_store']) && is_string($this->parameters)) {
            $parameters = json_decode($this->parameters, true) ?: [];
            if ($this->task->valid) {
                $default_parameters = $this->task->extractDefaultParameters();
                foreach ($default_parameters as $key => $value) {
                    if (!isset($parameters[$key])) {
                        $parameters[$key] = $value;
                    }
                }
            }
            $this->parameters = $parameters;
        }
    }

    /**
     * Stores the schedule in database. Will bail out with an exception if
     * the provided task does not exists. Will also nullify the title if it
     * matches the task name (see CronjobSchedule::getTitle()).
     *
     * @return CronjobSchedule Returns itself to allow chaining
     */
    public function store()
    {
        if ($this->task === null) {
            $message = sprintf('A task with the id "%s" does not exist.', $this->task_id);
            throw new InvalidArgumentException($message);
        }

        // Remove title if it is the default (task's name)
        if ($this->title === $this->task->name) {
            $this->title = null;
        }

        parent::store();

        return $this;
    }

    /**
     * Activates this schedule.
     *
     * @return CronjobSchedule Returns itself to allow chaining
     */
    public function activate()
    {
        $this->active         = 1;
        $this->next_execution = $this->calculateNextExecution();
        $this->store();

        return $this;
    }

    /**
     * Deactivates this schedule.
     *
     * @return CronjobSchedule Returns itself to allow chaining
     */
    public function deactivate()
    {
        $this->active = 0;
        $this->store();

        return $this;
    }

    /**
     * Executes this schedule.
     *
     * @param bool $force Pass true to force execution of  the schedule even
     *                    if it's not activated
     * @return mixed The result of the execution
     * @throws RuntimeException When either the schedule or the according is
     *                          not activated
     */
    public function execute($force = false)
    {
        if (!$force && !$this->active) {
            throw new RuntimeException('Execution aborted. Schedule is not active');
        }
        if (!$this->task->active) {
            throw new RuntimeException('Execution aborted. Associated task is not active');
        }

        $this->last_execution   = time();
        $this->execution_count += 1;
        $this->next_execution   = $this->calculateNextExecution();
        $this->store();

        $this->task->execution_count += 1;
        $this->task->store();

        $result = $this->task->engage($this->last_result, $this->parameters);

        if ($this->type === 'once') {
            $this->active = 0;
        }
        $this->last_result = $result;
        $this->store();

        return $result;
    }

    /**
     * Determines whether the schedule should execute given the provided
     * timestamp.
     *
     * @param mixed $now Defines the temporal fix point
     * @return bool Whether the schedule should execute or not.
     */
    public function shouldExecute($now = null)
    {
        return ($now ?: time()) >= $this->next_execution;
    }

    /**
     * Calculates the next execution for this schedule.
     *
     * For schedules of type 'once' the check solely tests whether the
     * timestamp has already passed and will return false in that case.
     * Otherwise the defined timestamp will be returned.
     *
     * For schedules of type 'periodic' the next execution
     * is calculated by increasing the current timestamp and testing
     * whether all conditions match. This is not the best method to test
     * and should be optimized sooner or later.
     *
     * @param mixed $now Defines the temporal fix point
     * @return int Timestamp of calculated next execution
     * @throws RuntimeException When calculation takes too long (you should
     *                          check the conditions for validity in that case)
     */
    public function calculateNextExecution($now = null)
    {
        $now = $now ?: time();

        if ($this->type === 'once') {
            return $now <= $this->next_execution
                ? $this->next_execution
                : false;
        }

        $result  = $now;
        $result -= $result % 60;

        $i = 366 * 24 * 60; // Maximum: A year
        $offset = 60;

        do {
            $result += $offset;

            // TODO: Performance - Adjust result according to conditions
            // See http://coderzone.org/library/PHP-PHP-Cron-Parser-Class_1084.htm
            $valid  = $this->testTimestamp($result, $this->minute, 'i')
                   && $this->testTimestamp($result, $this->hour, 'H')
                   && $this->testTimestamp($result, $this->day, 'd')
                   && $this->testTimestamp($result, $this->month, 'm')
                   && $this->testTimestamp($result, $this->day_of_week, 'N');

        } while (!$valid && $i-- > 0);

        if ($i <= 0) {
            throw new RuntimeException('No result, current: ' . date('d.m.Y H:i', $result));
        }

        $this->next_execution = $result;
        return $result;
    }

    /**
     * Tests a timestamp against the passed condition.
     *
     * @param int $timestamp The timestamp to test
     * @param mixed $condition Can be either null for "don't care", a positive
     *                         number for an exact moment or a negative number
     *                         for a repeating moment
     * @param String $format Format for date() to extract a portion of the
     *                       timestamp
     */
    protected function testTimestamp($timestamp, $condition, $format)
    {
        if ($condition === null) {
            return true;
        }

        $probe     = (int) date($format, $timestamp);
        $condition = (int) $condition;

        if ($condition < 0) {
            return ($probe % abs($condition)) === 0;
        }

        return $probe === $condition;
    }
}