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, $mIsRawMode;
  35
  36         /**
  37         * Constructor
  38         */
  39         public function __construct($main) {
  40                 parent :: __construct($main, 'result');
  41                 $this->mIsRawMode = false;
  42                 $this->reset();
  43         }
  44
  45         public function reset() {
  46                 $this->mData = array ();
  47         }
  48
  49         /**
  50          * Call this function when special elements such as '_element'
  51          * are needed by the formatter, for example in XML printing.
  52          */
  53         public function setRawMode() {
  54                 $this->mIsRawMode = true;
  55         }
  56
  57         public function getIsRawMode() {
  58                 return $this->mIsRawMode;
  59         }
  60
  61         public function & getData() {
  62                 return $this->mData;
  63         }
  64
  65         /**
  66          * Add an output value to the array by name.
  67          * Verifies that value with the same name has not been added before.
  68          */
  69         public static function setElement(& $arr, $name, $value) {
  70                 if ($arr === null || $name === null || $value === null || !is_array($arr) || is_array($name))
  71                         ApiBase :: dieDebug(__METHOD__, 'Bad parameter');
  72
  73                 if (!isset ($arr[$name])) {
  74                         $arr[$name] = $value;
  75                 }
  76                 elseif (is_array($arr[$name]) && is_array($value)) {
  77                         $merged = array_intersect_key($arr[$name], $value);
  78                         if (empty ($merged))
  79                                 $arr[$name] += $value;
  80                         else
  81                                 ApiBase :: dieDebug(__METHOD__, "Attempting to merge element $name");
  82                 } else
  83                         ApiBase :: dieDebug(__METHOD__, "Attempting to add element $name=$value, existing value is {$arr[$name]}");
  84         }
  85
  86         /**
  87          * Adds the content element to the array.
  88          * Use this function instead of hardcoding the '*' element.
  89          * @param string $subElemName when present, content element is created as a sub item of the arr.
  90          *  Use this parameter to create elements in format <elem>text</elem> without attributes
  91          */
  92         public static function setContent(& $arr, $value, $subElemName = null) {
  93                 if (is_array($value))
  94                         ApiBase :: dieDebug(__METHOD__, 'Bad parameter');
  95                 if (is_null($subElemName)) {
  96                         ApiResult :: setElement($arr, '*', $value);
  97                 } else {
  98                         if (!isset ($arr[$subElemName]))
  99                                 $arr[$subElemName] = array ();
 100                         ApiResult :: setElement($arr[$subElemName], '*', $value);
 101                 }
 102         }
 103
 104         //      public static function makeContentElement($tag, $value) {
 105         //              $result = array();
 106         //              ApiResult::setContent($result, )
 107         //      }
 108         //
 109         /**
 110          * In case the array contains indexed values (in addition to named),
 111          * all indexed values will have the given tag name.
 112          */
 113         public function setIndexedTagName(& $arr, $tag) {
 114                 // In raw mode, add the '_element', otherwise just ignore
 115                 if (!$this->getIsRawMode())
 116                         return;
 117                 if ($arr === null || $tag === null || !is_array($arr) || is_array($tag))
 118                         ApiBase :: dieDebug(__METHOD__, 'Bad parameter');
 119                 // Do not use setElement() as it is ok to call this more than once
 120                 $arr['_element'] = $tag;
 121         }
 122
 123         /**
 124          * Add value to the output data at the given path.
 125          * Path is an indexed array, each element specifing the branch at which to add the new value
 126          * Setting $path to array('a','b','c') is equivalent to data['a']['b']['c'] = $value
 127          */
 128         public function addValue($path, $name, $value) {
 129
 130                 $data = & $this->getData();
 131
 132                 if (!is_null($path)) {
 133                         if (is_array($path)) {
 134                                 foreach ($path as $p) {
 135                                         if (!isset ($data[$p]))
 136                                                 $data[$p] = array ();
 137                                         $data = & $data[$p];
 138                                 }
 139                         } else {
 140                                 if (!isset ($data[$path]))
 141                                         $data[$path] = array ();
 142                                 $data = & $data[$path];
 143                         }
 144                 }
 145
 146                 ApiResult :: setElement($data, $name, $value);
 147         }
 148
 149         public function execute() {
 150                 ApiBase :: dieDebug(__METHOD__, 'execute() is not supported on Result object');
 151         }
 152
 153         public function getVersion() {
 154                 return __CLASS__ . ': $Id$';
 155         }
 156 }
 157 ?>