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