includes/api/ApiResult.php

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