includes/libs/ParamValidator/Callbacks.php

   1 <?php
   2
   3 namespace Wikimedia\ParamValidator;
   4
   5 use Psr\Http\Message\UploadedFileInterface;
   6 use Wikimedia\Message\DataMessageValue;
   7
   8 /**
   9  * Interface defining callbacks needed by ParamValidator
  10  *
  11  * The user of ParamValidator is expected to pass an object implementing this
  12  * interface to ParamValidator's constructor.
  13  *
  14  * All methods in this interface accept an "options array". This is the same `$options`
  15  * passed to ParamValidator::getValue(), ParamValidator::validateValue(), and the like
  16  * and is intended for communication of non-global state.
  17  *
  18  * @since 1.34
  19  * @unstable
  20  */
  21 interface Callbacks {
  22
  23         /**
  24          * Test if a parameter exists in the request
  25          * @param string $name Parameter name
  26          * @param array $options Options array
  27          * @return bool True if present, false if absent.
  28          *  Return false for file upload parameters.
  29          */
  30         public function hasParam( $name, array $options );
  31
  32         /**
  33          * Fetch a value from the request
  34          *
  35          * Return `$default` for file-upload parameters.
  36          *
  37          * @param string $name Parameter name to fetch
  38          * @param mixed $default Default value to return if the parameter is unset.
  39          * @param array $options Options array
  40          * @return string|string[]|mixed A string or string[] if the parameter was found,
  41          *  or $default if it was not.
  42          */
  43         public function getValue( $name, $default, array $options );
  44
  45         /**
  46          * Test if a parameter exists as an upload in the request
  47          * @param string $name Parameter name
  48          * @param array $options Options array
  49          * @return bool True if present, false if absent.
  50          */
  51         public function hasUpload( $name, array $options );
  52
  53         /**
  54          * Fetch data for a file upload
  55          * @param string $name Parameter name of the upload
  56          * @param array $options Options array
  57          * @return UploadedFileInterface|null Uploaded file, or null if there is no file for $name.
  58          */
  59         public function getUploadedFile( $name, array $options );
  60
  61         /**
  62          * Record non-fatal conditions.
  63          * @param DataMessageValue $message Failure message
  64          * @param string $name Parameter name
  65          * @param mixed $value Parameter value
  66          * @param array $settings Parameter settings array
  67          * @param array $options Options array
  68          */
  69         public function recordCondition(
  70                 DataMessageValue $message, $name, $value, array $settings, array $options
  71         );
  72
  73         /**
  74          * Indicate whether "high limits" should be used.
  75          *
  76          * Some settings have multiple limits, one for "normal" users and a higher
  77          * one for "privileged" users. This is used to determine which class the
  78          * current user is in when necessary.
  79          *
  80          * @param array $options Options array
  81          * @return bool Whether the current user is privileged to use high limits
  82          */
  83         public function useHighLimits( array $options );
  84
  85 }