includes/libs/StatusValue.php

   1 <?php
   2 /**
   3  * This program is free software; you can redistribute it and/or modify
   4  * it under the terms of the GNU General Public License as published by
   5  * the Free Software Foundation; either version 2 of the License, or
   6  * (at your option) any later version.
   7  *
   8  * This program is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  11  * GNU General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License along
  14  * with this program; if not, write to the Free Software Foundation, Inc.,
  15  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  16  * http://www.gnu.org/copyleft/gpl.html
  17  *
  18  * @file
  19  */
  20
  21 /**
  22  * Generic operation result class
  23  * Has warning/error list, boolean status and arbitrary value
  24  *
  25  * "Good" means the operation was completed with no warnings or errors.
  26  *
  27  * "OK" means the operation was partially or wholly completed.
  28  *
  29  * An operation which is not OK should have errors so that the user can be
  30  * informed as to what went wrong. Calling the fatal() function sets an error
  31  * message and simultaneously switches off the OK flag.
  32  *
  33  * The recommended pattern for Status objects is to return a StatusValue
  34  * unconditionally, i.e. both on success and on failure -- so that the
  35  * developer of the calling code is reminded that the function can fail, and
  36  * so that a lack of error-handling will be explicit.
  37  *
  38  * The use of Message objects should be avoided when serializability is needed.
  39  *
  40  * @since 1.25
  41  */
  42 class StatusValue {
  43         /** @var bool */
  44         protected $ok = true;
  45         /** @var array */
  46         protected $errors = [];
  47
  48         /** @var mixed */
  49         public $value;
  50         /** @var array Map of (key => bool) to indicate success of each part of batch operations */
  51         public $success = [];
  52         /** @var int Counter for batch operations */
  53         public $successCount = 0;
  54         /** @var int Counter for batch operations */
  55         public $failCount = 0;
  56
  57         /**
  58          * Factory function for fatal errors
  59          *
  60          * @param string|MessageSpecifier $message Message key or object
  61          * @return StatusValue
  62          */
  63         public static function newFatal( $message /*, parameters...*/ ) {
  64                 $params = func_get_args();
  65                 $result = new static();
  66                 call_user_func_array( [ &$result, 'fatal' ], $params );
  67                 return $result;
  68         }
  69
  70         /**
  71          * Factory function for good results
  72          *
  73          * @param mixed $value
  74          * @return StatusValue
  75          */
  76         public static function newGood( $value = null ) {
  77                 $result = new static();
  78                 $result->value = $value;
  79                 return $result;
  80         }
  81
  82         /**
  83          * Returns whether the operation completed and didn't have any error or
  84          * warnings
  85          *
  86          * @return bool
  87          */
  88         public function isGood() {
  89                 return $this->ok && !$this->errors;
  90         }
  91
  92         /**
  93          * Returns whether the operation completed
  94          *
  95          * @return bool
  96          */
  97         public function isOK() {
  98                 return $this->ok;
  99         }
 100
 101         /**
 102          * @return mixed
 103          */
 104         public function getValue() {
 105                 return $this->value;
 106         }
 107
 108         /**
 109          * Get the list of errors
 110          *
 111          * Each error is a (message:string or MessageSpecifier,params:array) map
 112          *
 113          * @return array
 114          */
 115         public function getErrors() {
 116                 return $this->errors;
 117         }
 118
 119         /**
 120          * Change operation status
 121          *
 122          * @param bool $ok
 123          */
 124         public function setOK( $ok ) {
 125                 $this->ok = $ok;
 126         }
 127
 128         /**
 129          * Change operation resuklt
 130          *
 131          * @param bool $ok Whether the operation completed
 132          * @param mixed $value
 133          */
 134         public function setResult( $ok, $value = null ) {
 135                 $this->ok = $ok;
 136                 $this->value = $value;
 137         }
 138
 139         /**
 140          * Add a new warning
 141          *
 142          * @param string|MessageSpecifier $message Message key or object
 143          */
 144         public function warning( $message /*, parameters... */ ) {
 145                 $this->errors[] = [
 146                         'type' => 'warning',
 147                         'message' => $message,
 148                         'params' => array_slice( func_get_args(), 1 )
 149                 ];
 150         }
 151
 152         /**
 153          * Add an error, do not set fatal flag
 154          * This can be used for non-fatal errors
 155          *
 156          * @param string|MessageSpecifier $message Message key or object
 157          */
 158         public function error( $message /*, parameters... */ ) {
 159                 $this->errors[] = [
 160                         'type' => 'error',
 161                         'message' => $message,
 162                         'params' => array_slice( func_get_args(), 1 )
 163                 ];
 164         }
 165
 166         /**
 167          * Add an error and set OK to false, indicating that the operation
 168          * as a whole was fatal
 169          *
 170          * @param string|MessageSpecifier $message Message key or object
 171          */
 172         public function fatal( $message /*, parameters... */ ) {
 173                 $this->errors[] = [
 174                         'type' => 'error',
 175                         'message' => $message,
 176                         'params' => array_slice( func_get_args(), 1 )
 177                 ];
 178                 $this->ok = false;
 179         }
 180
 181         /**
 182          * Merge another status object into this one
 183          *
 184          * @param StatusValue $other Other StatusValue object
 185          * @param bool $overwriteValue Whether to override the "value" member
 186          */
 187         public function merge( $other, $overwriteValue = false ) {
 188                 $this->errors = array_merge( $this->errors, $other->errors );
 189                 $this->ok = $this->ok && $other->ok;
 190                 if ( $overwriteValue ) {
 191                         $this->value = $other->value;
 192                 }
 193                 $this->successCount += $other->successCount;
 194                 $this->failCount += $other->failCount;
 195         }
 196
 197         /**
 198          * Returns a list of status messages of the given type
 199          *
 200          * Each entry is a map of (message:string or MessageSpecifier,params:array))
 201          *
 202          * @param string $type
 203          * @return array
 204          */
 205         public function getErrorsByType( $type ) {
 206                 $result = [];
 207                 foreach ( $this->errors as $error ) {
 208                         if ( $error['type'] === $type ) {
 209                                 $result[] = $error;
 210                         }
 211                 }
 212
 213                 return $result;
 214         }
 215
 216         /**
 217          * Returns true if the specified message is present as a warning or error
 218          *
 219          * @param string|MessageSpecifier $message Message key or object to search for
 220          *
 221          * @return bool
 222          */
 223         public function hasMessage( $message ) {
 224                 if ( $message instanceof MessageSpecifier ) {
 225                         $message = $message->getKey();
 226                 }
 227                 foreach ( $this->errors as $error ) {
 228                         if ( $error['message'] instanceof MessageSpecifier
 229                                 && $error['message']->getKey() === $message
 230                         ) {
 231                                 return true;
 232                         } elseif ( $error['message'] === $message ) {
 233                                 return true;
 234                         }
 235                 }
 236
 237                 return false;
 238         }
 239
 240         /**
 241          * If the specified source message exists, replace it with the specified
 242          * destination message, but keep the same parameters as in the original error.
 243          *
 244          * Note, due to the lack of tools for comparing IStatusMessage objects, this
 245          * function will not work when using such an object as the search parameter.
 246          *
 247          * @param IStatusMessage|string $source Message key or object to search for
 248          * @param IStatusMessage|string $dest Replacement message key or object
 249          * @return bool Return true if the replacement was done, false otherwise.
 250          */
 251         public function replaceMessage( $source, $dest ) {
 252                 $replaced = false;
 253
 254                 foreach ( $this->errors as $index => $error ) {
 255                         if ( $error['message'] === $source ) {
 256                                 $this->errors[$index]['message'] = $dest;
 257                                 $replaced = true;
 258                         }
 259                 }
 260
 261                 return $replaced;
 262         }
 263
 264         /**
 265          * @return string
 266          */
 267         public function __toString() {
 268                 $status = $this->isOK() ? "OK" : "Error";
 269                 if ( count( $this->errors ) ) {
 270                         $errorcount = "collected " . ( count( $this->errors ) ) . " error(s) on the way";
 271                 } else {
 272                         $errorcount = "no errors detected";
 273                 }
 274                 if ( isset( $this->value ) ) {
 275                         $valstr = gettype( $this->value ) . " value set";
 276                         if ( is_object( $this->value ) ) {
 277                                 $valstr .= "\"" . get_class( $this->value ) . "\" instance";
 278                         }
 279                 } else {
 280                         $valstr = "no value set";
 281                 }
 282                 $out = sprintf( "<%s, %s, %s>",
 283                         $status,
 284                         $errorcount,
 285                         $valstr
 286                 );
 287                 if ( count( $this->errors ) > 0 ) {
 288                         $hdr = sprintf( "+-%'-4s-+-%'-25s-+-%'-40s-+\n", "", "", "" );
 289                         $i = 1;
 290                         $out .= "\n";
 291                         $out .= $hdr;
 292                         foreach ( $this->errors as $error ) {
 293                                 if ( $error['message'] instanceof MessageSpecifier ) {
 294                                         $key = $error['message']->getKey();
 295                                         $params = $error['message']->getParams();
 296                                 } elseif ( $error['params'] ) {
 297                                         $key = $error['message'];
 298                                         $params = $error['params'];
 299                                 } else {
 300                                         $key = $error['message'];
 301                                         $params = [];
 302                                 }
 303
 304                                 $out .= sprintf( "| %4d | %-25.25s | %-40.40s |\n",
 305                                         $i,
 306                                         $key,
 307                                         implode( " ", $params )
 308                                 );
 309                                 $i += 1;
 310                         }
 311                         $out .= $hdr;
 312                 }
 313
 314                 return $out;
 315         }
 316 }