Source for file lib_events.php

<?php
/*
 * Lokorin.com
 * Copyright 2004-2006
 * Licensed under the GNU LGPL. See COPYING for full terms.
 */
/**
 * Describes a library that handles everything related to timed events. The
 * timed events work very much as cron jobs except that they are checked on
 * every page load instead of being a running process.
 * @author Andreas Launila
 * @version $Revision: 1.2 $
 * @package com.lokorin.lokorin.lib
 * @license http://www.gnu.org/copyleft/lesser.html GNU Lesser General Public License
 */
 
/**
 * For access to common constants and functions.
 */
require_once('common.php');
 
/**
 * Gets all events that are due to be performed.
 * @return array An array of instances of TimedEvent. Each instance represents
 *          one event that should be performed. An empty array is returned if there
 *          are no due events.
 */
function getDueEvents() {
    global $db;
 
    $rows = $db->querySelect(TABLE_EVENTS, array("id"), 
        "WHERE `next_time` <= " . $db->escape(time()));
    $events = array();
    foreach($rows as $row) {
        $events[] = new TimedEvent($row["id"]);
    }
    return $events;
}
 
/**
 * Describes an event that is schedudled to be run every so often.
 * @author Andreas Launila
 * @package com.lokorin.lokorin.lib
 */
class TimedEvent extends TableEntry {
    /**
     * A description of the event.
     * @var string 
     */
    private $decsription;
    /**
     * A timestamp that describes the next point in time when the event should
     * be performed.
     * @var integer 
     */
    private $nextTime;
    /**
     * The name of the library that should be included before the event is run
     * and before the callback is called. If it's empty then no library is
     * included.
     * @var string 
     */
    private $libraryName;
    /**
     * The callback that should be called when the event is to be performed.
     * @var string 
     */
    private $callback;
    /**
     * A timestamp pattern for the timestamp that should be used as the next
     * point in time that the event should be triggered on failure.
     * @var string 
     */
    private $timestampFailure;
    /**
     * A timestamp pattern for the timestamp that should be used as the next
     * point in time that the event should be triggered on success.
     * @var string 
     */
    private $timestampSuccess;
    
    /**
     * Constructor for TimedEvent.
     * @param integer $id The unique identifier for the timed event.
     */
    public function __construct($id) {
        $fields = array(
            "description",
            "next_time",
            "library_name",
            "callback",
            "timestamp_failure",
            "timestamp_success"
        );
        parent::__construct(TABLE_EVENTS, $id, $fields);
    }
    
    /**
     * @see com.lokorin.dfcrafters.TableEntry.readRow($row)
     */
    public function readRow($row) {
        $this->description = $row["description"];
        $this->nextTime = $row["next_time"];
        $this->libraryName = $row["library_name"];
        $this->callback = $row["callback"];
        $this->timestampFailure = $row["timestamp_failure"];
        $this->timestampSuccess = $row["timestamp_success"];
    }
    
    /**
     * Gets a brief description of the event.
     * @return string A short description or name.
     */
    public function getDesciption() {
        return $this->description;
    }
    
    /**
     * Performs the event, correctly processing it and marking it as performed.
     * That means that it will not be performed again until a set number of
     * seconds have elapsed.
     */
    public function performEvent() {
        //Update the time as if a failure had occured before attempting the
        //event, this is to avoid double hits.
        $this->markAsPerformed($this->timestampFailure);
        
        //Load the libraries.
        if(strlen($this->libraryName) != '') {
            doInclude($this->libraryName);
        }
        
        //Call the callback.
        try {
            $callback = $this->callback;
            $callback();
            $this->markAsPerformed($this->timestampSuccess);
        } catch(Exception $e) {
            logException($e);
        }
    }
    
    /**
     * Marks the event as performed, updating the next time that it should be
     * performed.
     * @var string $timestampPattern The timestamp patternt that describes the
     *          next time that the event hsould be performed.
     * @throws IllegalArgumentException If the string is not a valid timestamp
     *          pattern.
     */
    private function markAsPerformed($timestampPattern) {
        //Validate the pattern.
        $matches = array();
        //floor|
        preg_match_all("/(floor|time|[0-9*()+-\/\s])+/", $timestampPattern, $matches);
        if(implode($matches[0]) != $timestampPattern) {
            throw new IllegalArgumentException("The pattern (".
                    $timestampPattern.") is not a valid timestamp pattern.");
        }
        
        //Get the new timestamp to use.
        ob_start();
        eval('echo '.$timestampPattern.';');
        $timestamp = ob_get_clean();
        
        //Enter it into the database.
        global $db;
        $vars = array(
            "next_time" => $timestamp
        );
        $idFields = array(
            "id"    => parent::$this->getId()
        );
        $db->queryUpdate(TABLE_EVENTS, $vars, $db->buildSqlSelector($idFields));
    }
}
 
?>