Skip to content

Latest commit

 

History

History
163 lines (91 loc) · 4.15 KB

PARAM.md

File metadata and controls

163 lines (91 loc) · 4.15 KB

@param and @var

Following attributes can be used with @param, they also apply for @var comment that is added to model class properties.

Just replace

@param [type] $name ...

with

@var [type] ...

in the examples below

@from

Syntax:

@param [type] $name [Description] {@from path|body|query|head}

Example:

@param string $name user name {@from body}

Overrides the parameter mapping, defines where to expect the parameter from. Value should be one of the following

  • path as part of url
  • query as part of the query string
  • body as part of the body of the request
  • head as part of the http header

Please note that unlike path and head other values are only suggestive and primarily used by API Explorer to build the interface

@type

Syntax:

string

@param string $name [Description] {@type email|date|datetime|timestamp}

array

@param array  $name [Description] {@type className}

Examples:

@param string $email email id {@type email}

Sub types for validation and documentation purpose. Email will validate the given string as email. Date and datetime will be validated as standard mysql date formats respectively. Timestamp will be validated as Unix timestamp.

@param array $author array of Authors {@type Author}

States that the given array of Author instances.

Take a look at Type API Class and tests in type.feature

@choice

Syntax:

@param string $name [Description] {@choice option1,option2...}

Example:

@param string $gender {@choice male,female,third}

Value for the parameter should match one of the choices, used for validation.

@min & @max

Syntax:

@param string|int|float|array $name [Description] {@min value}{@max value}

Examples:

string

@param string $name 3 to 10 characters in length {@min 3}{@max 10}

array

@param array $items at least one item is needed  {@min 1}

integer

@param int $age valid age should be 18 or above  {@min 18}

Minimum and maximum values for a parameter. For string and array parameters it is applied to the length. For numeric parameters it sets the range for the value.

Take a look at MinMax API Class and tests in minmax.feature

@fix

Syntax:

@param string|int|float|array $name [Description] {@fix true}

Example:

@param string $name 3 to 10 characters in length {@max 10}{@fix true}

Suggests the validator to attempt fixing the validation problem. In the above example Validator will trim off the excess characters instead of throwing an exception

Take a look at MinMaxFix API Class and tests in minmaxfix.feature

@pattern

Syntax:

@param string $name [Description] {@pattern /REGEX_HERE/REGEX_OPTIONS}

Example:

@param string $password at least one alpha and one numeric character
						{@pattern /^(?:[0-9]+[a-z]|[a-z]+[0-9])[a-z0-9]*$/i}

Used by the validator to make sure the parammeter value matches the regex pattern. It uses preg_match for this verification. Please note that / should be used as the delimiter.

Take a look at MinMaxFix API Class and tests in minmaxfix.feature

@message

Syntax:

@param string|int|float $name [Description] {@message value}

Example:

@param string $password Password 
						{@message Strong password with at least one alpha and one numeric character is required}

Used by the validator to show a custom error message when invalid value is submitted. Use it to list the requirements for a parameter

Take a look at MinMaxFix API Class and tests in minmaxfix.feature

@example

Syntax:

@param string|int|float $name [Description] {@example value}

Example:

@param string $name Name {@example Arul Kumaran}

Used by the explorer to prefill the value for the parameter