Validation
Validation
Introduction
There are a lot of times when you need to validate incoming input either from a form or from an incoming json request. It is wise to have some form of backend validation as it will allow you to build more secure applications. Masonite provides an extremely flexible and fluent way to validate this data.
Validations are based on rules where you can pass in a key or a list of keys to the rule. The validation will then use all the rules and apply them to the dictionary to validate.
You can see a list of available rules here.
Validating The Request
Incoming form or JSON data can be validated very simply. All you need to do is import the Validator
class, resolve it, and use the necessary rule methods.
This whole snippet will look like this in your controller method:
This validating will read like "user and email are required and the terms must be accepted" (more on available rules and what they mean in a bit)
Note you can either pass in a single value or a list of values
Creating a Rule
Sometimes you may cross a time where you need to create a new rule that isn't available in Masonite or there is such a niche use case that you need to build a rule for.
In this case you can create a new rule.
Rule Command
You can easily create a new rule boiler plate by running:
There is no particular reason that rules are lowercase class names. The main reason it is improves readability when you end up using it as a method if you choose to register the rule with the validation class like you will see below.
This will create a boiler plate rule inside app/rules/equals_masonite.py that looks like:
Constructing our Rule
Our rule class needs 3 methods that you see when you run the rule command, a passes
, message
and negated_message
methods.
Passes Method
The passes method needs to return some kind of boolean value for the use case in which this rule passes.
For example if you need to make a rule that a value always equals Masonite then you can make the method look like this:
When validating a dictionary like this:
then
the
attribute
will be the value (Masonite
)the
key
will be the dictionary key (name
)the
dictionary
will be the full dictionary in case you need to do any additional checks.
Message method
The message method needs to return a string used as the error message. If you are making the rule above then our rule may so far look something like:
Negated Message
The negated message method needs to return a message when this rule is negated. This will basically be a negated statement of the message
method:
Registering our Rule
Now the rule is created we can use it in 1 of 2 ways.
Importing our rule
We can either import directly into our controller method:
or we can register our rule and use it with the Validator class as normal.
Register the rule
In any service provider's boot method (preferably a provider where wsgi=False
to prevent it from running on every request) we can register our rule with the validator class.
If you don't have a provider yet we can make one specifically for adding custom rules:
Then inside this rule provider's boot method we can resolve and register our rule. This will look like:
Now instead of importing the rule we can just use it as normal:
notice we called the method as if it was apart of the validator class this whole time.
Registering rules is especially useful when creating packages for Masonite that contain new rules.
Using The Validator Class
In addition to validating the request class we can also use the validator class directly. This is useful if you need to validate your own dictionary:
Just put the dictionary as the first argument and then each rule being its own argument.
Using The Decorator
Masonite validation has a convenient decorator you can use on your controller methods. This will prevent the controller method being hit all together if validation isn't correct:
This will return a JSON response. You can also choose where to redirect back to:
As well as redirect back to where you came from (if you use the {{ back() }}
template helper)
Both of these redirections will redirect with errors and input. So you can use the
{{ old() }}
template helper to get previous input.
Rule Enclosures
Rule enclosures are self contained classes with rules. You can use these to help reuse your validation logic. For example if you see you are using the same rules often you can use an enclosure to always keep them together and reuse them throughout your code base.
Rule Enclosure Command
You can create a rule enclosure by running:
You will then see a file generated like this inside app/rules:
Creating the Rule Enclosure
You can then fill the list with rules:
You can then use the rule enclosure like this:
You can also use this in addition to other rules:
Message Bag
Working with errors may be a lot especially if you have a lot of errors which results in quite a big dictionary to work with.
Because of this, Masonite Validation comes with a MessageBag
class which you can use to wrap your errors in. This will look like this:
Getting All Errors:
You can easily get all errors using the all()
method:
Checking for any errors
Checking if the bag is Empty
This is just the opposite of the any()
method.
Checking For a Specific Error
Getting the first Key:
Getting the Number of Errors:
Converting to JSON
Get the Amount of Messages:
Get the Messages:
Get the Errors
Get all the Messages:
Merge a Dictionary
You can also merge an existing dictionary into the bag with the errors:
Template Helper
You can use the bag()
template helper which will contain the list of errors. Inside an HTML template you can do something like this:
This will give you all the errors inside each list.
Nested Validations
Sometimes you will need to check values that aren't on the top level of a dictionary like the examples shown here. In this case we can use dot notation to validate deeper dictionaries:
notice the dot notation here. Each .
being a deeper level to the dictionary.
Nested Validations With Lists
Sometimes your validations will have lists and you will need to ensure that each element in the list validates. For example you want to make sure that a user passes in a list of names and ID's.
For this you can use the * asterisk to validate these:
Here is an example to make sure that street is a required field:
Custom Messages
All errors returned will be very generic. Most times you will need to specify some custom error that is more tailored to your user base.
Each rule has a messages keyword arg that can be used to specify your custom errors.
Now instead of returning the generic errors, the error message returned will be the one you supplied.
Leaving out a message will result in the generic one still being returned for that value.
Exceptions
By default, Masonite will not throw exceptions when it encounters failed validations. You can force Masonite to raise a ValueError
when it hits a failed validation:
Now if the required rule fails it will throw a ValueError
. You can catch the message like so:
Custom Exceptions
You can also specify which exceptions should be thrown with which key being checked by using a dictionary:
All other rules within an explicit exception error will throw the ValueError
.
String Validation
In addition to using the methods provided below, you can also use each one as a pipe delimitted string. For example these two validations are identical:
These rules are identical so use whichever feels more comfortable.
Available Rules
Accepted
The accepted rule is most useful when seeing if a checkbox has been checked. When a checkbox is submitted it usually has the value of on
so this rule will check to make sure the value is either on, 1, or yes.
Active_domain
This is used to verify that the domain being passed in is a DNS resolvable domain name. You can also do this for email addresses as well. The preferred search is domain.com but Masonite will strip out http://
, https://
and www
automatically for you.
After_today
Used to make sure the date is a date after today. In this example, this will work for any day that is 2019-10-21 or later.
You may also pass in a timezone for this rule:
Before_today
Used to make sure the date is a date before today. In this example, this will work for any day that is 2019-10-19 or earlier.
You may also pass in a timezone for this rule:
Confirmed
This rule is used to make sure a key is "confirmed". This is simply a key_confirmation
representation of the key.
For example, if you need to confirm a password
you would set the password confirmation to password_confirmation
.
Contains
This is used to make sure a value exists inside an iterable (like a list or string). You may want to check if the string contains the value Masonite for example:
Date
This is used to verify that the value is a valid date. Pendulum module is used to verify validity. It supports the RFC 3339 format, most ISO 8601 formats and some other common formats.
Different
Used to check that value is different from another field value. It is the opposite of matches validation rule.
Distinct
Used to check that an array value contains distinct items.
Does_not
Used for running a set of rules when a set of rules does not match. Has a then()
method as well. Can be seen as the opposite of when.
Email
This is useful for verifying that a value is a valid email address
Equals
Used to make sure a dictionary value is equal to a specific value
Exists
Checks to see if a key exists in the dictionary.
This is good when used with the when rule:
Exists_in_db
Checks that a record field equal to the given value exists in specified database table.
If the attribute does not match the table field name, the table field name can be specified
If you prefer to specify the ORM Model name instead of the table name you can use a fully qualified path to your model
Finally the database connection can be overriden
File
Used to make sure that value is a valid file.
Additionally you can check file size, with different file size formats:
Finally file type can be checked through a MIME types list:
You can combine all those file checks at once:
For image or video file type validation prefer the direct image and video validation rules.
Greater_than
This is used to make sure a value is greater than a specific value
Image
Used to make sure that value is a valid image.
Valid image types are defined by all MIME types starting with image/
. For more details you can check mimetypes
Python package which gives known MIME types with mimetypes.types_map
.
Additionally you can check image size as with basic file validator
In_range
Used when you need to check if an integer is within a given range of numbers
Ip
You can also check if the input is a valid IPv4 address:
Is_future
Checks to see the date and time passed is in the future. This will pass even if the datetime is 5 minutes in the future.
You may also pass in a timezone for this rule:
Is_list
Used to make sure the value is a list (a Python list instance)
*
notation can also be used
Is_in
Used to make sure if a value is in a specific value
notice how 5 is in the list
Is_past
Checks to see the date and time passed is in the past. This will pass even if the datetime is 5 minutes in the past.
You may also pass in a timezone for this rule:
Isnt
This will negate all rules. So if you need to get the opposite of any of these rules you will add them as rules inside this rule.
For example to get the opposite if is_in
you will do:
This will produce an error because age it is looking to make sure age is not in the list now.
Json
Used to make sure a given value is actually a JSON object
Length
Used to make sure a string is of a certain length
Less_than
This is used to make sure a value is less than a specific value
Matches
Used to make sure the value matches another field value
None
Used to make sure the value is None
Numeric
Used to make sure a value is a numeric value
One_of
Sometimes you will want only one of several fields to be required. At least one of them need to be required.
This will pass because at least 1 value has been found: user
.
Phone
You can also use the phone validator to validate the most common phone number formats:
The available patterns are:
123-456-7890
(123)456-7890
Postal Code
Every country has their own postal code formats. We added regular expressions for over 130 countries which you can specify by using a comma separated string of country codes:
Please look up the "alpha-2 code" for available country formats.
Regex
Sometimes you want to do more complex validations on some fields. This rule allows to validate against a regular expression directly. In the following example we check that username
value is a valid user name (without special characters and between 3 and 16 characters).
Required
Used to make sure the value is actually available in the dictionary and not null. This will add errors if the key is not present. To check only the presence of the value in the dictionary use exists.
Required If
Used to make sure that value is present and not empty only if an other field has a given value.
Required With
Used to make sure that value is present and not empty onlyf if any of the other specified fields are present.
String
Used to make sure the value is a string
Strong
The strong rule is used to make sure a string has a certain amount of characters required to be considered a "strong" string.
This is really useful for passwords when you want to make sure a password has at least 8 characters, have at least 2 uppercase letters and at least 2 special characters.
Timezone
You can also validate that a value passed in a valid timezone
Truthy
Used to make sure a value is a truthy value. This is anything that would pass in a simple if statement.
Unique_in_db
Checks that no record should exist for this attribute within the specified database table.
Here the validation will pass if no record exists in users
table with email
equals to user@example.com
.
The same options of exists_in_db
rule can be used. If the attribute does not match the table field name, the table field name can be specified