servlet.php

Go to the documentation of this file.

<?php

  /*
  Easy PHP Framework

  Copyright (c) 2005 Michal Molhanec

  This software is provided 'as-is', without any express or implied
  warranty. In no event will the authors be held liable for any damages
  arising from the use of this software.

  Permission is granted to anyone to use this software for any purpose,
  including commercial applications, and to alter it and redistribute
  it freely, subject to the following restrictions:

      1. The origin of this software must not be misrepresented;
         you must not claim that you wrote the original software.
         If you use this software in a product, an acknowledgment
         in the product documentation would be appreciated but
         is not required.

      2. Altered source versions must be plainly marked as such,
         and must not be misrepresented as being the original software.

      3. This notice may not be removed or altered from any
         source distribution.
  */

  /**
   *  Base class for all servlets.
   */
  class Servlet {

    /// List with error messages.
    private $errorlist = array();
    /// DomDocument of the resulting page.
    private $doc;
    /// Base page DomElement
    private $page;

    /**
     *  Adds message to the errorlist.
     */
    function add_to_errorlist($msg) {
      $this->errorlist[] = $msg;
    }

    /**
     *  If the $errormsg is empty, it fills it with default text
     *  'Please enter $name.'
     *  @param[in,out] $errormsg Error message or empty string.
     *  @param[in] $name Name of required variable.
     */
    function fill_errormsg(&$errormsg, $name) {
      if ($errormsg == ''):
        $errormsg = "Please enter $name.";
      endif;
    }

    /**
     *  Requests a variable named $name from array $src and after
     *  converting it with $convertor() its put into $var.
     *  If its not found, error message $errormsg is inserted into
     *  error list.
     *  @param[in] $name Name of the variable.
     *  @param[out] $var Variable value.
     *  @param[in] $errormsg Error message.
     *  @param[in] $src Input array, typically $_GET, $_POST etc.
     *  @param[in] $convertor Convertor function. It should return TRUE
     *    on success, FALSE otherwise.
     */
    function req($name, &$var, $errormsg, $src, $convertor) {
      if (!isset($src[$name]) || !$this->$convertor($var, $src[$name])):
        $this->fill_errormsg($errormsg, $name);
        $this->add_to_errorlist($errormsg);
      endif;
    }

    /**
     *  Like req(), but if the variable is not found, it simply
     *  returns without generating an error and without
     *  touching $var.
     */
    function opt($name, &$var, $src, $convertor) {
      if (isset($src[$name])):
        $this->$convertor($var, $src[$name]);
      endif;
    }

    ///////////////////////////////////////////////////////////////
    //// Convertors
    ///////////////////////////////////////////////////////////////

    /// used by string_convert()
    private static $control_characters =
      "\x00\x01\x02\x03\x04\x05\x06\x07\x08\x0B\x0C\x0E\x0F\x10\x11\x12\x13\x14\x15\x16\x17\x18\x19\x1A\x1B\x1C\x1D\x1E\x1F";
    /// used by string_convert()
    private static $replacement = //str_repeat("\r", strlen(Servlet::$control_characters));
      "\x0D\x0D\x0D\x0D\x0D\x0D\x0D\x0D\x0D\x0D\x0D\x0D\x0D\x0D\x0D\x0D\x0D\x0D\x0D\x0D\x0D\x0D\x0D\x0D\x0D\x0D\x0D\x0D\x0D";

    /**
     *  String convertor for req() and opt().
     */
    function string_convert(&$var, $src) {
      // we remove all control (i.e. with ASCII value lower than 0x20 (space),
      // except of 0x0A (line feed) and 0x09 (tabulator)
      $src = strtr($src, Servlet::$control_characters, Servlet::$replacement);
      $src = str_replace("\r", '', $src);  // \r === \x0D
      $src = trim($src);
      if ($src === ''):
        return FALSE;
      endif;
      $var = $src;
      return TRUE;
    }

    /**
     *  Yes/No (good for radiobuttons) convertor for req() and opt().
     */
    function yesno_convert(&$var, $src) {
      switch ($src):
        case '1': $var = 1; break;
        case '0': $var = 0; break;
        default: return FALSE;
      endswitch;
      return TRUE;
    }

    /**
     *  On/Off (good for checkboxes) convertor for req() and opt().
     */
    function onoff_convert(&$var, $src) {
      if ($src):
        $var = 1;
      else:
        $var = 0;
      endif;
      return TRUE;
    }

    /**
     *  Integer convertor for req() and opt().
     */
    function int_convert(&$var, $src) {
      $src = (int) $src;
      if ($src === 0):
        return FALSE;
      endif;
      $var = $src;
      return TRUE;
    }
    
    /**
     *  Array convertor for req() and opt().
     */
    function array_convert(&$var, $src) {
      if (!is_array($src) or count($src) == 0):
        return FALSE;
      endif;
      $var = $src;
      return TRUE;
    }

    ///////////////////////////////////////////////////////////////
    //// xxx_yyyyy
    ///////////////////////////////////////////////////////////////

    function req_string($name, &$var, $errormsg, $src) {
      $this->req($name, $var, $errormsg, $src, 'string_convert');
    }

    function opt_string($name, &$var, $src) {
      $this->opt($name, $var, $src, 'string_convert');
    }

    function req_yesno($name, &$var, $errormsg, $src) {
      $this->req($name, $var, $errormsg, $src, 'yesno_convert');
    }

    function opt_yesno($name, &$var, $src) {
      $this->opt($name, $var, $src, 'yesno_convert');
    }

    function req_onoff($name, &$var, $errormsg, $src) {
      $this->req($name, $var, $errormsg, $src, 'onoff_convert');
    }

    function opt_onoff($name, &$var, $src) {
      $this->opt($name, $var, $src, 'onoff_convert');
    }

    function req_int($name, &$var, $errormsg, $src) {
      $this->req($name, $var, $errormsg, $src, 'int_convert');
    }

    function opt_int($name, &$var, $src) {
      $this->opt($name, $var, $src, 'int_convert');
    }

    function req_array($name, &$var, $errormsg, $src) {
      $this->req($name, $var, $errormsg, $src, 'array_convert');
    }

    function opt_array($name, &$var, $src) {
      $this->opt($name, $var, $src, 'array_convert');
    }

    ///////////////////////////////////////////////////////////////
    //// string
    ///////////////////////////////////////////////////////////////

    function req_post_string($name, &$var, $errormsg = '') {
      $this->req_string($name, $var, $errormsg, $_POST);
    }

    function req_get_string($name, &$var, $errormsg = '') {
      $this->req_string($name, $var, $errormsg, $_GET);
    }

    function opt_post_string($name, &$var) {
      $this->opt_string($name, $var, $_POST);
    }

    function opt_get_string($name, &$var) {
      $this->opt_string($name, $var, $_GET);
    }

    ///////////////////////////////////////////////////////////////
    //// yesno
    ///////////////////////////////////////////////////////////////

    function req_post_yesno($name, &$var, $errormsg = '') {
      $this->req_yesno($name, $var, $errormsg, $_POST);
    }

    function req_get_yesno($name, &$var, $errormsg = '') {
      $this->req_yesno($name, $var, $errormsg, $_GET);
    }

    function opt_post_yesno($name, &$var) {
      $this->opt_yesno($name, $var, $_POST);
    }

    function opt_get_yesno($name, &$var) {
      $this->opt_yesno($name, $var, $_GET);
    }

    ///////////////////////////////////////////////////////////////
    //// onoff
    ///////////////////////////////////////////////////////////////

    function req_post_onoff($name, &$var, $errormsg = '') {
      $this->req_onoff($name, $var, $errormsg, $_POST);
    }

    function req_get_onoff($name, &$var, $errormsg = '') {
      $this->req_onoff($name, $var, $errormsg, $_GET);
    }

    function opt_post_onoff($name, &$var) {
      $this->opt_onoff($name, $var, $_POST);
    }

    function opt_get_onoff($name, &$var) {
      $this->opt_onoff($name, $var, $_GET);
    }

    ///////////////////////////////////////////////////////////////
    //// int
    ///////////////////////////////////////////////////////////////

    function req_post_int($name, &$var, $errormsg = '') {
      $this->req_int($name, $var, $errormsg, $_POST);
    }

    function req_get_int($name, &$var, $errormsg = '') {
      $this->req_int($name, $var, $errormsg, $_GET);
    }

    function opt_post_int($name, &$var) {
      $this->opt_int($name, $var, $_POST);
    }

    function opt_get_int($name, &$var) {
      $this->opt_int($name, $var, $_GET);
    }

    ///////////////////////////////////////////////////////////////
    //// array
    ///////////////////////////////////////////////////////////////

    function req_post_array($name, &$var, $errormsg = '') {
      $this->req_array($name, $var, $errormsg, $_POST);
    }

    function req_get_array($name, &$var, $errormsg = '') {
      $this->req_array($name, $var, $errormsg, $_GET);
    }

    function opt_post_array($name, &$var) {
      $this->opt_array($name, $var, $_POST);
    }

    function opt_get_array($name, &$var) {
      $this->opt_array($name, $var, $_GET);
    }

    ///////////////////////////////////////////////////////////////
    //// rest
    ///////////////////////////////////////////////////////////////

    /**
     *  This function is called after starting the servlet, to check
     *  if all required parameters are OK. Instead of just throwing
     *  an exception on error, it should locate as much of problems
     *  as possible and add then to the error list.
     *  This function MAY NOT generate any page content.
     *  @throw Exception If it throws exception, its message is shown
     *    as an error message.
     */
    function validate_input() {}
    
    /**
     *  You should do your application logic here.
     *  @throw Exception It should throw expcetion on error.
     */
    function work() {}
    
    /**
     *  This should return page name without extension. Based on this value
     *  it is located XSLT stylesheet in the view subdir.
     *  On default it returns 'index'.
     */
    function get_page_name() { return 'index'; }
    
    /**
     *  This should return page title.
     */
    function get_title() { return ''; }
    
    /**
     *  This should return page URL. By default it returns
     *  $this->get_page_name() . '.php'. See sources for
     *  exact behaviour.
     */
    function get_referer() {
      $pagename = $this->get_page_name();
      if ($pagename == 'index' or starts_with('do_', $pagename)):
        return '';
      endif;
      return $pagename . '.php';
    }


    /**
     *  Call this on your servlet to start the action.
     */
    function run() {
      $this->create_doc();
      
      try {
        $this->validate_input();
      } catch (Exception $e) {
        $this->add_to_errorlist($e->getMessage());
      }

      if (count($this->errorlist) > 0):
        foreach ($this->errorlist as $errormsg):
          $this->add('msg', array('desc' => $errormsg));
        endforeach;
        $this->show('error');
        exit;
      endif;

      try {
        $this->work();
      } catch (Exception $e) {
        $this->create_doc(); // reset the document
        $this->add('msg', array('desc' => $e->getMessage()));
        $this->show('error');
        exit;
      }

      $this->show($this->get_page_name());
    }

    /**
     *  Resets the output document.
     */
    function create_doc() {
      $this->doc = new DomDocument();
      $this->page = $this->doc->createElement('page');
      $this->doc->appendChild($this->page);
    }

    /**
     *  Adds page attribute.
     */
    function page_attr($name, $value) {
      $this->page->setAttribute($name, $value);
    }

    /**
     *  Adds page elements.
     *  @param $name Name of container element.
     *  @param $elems Array of DOMNodes.
     *  @param $where Element under which will be the new container
     *    element containing $elems appended. If NULL, $this->page is used.
     */
    function page_elems($name, $elems, $where=NULL) {
      $container = $this->doc->createElement($name);
      foreach ($elems as $elem):
        $container->appendChild($elem);
      endforeach;
      if (!$where):
        $where = $this->page;
      endif;
      $where->appendChild($container);
    }


    /**
     *  Adds attributes.
     *  @param $name Name of new page element.
     *  @param $attrs Array of attributes. Element of the array can be
     *    string, in which case is added like in page_attr(),
     *    or array, in which case is added like page_elems().
     */
    function add($name, $attrs) {
      $elem = $this->doc->createElement($name);
      foreach ($attrs as $name => $value):
        if (is_array($value)):
          $this->page_elems($name, $value, $elem);
        else:
          $elem->setAttribute($name, $value);
        endif;
      endforeach;
      $this->page->appendChild($elem);
    }

    /**
     *  Renders page to HTML and sends it to browser.
     *  @param $pagename Name of the XSLT stylesheet without extension.
     */
    function show($pagename) {
      $xsl = new DomDocument();
      $xsl->load("view/$pagename.xsl");

      $proc = new xsltprocessor();
      $proc->importStylesheet($xsl);

      $this->page_attr('title', $this->get_title());

      $referer = $this->get_referer();
      if ($referer):
        $this->page_attr('referer', '?r=' . url($referer));
      endif;
      
      if (isset($_SESSION['user'])):
        $this->page_attr('login', $_SESSION['user']['name']);
      endif;
      
      echo $proc->transformToXML($this->doc);
    }

    /**
     *  @return Page DOMDocument.
     */
    function get_doc() {
      return $this->doc;
    }

    /**
     *  @return Root page element.
     */
    function get_page() {
      return $this->page;
    }

  }
  
?>

---