Standardize and improve validation message templates #1670

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged

alganet merged 1 commit into Respect:main from alganet:template-changes

Feb 3, 2026

docs/feature-guide.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -149,7 +149,7 @@ Provide unique messages for each validator in a chain:
  
    ```php

    v::alnum()->lowercase()->assert($input, [

        'alnum' => 'Your username must contain only letters and digits',

        'alnum' => 'Your username must consist only of letters and digits',

        'lowercase' => 'Your username must be lowercase',

    ]);

    ```

docs/handling-exceptions.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -49,7 +49,7 @@ try {
  
    The code above generates the following output:

    ```no-highlight

    "The Panda" must contain only letters (a-z) and digits (0-9)

    "The Panda" must consist only of letters (a-z) and digits (0-9)

    ```

    ### Full exception message

    @@ -71,8 +71,8 @@ The code above generates the following output:
  
    ```no-highlight

    - "The Panda" must pass all the rules

      - "The Panda" must contain only letters (a-z) and digits (0-9)

      - "The Panda" must contain only lowercase letters

      - "The Panda" must consist only of letters (a-z) and digits (0-9)

      - "The Panda" must consist only of lowercase letters

    ```

    ### Full exception messages as an array

    @@ -96,8 +96,8 @@ The code above generates the following output:
  
    Array

    (

        [__root__] => "The Panda" must pass all the rules

        [alnum] => "The Panda" must contain only letters (a-z) and digits (0-9)

        [lowercase] => "The Panda" must contain only lowercase letters

        [alnum] => "The Panda" must consist only of letters (a-z) and digits (0-9)

        [lowercase] => "The Panda" must consist only of lowercase letters

    )

    ```

    @@ -183,7 +183,7 @@ try {
  
                'The Panda',

                [

                    '__root__' => 'The given input is not valid',

                    'alnum' => 'Your username must contain only letters and digits',

                    'alnum' => 'Your username must consist only of letters and digits',

                    'lowercase' => 'Your username must be lowercase',

                ]

            );

    @@ -198,7 +198,7 @@ The code above generates the following output.
  
    Array

    (

        [__root__] => The given input is not valid

        [alnum] => Your username must contain only letters and digits

        [alnum] => Your username must consist only of letters and digits

        [lowercase] => Your username must be lowercase

    )

    ```

docs/handling-results.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -54,8 +54,8 @@ $result = v::alnum()->lowercase()->validate('The Panda');
  
    echo $result->getFullMessage();

    // → - "The Panda" must pass all the rules

    // →   - "The Panda" must contain only letters (a-z) and digits (0-9)

    // →   - "The Panda" must contain only lowercase letters

    // →   - "The Panda" must consist only of letters (a-z) and digits (0-9)

    // →   - "The Panda" must consist only of lowercase letters

    ```

    ### getMessages()

    @@ -69,8 +69,8 @@ print_r($result->getMessages());
  
    // Array

    // (

    //     [__root__] => "The Panda" must pass all the rules

    //     [alnum] => "The Panda" must contain only letters (a-z) and digits (0-9)

    //     [lowercase] => "The Panda" must contain only lowercase letters

    //     [alnum] => "The Panda" must consist only of letters (a-z) and digits (0-9)

    //     [lowercase] => "The Panda" must consist only of lowercase letters

    // )

    ```

docs/messages/translation.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -36,10 +36,10 @@ Use the `|trans` modifier to translate parameter values:
  
    ```php

    // Message template

    '{{subject}} must be a valid telephone number for country {{countryName|trans}}'

    '{{subject}} must be a valid phone number for country {{countryName|trans}}'

    // Translations needed

    '{{subject}} must be a valid telephone number for country {{countryName|trans}}' => '{{subject}} deve ser um número de telefone válido para o país {{countryName|trans}}',

    '{{subject}} must be a valid phone number for country {{countryName|trans}}' => '{{subject}} deve ser um número de telefone válido para o país {{countryName|trans}}',

    'Palestine' => 'Palestina',

    ```

docs/validators/All.md

-Original file line number
+Diff line change
@@ Expand Up @@
     ```php
     v::all(v::floatType())->assert([1.5, 2]);
-    // → Every item in `[1.5, 2]` must be float
+    // → Every item in `[1.5, 2]` must be a float
     v::not(v::all(v::intType()))->assert([1, 2, -3]);
     // → Every item in `[1, 2, -3]` must not be an integer
@@ Expand Down @@

docs/validators/Alnum.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -18,10 +18,10 @@ v::alnum(' ')->assert('foo 123');
  
    // Validation passes successfully

    v::alnum()->assert('foo 123');

    // → "foo 123" must contain only letters (a-z) and digits (0-9)

    // → "foo 123" must consist only of letters (a-z) and digits (0-9)

    v::alnum()->assert('100%');

    // → "100%" must contain only letters (a-z) and digits (0-9)

    // → "100%" must consist only of letters (a-z) and digits (0-9)

    v::alnum('%')->assert('100%');

    // Validation passes successfully

    @@ -35,7 +35,7 @@ You can restrict case using the [Lowercase](Lowercase.md) and
  
    ```php

    v::alnum()->uppercase()->assert('example');

    // → "example" must contain only uppercase letters

    // → "example" must consist only of uppercase letters

    ```

    Message template for this validator includes `{{additionalChars}}` as the string

    @@ -45,17 +45,17 @@ of extra chars passed as the parameter.
  
    ### `Alnum::TEMPLATE_STANDARD`

    |       Mode | Template                                                     |

    | ---------: | :----------------------------------------------------------- |

    |  `default` | {{subject}} must contain only letters (a-z) and digits (0-9) |

    | `inverted` | {{subject}} must not contain letters (a-z) or digits (0-9)   |

    |       Mode | Template                                                           |

    | ---------: | :----------------------------------------------------------------- |

    |  `default` | {{subject}} must consist only of letters (a-z) and digits (0-9)    |

    | `inverted` | {{subject}} must not consist only of letters (a-z) or digits (0-9) |

    ### `Alnum::TEMPLATE_EXTRA`

    |       Mode | Template                                                                           |

    | ---------: | :--------------------------------------------------------------------------------- |

    |  `default` | {{subject}} must contain only letters (a-z), digits (0-9), and {{additionalChars}} |

    | `inverted` | {{subject}} must not contain letters (a-z), digits (0-9), or {{additionalChars}}   |

    |       Mode | Template                                                                                 |

    | ---------: | :--------------------------------------------------------------------------------------- |

    |  `default` | {{subject}} must consist only of letters (a-z), digits (0-9), or {{additionalChars}}     |

    | `inverted` | {{subject}} must not consist only of letters (a-z), digits (0-9), or {{additionalChars}} |

    ## Template placeholders

    @@ -72,6 +72,7 @@ of extra chars passed as the parameter.
  
    | Version | Description                               |

    | ------: | :---------------------------------------- |

    |   3.0.0 | Templates changed                         |

    |   2.0.0 | Removed support to whitespaces by default |

    |   0.3.9 | Created                                   |

docs/validators/Alpha.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -16,10 +16,10 @@ v::alpha(' ')->assert('some name');
  
    // Validation passes successfully

    v::alpha()->assert('some name');

    // → "some name" must contain only letters (a-z)

    // → "some name" must consist only of letters (a-z)

    v::alpha()->assert('Cedric-Fabian');

    // → "Cedric-Fabian" must contain only letters (a-z)

    // → "Cedric-Fabian" must consist only of letters (a-z)

    v::alpha('-')->assert('Cedric-Fabian');

    // Validation passes successfully

    @@ -33,24 +33,24 @@ You can restrict case using the [Lowercase](Lowercase.md) and
  
    ```php

    v::alpha()->uppercase()->assert('example');

    // → "example" must contain only uppercase letters

    // → "example" must consist only of uppercase letters

    ```

    ## Templates

    ### `Alpha::TEMPLATE_STANDARD`

    |       Mode | Template                                    |

    | ---------: | :------------------------------------------ |

    |  `default` | {{subject}} must contain only letters (a-z) |

    | `inverted` | {{subject}} must not contain letters (a-z)  |

    |       Mode | Template                                           |

    | ---------: | :------------------------------------------------- |

    |  `default` | {{subject}} must consist only of letters (a-z)     |

    | `inverted` | {{subject}} must not consist only of letters (a-z) |

    ### `Alpha::TEMPLATE_EXTRA`

    |       Mode | Template                                                            |

    | ---------: | :------------------------------------------------------------------ |

    |  `default` | {{subject}} must contain only letters (a-z) and {{additionalChars}} |

    | `inverted` | {{subject}} must not contain letters (a-z) or {{additionalChars}}   |

    |       Mode | Template                                                                  |

    | ---------: | :------------------------------------------------------------------------ |

    |  `default` | {{subject}} must consist only of letters (a-z) or {{additionalChars}}     |

    | `inverted` | {{subject}} must not consist only of letters (a-z) or {{additionalChars}} |

    ## Template placeholders

    @@ -67,6 +67,7 @@ v::alpha()->uppercase()->assert('example');
  
    | Version | Description                               |

    | ------: | :---------------------------------------- |

    |   3.0.0 | Templates changed                         |

    |   2.0.0 | Removed support to whitespaces by default |

    |   0.3.9 | Created                                   |

docs/validators/ArrayVal.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -25,10 +25,10 @@ v::arrayVal()->assert(new SimpleXMLElement('<xml></xml>'));
  
    ### `ArrayVal::TEMPLATE_STANDARD`

    |       Mode | Template                               |

    | ---------: | :------------------------------------- |

    |  `default` | {{subject}} must be an array value     |

    | `inverted` | {{subject}} must not be an array value |

    |       Mode | Template                         |

    | ---------: | :------------------------------- |

    |  `default` | {{subject}} must be an array     |

    | `inverted` | {{subject}} must not be an array |

    ## Template placeholders

    @@ -45,6 +45,7 @@ v::arrayVal()->assert(new SimpleXMLElement('<xml></xml>'));
  
    | Version | Description                                                                                  |

    | ------: | :------------------------------------------------------------------------------------------- |

    |   3.0.0 | Templates changed                                                                            |

    |   2.0.0 | `SimpleXMLElement` is also considered as valid                                               |

    |   1.0.0 | Renamed from `Arr` to `ArrayVal` and validate only if the input can be used as an array (#1) |

    |   0.3.9 | Created as `Arr`                                                                             |

docs/validators/Attributes.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -47,13 +47,13 @@ v::attributes()->assert(new Person('', '2020-06-23', 'john.doe@gmail.com', '+120
  
    // → `.name` must be defined

    v::attributes()->assert(new Person('John Doe', 'not a date', 'john.doe@gmail.com', '+12024561111'));

    // → `.birthdate` must be a valid date in the format "2005-12-30"

    // → `.birthdate` must be a date in the "2005-12-30" format

    v::attributes()->assert(new Person('John Doe', '2020-06-23', 'not an email', '+12024561111'));

    // → `.email` must be a valid email address or must be null

    // → `.email` must be an email address or must be null

    v::attributes()->assert(new Person('John Doe', '2020-06-23', 'john.doe@gmail.com', 'not a phone number'));

    // → `.phone` must be a valid telephone number or must be null

    // → `.phone` must be a phone number or must be null

    v::attributes()->assert(new Person('John Doe', '2020-06-23'));

    // → - `Person { +$name="John Doe" +$birthdate="2020-06-23" +$email=null +$phone=null }` must pass at least one of the rules

    @@ -63,9 +63,9 @@ v::attributes()->assert(new Person('John Doe', '2020-06-23'));
  
    v::attributes()->assert(new Person('', 'not a date', 'not an email', 'not a phone number'));

    // → - `Person { +$name="" +$birthdate="not a date" +$email="not an email" +$phone="not a phone number" }` must pass the rules

    // →   - `.name` must be defined

    // →   - `.birthdate` must be a valid date in the format "2005-12-30"

    // →   - `.email` must be a valid email address or must be null

    // →   - `.phone` must be a valid telephone number or must be null

    // →   - `.birthdate` must be a date in the "2005-12-30" format

    // →   - `.email` must be an email address or must be null

    // →   - `.phone` must be a phone number or must be null

    ```

    ## Caveats

docs/validators/Base64.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -14,7 +14,7 @@ v::base64()->assert('cmVzcGVjdCE=');
  
    // Validation passes successfully

    v::base64()->assert('respect!');

    // → "respect!" must be a base64 encoded string

    // → "respect!" must be a base64-encoded string

    ```

    ## Templates

    @@ -23,8 +23,8 @@ v::base64()->assert('respect!');
  
    |       Mode | Template                                        |

    | ---------: | :---------------------------------------------- |

    |  `default` | {{subject}} must be a base64 encoded string     |

    | `inverted` | {{subject}} must not be a base64 encoded string |

    |  `default` | {{subject}} must be a base64-encoded string     |

    | `inverted` | {{subject}} must not be a base64-encoded string |

    ## Template placeholders

    @@ -38,9 +38,10 @@ v::base64()->assert('respect!');
  
    ## Changelog

    | Version | Description |

    | ------: | :---------- |

    |   2.0.0 | Created     |

    | Version | Description       |

    | ------: | :---------------- |

    |   3.0.0 | Templates changed |

    |   2.0.0 | Created           |

    ## See Also

docs/validators/BoolVal.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -33,10 +33,10 @@ v::boolVal()->assert(0);
  
    ### `BoolVal::TEMPLATE_STANDARD`

    |       Mode | Template                                |

    | ---------: | :-------------------------------------- |

    |  `default` | {{subject}} must be a boolean value     |

    | `inverted` | {{subject}} must not be a boolean value |

    |       Mode | Template                          |

    | ---------: | :-------------------------------- |

    |  `default` | {{subject}} must be a boolean     |

    | `inverted` | {{subject}} must not be a boolean |

    ## Template placeholders

docs/validators/Bsn.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -18,10 +18,10 @@ v::bsn()->assert('612890053');
  
    ### `Bsn::TEMPLATE_STANDARD`

    |       Mode | Template                            |

    | ---------: | :---------------------------------- |

    |  `default` | {{subject}} must be a valid BSN     |

    | `inverted` | {{subject}} must not be a valid BSN |

    |       Mode | Template                      |

    | ---------: | :---------------------------- |

    |  `default` | {{subject}} must be a BSN     |

    | `inverted` | {{subject}} must not be a BSN |

    ## Template placeholders

    @@ -35,9 +35,10 @@ v::bsn()->assert('612890053');
  
    ## Changelog

    | Version | Description |

    | ------: | :---------- |

    |   1.0.0 | Created     |

    | Version | Description       |

    | ------: | :---------------- |

    |   3.0.0 | Templates changed |

    |   1.0.0 | Created           |

    ## See Also

docs/validators/CallableType.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -24,10 +24,10 @@ v::callableType()->assert([new DateTime(), 'format']);
  
    ### `CallableType::TEMPLATE_STANDARD`

    |       Mode | Template                           |

    | ---------: | :--------------------------------- |

    |  `default` | {{subject}} must be a callable     |

    | `inverted` | {{subject}} must not be a callable |

    |       Mode | Template                                    |

    | ---------: | :------------------------------------------ |

    |  `default` | {{subject}} must be a callable function     |

    | `inverted` | {{subject}} must not be a callable function |

    ## Template placeholders

docs/validators/Charset.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -15,7 +15,7 @@ v::charset('ASCII')->assert('sugar');
  
    // Validation passes successfully

    v::charset('ASCII')->assert('açúcar');

    // → "açúcar" must only contain characters from the `["ASCII"]` charset

    // → "açúcar" must consist only of characters from the "ASCII" character-set

    v::charset('ISO-8859-1', 'EUC-JP')->assert('日本国');

    // Validation passes successfully

    @@ -27,10 +27,10 @@ The array format is a logic OR, not AND.
  
    ### `Charset::TEMPLATE_STANDARD`

    |       Mode | Template                                                                          |

    | ---------: | :-------------------------------------------------------------------------------- |

    |  `default` | {{subject}} must only contain characters from the {{charset&#124;raw}} charset    |

    | `inverted` | {{subject}} must not contain any characters from the {{charset&#124;raw}} charset |

    |       Mode | Template                                                                                        |

    | ---------: | :---------------------------------------------------------------------------------------------- |

    |  `default` | {{subject}} must consist only of characters from the {{charset&#124;list:or}} character-set     |

    | `inverted` | {{subject}} must not consist only of characters from the {{charset&#124;list:or}} character-set |

    ## Template placeholders

    @@ -47,6 +47,7 @@ The array format is a logic OR, not AND.
  
    | Version | Description                                           |

    | ------: | :---------------------------------------------------- |

    |   3.0.0 | Templates changed                                     |

    |   2.0.0 | Charset supports multiple charsets on its constructor |

    |   0.5.0 | Created                                               |

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Standardize and improve validation message templates #1670

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!