# @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}

Subtypes 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.

Code:

Following api class shows various usage examples

    <?php

    class Type
    {

        /**
         * UUID validation
         *
         * @param string $uuid {@from body}{@type uuid}
         *
         * @return string {@type uuid}
         */
        function postUUID($uuid)
        {
            return $uuid;
        }

        /**
         * Email validation
         *
         * @param string $email {@from body}{@type email}
         *
         * @return string {@type email}
         */
        function postEmail($email)
        {
            return $email;
        }

        /**
         * Date validation
         *
         * @param string $date {@from body}{@type date}
         *
         * @return string {@type date}
         */
        function postDate($date)
        {
            return $date;
        }

        /**
         * Array of dates
         *
         * @param array $dates Dates array{@from body}{@type date}
         *
         * @return array {@type date}
         */
        function postDates(array $dates)
        {
            return $dates;
        }

        /**
         * DateTime validation
         *
         * @param string $datetime {@from body}{@type datetime}
         *
         * @return string {@type datetime}
         */
        function postDatetime($datetime)
        {
            return $datetime;
        }

        /**
         * time validation
         *
         * @param string $time {@from body}{@type time}
         *
         * @return string {@type time}
         */
        function postTime($time)
        {
            return $time;
        }

        /**
         * time validation in 12 hour format
         *
         * @param string $time12 {@from body}{@type time12}
         *
         * @return string {@type time12}
         */
        function postTime12($time12)
        {
            return $time12;
        }

        /**
         * Timestamp validation
         *
         * @param string $timestamp {@from body}{@type timestamp}
         *
         * @return string {@type timestamp}
         */
        function postTimestamp($timestamp)
        {
            return $timestamp;
        }

        /**
         * Integer validation
         *
         * @param array $integers {@type int}
         *
         * @return array {@type int}
         */
        function postIntegers(array $integers)
        {
            return $integers;
        }

        /**
         * Array of numbers
         *
         * @param array $numbers {@type float}
         *
         * @return array {@type float}
         */
        function postNumbers(array $numbers)
        {
            return $numbers;
        }

        /**
         * Array of time strings
         *
         * @param array $times {@from body}{@type time}
         *
         * @return array {@type time}
         */
        function postTimes(array $times)
        {
            return $times;
        }

        /**
         * Array of timestamps
         *
         * @param array $timestamps {@from body}{@type timestamp}
         *
         * @return array {@type timestamp}
         */
        function postTimestamps(array $timestamps)
        {
            return $timestamps;
        }

        /**
         * Custom class parameter
         *
         * @param Author $author
         *
         * @return Author
         */
        function postAuthor(Author $author)
        {
            return $author;
        }

        /**
         * Array of authors
         *
         * @param array $authors {@type Author}
         *
         * @return array {@type Author}
         */
        function postAuthors(array $authors)
        {
            return $authors;
        }

        /**
         * An associative array
         *
         * @param array $object {@type associative}
         *
         * @return array {@type associative}
         */
        function postObject(array $object)
        {
            return $object;
        }

        /**
         * An indexed array
         *
         * @param array $array {@type indexed}
         *
         * @return array {@type indexed}
         */
        function postArray(array $array)
        {
            return $array;
        }

        /**
         * An array indexed or associative
         *
         * @param array $array
         *
         * @return array
         */
        function postArrayOrObject(array $array)
        {
            return $array;
        }
    }

    class Author
    {
        /**
         * @var string {@from body} {@min 3}{@max 100}
         * name of the Author {@required true}
         */
        public $name = 'Name';
        /**
         * @var string {@type email} {@from body} {@required false}
         * email id of the Author
         */
        public $email = 'name@domain.com';
    }

Test:

Running the following command on the terminal from the project root

    vendor/bin/behat  features/tests/param/type.feature

