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
  44         /** @var bool */
  45         protected $ok = true;
  46
  47         /** @var array[] */
  48         protected $errors = [];
  49
  50         /** @var mixed */
  51         public $value;
  52
  53         /** @var bool[] Map of (key => bool) to indicate success of each part of batch operations */
  54         public $success = [];
  55
  56         /** @var int Counter for batch operations */
  57         public $successCount = 0;
  58
  59         /** @var int Counter for batch operations */
  60         public $failCount = 0;
  61
  62         /**
  63          * Factory function for fatal errors
  64          *
  65          * @param string|MessageSpecifier $message Message key or object
  66          * @param mixed ...$parameters
  67          * @return static
  68          */
  69         public static function newFatal( $message, ...$parameters ) {
  70                 $result = new static();
  71                 $result->fatal( $message, ...$parameters );
  72                 return $result;
  73         }
  74
  75         /**
  76          * Factory function for good results
  77          *
  78          * @param mixed|null $value
  79          * @return static
  80          */
  81         public static function newGood( $value = null ) {
  82                 $result = new static();
  83                 $result->value = $value;
  84                 return $result;
  85         }
  86
  87         /**
  88          * Splits this StatusValue object into two new StatusValue objects, one which contains only
  89          * the error messages, and one that contains the warnings, only. The returned array is
  90          * defined as:
  91          * [
  92          *     0 => object(StatusValue) # the StatusValue with error messages, only
  93          *     1 => object(StatusValue) # The StatusValue with warning messages, only
  94          * ]
  95          *
  96          * @return static[]
  97          */
  98         public function splitByErrorType() {
  99                 $errorsOnlyStatusValue = clone $this;
 100                 $warningsOnlyStatusValue = clone $this;
 101                 $warningsOnlyStatusValue->ok = true;
 102
 103                 $errorsOnlyStatusValue->errors = $warningsOnlyStatusValue->errors = [];
 104                 foreach ( $this->errors as $item ) {
 105                         if ( $item['type'] === 'warning' ) {
 106                                 $warningsOnlyStatusValue->errors[] = $item;
 107                         } else {
 108                                 $errorsOnlyStatusValue->errors[] = $item;
 109                         }
 110                 }
 111
 112                 return [ $errorsOnlyStatusValue, $warningsOnlyStatusValue ];
 113         }
 114
 115         /**
 116          * Returns whether the operation completed and didn't have any error or
 117          * warnings
 118          *
 119          * @return bool
 120          */
 121         public function isGood() {
 122                 return $this->ok && !$this->errors;
 123         }
 124
 125         /**
 126          * Returns whether the operation completed
 127          *
 128          * @return bool
 129          */
 130         public function isOK() {
 131                 return $this->ok;
 132         }
 133
 134         /**
 135          * @return mixed
 136          */
 137         public function getValue() {
 138                 return $this->value;
 139         }
 140
 141         /**
 142          * Get the list of errors
 143          *
 144          * Each error is a (message:string or MessageSpecifier,params:array) map
 145          *
 146          * @return array[]
 147          */
 148         public function getErrors() {
 149                 return $this->errors;
 150         }
 151
 152         /**
 153          * Change operation status
 154          *
 155          * @param bool $ok
 156          */
 157         public function setOK( $ok ) {
 158                 $this->ok = $ok;
 159         }
 160
 161         /**
 162          * Change operation result
 163          *
 164          * @param bool $ok Whether the operation completed
 165          * @param mixed|null $value
 166          */
 167         public function setResult( $ok, $value = null ) {
 168                 $this->ok = (bool)$ok;
 169                 $this->value = $value;
 170         }
 171
 172         /**
 173          * Add a new warning
 174          *
 175          * @param string|MessageSpecifier $message Message key or object
 176          * @param mixed ...$parameters
 177          */
 178         public function warning( $message, ...$parameters ) {
 179                 $this->errors[] = [
 180                         'type' => 'warning',
 181                         'message' => $message,
 182                         'params' => $parameters
 183                 ];
 184         }
 185
 186         /**
 187          * Add an error, do not set fatal flag
 188          * This can be used for non-fatal errors
 189          *
 190          * @param string|MessageSpecifier $message Message key or object
 191          * @param mixed ...$parameters
 192          */
 193         public function error( $message, ...$parameters ) {
 194                 $this->errors[] = [
 195                         'type' => 'error',
 196                         'message' => $message,
 197                         'params' => $parameters
 198                 ];
 199         }
 200
 201         /**
 202          * Add an error and set OK to false, indicating that the operation
 203          * as a whole was fatal
 204          *
 205          * @param string|MessageSpecifier $message Message key or object
 206          * @param mixed ...$parameters
 207          */
 208         public function fatal( $message, ...$parameters ) {
 209                 $this->errors[] = [
 210                         'type' => 'error',
 211                         'message' => $message,
 212                         'params' => $parameters
 213                 ];
 214                 $this->ok = false;
 215         }
 216
 217         /**
 218          * Merge another status object into this one
 219          *
 220          * @param StatusValue $other
 221          * @param bool $overwriteValue Whether to override the "value" member
 222          */
 223         public function merge( $other, $overwriteValue = false ) {
 224                 $this->errors = array_merge( $this->errors, $other->errors );
 225                 $this->ok = $this->ok && $other->ok;
 226                 if ( $overwriteValue ) {
 227                         $this->value = $other->value;
 228                 }
 229                 $this->successCount += $other->successCount;
 230                 $this->failCount += $other->failCount;
 231         }
 232
 233         /**
 234          * Returns a list of status messages of the given type
 235          *
 236          * Each entry is a map of:
 237          *   - message: string message key or MessageSpecifier
 238          *   - params: array list of parameters
 239          *
 240          * @param string $type
 241          * @return array[]
 242          */
 243         public function getErrorsByType( $type ) {
 244                 $result = [];
 245                 foreach ( $this->errors as $error ) {
 246                         if ( $error['type'] === $type ) {
 247                                 $result[] = $error;
 248                         }
 249                 }
 250
 251                 return $result;
 252         }
 253
 254         /**
 255          * Returns true if the specified message is present as a warning or error
 256          *
 257          * @param string|MessageSpecifier $message Message key or object to search for
 258          *
 259          * @return bool
 260          */
 261         public function hasMessage( $message ) {
 262                 if ( $message instanceof MessageSpecifier ) {
 263                         $message = $message->getKey();
 264                 }
 265                 foreach ( $this->errors as $error ) {
 266                         if ( $error['message'] instanceof MessageSpecifier
 267                                 && $error['message']->getKey() === $message
 268                         ) {
 269                                 return true;
 270                         } elseif ( $error['message'] === $message ) {
 271                                 return true;
 272                         }
 273                 }
 274
 275                 return false;
 276         }
 277
 278         /**
 279          * If the specified source message exists, replace it with the specified
 280          * destination message, but keep the same parameters as in the original error.
 281          *
 282          * Note, due to the lack of tools for comparing IStatusMessage objects, this
 283          * function will not work when using such an object as the search parameter.
 284          *
 285          * @param MessageSpecifier|string $source Message key or object to search for
 286          * @param MessageSpecifier|string $dest Replacement message key or object
 287          * @return bool Return true if the replacement was done, false otherwise.
 288          */
 289         public function replaceMessage( $source, $dest ) {
 290                 $replaced = false;
 291
 292                 foreach ( $this->errors as $index => $error ) {
 293                         if ( $error['message'] === $source ) {
 294                                 $this->errors[$index]['message'] = $dest;
 295                                 $replaced = true;
 296                         }
 297                 }
 298
 299                 return $replaced;
 300         }
 301
 302         /**
 303          * @return string
 304          */
 305         public function __toString() {
 306                 $status = $this->isOK() ? "OK" : "Error";
 307                 if ( count( $this->errors ) ) {
 308                         $errorcount = "collected " . ( count( $this->errors ) ) . " error(s) on the way";
 309                 } else {
 310                         $errorcount = "no errors detected";
 311                 }
 312                 if ( isset( $this->value ) ) {
 313                         $valstr = gettype( $this->value ) . " value set";
 314                         if ( is_object( $this->value ) ) {
 315                                 $valstr .= "\"" . get_class( $this->value ) . "\" instance";
 316                         }
 317                 } else {
 318                         $valstr = "no value set";
 319                 }
 320                 $out = sprintf( "<%s, %s, %s>",
 321                         $status,
 322                         $errorcount,
 323                         $valstr
 324                 );
 325                 if ( count( $this->errors ) > 0 ) {
 326                         $hdr = sprintf( "+-%'-4s-+-%'-25s-+-%'-40s-+\n", "", "", "" );
 327                         $i = 1;
 328                         $out .= "\n";
 329                         $out .= $hdr;
 330                         foreach ( $this->errors as $error ) {
 331                                 if ( $error['message'] instanceof MessageSpecifier ) {
 332                                         $key = $error['message']->getKey();
 333                                         $params = $error['message']->getParams();
 334                                 } elseif ( $error['params'] ) {
 335                                         $key = $error['message'];
 336                                         $params = $error['params'];
 337                                 } else {
 338                                         $key = $error['message'];
 339                                         $params = [];
 340                                 }
 341
 342                                 $out .= sprintf( "| %4d | %-25.25s | %-40.40s |\n",
 343                                         $i,
 344                                         $key,
 345                                         implode( " ", $params )
 346                                 );
 347                                 $i += 1;
 348                         }
 349                         $out .= $hdr;
 350                 }
 351
 352                 return $out;
 353         }
 354 }