includes/api/ApiResult.php

   1 <?php
   2
   3
   4 /*
   5  * Created on Sep 4, 2006
   6  *
   7  * API for MediaWiki 1.8+
   8  *
   9  * Copyright (C) 2006 Yuri Astrakhan <FirstnameLastname@gmail.com>
  10  *
  11  * This program is free software; you can redistribute it and/or modify
  12  * it under the terms of the GNU General Public License as published by
  13  * the Free Software Foundation; either version 2 of the License, or
  14  * (at your option) any later version.
  15  *
  16  * This program is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  19  * GNU General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU General Public License along
  22  * with this program; if not, write to the Free Software Foundation, Inc.,
  23  * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  24  * http://www.gnu.org/copyleft/gpl.html
  25  */
  26
  27 if (!defined('MEDIAWIKI')) {
  28         // Eclipse helper - will be ignored in production
  29         require_once ('ApiBase.php');
  30 }
  31
  32 class ApiResult extends ApiBase {
  33
  34         private $mData;
  35
  36         /**
  37         * Constructor
  38         */
  39         public function __construct($main) {
  40                 parent :: __construct($main, 'result');
  41                 $this->Reset();
  42         }
  43
  44         public function Reset() {
  45                 $this->mData = array ();
  46         }
  47
  48         function & getData() {
  49                 return $this->mData;
  50         }
  51
  52         /**
  53          * Add an output value to the array by name.
  54          * Verifies that value with the same name has not been added before.
  55          */
  56         public static function setElement(& $arr, $name, $value) {
  57                 if ($arr === null || $name === null || $value === null || !is_array($arr) || is_array($name))
  58                         ApiBase :: dieDebug(__METHOD__, 'Bad parameter');
  59
  60                 if (!isset ($arr[$name])) {
  61                         $arr[$name] = $value;
  62                 }
  63                 elseif (is_array($arr[$name]) && is_array($value)) {
  64                         $merged = array_intersect_key($arr[$name], $value);
  65                         if (empty ($merged))
  66                                 $arr[$name] += $value;
  67                         else
  68                                 ApiBase :: dieDebug(__METHOD__, "Attempting to merge element $name");
  69                 } else
  70                         ApiBase :: dieDebug(__METHOD__, "Attempting to add element $name=$value, existing value is {$arr[$name]}");
  71         }
  72
  73         /**
  74          * Adds the content element to the array.
  75          * Use this function instead of hardcoding the '*' element.
  76          * @param string $subElemName when present, content element is created as a sub item of the arr.
  77          *  Use this parameter to create elements in format <elem>text</elem> without attributes
  78          */
  79         public static function setContent(& $arr, $value, $subElemName = null) {
  80                 if (is_array($value))
  81                         ApiBase :: dieDebug(__METHOD__, 'Bad parameter');
  82                 if (is_null($subElemName)) {
  83                         ApiResult :: setElement($arr, '*', $value);
  84                 } else {
  85                         if (!isset ($arr[$subElemName]))
  86                                 $arr[$subElemName] = array ();
  87                         ApiResult :: setElement($arr[$subElemName], '*', $value);
  88                 }
  89         }
  90
  91         //      public static function makeContentElement($tag, $value) {
  92         //              $result = array();
  93         //              ApiResult::setContent($result, )
  94         //      }
  95         //
  96         /**
  97          * In case the array contains indexed values (in addition to named),
  98          * all indexed values will have the given tag name.
  99          */
 100         public static function setIndexedTagName(& $arr, $tag) {
 101                 // Do not use setElement() as it is ok to call this more than once
 102                 if ($arr === null || $tag === null || !is_array($arr) || is_array($tag))
 103                         ApiBase :: dieDebug(__METHOD__, 'Bad parameter');
 104                 $arr['_element'] = $tag;
 105         }
 106
 107         /**
 108          * Add value to the output data at the given path.
 109          * Path is an indexed array, each element specifing the branch at which to add the new value
 110          * Setting $path to array('a','b','c') is equivalent to data['a']['b']['c'] = $value
 111          */
 112         public function addValue($path, $name, $value) {
 113
 114                 $data = & $this->getData();
 115
 116                 if (!is_null($path)) {
 117                         if (is_array($path)) {
 118                                 foreach ($path as $p) {
 119                                         if (!isset ($data[$p]))
 120                                                 $data[$p] = array ();
 121                                         $data = & $data[$p];
 122                                 }
 123                         } else {
 124                                 if (!isset ($data[$path]))
 125                                         $data[$path] = array ();
 126                                 $data = & $data[$path];
 127                         }
 128                 }
 129
 130                 ApiResult :: setElement($data, $name, $value);
 131         }
 132
 133         /**
 134         * Recursivelly removes any elements from the array that begin with an '_'.
 135         * The content element '*' is the only special element that is left.
 136         * Use this method when the entire data object gets sent to the user.
 137         */
 138         public function SanitizeData() {
 139                 ApiResult :: SanitizeDataInt($this->mData);
 140         }
 141
 142         private static function SanitizeDataInt(& $data) {
 143                 foreach ($data as $key => & $value) {
 144                         if ($key[0] === '_') {
 145                                 unset ($data[$key]);
 146                         }
 147                         elseif (is_array($value)) {
 148                                 ApiResult :: SanitizeDataInt($value);
 149                         }
 150                 }
 151         }
 152
 153         public function execute() {
 154                 ApiBase :: dieDebug(__METHOD__, 'execute() is not supported on Result object');
 155         }
 156
 157         public function getVersion() {
 158                 return __CLASS__ . ': $Id$';
 159         }
 160 }
 161 ?>