Will test the above api for the following features

    @param @type
    Feature: Type Attribute

      Scenario Outline: valid UUID version 1
        Given that I send {"uuid":<uuid>}
        And the request is sent as JSON
        When I request "tests/param/type/uuid"
        Then the response status code should be 200
        And the response is JSON
        And the type is "string"
        And the response equals <lowercase>

        Examples:
          | uuid                                   | lowercase                              |
          | "4b972cba-f138-11e7-8c3f-9a214cf093ae" | "4b972cba-f138-11e7-8c3f-9a214cf093ae" |
          | "4b973020-f138-11e7-8c3f-9a214cf093ae" | "4b973020-f138-11e7-8c3f-9a214cf093ae" |
          | "4B973200-F138-11E7-8C3F-9A214CF093AE" | "4b973200-f138-11e7-8c3f-9a214cf093ae" |
          | "4b9733b8-f138-11e7-8c3f-9a214cf093ae" | "4b9733b8-f138-11e7-8c3f-9a214cf093ae" |

      Scenario Outline: valid UUID version 4
        Given that I send {"uuid":<uuid>}
        And the request is sent as JSON
        When I request "tests/param/type/uuid"
        Then the response status code should be 200
        And the response is JSON
        And the type is "string"
        And the response equals <lowercase>

        Examples:
          | uuid                                   | lowercase                              |
          | "040FDD24-CD36-4B94-A5E5-3AD72917686F" | "040fdd24-cd36-4b94-a5e5-3ad72917686f" |
          | "16bea809-4d60-42b8-9de2-03d464979f74" | "16bea809-4d60-42b8-9de2-03d464979f74" |
          | "c0b32c01-3892-4202-a955-dc1ae8323ca3" | "c0b32c01-3892-4202-a955-dc1ae8323ca3" |
          | "fd71a4f8-5423-48b1-863d-fea243503d59" | "fd71a4f8-5423-48b1-863d-fea243503d59" |

      Scenario Outline: Invalid UUID
        Given that I send {"uuid":<uuid>}
        And the request is sent as JSON
        When I request "tests/param/type/uuid"
        Then the response status code should be 400

        Examples:
          | uuid                                    |
          | "040fdd24-cd36-4b94-a5e5-3ad72917686"   |
          | "16bea8$9-4d60-42b8-9de2-03d464979f_4"  |
          | "c0b32c01-3892-4202-a955-dc1ae8323c"    |
          | "fd71a4f8-5423-48b1-863d-fea243503d593" |
          | "fd71a4f-54238-48b1-863d-fea243503d59"  |

      Scenario Outline: Email
        Given that I send {"email":<email>}
        And the request is sent as JSON
        When I request "tests/param/type/email"
        Then the response status code should be 200
        And the response is JSON
        And the type is "string"
        And the response equals <email>

        Examples:
          | email                 |
          | "$A12345@example.com" |
          | "!def!xyz%abc@my.co"  |
          | "sane@h.io"           |

      Scenario Outline: Email as the only body
        Given that I send <email>
        And the request is sent as JSON
        When I request "tests/param/type/email"
        Then the response status code should be 200
        And the response is JSON
        And the type is "string"
        And the response equals <email>

        Examples:
          | email                 |
          | "$A12345@example.com" |
          | "!def!xyz%abc@my.co"  |
          | "sane@h.io"           |

      Scenario Outline: Invalid Email
        Given that I send {"email":<email>}
        And the request is sent as JSON
        When I request "tests/param/type/email"
        Then the response status code should be 400
        And the response is JSON

        Examples:
          | email              |
          | "some.thing@wrong" |
          | "missing@dot"      |
          | "missing.at"       |

      Scenario Outline: Invalid Email as the only body
        Given that I send <email>
        And the request is sent as JSON
        When I request "tests/param/type/email"
        Then the response status code should be 400
        And the response is JSON

        Examples:
          | email              |
          | "some.thing@wrong" |
          | "missing@dot"      |
          | "missing.at"       |

      Scenario Outline: Date
        Given that I send {"date":<date>}
        And the request is sent as JSON
        When I request "tests/param/type/date"
        Then the response status code should be 200
        And the response is JSON
        And the type is "string"
        And the response equals <date>

        Examples:
          | date         |
          | "2013-08-10" |
          | "1974-03-30" |
          | "1600-12-17" |

      Scenario Outline: Date as the only body
        Given that I send <date>
        And the request is sent as JSON
        When I request "tests/param/type/date"
        Then the response status code should be 200
        And the response is JSON
        And the type is "string"
        And the response equals <date>

        Examples:
          | date         |
          | "2013-08-10" |
          | "1974-03-30" |
          | "1600-12-17" |

      Scenario Outline: Invalid Date
        Given that I send {"date":<date>}
        And the request is sent as JSON
        When I request "tests/param/type/date"
        Then the response status code should be 400
        And the response is JSON

        Examples:
          | date         |
          | "YYY-MM-DD"  |
          | "10-08-2013" |
          | "2013-13-10" |
          | "2013-02-30" |
          | "2013/08/10" |

      Scenario Outline: Invalid Date as the only body
        Given that I send <date>
        And the request is sent as JSON
        When I request "tests/param/type/date"
        Then the response status code should be 400
        And the response is JSON

        Examples:
          | date         |
          | "YYY-MM-DD"  |
          | "10-08-2013" |
          | "2013-13-10" |
          | "2013-02-30" |
          | "2013/08/10" |

      Scenario Outline: Date and Time
        Given that I send {"datetime":<datetime>}
        And the request is sent as JSON
        When I request "tests/param/type/datetime"
        Then the response status code should be 200
        And the response is JSON
        And the type is "string"
        And the response equals <datetime>

        Examples:
          | datetime              |
          | "2013-08-10 00:34:18" |

      Scenario Outline: Invalid Date and Time
        Given that I send {"datetime":<datetime>}
        And the request is sent as JSON
        When I request "tests/param/type/datetime"
        Then the response status code should be 400
        And the response is JSON

        Examples:
          | datetime              |
          | "2013-08-10"          |
          | "2013-08-10 25:70:11" |
          | "2013/08/10 00:34:18" |

      Scenario Outline: Time Stamp
        Given that I send {"timestamp":<timestamp>}
        And the request is sent as JSON
        When I request "tests/param/type/timestamp"
        Then the response status code should be 200
        And the response is JSON
        And the type is "int"
        And the response equals <expected>

        Examples:
          | timestamp    | expected   |
          | "1376094488" | 1376094488 |
          | 1376094488   | 1376094488 |
          | "0123"       | 123        |
          | 123.0        | 123        |
          | 1            | 1          |
          | 0            | 0          |

      Scenario Outline: Time Stamp as the only body
        Given that I send <timestamp>
        And the request is sent as JSON
        When I request "tests/param/type/timestamp"
        Then the response status code should be 200
        And the response is JSON
        And the type is "int"
        And the response equals <expected>

        Examples:
          | timestamp    | expected   |
          | "1376094488" | 1376094488 |
          | 1376094488   | 1376094488 |
          | "0123"       | 123        |
          | 123.0        | 123        |
          | 1            | 1          |

      Scenario Outline: Invalid Time Stamp
        Given that I send {"timestamp":<timestamp>}
        And the request is sent as JSON
        When I request "tests/param/type/timestamp"
        Then the response status code should be 400
        And the response is JSON

        Examples:
          | timestamp             |
          | "2013-08-10"          |
          | "2013-08-10 00:34:18" |
          | "0xFF"                |
          | 1.1                   |

      Scenario Outline: Invalid Time Stamp as the only body
        Given that I send <timestamp>
        And the request is sent as JSON
        When I request "tests/param/type/timestamp"
        Then the response status code should be 400
        And the response is JSON

        Examples:
          | timestamp             |
          | "2013-08-10"          |
          | "2013-08-10 00:34:18" |
          | "0xFF"                |
          | 1.1                   |

      Scenario Outline: An Array of Integers
        Given that I send {"integers":<integers>}
        And the request is sent as JSON
        When I request "tests/param/type/integers"
        Then the response status code should be 200
        And the response is JSON
        And the response equals <expected>

        Examples:
          | integers          | expected          |
          | []                | []                |
          | {}                | []                |
          | [1,3298473984,23] | [1,3298473984,23] |
          | [0]               | [0]               |

      Scenario Outline: An Array of Integers as the only body
        Given that I send <integers>
        And the request is sent as JSON
        When I request "tests/param/type/integers"
        Then the response status code should be 200
        And the response is JSON
        And the response equals <expected>

        Examples:
          | integers          | expected          |
          | []                | []                |
          | {}                | []                |
          | [1,3298473984,23] | [1,3298473984,23] |
          | [0]               | [0]               |

      Scenario Outline: Invalid Array of Integers
        Given that I send {"integers":<integers>}
        And the request is sent as JSON
        When I request "tests/param/type/integers"
        Then the response status code should be 400
        And the response is JSON

        Examples:
          | integers        |
          | ""              |
          | [true,false]    |
          | [null]          |
          | [1.34]          |
          | {"key":"value"} |

      Scenario Outline: Invalid Array of Integers as the only body
        Given that I send <integers>
        And the request is sent as JSON
        When I request "tests/param/type/integers"
        Then the response status code should be 400
        And the response is JSON

        Examples:
          | integers        |
          | ""              |
          | [true,false]    |
          | [null]          |
          | [1.34]          |
          | {"key":"value"} |

      Scenario Outline: An Array of Floating Points
        Given that I send {"numbers":<numbers>}
        And the request is sent as JSON
        When I request "tests/param/type/numbers"
        Then the response status code should be 200
        And the response is JSON
        And the response equals <expected>

        Examples:
          | numbers            | expected           |
          | []                 | []                 |
          | {}                 | []                 |
          | [1,329.8473984,23] | [1,329.8473984,23] |
          | [0.00001]          | [1.0e-5]           |

      Scenario Outline: An Array of Floating Points as the only body
        Given that I send <numbers>
        And the request is sent as JSON
        When I request "tests/param/type/numbers"
        Then the response status code should be 200
        And the response is JSON
        And the response equals <expected>

        Examples:
          | numbers            | expected           |
          | []                 | []                 |
          | {}                 | []                 |
          | [1,329.8473984,23] | [1,329.8473984,23] |
          | [0.00001]          | [1.0e-5]           |
          | [0.10e-4]          | [1.0e-5]           |

      Scenario Outline: Invalid Array of Floats as the only body
        Given that I send <numbers>
        And the request is sent as JSON
        When I request "tests/param/type/numbers"
        Then the response status code should be 400
        And the response is JSON

        Examples:
          | numbers         |
          | ""              |
          | [true,false]    |
          | [null]          |
          | {"key":"value"} |

      Scenario Outline: Custom Class
        Given that I send <author>
        And the request is sent as JSON
        When I request "tests/param/type/author"
        Then the response status code should be 200
        And the response is JSON
        And the response equals <expected>

        Examples:
          | author                                      | expected                                    |
          | {"name":"Arul"}                             | {"name":"Arul","email":"name@domain.com"}   |
          | {"name":"Arul","email":"arul@luracast.com"} | {"name":"Arul","email":"arul@luracast.com"} |
          | {"name":"name","email":"a@b.c"}             | {"name":"name","email":"a@b.c"}             |

      Scenario Outline: Invalid data for Custom Class
        Given that I send <author>
        And the request is sent as JSON
        When I request "tests/param/type/author"
        Then the response status code should be 400
        And the response is JSON

        Examples:
          | author                         |
          | ""                             |
          | [true,false]                   |
          | [null]                         |
          | {"key":"value"}                |
          | {"name":"12","email":"a@b.c"}  |
          | {"email":"a@b.c"}              |
          | {"email":"ab.c","name":"1234"} |
          | {"email":"a@b.c","name":"ab"}  |

      Scenario Outline: Array of Custom Class objects
        Given that I send <authors>
        And the request is sent as JSON
        When I request "tests/param/type/authors"
        Then the response status code should be 200
        And the response is JSON
        And the response equals <expected>

        Examples:
          | authors                                       | expected                                      |
          | [{"name":"Arul"}]                             | [{"name":"Arul","email":"name@domain.com"}]   |
          | [{"name":"Arul","email":"arul@luracast.com"}] | [{"name":"Arul","email":"arul@luracast.com"}] |
          | [{"name":"name","email":"a@b.c"}]             | [{"name":"name","email":"a@b.c"}]             |

      Scenario Outline: Invalid data for array of Custom Class objects
        Given that I send <authors>
        And the request is sent as JSON
        When I request "tests/param/type/authors"
        Then the response status code should be 400
        And the response is JSON

        Examples:
          | authors                        |
          | ""                             |
          | [true,false]                   |
          | [null]                         |
          | {"key":"value"}                |
          | {"name":"12","email":"a@b.c"}  |
          | {"email":"a@b.c"}              |
          | {"email":"ab.c","name":"1234"} |

