Page Menu
Home
c4science
Search
Configure Global Search
Log In
Files
F72199700
AphrontHTTPParameterType.php
No One
Temporary
Actions
Download File
Edit File
Delete File
View Transforms
Subscribe
Mute Notifications
Award Token
Subscribers
None
File Metadata
Details
File Info
Storage
Attached
Created
Mon, Jul 15, 06:18
Size
7 KB
Mime Type
text/x-php
Expires
Wed, Jul 17, 06:18 (1 d, 23 h)
Engine
blob
Format
Raw Data
Handle
19038268
Attached To
rPH Phabricator
AphrontHTTPParameterType.php
View Options
<?php
/**
* 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.
*
* @task read Reading Values from a Request
* @task info Information About the Type
* @task util Parsing Utilities
* @task impl Implementation
*/
abstract
class
AphrontHTTPParameterType
extends
Phobject
{
private
$viewer
;
/* -( Reading Values from a Request )-------------------------------------- */
/**
* 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.
*
* @param PhabricatorUser Current viewer.
* @return this
* @task read
*/
final
public
function
setViewer
(
PhabricatorUser
$viewer
)
{
$this
->
viewer
=
$viewer
;
return
$this
;
}
/**
* Get the current viewer.
*
* @return PhabricatorUser Current viewer.
* @task read
*/
final
public
function
getViewer
()
{
if
(!
$this
->
viewer
)
{
throw
new
PhutilInvalidStateException
(
'setViewer'
);
}
return
$this
->
viewer
;
}
/**
* Test if a value is present in a request.
*
* @param AphrontRequest The incoming request.
* @param string The key to examine.
* @return bool True if a readable value is present in the request.
* @task read
*/
final
public
function
getExists
(
AphrontRequest
$request
,
$key
)
{
return
$this
->
getParameterExists
(
$request
,
$key
);
}
/**
* Read a value from a request.
*
* If the value is not present, a default value is returned (usually `null`).
* Use @{method:getExists} to test if a value is present.
*
* @param AphrontRequest The incoming request.
* @param string The key to examine.
* @return wild Value, or default if value is not present.
* @task read
*/
final
public
function
getValue
(
AphrontRequest
$request
,
$key
)
{
if
(!
$this
->
getExists
(
$request
,
$key
))
{
return
$this
->
getParameterDefault
();
}
return
$this
->
getParameterValue
(
$request
,
$key
);
}
/**
* Get the default value for this parameter type.
*
* @return wild Default value for this type.
* @task read
*/
final
public
function
getDefaultValue
()
{
return
$this
->
getParameterDefault
();
}
/* -( Information About the Type )----------------------------------------- */
/**
* Get a short name for this type, like `string` or `list<phid>`.
*
* @return string Short type name.
* @task info
*/
final
public
function
getTypeName
()
{
return
$this
->
getParameterTypeName
();
}
/**
* 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.
* @task info
*/
final
public
function
getFormatDescriptions
()
{
return
$this
->
getParameterFormatDescriptions
();
}
/**
* 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.
* @task info
*/
final
public
function
getExamples
()
{
return
$this
->
getParameterExamples
();
}
/* -( Utilities )---------------------------------------------------------- */
/**
* Call another type's existence check.
*
* This method allows a type to reuse the exitence 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.
*
* @param AphrontHTTPParameterType The other type.
* @param AphrontRequest Incoming request.
* @param string Key to examine.
* @return bool True if the parameter exists.
* @task util
*/
final
protected
function
getExistsWithType
(
AphrontHTTPParameterType
$type
,
AphrontRequest
$request
,
$key
)
{
$type
->
setViewer
(
$this
->
getViewer
());
return
$type
->
getParameterExists
(
$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.
*
* @param AphrontHTTPParameterType The other type.
* @param AphrontRequest Incoming request.
* @param string Key to examine.
* @return wild Parsed value.
* @task util
*/
final
protected
function
getValueWithType
(
AphrontHTTPParameterType
$type
,
AphrontRequest
$request
,
$key
)
{
$type
->
setViewer
(
$this
->
getViewer
());
return
$type
->
getValue
(
$request
,
$key
);
}
/**
* Get a list of all available parameter types.
*
* @return list<AphrontHTTPParameterType> List of all available types.
* @task util
*/
final
public
static
function
getAllTypes
()
{
return
id
(
new
PhutilClassMapQuery
())
->
setAncestorClass
(
__CLASS__
)
->
setUniqueMethod
(
'getTypeName'
)
->
setSortMethod
(
'getTypeName'
)
->
execute
();
}
/* -( Implementation )----------------------------------------------------- */
/**
* Test if a parameter exists in a request.
*
* See @{method: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
* @{method:getExistsWithType}.
*
* @param AphrontRequest The incoming request.
* @param string The key to examine.
* @return bool True if a readable value is present in the request.
* @task impl
*/
protected
function
getParameterExists
(
AphrontRequest
$request
,
$key
)
{
return
$request
->
getExists
(
$key
);
}
/**
* Parse a value from a request.
*
* See @{method:getValue}. This method will //only// be called if this type
* has already asserted that the value exists with
* @{method:getParameterExists}.
*
* To call another type's behavior in order to parse a value, use
* @{method:getValueWithType}.
*
* @param AphrontRequest The incoming request.
* @param string The key to examine.
* @return wild Parsed value.
* @task impl
*/
abstract
protected
function
getParameterValue
(
AphrontRequest
$request
,
$key
);
/**
* Return a simple type name string, like "string" or "list<phid>".
*
* See @{method:getTypeName}.
*
* @return string Short type name.
* @task impl
*/
abstract
protected
function
getParameterTypeName
();
/**
* Return a human-readable list of format descriptions.
*
* See @{method:getFormatDescriptions}.
*
* @return list<string> Human-readable list of acceptable formats.
* @task impl
*/
abstract
protected
function
getParameterFormatDescriptions
();
/**
* Return a human-readable list of examples.
*
* See @{method:getExamples}.
*
* @return list<string> Human-readable list of format examples.
* @task impl
*/
abstract
protected
function
getParameterExamples
();
/**
* Return the default value for this parameter type.
*
* See @{method:getDefaultValue}. If unspecified, the default is `null`.
*
* @return wild Default value.
* @task impl
*/
protected
function
getParameterDefault
()
{
return
null
;
}
}
Event Timeline
Log In to Comment