Page MenuHomePhabricator
Diviner Phabricator Tech Docs AphrontHTTPParameterType

abstract class AphrontHTTPParameterType
Phabricator Technical Documentation (Aphront)

Defines how to read a complex value from an HTTP request.

Most HTTP parameters are simple (like strings or integers) but some parameters accept more complex values (like lists of users or project names).

This class handles reading simple and complex values from a request, performing any required parsing or lookups, and returning a result in a standard format.

Tasks

Reading Values from a Request

  • final public function setViewer($viewer) — Set the current viewer.
  • final public function getViewer() — Get the current viewer.
  • final public function getExists($request, $key) — Test if a value is present in a request.
  • final public function getValue($request, $key) — Read a value from a request.
  • final public function getDefaultValue() — Get the default value for this parameter type.

Information About the Type

  • final public function getTypeName() — Get a short name for this type, like `string` or `list<phid>`.
  • final public function getFormatDescriptions() — Get a list of human-readable descriptions of acceptable formats for this type.
  • final public function getExamples() — Get a list of human-readable examples of how to format this type as an HTTP GET parameter.

Parsing Utilities

  • final protected function getExistsWithType($type, $request, $key) — Call another type's existence check.
  • final protected function getValueWithType($type, $request, $key) — Call another type's value parser.
  • final public static function getAllTypes() — Get a list of all available parameter types.

Implementation

Methods

final public function setViewer($viewer)

Set the current viewer.

Some parameter types perform complex parsing involving lookups. For example, a type might lookup usernames or project names. These types need to use the current viewer to execute queries.

Parameters
PhabricatorUser$viewerCurrent viewer.
Return
this

final public function getViewer()

Get the current viewer.

Return
PhabricatorUserCurrent viewer.

final public function getExists($request, $key)

Test if a value is present in a request.

Parameters
AphrontRequest$requestThe incoming request.
string$keyThe key to examine.
Return
boolTrue if a readable value is present in the request.

final public function getValue($request, $key)

Read a value from a request.

If the value is not present, a default value is returned (usually null). Use getExists() to test if a value is present.

Parameters
AphrontRequest$requestThe incoming request.
string$keyThe key to examine.
Return
wildValue, or default if value is not present.

final public function getDefaultValue()

Get the default value for this parameter type.

Return
wildDefault value for this type.

final public function getTypeName()

Get a short name for this type, like string or list<phid>.

Return
stringShort type name.

final public function getFormatDescriptions()

Get a list of human-readable descriptions of acceptable formats for this type.

For example, a type might return strings like these:

Any positive integer. A comma-separated list of PHIDs.

This is used to explain to users how to specify a type when generating documentation.

Return
list<string>Human-readable list of acceptable formats.

final public function getExamples()

Get a list of human-readable examples of how to format this type as an HTTP GET parameter.

For example, a type might return strings like these:

v=123 v[]=1&v[]=2

This is used to show users how to specify parameters of this type in generated documentation.

Return
list<string>Human-readable list of format examples.

final protected function getExistsWithType($type, $request, $key)

Call another type's existence check.

This method allows a type to reuse the existence behavior of a different type. For example, a "list of users" type may have the same basic existence check that a simpler "list of strings" type has, and can just call the simpler type to reuse its behavior.

Parameters
AphrontHTTPParameterType$typeThe other type.
AphrontRequest$requestIncoming request.
string$keyKey to examine.
Return
boolTrue if the parameter exists.

final protected function getValueWithType($type, $request, $key)

Call another type's value parser.

This method allows a type to reuse the parsing behavior of a different type. For example, a "list of users" type may start by running the same basic parsing that a simpler "list of strings" type does.

Parameters
AphrontHTTPParameterType$typeThe other type.
AphrontRequest$requestIncoming request.
string$keyKey to examine.
Return
wildParsed value.

final public static function getAllTypes()

Get a list of all available parameter types.

Return
list<AphrontHTTPParameterType>List of all available types.

protected function getParameterExists($request, $key)

Test if a parameter exists in a request.

See getExists(). By default, this method tests if the key is present in the request.

To call another type's behavior in order to perform this check, use getExistsWithType().

Parameters
AphrontRequest$requestThe incoming request.
string$keyThe key to examine.
Return
boolTrue if a readable value is present in the request.

abstract protected function getParameterValue($request, $key)

Parse a value from a request.

See getValue(). This method will only be called if this type has already asserted that the value exists with getParameterExists().

To call another type's behavior in order to parse a value, use getValueWithType().

Parameters
AphrontRequest$requestThe incoming request.
string$keyThe key to examine.
Return
wildParsed value.

abstract protected function getParameterTypeName()

Return a simple type name string, like "string" or "list<phid>".

See getTypeName().

Return
stringShort type name.

abstract protected function getParameterFormatDescriptions()

Return a human-readable list of format descriptions.

See getFormatDescriptions().

Return
list<string>Human-readable list of acceptable formats.

abstract protected function getParameterExamples()

Return a human-readable list of examples.

See getExamples().

Return
list<string>Human-readable list of format examples.

protected function getParameterDefault()

Return the default value for this parameter type.

See getDefaultValue(). If unspecified, the default is null.

Return
wildDefault value.
Defined
src/aphront/httpparametertype/AphrontHTTPParameterType.php:18
Phabricator · Built by Phacility