## @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.

Code:

Following api class shows various usage examples

    <?php
    /**
     * Class MinMax provides an api to check min and max
     * attributes for array, int, and string
     */
    class MinMax
    {

        /**
         * Restrict the number of items in an array
         *
         * @param array $array {@min 2}{@max 5}
         *
         * @return array
         */
        function postArray(array $array)
        {
            return $array;
        }

        /**
         * Restrict the value
         *
         * @param int $int {@min 2}{@max 5}{@from path}
         *
         * @return int
         */
        function getInt($int)
        {
            return $int;
        }

        /**
         * Restrict the length of the string
         *
         * @param string $string {@min 2}{@max 5}{@from path}
         *
         * @return string
         */
        function getString($string)
        {
            return $string;
        }
    }

Test:

Running the following command on the terminal from the project root

    vendor/bin/behat  features/tests/param/minmax.feature

Will test the above api for the following features

    @param @min @max
    Feature: Minimum and Maximum

      Scenario Outline: Int
        When I request "tests/param/minmax/int/<number>"
        Then the response status code should be 200
        And the response is JSON
        And the type is "int"
        And the value equals <number>

        Examples:
          | number |
          |   2    |
          |   3    |
          |   4    |
          |   5    |

      Scenario: Int lower than the minimum
        When I request "tests/param/minmax/int/1"
        Then the response status code should be 400
        And the response is JSON

      Scenario: Int higher than maximum
        When I request "tests/param/minmax/int/6"
        Then the response status code should be 400
        And the response is JSON

      Scenario: String
        When I request "tests/param/minmax/string/me"
        Then the response status code should be 200
        And the response is JSON
        And the type is "string"
        And the value equals "me"

      Scenario: Short String
        When I request "tests/param/minmax/string/i"
        Then the response status code should be 400
        And the response is JSON

      Scenario: Lengthy String
        When I request "tests/param/minmax/string/arulkumaran"
        Then the response status code should be 400
        And the response is JSON

      Scenario Outline: Array
        Given that I send <data>
        And the request is sent as JSON
        When I request "tests/param/minmax/array"
        Then the response status code should be 200
        And the response is JSON

        Examples:
           |  data       |
           | [1,2]       |
           | [1,2,3]     |
           | [1,2,3,4]   |
           | [1,2,3,4,5] |

      Scenario Outline: Array out of range
        Given that I send <data>
        And the request is sent as JSON
        When I request "tests/param/minmax/array"
        Then the response status code should be 400
        And the response is JSON

        Examples:
           |  data             |
           | []                |
           | [1]               |
           | [1,2,3,4,5,6]     |
           | [1,2,3,4,5,6,7]   |
           | [1,2,3,4,5,6,7,8] |

