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.
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.
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
22 * Generic operation result class
23 * Has warning/error list, boolean status and arbitrary value
25 * "Good" means the operation was completed with no warnings or errors.
27 * "OK" means the operation was partially or wholly completed.
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.
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.
38 * The use of Message objects should be avoided when serializability is needed.
48 protected $errors = [];
53 /** @var bool[] Map of (key => bool) to indicate success of each part of batch operations */
56 /** @var int Counter for batch operations */
57 public $successCount = 0;
59 /** @var int Counter for batch operations */
60 public $failCount = 0;
63 * Factory function for fatal errors
65 * @param string|MessageSpecifier $message Message key or object
68 public static function newFatal( $message /*, parameters...*/ ) {
69 $params = func_get_args();
70 $result = new static();
71 call_user_func_array( [ &$result, 'fatal' ], $params );
76 * Factory function for good results
81 public static function newGood( $value = null ) {
82 $result = new static();
83 $result->value
= $value;
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
92 * 0 => object(StatusValue) # the StatusValue with error messages, only
93 * 1 => object(StatusValue) # The StatusValue with warning messages, only
96 * @return StatusValue[]
98 public function splitByErrorType() {
99 $errorsOnlyStatusValue = clone $this;
100 $warningsOnlyStatusValue = clone $this;
101 $warningsOnlyStatusValue->ok
= true;
103 $errorsOnlyStatusValue->errors
= $warningsOnlyStatusValue->errors
= [];
104 foreach ( $this->errors
as $item ) {
105 if ( $item['type'] === 'warning' ) {
106 $warningsOnlyStatusValue->errors
[] = $item;
108 $errorsOnlyStatusValue->errors
[] = $item;
112 return [ $errorsOnlyStatusValue, $warningsOnlyStatusValue ];
116 * Returns whether the operation completed and didn't have any error or
121 public function isGood() {
122 return $this->ok
&& !$this->errors
;
126 * Returns whether the operation completed
130 public function isOK() {
137 public function getValue() {
142 * Get the list of errors
144 * Each error is a (message:string or MessageSpecifier,params:array) map
148 public function getErrors() {
149 return $this->errors
;
153 * Change operation status
157 public function setOK( $ok ) {
162 * Change operation result
164 * @param bool $ok Whether the operation completed
165 * @param mixed $value
167 public function setResult( $ok, $value = null ) {
168 $this->ok
= (bool)$ok;
169 $this->value
= $value;
175 * @param string|MessageSpecifier $message Message key or object
177 public function warning( $message /*, parameters... */ ) {
180 'message' => $message,
181 'params' => array_slice( func_get_args(), 1 )
186 * Add an error, do not set fatal flag
187 * This can be used for non-fatal errors
189 * @param string|MessageSpecifier $message Message key or object
191 public function error( $message /*, parameters... */ ) {
194 'message' => $message,
195 'params' => array_slice( func_get_args(), 1 )
200 * Add an error and set OK to false, indicating that the operation
201 * as a whole was fatal
203 * @param string|MessageSpecifier $message Message key or object
205 public function fatal( $message /*, parameters... */ ) {
208 'message' => $message,
209 'params' => array_slice( func_get_args(), 1 )
215 * Merge another status object into this one
217 * @param StatusValue $other Other StatusValue object
218 * @param bool $overwriteValue Whether to override the "value" member
220 public function merge( $other, $overwriteValue = false ) {
221 $this->errors
= array_merge( $this->errors
, $other->errors
);
222 $this->ok
= $this->ok
&& $other->ok
;
223 if ( $overwriteValue ) {
224 $this->value
= $other->value
;
226 $this->successCount +
= $other->successCount
;
227 $this->failCount +
= $other->failCount
;
231 * Returns a list of status messages of the given type
233 * Each entry is a map of:
234 * - message: string message key or MessageSpecifier
235 * - params: array list of parameters
237 * @param string $type
240 public function getErrorsByType( $type ) {
242 foreach ( $this->errors
as $error ) {
243 if ( $error['type'] === $type ) {
252 * Returns true if the specified message is present as a warning or error
254 * @param string|MessageSpecifier $message Message key or object to search for
258 public function hasMessage( $message ) {
259 if ( $message instanceof MessageSpecifier
) {
260 $message = $message->getKey();
262 foreach ( $this->errors
as $error ) {
263 if ( $error['message'] instanceof MessageSpecifier
264 && $error['message']->getKey() === $message
267 } elseif ( $error['message'] === $message ) {
276 * If the specified source message exists, replace it with the specified
277 * destination message, but keep the same parameters as in the original error.
279 * Note, due to the lack of tools for comparing IStatusMessage objects, this
280 * function will not work when using such an object as the search parameter.
282 * @param MessageSpecifier|string $source Message key or object to search for
283 * @param MessageSpecifier|string $dest Replacement message key or object
284 * @return bool Return true if the replacement was done, false otherwise.
286 public function replaceMessage( $source, $dest ) {
289 foreach ( $this->errors
as $index => $error ) {
290 if ( $error['message'] === $source ) {
291 $this->errors
[$index]['message'] = $dest;
302 public function __toString() {
303 $status = $this->isOK() ?
"OK" : "Error";
304 if ( count( $this->errors
) ) {
305 $errorcount = "collected " . ( count( $this->errors
) ) . " error(s) on the way";
307 $errorcount = "no errors detected";
309 if ( isset( $this->value
) ) {
310 $valstr = gettype( $this->value
) . " value set";
311 if ( is_object( $this->value
) ) {
312 $valstr .= "\"" . get_class( $this->value
) . "\" instance";
315 $valstr = "no value set";
317 $out = sprintf( "<%s, %s, %s>",
322 if ( count( $this->errors
) > 0 ) {
323 $hdr = sprintf( "+-%'-4s-+-%'-25s-+-%'-40s-+\n", "", "", "" );
327 foreach ( $this->errors
as $error ) {
328 if ( $error['message'] instanceof MessageSpecifier
) {
329 $key = $error['message']->getKey();
330 $params = $error['message']->getParams();
331 } elseif ( $error['params'] ) {
332 $key = $error['message'];
333 $params = $error['params'];
335 $key = $error['message'];
339 $out .= sprintf( "| %4d | %-25.25s | %-40.40s |\n",
342 implode( " ", $params )