[Summary view]

   1  <?php
   2  
   3  // This file is part of Moodle - http://moodle.org/
   4  //
   5  // Moodle is free software: you can redistribute it and/or modify
   6  // it under the terms of the GNU General Public License as published by
   7  // the Free Software Foundation, either version 3 of the License, or
   8  // (at your option) any later version.
   9  //
  10  // Moodle is distributed in the hope that it will be useful,
  11  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  // GNU General Public License for more details.
  14  //
  15  // You should have received a copy of the GNU General Public License
  16  // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  17  
  18  /**
  19   * @package    moodlecore
  20   * @subpackage backup-structure
  21   * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
  22   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23   *
  24   * TODO: Finish phpdocs
  25   */
  26  
  27  /**
  28   * Abstract class representing one atom (name/value) piece of information
  29   */
  30  abstract class base_atom {
  31  
  32      /** @var string name of the element (maps to XML name) */
  33      private $name;
  34  
  35      /** @var string value of the element (maps to XML content) */
  36      private $value;
  37  
  38      /** @var bool flag to indicate when one value has been set (true) or no (false) */
  39      private $is_set;
  40  
  41      /**
  42       * Constructor - instantiates one base_atom, specifying its basic info.
  43       *
  44       * @param string $name name of the element
  45       * @param string $value optional value of the element
  46       */
  47      public function __construct($name) {
  48  
  49          $this->validate_name($name); // Check name
  50  
  51          $this->name  = $name;
  52          $this->value = null;
  53          $this->is_set= false;
  54      }
  55  
  56      protected function validate_name($name) {
  57          // Validate various name constraints, throwing exception if needed
  58          if (empty($name)) {
  59              throw new base_atom_struct_exception('backupatomemptyname', $name);
  60          }
  61          if (preg_replace('/\s/', '', $name) != $name) {
  62              throw new base_atom_struct_exception('backupatomwhitespacename', $name);
  63          }
  64          if (preg_replace('/[^\x30-\x39\x41-\x5a\x5f\x61-\x7a]/', '', $name) != $name) {
  65              throw new base_atom_struct_exception('backupatomnotasciiname', $name);
  66          }
  67      }
  68  
  69  /// Public API starts here
  70  
  71      public function get_name() {
  72          return $this->name;
  73      }
  74  
  75      public function get_value() {
  76          return $this->value;
  77      }
  78  
  79      public function set_value($value) {
  80          if ($this->is_set) {
  81              throw new base_atom_content_exception('backupatomalreadysetvalue', $value);
  82          }
  83          $this->value = $value;
  84          $this->is_set= true;
  85      }
  86  
  87      public function clean_value() {
  88          $this->value = null;
  89          $this->is_set= false;
  90      }
  91  
  92      public function is_set() {
  93          return $this->is_set;
  94      }
  95  
  96      public function to_string($showvalue = false) {
  97          $output = $this->name;
  98          if ($showvalue) {
  99              $value = $this->is_set ? $this->value : 'not set';
 100              $output .= ' => ' . $value;
 101          }
 102          return $output;
 103      }
 104  }
 105  
 106  /**
 107   * base_atom abstract exception class
 108   *
 109   * This exceptions will be used by all the base_atom classes
 110   * in order to detect any problem or miss-configuration
 111   */
 112  abstract class base_atom_exception extends moodle_exception {
 113  
 114      /**
 115       * Constructor - instantiates one base_atom_exception.
 116       *
 117       * @param string $errorcode key for the corresponding error string
 118       * @param object $a extra words and phrases that might be required in the error string
 119       * @param string $debuginfo optional debugging information
 120       */
 121      public function __construct($errorcode, $a = null, $debuginfo = null) {
 122          parent::__construct($errorcode, '', '', $a, $debuginfo);
 123      }
 124  }
 125  
 126  /**
 127   * base_atom exception to control all the errors while creating the objects
 128   *
 129   * This exception will be thrown each time the base_atom class detects some
 130   * inconsistency related with the creation of objects and their attributes
 131   * (wrong names)
 132   */
 133  class base_atom_struct_exception extends base_atom_exception {
 134  
 135      /**
 136       * Constructor - instantiates one base_atom_struct_exception
 137       *
 138       * @param string $errorcode key for the corresponding error string
 139       * @param object $a extra words and phrases that might be required in the error string
 140       * @param string $debuginfo optional debugging information
 141       */
 142      public function __construct($errorcode, $a = null, $debuginfo = null) {
 143          parent::__construct($errorcode, $a, $debuginfo);
 144      }
 145  }
 146  
 147  /**
 148   * base_atom exception to control all the errors while setting the values
 149   *
 150   * This exception will be thrown each time the base_atom class detects some
 151   * inconsistency related with the creation of contents (values) of the objects
 152   * (bad contents, setting without cleaning...)
 153   */
 154  class base_atom_content_exception extends base_atom_exception {
 155  
 156      /**
 157       * Constructor - instantiates one base_atom_content_exception
 158       *
 159       * @param string $errorcode key for the corresponding error string
 160       * @param object $a extra words and phrases that might be required in the error string
 161       * @param string $debuginfo optional debugging information
 162       */
 163      public function __construct($errorcode, $a = null, $debuginfo = null) {
 164          parent::__construct($errorcode, $a, $debuginfo);
 165      }
 166  }