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