includes/libs/ParamValidator/ValidationException.php

   1 <?php
   2
   3 namespace Wikimedia\ParamValidator;
   4
   5 use Exception;
   6 use Throwable;
   7 use UnexpectedValueException;
   8
   9 /**
  10  * Error reporting for ParamValidator
  11  *
  12  * @since 1.34
  13  */
  14 class ValidationException extends UnexpectedValueException {
  15
  16         /** @var string */
  17         protected $paramName;
  18
  19         /** @var mixed */
  20         protected $paramValue;
  21
  22         /** @var array */
  23         protected $settings;
  24
  25         /** @var string */
  26         protected $failureCode;
  27
  28         /** @var (string|int|string[])[] */
  29         protected $failureData;
  30
  31         /**
  32          * @param string $name Parameter name being validated
  33          * @param mixed $value Value of the parameter
  34          * @param array $settings Settings array being used for validation
  35          * @param string $code Failure code. See getFailureCode() for requirements.
  36          * @param (string|int|string[])[] $data Data for the failure code.
  37          *  See getFailureData() for requirements.
  38          * @param Throwable|Exception|null $previous Previous exception causing this failure
  39          */
  40         public function __construct( $name, $value, $settings, $code, $data, $previous = null ) {
  41                 parent::__construct( self::formatMessage( $name, $code, $data ), 0, $previous );
  42
  43                 $this->paramName = $name;
  44                 $this->paramValue = $value;
  45                 $this->settings = $settings;
  46                 $this->failureCode = $code;
  47                 $this->failureData = $data;
  48         }
  49
  50         /**
  51          * Make a simple English message for the exception
  52          * @param string $name
  53          * @param string $code
  54          * @param array $data
  55          * @return string
  56          */
  57         private static function formatMessage( $name, $code, $data ) {
  58                 $ret = "Validation of `$name` failed: $code";
  59                 foreach ( $data as $k => $v ) {
  60                         if ( is_array( $v ) ) {
  61                                 $v = implode( ', ', $v );
  62                         }
  63                         $ret .= "; $k => $v";
  64                 }
  65                 return $ret;
  66         }
  67
  68         /**
  69          * Fetch the parameter name that failed validation
  70          * @return string
  71          */
  72         public function getParamName() {
  73                 return $this->paramName;
  74         }
  75
  76         /**
  77          * Fetch the parameter value that failed validation
  78          * @return mixed
  79          */
  80         public function getParamValue() {
  81                 return $this->paramValue;
  82         }
  83
  84         /**
  85          * Fetch the settings array that failed validation
  86          * @return array
  87          */
  88         public function getSettings() {
  89                 return $this->settings;
  90         }
  91
  92         /**
  93          * Fetch the validation failure code
  94          *
  95          * A validation failure code is a reasonably short string matching the regex
  96          * `/^[a-z][a-z0-9-]*$/`.
  97          *
  98          * Users are encouraged to use this with a suitable i18n mechanism rather
  99          * than relying on the limited English text returned by getMessage().
 100          *
 101          * @return string
 102          */
 103         public function getFailureCode() {
 104                 return $this->failureCode;
 105         }
 106
 107         /**
 108          * Fetch the validation failure data
 109          *
 110          * This returns additional data relevant to the particular failure code.
 111          *
 112          * Keys in the array are short ASCII strings. Values are strings or
 113          * integers, or arrays of strings intended to be displayed as a
 114          * comma-separated list. For any particular code the same keys are always
 115          * returned in the same order, making it safe to use array_values() and
 116          * access them positionally if that is desired.
 117          *
 118          * For example, the data for a hypothetical "integer-out-of-range" code
 119          * might have data `[ 'min' => 0, 'max' => 100 ]` indicating the range of
 120          * allowed values.
 121          *
 122          * @return (string|int|string[])[]
 123          */
 124         public function getFailureData() {
 125                 return $this->failureData;
 126         }
 127
 128 }