Definition

Rule definition array defaults.

Rule definition schema/structure.

NOTE: All words prefixed with the @ symbol are variables specific to the rule definition.

• @rule: (object) [magic] The rule object. This value is a magic value and is not required inside rule definition array. It is used to retrieve the rule object. Useful for getting/setting some data of the rule object like the statement or any other attribute inside the callback if needed.

• @name: (string) [required] Rule name. This value can be any string consisting of alphanumeric characters, dots, dashes, underscores (matches: /^[A-Za-z0-9_\-\.]+$/), and between 2 and 255 characters.

• @arguments: (array|null) [optional] Rule arguments. If empty, this means that the rule accepts no arguments. Otherwise, it denotes the data types of the arguments. This value serves two roles, at parsing time it will be used to set arguments data types, later on it will be filled with the actual values in their expected data types. Valid data types casts are: null, boolean or bool, integer or int, float or double, string, array, and object. All data types must be stringified using JSON Spec rules and when supplied, some extra care needs to be taken (especially with array and object), the JSON needs to be escaped by wrapping it as a whole with' (single quotes) and escaping any single quotes inside the JSON with \ (backslash) —using addcslashes($json, "'")— to avoid CSV collisions when parsing. Arguments can also be variadic by prefixing them with ... (i.e '...string'). Note that only the last argument can be variadic, if an argument is variadic and is not the last, all extra arguments will be packed into the resulting array starting from the variadic position.

• @callback: (callable|null) [optional] Rule callback function. This is where the logic of the rule lives. The callback should validate, sanitize, or check the input and return some value. If empty, the input value will be simply returned as is (fallback: fn ($input) => $input).

• @parameters: (array|null) [optional] Rule callback parameters. Normally this should look something like ['@input'] (fallback: ['@input']). More parameters can be added depending on callback function requirements. The position of the @input depends on the callback function (can be first or any other position). Note that the @input will be injected when the rule is executed. This value has access to the @rule, @name, @input, and @arguments injectables. Nested data can be accessed using dot notation @injectable.someKey or @injectable.0 (with numeric arrays). Fallbacks can also be specified using the syntax @injectable.someKey:fallback (fallbacks must be scalar).

• @input: (mixed) [magic] Rule input. This value is a magic value and is not required inside rule definition array. It references the input value that was provided to the rule when executed.

• @output: (mixed) [magic] Rule callback output. This value is a magic value and is not required inside rule definition array. It references the output resulting from executing rule callback on rule input (fallback: @input, see @callback).

• @comparison: (array|null) [optional] Rule comparison. This is used to compare the rule's callback result against any currently available data. Normally this should look something like ['@output', '!==', false] (fallback: ['@output', '&&', true], returns truthiness of the result). This value has access to the @rule, @name, @input, @arguments, @callback, @parameters, and @output injectables. Nested data can be accessed using dot notation @injectable.someKey or @injectable.0 (with numeric arrays). Fallbacks can also be specified using the syntax @injectable.someKey:fallback (fallbacks must be scalar). All PHP logical and bitwise operators are available with the same syntax (but of course as strings), namely: (L) Logical: ! or not; == or eq; != or <> or neq; === or id; !== or nid; < or lt; <= or lte; > or gt; >= or gte; && or and; || or or; xor. (B) Bitwise: ~; &; |; ^; <<; >>. If an invalid operator is specified, && will be used instead.

• @message: (string|null) [optional] Rule message. This value is optional and is used during validation to provide feedback to the user in case of failure. This value has access to the @input, @output, @arguments, @parameters, @label and @extra injectables. Nested data can be accessed using dot notation @injectable.someKey or @injectable.0 (with numeric arrays). Fallbacks can also be specified using the syntax @injectable.0:fallback (fallbacks must be scalar). Note that injectables in messages have to be wrapped with } (i.e. ${@injectable:fallback}) as placeholder.

• @variables: (array|null) [magic|optional] Rule variables. This value is a magic/optional and is not required inside rule definition array. It is an associative array that holds injectables that can be used to inject some variables into @message placeholders. It contains the variables @input, @output, @arguments, @parameters, @label, and @extra after executing the rule. The @label injectable, is a special injectable that should be overwritten by the validator that executed the rule, it serves as a label for the message to provide more friendly and specific error messages (fallback: The field). The @variables may also sometimes contain the @extra variable, this injectable is also a special injectable that contains some extra variables that the @callback may want to make available to the @message (this is a convention and is not a hard rule). If the @variables is provided in the definition, it will be merged with rule variables after the execution. Note that variables (with the same keys) resulting from executing the rule will overwrite the ones provided in the definition.

• @description: (string|null) [optional] Rule description. This value is optional and has no purpose other than to provide a description for the rule.

• @example: (string|null) [optional] Rule example. This value is optional and has no purpose other than to provide an example of how to use the rule.

Rule definition array.