## @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.

Code:

Following api class shows various usage examples

    <?php
    /**
     * Class MinMaxFix provides an api to check min and max
     * attributes for array, int, and string.
     * It also suggests the validator to fix the values if possible
     */
    class MinMaxFix
    {

        /**
         * Restrict the number of items in an array
         *
         * @param array $array {@min 2}{@max 5}{@fix true}
         *
         * @return array
         */
        function postArray(array $array)
        {
            return $array;
        }

        /**
         * Restrict the value
         *
         * @param int $int {@min 2}{@max 5}{@fix true}{@from path}
         *
         * @return int
         */
        function getInt($int)
        {
            return $int;
        }

        /**
         * Restrict the length of the string
         *
         * @param string $string {@min 2}{@max 5}{@fix true}{@from body}
         *
         * @return string
         */
        function postString($string)
        {
            return $string;
        }
    }

Test:

Running the following command on the terminal from the project root

    vendor/bin/behat  features/tests/param/minmaxfix.feature

Will test the above api for the following features

    @param @min @max @fix
    Feature: Minimum and Maximum with Fix

      Scenario Outline: Int
        When I request "tests/param/minmaxfix/int/<number>"
        Then the response status code should be 200
        And the response is JSON
        And the type is "int"
        And the response equals <expected>

      Examples:
        | number | expected |
        | 0      | 2        |
        | 1      | 2        |
        | 2      | 2        |
        | 3      | 3        |
        | 4      | 4        |
        | 5      | 5        |
        | 6      | 5        |
        | 7      | 5        |

      Scenario Outline: String
        Given that I send {"string":<string>}
        And the request is sent as JSON
        When I request "tests/param/minmaxfix/string"
        Then the response status code should be 200
        And the response is JSON
        And the type is "string"
        And the response equals <expected>

      Examples:
        | string    | expected |
        | "a"       | "aa"     |
        | "ab"      | "ab"     |
        | "abc"     | "abc"    |
        | "abcd"    | "abcd"   |
        | "abcde"   | "abcde"  |
        | "abcdef"  | "abcde"  |
        | "abcdefg" | "abcde"  |
        | "abcdefh" | "abcde"  |

      Scenario Outline: Array out of maximum range
        Given that I send <array>
        And the request is sent as JSON
        When I request "tests/param/minmaxfix/array"
        Then the response status code should be 200
        And the response is JSON
        And the response equals <expected>

      Examples:
        | array             | expected    |
        | [1,2]             | [1,2]       |
        | [1,2,3]           | [1,2,3]     |
        | [1,2,3,4]         | [1,2,3,4]   |
        | [1,2,3,4,5]       | [1,2,3,4,5] |
        | [1,2,3,4,5,6]     | [1,2,3,4,5] |
        | [1,2,3,4,5,6,7]   | [1,2,3,4,5] |
        | [1,2,3,4,5,6,7,8] | [1,2,3,4,5] |

      Scenario Outline: Array short of minimum is not expected
        Given that I send <array>
        And the request is sent as JSON
        When I request "tests/param/minmaxfix/array"
        Then the response status code should be 400
        And the response is JSON

      Examples:
        | array |
        | []    |
        | [1]   |

