src/aphront/httpparametertype/AphrontHTTPParameterType.php

   1 <?php
   2
   3 /**
   4  * Defines how to read a complex value from an HTTP request.
   5  *
   6  * Most HTTP parameters are simple (like strings or integers) but some
   7  * parameters accept more complex values (like lists of users or project names).
   8  *
   9  * This class handles reading simple and complex values from a request,
  10  * performing any required parsing or lookups, and returning a result in a
  11  * standard format.
  12  *
  13  * @task read Reading Values from a Request
  14  * @task info Information About the Type
  15  * @task util Parsing Utilities
  16  * @task impl Implementation
  17  */
  18 abstract class AphrontHTTPParameterType extends Phobject {
  19
  20
  21   private $viewer;
  22
  23
  24 /* -(  Reading Values from a Request  )-------------------------------------- */
  25
  26
  27   /**
  28    * Set the current viewer.
  29    *
  30    * Some parameter types perform complex parsing involving lookups. For
  31    * example, a type might lookup usernames or project names. These types need
  32    * to use the current viewer to execute queries.
  33    *
  34    * @param PhabricatorUser Current viewer.
  35    * @return this
  36    * @task read
  37    */
  38   final public function setViewer(PhabricatorUser $viewer) {
  39     $this->viewer = $viewer;
  40     return $this;
  41   }
  42
  43
  44   /**
  45    * Get the current viewer.
  46    *
  47    * @return PhabricatorUser Current viewer.
  48    * @task read
  49    */
  50   final public function getViewer() {
  51     if (!$this->viewer) {
  52       throw new PhutilInvalidStateException('setViewer');
  53     }
  54     return $this->viewer;
  55   }
  56
  57
  58   /**
  59    * Test if a value is present in a request.
  60    *
  61    * @param AphrontRequest The incoming request.
  62    * @param string The key to examine.
  63    * @return bool True if a readable value is present in the request.
  64    * @task read
  65    */
  66   final public function getExists(AphrontRequest $request, $key) {
  67     return $this->getParameterExists($request, $key);
  68   }
  69
  70
  71   /**
  72    * Read a value from a request.
  73    *
  74    * If the value is not present, a default value is returned (usually `null`).
  75    * Use @{method:getExists} to test if a value is present.
  76    *
  77    * @param AphrontRequest The incoming request.
  78    * @param string The key to examine.
  79    * @return wild Value, or default if value is not present.
  80    * @task read
  81    */
  82   final public function getValue(AphrontRequest $request, $key) {
  83
  84     if (!$this->getExists($request, $key)) {
  85       return $this->getParameterDefault();
  86     }
  87
  88     return $this->getParameterValue($request, $key);
  89   }
  90
  91
  92   /**
  93    * Get the default value for this parameter type.
  94    *
  95    * @return wild Default value for this type.
  96    * @task read
  97    */
  98   final public function getDefaultValue() {
  99     return $this->getParameterDefault();
 100   }
 101
 102
 103 /* -(  Information About the Type  )----------------------------------------- */
 104
 105
 106   /**
 107    * Get a short name for this type, like `string` or `list<phid>`.
 108    *
 109    * @return string Short type name.
 110    * @task info
 111    */
 112   final public function getTypeName() {
 113     return $this->getParameterTypeName();
 114   }
 115
 116
 117   /**
 118    * Get a list of human-readable descriptions of acceptable formats for this
 119    * type.
 120    *
 121    * For example, a type might return strings like these:
 122    *
 123    * > Any positive integer.
 124    * > A comma-separated list of PHIDs.
 125    *
 126    * This is used to explain to users how to specify a type when generating
 127    * documentation.
 128    *
 129    * @return list<string> Human-readable list of acceptable formats.
 130    * @task info
 131    */
 132   final public function getFormatDescriptions() {
 133     return $this->getParameterFormatDescriptions();
 134   }
 135
 136
 137   /**
 138    * Get a list of human-readable examples of how to format this type as an
 139    * HTTP GET parameter.
 140    *
 141    * For example, a type might return strings like these:
 142    *
 143    * > v=123
 144    * > v[]=1&v[]=2
 145    *
 146    * This is used to show users how to specify parameters of this type in
 147    * generated documentation.
 148    *
 149    * @return list<string> Human-readable list of format examples.
 150    * @task info
 151    */
 152   final public function getExamples() {
 153     return $this->getParameterExamples();
 154   }
 155
 156
 157 /* -(  Utilities  )---------------------------------------------------------- */
 158
 159
 160   /**
 161    * Call another type's existence check.
 162    *
 163    * This method allows a type to reuse the existence behavior of a different
 164    * type. For example, a "list of users" type may have the same basic
 165    * existence check that a simpler "list of strings" type has, and can just
 166    * call the simpler type to reuse its behavior.
 167    *
 168    * @param AphrontHTTPParameterType The other type.
 169    * @param AphrontRequest Incoming request.
 170    * @param string Key to examine.
 171    * @return bool True if the parameter exists.
 172    * @task util
 173    */
 174   final protected function getExistsWithType(
 175     AphrontHTTPParameterType $type,
 176     AphrontRequest $request,
 177     $key) {
 178
 179     $type->setViewer($this->getViewer());
 180
 181     return $type->getParameterExists($request, $key);
 182   }
 183
 184
 185   /**
 186    * Call another type's value parser.
 187    *
 188    * This method allows a type to reuse the parsing behavior of a different
 189    * type. For example, a "list of users" type may start by running the same
 190    * basic parsing that a simpler "list of strings" type does.
 191    *
 192    * @param AphrontHTTPParameterType The other type.
 193    * @param AphrontRequest Incoming request.
 194    * @param string Key to examine.
 195    * @return wild Parsed value.
 196    * @task util
 197    */
 198   final protected function getValueWithType(
 199     AphrontHTTPParameterType $type,
 200     AphrontRequest $request,
 201     $key) {
 202
 203     $type->setViewer($this->getViewer());
 204
 205     return $type->getValue($request, $key);
 206   }
 207
 208
 209   /**
 210    * Get a list of all available parameter types.
 211    *
 212    * @return list<AphrontHTTPParameterType> List of all available types.
 213    * @task util
 214    */
 215   final public static function getAllTypes() {
 216     return id(new PhutilClassMapQuery())
 217       ->setAncestorClass(__CLASS__)
 218       ->setUniqueMethod('getTypeName')
 219       ->setSortMethod('getTypeName')
 220       ->execute();
 221   }
 222
 223
 224 /* -(  Implementation  )----------------------------------------------------- */
 225
 226
 227   /**
 228    * Test if a parameter exists in a request.
 229    *
 230    * See @{method:getExists}. By default, this method tests if the key is
 231    * present in the request.
 232    *
 233    * To call another type's behavior in order to perform this check, use
 234    * @{method:getExistsWithType}.
 235    *
 236    * @param AphrontRequest The incoming request.
 237    * @param string The key to examine.
 238    * @return bool True if a readable value is present in the request.
 239    * @task impl
 240    */
 241   protected function getParameterExists(AphrontRequest $request, $key) {
 242     return $request->getExists($key);
 243   }
 244
 245
 246   /**
 247    * Parse a value from a request.
 248    *
 249    * See @{method:getValue}. This method will //only// be called if this type
 250    * has already asserted that the value exists with
 251    * @{method:getParameterExists}.
 252    *
 253    * To call another type's behavior in order to parse a value, use
 254    * @{method:getValueWithType}.
 255    *
 256    * @param AphrontRequest The incoming request.
 257    * @param string The key to examine.
 258    * @return wild Parsed value.
 259    * @task impl
 260    */
 261   abstract protected function getParameterValue(AphrontRequest $request, $key);
 262
 263
 264   /**
 265    * Return a simple type name string, like "string" or "list<phid>".
 266    *
 267    * See @{method:getTypeName}.
 268    *
 269    * @return string Short type name.
 270    * @task impl
 271    */
 272   abstract protected function getParameterTypeName();
 273
 274
 275   /**
 276    * Return a human-readable list of format descriptions.
 277    *
 278    * See @{method:getFormatDescriptions}.
 279    *
 280    * @return list<string> Human-readable list of acceptable formats.
 281    * @task impl
 282    */
 283   abstract protected function getParameterFormatDescriptions();
 284
 285
 286   /**
 287    * Return a human-readable list of examples.
 288    *
 289    * See @{method:getExamples}.
 290    *
 291    * @return list<string> Human-readable list of format examples.
 292    * @task impl
 293    */
 294   abstract protected function getParameterExamples();
 295
 296
 297   /**
 298    * Return the default value for this parameter type.
 299    *
 300    * See @{method:getDefaultValue}. If unspecified, the default is `null`.
 301    *
 302    * @return wild Default value.
 303    * @task impl
 304    */
 305   protected function getParameterDefault() {
 306     return null;
 307   }
 308
 309 }