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          */
  77         public static function setContent(& $arr, $value) {
  78                 if (is_array($value))
  79                         ApiBase :: dieDebug(__METHOD__, 'Bad parameter');
  80                 ApiResult :: setElement($arr, '*', $value);
  81         }
  82
  83         //      public static function makeContentElement($tag, $value) {
  84         //              $result = array();
  85         //              ApiResult::setContent($result, )
  86         //      }
  87         //
  88         /**
  89          * In case the array contains indexed values (in addition to named),
  90          * all indexed values will have the given tag name.
  91          */
  92         public static function setIndexedTagName(& $arr, $tag) {
  93                 // Do not use setElement() as it is ok to call this more than once
  94                 if ($arr === null || $tag === null || !is_array($arr) || is_array($tag))
  95                         ApiBase :: dieDebug(__METHOD__, 'Bad parameter');
  96                 $arr['_element'] = $tag;
  97         }
  98
  99         /**
 100          * Add value to the output data at the given path.
 101          * Path is an indexed array, each element specifing the branch at which to add the new value
 102          * Setting $path to array('a','b','c') is equivalent to data['a']['b']['c'] = $value
 103          */
 104         public function addValue($path, $name, $value) {
 105
 106                 $data = & $this->getData();
 107
 108                 if (!is_null($path)) {
 109                         if (is_array($path)) {
 110                                 foreach ($path as $p) {
 111                                         if (!isset ($data[$p]))
 112                                                 $data[$p] = array ();
 113                                         $data = & $data[$p];
 114                                 }
 115                         } else {
 116                                 if (!isset ($data[$path]))
 117                                         $data[$path] = array ();
 118                                 $data = & $data[$path];
 119                         }
 120                 }
 121
 122                 ApiResult :: setElement($data, $name, $value);
 123         }
 124
 125         /**
 126         * Recursivelly removes any elements from the array that begin with an '_'.
 127         * The content element '*' is the only special element that is left.
 128         * Use this method when the entire data object gets sent to the user.
 129         */
 130         public function SanitizeData() {
 131                 ApiResult :: SanitizeDataInt($this->mData);
 132         }
 133
 134         private static function SanitizeDataInt(& $data) {
 135                 foreach ($data as $key => & $value) {
 136                         if ($key[0] === '_') {
 137                                 unset ($data[$key]);
 138                         }
 139                         elseif (is_array($value)) {
 140                                 ApiResult :: SanitizeDataInt($value);
 141                         }
 142                 }
 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 ?>