## @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.

Code:

Following api class shows various usage examples

    <?php

    /**
     * Class Validation provides api to check validation
     */
    class Validation
    {
        /**
         * Make sure string is converted properly to bool
         * @param bool $value {@from query}
         * @return bool
         */
        function getBoolean($value)
        {
            return $value;
        }

        /**
         * Make sure string is converted properly to bool
         * @param bool $value {@from query}{@fix true}
         * @return bool
         */
        function getBoolFix($value)
        {
            return $value;
        }

        /**
         * Validate with regex
         *
         * @param string $password  {@pattern /^(?:[0-9]+[a-z]|[a-z]+[0-9])[a-z0-9]*$/i}
         *                          {@message Strong password with at least
         *                          one alpha and one numeric character is required}
         *
         * @return string
         */
        function postPattern($password)
        {
            return $password;
        }

    }

Test:

Running the following command on the terminal from the project root

    vendor/bin/behat  features/tests/param/validation.feature

Will test the above api for the following features

    @param @type
    Feature: Validation

      Scenario: Consider "true" string as true
        When I request "tests/param/validation/boolean?value=true"
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals true

      Scenario: Consider "TruE" string as true
        When I request "tests/param/validation/boolean?value=TruE"
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals true

      Scenario: Consider "false" string as false
        When I request "tests/param/validation/boolean?value=false"
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals false

      Scenario: Consider "FALSE" string as false
        When I request "tests/param/validation/boolean?value=FALSE"
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals false

      Scenario: Consider number 1 as true
        When I request "tests/param/validation/boolean?value=1"
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals true

      Scenario: Consider number 0 as false
        When I request "tests/param/validation/boolean?value=0"
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals false

      Scenario: Don't accept any number for a boolean
        When I request "tests/param/validation/boolean?value=30873"
        Then the response status code should be 400

      Scenario: Don't accept fractional number for a boolean
        When I request "tests/param/validation/boolean?value=0.234"
        Then the response status code should be 400

      Scenario: Don't accept any string for a boolean
        When I request "tests/param/validation/boolean?value=not_boolean"
        Then the response status code should be 400

      Scenario: Fix "true" string as true
        When I request "tests/param/validation/boolfix?value=true"
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals true

      Scenario: Fix "false" string as false
        When I request "tests/param/validation/boolfix?value=true"
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals true

      Scenario: Fix number 1 as true
        When I request "tests/param/validation/boolfix?value=1"
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals true

      Scenario: Fix number 0 as false
        When I request "tests/param/validation/boolfix?value=0"
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals false

      Scenario: Fix positive numbers as a boolean true
        When I request "tests/param/validation/boolfix?value=30873"
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals true

      Scenario: Fix negative numbers as a boolean true
        When I request "tests/param/validation/boolfix?value=-23"
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals true

      Scenario: Fix fractional numbers as a boolean true
        When I request "tests/param/validation/boolfix?value=0.3"
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals true

      Scenario: Fix non empty string as a boolean true
        When I request "tests/param/validation/boolfix?value=not_empty"
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals true

      Scenario: Fix empty string as a boolean false
        When I request "tests/param/validation/boolfix?value="
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals false

      Scenario Outline: Valid Password
        Given that I send {"password":<password>}
        And the request is sent as JSON
        When I request "tests/param/validation/pattern"
        Then the response status code should be 200
        And the response is JSON
        And the type is "string"
        And the response equals <password>

      Examples:
        | password |
        | "1a"     |
        | "b2"     |
        | "some1"  |

      Scenario Outline: Invalid Password
        Given that I send {"password":<password>}
        And the request is sent as JSON
        When I request "tests/param/validation/pattern"
        Then the response status code should be 400
        And the response is JSON
        And the type is "object"
        And the "error.message" property equals "Bad Request: Strong password with at least one alpha and one numeric character is required"

      Examples:
        | password   |
        | "arul"     |
        | "12345678" |
        | "ONEtwo"   |

