Skip to content
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

Form: Serverside validation rules #228

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 77 additions & 2 deletions docs/general-concepts/forms/server-side-validation.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,82 @@ This is triggered by specifying a `validate=...` attribute in your form definiti
```
The `validate="tel"` line triggers the validation on this field, and it will use the `test` function in TelRule in libraries/src/Form/Rule to check if the field value is valid.

You can see the list of validation rules that Joomla provides by looking at the class files in the libraries/src/Form/Rule directory, and choose what validation routine you want to run against the fields in your form. For example, to use the EmailRule you would include `validate="email"` against the email field in your form definition.
### List of available validation rules
You can see the list of validation rules that Joomla provides by looking at the class files in the `libraries/src/Form/Rule` directory. Following is a list of all those rules. The title of the entry is the string you have to use in the `validate` attribute.

#### boolean
Checks the value to be either `1`, `0`, `true` or `false`.

#### calendar
Checks the value to be either `now` or a value which the PHP DateTime object accepts.

#### captcha
Validates the value against a captcha solution. This rule has the optional attributes `plugin` and `namespace` to force a specific captcha plugin. If not set, the globally set captcha will be used.

#### color
Checks if the string is 3 or 6 characters long and consists of hexadecimal characters.

#### cssidentifier/cssidentifiersubstring
Checks if the string is a (series of) valid CSS identifiers.

#### email
Check if the string is a valid e-mail adress.
If the attribute `tld` is set to `tld` or `required`, a TLD with at least 2 characters is required.
If the attribute `validDomains` is set to a component name and field name, it tries to load a list of valid domains from the component configuration of said component. The default value is `com_users.domains`. The field supports validating multiple e-mail adresses when the attribute `multiple` is set.
By setting the attribute `unique`, it checks if the adress is already in use in the `#__users` table.

#### equals/notequals
Compares the value to another field of the form given by the `field` attribute.

#### exists
Checks if the value is present in a database table. The table to check is controlled by `exists_table` and the column by `exists_column`. If the column is not given, it defaults to `id`.

#### filepath
Checks if the value is a valid file path. This does NOT check if the file exists, just that the path is inside of the Joomla folder. You can define a list of folders (separated by the pipe symbol (`|`)) to exclude by setting the `exclude` attribute.

#### folderpathexists
Checks if the given path is a valid folder from the root of the Joomla installation and if that folder exists.

#### modulelayout
This checks if the string is valid as a module layout name

#### number
Checks if a number is in a certain range between a `min` and `max` value. These attributes are optional and the comparison is done with float values.

#### options
Checks if the value is from the given options of the field.

#### password
Ensures the given string meets the password requirements set in Joomla.

#### regex
Allows to validate against a regular expression, which is given by `validate_regex`.

#### rules
Ensures that all actions posted are valid for this field.

#### showon
Ensures the given string is in valid `showon` format.

#### subform
Allows to validate subforms field by field.

#### tel
Validate an input as a telephone number. You can influence this by using the attribute `plan`, which allows for the values `northamerica`, `us`, `International`, `int`, `missdn` or `IETF`.

#### time
Validate the input as a valid time. You can limit the valid values by setting the attributes `min`, `max` and `step`.

#### url
Validates the input as a URL and checks for XSS attacks. You can disabled the XSS checks by setting the attribute `disableXssCheck`. You can limit valid values further by setting the attributes `schemes` and `relative`.

#### userid
Checks if the input is a valid user ID.

#### username
Checks if the username is unique in the `#__users` table.


### Custom Server-side Validation
You can define your own validation for a field by writing a custom validation rule. We'll take as an example a custom rule called "custom" which we'll use to replace the Joomla-provided telephone number validation. You can obviously call your own rule whatever you like. Then you have to do 3 things:
- In your field definition against the field add the attribute `validate="custom"` against your field
Expand Down Expand Up @@ -120,4 +195,4 @@ class TelephoneRule extends FormRule
return false;
}
}
```
```