includes/Status.php

   1 <?php
   2 /**
   3  * Generic operation result.
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  */
  22
  23 /**
  24  * Generic operation result class
  25  * Has warning/error list, boolean status and arbitrary value
  26  *
  27  * "Good" means the operation was completed with no warnings or errors.
  28  *
  29  * "OK" means the operation was partially or wholly completed.
  30  *
  31  * An operation which is not OK should have errors so that the user can be
  32  * informed as to what went wrong. Calling the fatal() function sets an error
  33  * message and simultaneously switches off the OK flag.
  34  *
  35  * The recommended pattern for Status objects is to return a Status object
  36  * unconditionally, i.e. both on success and on failure -- so that the
  37  * developer of the calling code is reminded that the function can fail, and
  38  * so that a lack of error-handling will be explicit.
  39  */
  40 class Status {
  41         var $ok = true;
  42         var $value;
  43
  44         /** Counters for batch operations */
  45         public $successCount = 0, $failCount = 0;
  46         /** Array to indicate which items of the batch operations were successful */
  47         public $success = array();
  48
  49         /*semi-private*/ var $errors = array();
  50         /*semi-private*/ var $cleanCallback = false;
  51
  52         /**
  53          * Factory function for fatal errors
  54          *
  55          * @param string|Message $message message name or object
  56          * @return Status
  57          */
  58         static function newFatal( $message /*, parameters...*/ ) {
  59                 $params = func_get_args();
  60                 $result = new self;
  61                 call_user_func_array( array( &$result, 'error' ), $params );
  62                 $result->ok = false;
  63                 return $result;
  64         }
  65
  66         /**
  67          * Factory function for good results
  68          *
  69          * @param $value Mixed
  70          * @return Status
  71          */
  72         static function newGood( $value = null ) {
  73                 $result = new self;
  74                 $result->value = $value;
  75                 return $result;
  76         }
  77
  78         /**
  79          * Change operation result
  80          *
  81          * @param $ok Boolean: whether the operation completed
  82          * @param $value Mixed
  83          */
  84         function setResult( $ok, $value = null ) {
  85                 $this->ok = $ok;
  86                 $this->value = $value;
  87         }
  88
  89         /**
  90          * Returns whether the operation completed and didn't have any error or
  91          * warnings
  92          *
  93          * @return Boolean
  94          */
  95         function isGood() {
  96                 return $this->ok && !$this->errors;
  97         }
  98
  99         /**
 100          * Returns whether the operation completed
 101          *
 102          * @return Boolean
 103          */
 104         function isOK() {
 105                 return $this->ok;
 106         }
 107
 108         /**
 109          * Add a new warning
 110          *
 111          * @param string|Message $message message name or object
 112          */
 113         function warning( $message /*, parameters... */ ) {
 114                 $params = array_slice( func_get_args(), 1 );
 115                 $this->errors[] = array(
 116                         'type' => 'warning',
 117                         'message' => $message,
 118                         'params' => $params );
 119         }
 120
 121         /**
 122          * Add an error, do not set fatal flag
 123          * This can be used for non-fatal errors
 124          *
 125          * @param string|Message $message message name or object
 126          */
 127         function error( $message /*, parameters... */ ) {
 128                 $params = array_slice( func_get_args(), 1 );
 129                 $this->errors[] = array(
 130                         'type' => 'error',
 131                         'message' => $message,
 132                         'params' => $params );
 133         }
 134
 135         /**
 136          * Add an error and set OK to false, indicating that the operation
 137          * as a whole was fatal
 138          *
 139          * @param string|Message $message message name or object
 140          */
 141         function fatal( $message /*, parameters... */ ) {
 142                 $params = array_slice( func_get_args(), 1 );
 143                 $this->errors[] = array(
 144                         'type' => 'error',
 145                         'message' => $message,
 146                         'params' => $params );
 147                 $this->ok = false;
 148         }
 149
 150         /**
 151          * Sanitize the callback parameter on wakeup, to avoid arbitrary execution.
 152          */
 153         function __wakeup() {
 154                 $this->cleanCallback = false;
 155         }
 156
 157         /**
 158          * @param $params array
 159          * @return array
 160          */
 161         protected function cleanParams( $params ) {
 162                 if ( !$this->cleanCallback ) {
 163                         return $params;
 164                 }
 165                 $cleanParams = array();
 166                 foreach ( $params as $i => $param ) {
 167                         $cleanParams[$i] = call_user_func( $this->cleanCallback, $param );
 168                 }
 169                 return $cleanParams;
 170         }
 171
 172         /**
 173          * Get the error list as a wikitext formatted list
 174          *
 175          * @param string $shortContext a short enclosing context message name, to
 176          *        be used when there is a single error
 177          * @param string $longContext a long enclosing context message name, for a list
 178          * @return String
 179          */
 180         function getWikiText( $shortContext = false, $longContext = false ) {
 181                 if ( count( $this->errors ) == 0 ) {
 182                         if ( $this->ok ) {
 183                                 $this->fatal( 'internalerror_info',
 184                                         __METHOD__ . " called for a good result, this is incorrect\n" );
 185                         } else {
 186                                 $this->fatal( 'internalerror_info',
 187                                         __METHOD__ . ": Invalid result object: no error text but not OK\n" );
 188                         }
 189                 }
 190                 if ( count( $this->errors ) == 1 ) {
 191                         $s = $this->getErrorMessage( $this->errors[0] );
 192                         if ( $shortContext ) {
 193                                 $s = wfMessage( $shortContext, $s )->plain();
 194                         } elseif ( $longContext ) {
 195                                 $s = wfMessage( $longContext, "* $s\n" )->plain();
 196                         }
 197                 } else {
 198                         $s = '* ' . implode( "\n* ",
 199                                 $this->getErrorMessageArray( $this->errors ) ) . "\n";
 200                         if ( $longContext ) {
 201                                 $s = wfMessage( $longContext, $s )->plain();
 202                         } elseif ( $shortContext ) {
 203                                 $s = wfMessage( $shortContext, "\n$s\n" )->plain();
 204                         }
 205                 }
 206                 return $s;
 207         }
 208
 209         /**
 210          * Return the message for a single error.
 211          * @param $error Mixed With an array & two values keyed by
 212          * 'message' and 'params', use those keys-value pairs.
 213          * Otherwise, if its an array, just use the first value as the
 214          * message and the remaining items as the params.
 215          *
 216          * @return String
 217          */
 218         protected function getErrorMessage( $error ) {
 219                 if ( is_array( $error ) ) {
 220                         if ( isset( $error['message'] ) && $error['message'] instanceof Message ) {
 221                                 $msg = $error['message'];
 222                         } elseif ( isset( $error['message'] ) && isset( $error['params'] ) ) {
 223                                 $msg = wfMessage( $error['message'],
 224                                         array_map( 'wfEscapeWikiText', $this->cleanParams( $error['params'] ) ) );
 225                         } else {
 226                                 $msgName = array_shift( $error );
 227                                 $msg = wfMessage( $msgName,
 228                                         array_map( 'wfEscapeWikiText', $this->cleanParams( $error ) ) );
 229                         }
 230                 } else {
 231                         $msg = wfMessage( $error );
 232                 }
 233                 return $msg->plain();
 234         }
 235
 236         /**
 237          * Get the error message as HTML. This is done by parsing the wikitext error
 238          * message.
 239          *
 240          * @note: this does not perform a full wikitext to HTML conversion, it merely applies
 241          *        a message transformation.
 242          * @todo figure out whether that is actually The Right Thing.
 243          */
 244         public function getHTML( $shortContext = false, $longContext = false ) {
 245                 $text = $this->getWikiText( $shortContext, $longContext );
 246                 return MessageCache::singleton()->transform( $text, true );
 247         }
 248
 249         /**
 250          * Return an array with the wikitext for each item in the array.
 251          * @param $errors Array
 252          * @return Array
 253          */
 254         protected function getErrorMessageArray( $errors ) {
 255                 return array_map( array( $this, 'getErrorMessage' ), $errors );
 256         }
 257
 258         /**
 259          * Merge another status object into this one
 260          *
 261          * @param $other Status Other Status object
 262          * @param $overwriteValue Boolean: whether to override the "value" member
 263          */
 264         function merge( $other, $overwriteValue = false ) {
 265                 $this->errors = array_merge( $this->errors, $other->errors );
 266                 $this->ok = $this->ok && $other->ok;
 267                 if ( $overwriteValue ) {
 268                         $this->value = $other->value;
 269                 }
 270                 $this->successCount += $other->successCount;
 271                 $this->failCount += $other->failCount;
 272         }
 273
 274         /**
 275          * Get the list of errors (but not warnings)
 276          *
 277          * @return array A list in which each entry is an array with a message key as its first element.
 278          *         The remaining array elements are the message parameters.
 279          */
 280         function getErrorsArray() {
 281                 return $this->getStatusArray( "error" );
 282         }
 283
 284         /**
 285          * Get the list of warnings (but not errors)
 286          *
 287          * @return array A list in which each entry is an array with a message key as its first element.
 288          *         The remaining array elements are the message parameters.
 289          */
 290         function getWarningsArray() {
 291                 return $this->getStatusArray( "warning" );
 292         }
 293
 294         /**
 295          * Returns a list of status messages of the given type
 296          * @param $type String
 297          *
 298          * @return Array
 299          */
 300         protected function getStatusArray( $type ) {
 301                 $result = array();
 302                 foreach ( $this->errors as $error ) {
 303                         if ( $error['type'] === $type ) {
 304                                 if ( $error['message'] instanceof Message ) {
 305                                         $result[] = array_merge( array( $error['message']->getKey() ), $error['message']->getParams() );
 306                                 } elseif ( $error['params'] ) {
 307                                         $result[] = array_merge( array( $error['message'] ), $error['params'] );
 308                                 } else {
 309                                         $result[] = array( $error['message'] );
 310                                 }
 311                         }
 312                 }
 313                 return $result;
 314         }
 315
 316         /**
 317          * Returns a list of status messages of the given type, with message and
 318          * params left untouched, like a sane version of getStatusArray
 319          *
 320          * @param $type String
 321          *
 322          * @return Array
 323          */
 324         public function getErrorsByType( $type ) {
 325                 $result = array();
 326                 foreach ( $this->errors as $error ) {
 327                         if ( $error['type'] === $type ) {
 328                                 $result[] = $error;
 329                         }
 330                 }
 331                 return $result;
 332         }
 333
 334         /**
 335          * Returns true if the specified message is present as a warning or error
 336          *
 337          * Note, due to the lack of tools for comparing Message objects, this
 338          * function will not work when using a Message object as a parameter.
 339          *
 340          * @param string $msg message name
 341          * @return Boolean
 342          */
 343         function hasMessage( $msg ) {
 344                 foreach ( $this->errors as $error ) {
 345                         if ( $error['message'] === $msg ) {
 346                                 return true;
 347                         }
 348                 }
 349                 return false;
 350         }
 351
 352         /**
 353          * If the specified source message exists, replace it with the specified
 354          * destination message, but keep the same parameters as in the original error.
 355          *
 356          * Note, due to the lack of tools for comparing Message objects, this
 357          * function will not work when using a Message object as the search parameter.
 358          *
 359          * @param $source Message|String: Message key or object to search for
 360          * @param $dest Message|String: Replacement message key or object
 361          * @return bool Return true if the replacement was done, false otherwise.
 362          */
 363         function replaceMessage( $source, $dest ) {
 364                 $replaced = false;
 365                 foreach ( $this->errors as $index => $error ) {
 366                         if ( $error['message'] === $source ) {
 367                                 $this->errors[$index]['message'] = $dest;
 368                                 $replaced = true;
 369                         }
 370                 }
 371                 return $replaced;
 372         }
 373
 374         /**
 375          * Backward compatibility function for WikiError -> Status migration
 376          *
 377          * @return String
 378          */
 379         public function getMessage() {
 380                 return $this->getWikiText();
 381         }
 382
 383         /**
 384          * @return mixed
 385          */
 386         public function getValue() {
 387                 return $this->value;
 388         }
 389 }