includes/libs/ParamValidator/README.md

   1 Wikimedia API Parameter Validator
   2 =================================
   3
   4 This library implements a system for processing and validating parameters to an
   5 API from data like that in PHP's `$_GET`, `$_POST`, and `$_FILES` arrays, based
   6 on a declarative definition of available parameters.
   7
   8 Usage
   9 -----
  10
  11 <pre lang="php">
  12 use Wikimedia\ParamValidator\ParamValidator;
  13 use Wikimedia\ParamValidator\TypeDef\IntegerDef;
  14 use Wikimedia\ParamValidator\SimpleCallbacks as ParamValidatorCallbacks;
  15 use Wikimedia\ParamValidator\ValidationException;
  16
  17 $validator = new ParamValidator(
  18         new ParamValidatorCallbacks( $_POST + $_GET, $_FILES ),
  19         $serviceContainer->getObjectFactory()
  20 );
  21
  22 try {
  23         $intValue = $validator->getValue( 'intParam', [
  24                         ParamValidator::PARAM_TYPE => 'integer',
  25                         ParamValidator::PARAM_DEFAULT => 0,
  26                         IntegerDef::PARAM_MIN => 0,
  27                         IntegerDef::PARAM_MAX => 5,
  28         ] );
  29 } catch ( ValidationException $ex ) {
  30         $error = lookupI18nMessage( 'param-validator-error-' . $ex->getFailureCode() );
  31         echo "Validation error: $error\n";
  32 }
  33 </pre>
  34
  35 I18n
  36 ----
  37
  38 This library is designed to generate output in a manner suited to use with an
  39 i18n system. To that end, errors and such are indicated by means of "codes"
  40 consisting of ASCII lowercase letters, digits, and hyphen (and always beginning
  41 with a letter).
  42
  43 Additional details about each error, such as the allowed range for an integer
  44 value, are similarly returned by means of associative arrays with keys being
  45 similar "code" strings and values being strings, integers, or arrays of strings
  46 that are intended to be formatted as a list (e.g. joined with commas). The
  47 details for any particular "message" will also always have the same keys in the
  48 same order to facilitate use with i18n systems using positional rather than
  49 named parameters.
  50
  51 For possible codes and their parameters, see the documentation of the relevant
  52 `PARAM_*` constants and TypeDef classes.
  53
  54 Running tests
  55 -------------
  56
  57     composer install --prefer-dist
  58     composer test