## @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 on invalid value submission. Use it to list the requirements for a parameter.

Code:

Following api class shows various usage examples

    <?php

    /**
     * Class Validation provides api to check validation
     */
    class Validation
    {
        /**
         * Make sure string is converted properly to bool
         * @param bool $value {@from query}
         * @return bool
         */
        function getBoolean($value)
        {
            return $value;
        }

        /**
         * Make sure string is converted properly to bool
         * @param bool $value {@from query}{@fix true}
         * @return bool
         */
        function getBoolFix($value)
        {
            return $value;
        }

        /**
         * Validate with regex
         *
         * @param string $password  {@pattern /^(?:[0-9]+[a-z]|[a-z]+[0-9])[a-z0-9]*$/i}
         *                          {@message Strong password with at least
         *                          one alpha and one numeric character is required}
         *
         * @return string
         */
        function postPattern($password)
        {
            return $password;
        }

    }

Test:

Running the following command on the terminal from the project root

    vendor/bin/behat  features/tests/param/validation.feature

Will test the above api for the following features

    @param @type
    Feature: Validation

      Scenario: Consider "true" string as true
        When I request "tests/param/validation/boolean?value=true"
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals true

      Scenario: Consider "TruE" string as true
        When I request "tests/param/validation/boolean?value=TruE"
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals true

      Scenario: Consider "false" string as false
        When I request "tests/param/validation/boolean?value=false"
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals false

      Scenario: Consider "FALSE" string as false
        When I request "tests/param/validation/boolean?value=FALSE"
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals false

      Scenario: Consider number 1 as true
        When I request "tests/param/validation/boolean?value=1"
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals true

      Scenario: Consider number 0 as false
        When I request "tests/param/validation/boolean?value=0"
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals false

      Scenario: Don't accept any number for a boolean
        When I request "tests/param/validation/boolean?value=30873"
        Then the response status code should be 400

      Scenario: Don't accept fractional number for a boolean
        When I request "tests/param/validation/boolean?value=0.234"
        Then the response status code should be 400

      Scenario: Don't accept any string for a boolean
        When I request "tests/param/validation/boolean?value=not_boolean"
        Then the response status code should be 400

      Scenario: Fix "true" string as true
        When I request "tests/param/validation/boolfix?value=true"
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals true

      Scenario: Fix "false" string as false
        When I request "tests/param/validation/boolfix?value=true"
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals true

      Scenario: Fix number 1 as true
        When I request "tests/param/validation/boolfix?value=1"
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals true

      Scenario: Fix number 0 as false
        When I request "tests/param/validation/boolfix?value=0"
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals false

      Scenario: Fix positive numbers as a boolean true
        When I request "tests/param/validation/boolfix?value=30873"
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals true

      Scenario: Fix negative numbers as a boolean true
        When I request "tests/param/validation/boolfix?value=-23"
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals true

      Scenario: Fix fractional numbers as a boolean true
        When I request "tests/param/validation/boolfix?value=0.3"
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals true

      Scenario: Fix non empty string as a boolean true
        When I request "tests/param/validation/boolfix?value=not_empty"
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals true

      Scenario: Fix empty string as a boolean false
        When I request "tests/param/validation/boolfix?value="
        Then the response status code should be 200
        And the response is JSON
        And the type is "bool"
        And the response equals false

      Scenario Outline: Valid Password
        Given that I send {"password":<password>}
        And the request is sent as JSON
        When I request "tests/param/validation/pattern"
        Then the response status code should be 200
        And the response is JSON
        And the type is "string"
        And the response equals <password>

      Examples:
        | password |
        | "1a"     |
        | "b2"     |
        | "some1"  |

      Scenario Outline: Invalid Password
        Given that I send {"password":<password>}
        And the request is sent as JSON
        When I request "tests/param/validation/pattern"
        Then the response status code should be 400
        And the response is JSON
        And the type is "object"
        And the "error.message" property equals "Bad Request: Strong password with at least one alpha and one numeric character is required"

      Examples:
        | password   |
        | "arul"     |
        | "12345678" |
        | "ONEtwo"   |

## @example

Syntax:

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

Example:

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

Used by the explorer to pre-fill the value for the parameter