class.event.php

<?php
/**
 * @package toolkit
 */

/**
 * The abstract Event classes defines some base methods that all Events inherit.
 * It has one abstract method, `__trigger()`, which Events must implement. Event
 * execution is determined based on an action (which maps to a form action
 * from the Frontend). A load function determines whether this Event matches
 * the action and if so, call the Event's `__trigger()` to run the logic. On every page
 * load, all Event's that are attached to the page will have their load function's executed.
 * Events are called in order of their priority and if there is more than one event
 * with the same priority, in alphabetical order. An event class is saved through the
 * Symphony backend, which uses an event template defined in `TEMPLATE . /event.tpl`
 * Events implement the iEvent interface, which defines the load and about functions.
 *
 * @link http://getsymphony.com/learn/concepts/view/events/
 */
abstract class Event
{
    /**
     * Represents High Priority, that this event should run first
     * @var integer
     */
    const kHIGH = 3;

    /**
     * Represents Normal Priority, that this event should run normally.
     * This is the default Event Priority
     * @var integer
     */
    const kNORMAL = 2;

    /**
     * Represents High Priority, that this event should run last
     * @var integer
     */
    const kLOW = 1;

    /**
     * Holds all the environment variables which include parameters set
     * by other Datasources or Events.
     * @var array
     */
    protected $_env = array();

    /**
     * The constructor for an Event sets `$this->_env` from the given parameters
     *
     * @param array $env
     *  The environment variables from the Frontend class which includes
     *  any params set by Symphony or Datasources or by other Events
     */
    public function __construct(array $env = null)
    {
        $this->_env = $env;
    }

    /**
     * This function is required in order to edit it in the event editor page.
     * Do not overload this function if you are creating a custom event. It is only
     * used by the event editor.
     *
     * @return boolean
     *   true if event can be edited, false otherwise. Defaults to false
     */
    public static function allowEditorToParse()
    {
        return false;
    }

    /**
     * This function is required in order to identify what section this event is for. It
     * is used in the event editor. It must remain intact. Do not overload this function in
     * custom events.
     *
     * @return string|integer|null
     */
    public static function getSource()
    {
        return null;
    }

    /**
     * Returns a string of HTML or an XMLElement of documentation for the current event.
     * By default this will be an example of a HTML form that can populate the chosen section and
     * any filter information. Documentation is shown in the Symphony backend when a user tries to
     * edit an event but it's `allowEditorToParse()` returns `false`. If this is not implemented by
     * the event, a default Symphony message will appear.
     *
     * @return string|XMLElement
     */
    public static function documentation()
    {
        return __('This event has been customised and cannot be viewed from Symphony.');
    }

    /**
     * Returns the path to the email-notification-template by looking at the
     * `WORKSPACE/template/` directory, then at the `TEMPLATES`
     * directory for the convention `notification.*.tpl`. If the template
     * is not found, false is returned
     *
     * @param string $language
     *  Language used in system
     * @return mixed
     *  String, which is the path to the template if the template is found,
     *  false otherwise
     */
    public static function getNotificationTemplate($language)
    {
        $langformat = '%s/email.entrycreated.%s.tpl';
        $defaultformat = '%s/email.entrycreated.tpl';

        if (file_exists($template = sprintf($langformat, WORKSPACE . '/template', $language))) {
            return $template;
        } elseif (file_exists($template = sprintf($defaultformat, WORKSPACE . '/template'))) {
            return $template;
        } elseif (file_exists($template = sprintf($langformat, TEMPLATE, $language))) {
            return $template;
        } elseif (file_exists($template = sprintf($defaultformat, TEMPLATE))) {
            return $template;
        } else {
            return false;
        }
    }


    /**
     * Priority determines Event importance and when it should be executed.
     * The default priority for an event is `Event::kNORMAL`, with `Event::kHIGH` and
     * `Event::kLOW` being the other available options. Events execution is `Event::kHIGH`
     * to `Event::kNORMAL` to `Event::kLOW`. If there are more than one event at the
     * same priority level, they are sorted alphabetically by event handle and executed
     * in that order for that priority.
     *
     * @see toolkit.FrontendPage#__findEventOrder()
     * @return integer
     *  The available constants are `Event::kLOW`, `Event::kNORMAL` and `Event::kHIGH`.
     *  Defaults to `Event::kNORMAL`
     */
    public function priority()
    {
        return self::kNORMAL;
    }

    /**
     * This function must be included in an event. The purpose of this function
     * is to define the logic of this particular event. It assumes that this event
     * has already been triggered from the load function
     *
     * @since Symphony 2.3
     * @return XMLElement
     *  Returns an `XMLElement` with the event information (success or failure included)
     */
    protected function __trigger()
    {
        // this is a hack, due to lack of missing iEvent implementations
        if (!is_callable([$this, 'execute'])) {
            throw new Exception('Can not trigger event, missing execute() function');
        }
        return $this->execute();
    }
}