Links

Validation

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.

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:
from masonite.validation import Validator
from masonite.request import Request
from masonite.response import Response
​
def show(self, request: Request, response: Response, validate: Validator):
"""
Incoming Input: {
'user': 'username123',
'email': '[email protected]',
'terms': 'on'
}
"""
errors = request.validate(
validate.required(['user', 'email']),
validate.accepted('terms')
)
​
if errors:
return response.back().with_errors(errors)
This validation 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

Displaying Errors in Views

You can simply display validation errors in views like this:
@if session().has('errors'):
<div class="bg-yellow-400">
<div class="bg-yellow-200 text-yellow-800 px-4 py-2">
<ul>
@for key, error_list in session().get('errors').items():
@for error in error_list
<li>{{ error }}</li>
@endfor
@endfor
</ul>
</div>
</div>
@endif
If you want to handle errors in views specifically you will need to add the ShareErrorsInSessionMiddleware middleware into your route middlewares. errors will be injected to views as a MessageBag instance allowing to handle errors easily:
@if errors.any():
<div class="bg-yellow-400">
<div class="bg-yellow-200 text-yellow-800 px-4 py-2">
<ul>
@for key, message in errors.all().items()
<li>{{ message }}</li>
@endfor
</ul>
</div>
</div>
@endif
​
<form method="post" action="/contact">
{{ csrf_field }}
<div>
<label for="name">Name</label>
<input type="text" name="name" placeholder="Name">
@if errors.has('name')
<span>{{ errors.get('name')[0] }}</span>
@endif
</div>
<div>
<label for="email">Email</label>
<input type="email" name="email" placeholder="Email">
@if errors.has('email')
<span>{{ errors.get('email')[0] }}</span>
@endif
</div>
<div>
<label for="message">Message</label>
<textarea name="message" placeholder="Message"></textarea>
@if errors.has('message')
<span>{{ errors.get('message')[0] }}</span>
@endif
</div>
<button type="submit">Send</button>
</form>

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:
terminal
$ python craft rule equals_masonite
There is no particular reason that rules are lowercase class names. The main reason is that it 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:
class equals_masonite(BaseValidation):
"""A rule_name validation class
"""
​
def passes(self, attribute, key, dictionary):
"""The passing criteria for this rule.
​
...
"""
return attribute
​
def message(self, key):
"""A message to show when this rule fails
​
...
"""
return '{} is required'.format(key)
​
def negated_message(self, key):
"""A message to show when this rule is negated using a negation rule like 'isnt()'
​
...
"""
return '{} is not required'.format(key)

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:
def passes(self, attribute, key, dictionary):
"""The passing criteria for this rule.
​
...
"""
return attribute == 'Masonite'
When validating a dictionary like this:
{
'name': 'Masonite'
}
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:
def passes(self, attribute, key, dictionary):
"""The passing criteria for this rule.
​
...
"""
return attribute == 'Masonite'
​
def message(self, key):
return '{} must be equal to Masonite'.format(key)
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:
def passes(self, attribute, key, dictionary):
"""The passing criteria for this rule.
​
...
"""
return attribute == 'Masonite'
​
def message(self, key):
return '{} must be equal to Masonite'.format(key)
​
def negated_message(self, key):
return '{} must not be equal to Masonite'.format(key)

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:
from masonite.validation import Validator
from app.rules.equals_masonite import equals_masonite
​
def show(self, request: Request, validate: Validator):
"""
Incoming Input: {
'user': 'username123',
'company': 'Masonite'
}
"""
valid = request.validate(
​
validate.required(['user', 'company']),
equals_masonite('company')
​
)
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:
terminal
$ python craft provider RuleProvider
Then inside this rule provider's boot method we can resolve and register our rule. This will look like:
from app.rules.equals_masonite import equals_masonite
from masonite.validation import Validator
​
class RuleProvider(ServiceProvider):
"""Provides Services To The Service Container
"""
​
def __init__(self, application):
self.application = application
​
def register(self, validator: Validator):
"""Boots services required by the container
"""
​
self.application.make('validator').register(equals_masonite)
Now instead of importing the rule we can just use it as normal:
from masonite.validation import Validator
​
def show(self, request: Request, validate: Validator):
"""
Incoming Input: {
'user': 'username123',
'company': 'Masonite'
}
"""
valid = request.validate(
​
validate.required(['user', 'company']),
validate.equals_masonite('company')
​
)
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:
from masonite.validation import Validator
​
def show(self, validator: Validator):
"""
Incoming Input: {
'user': 'username123',
'company': 'Masonite'
}
"""
valid = validator.validate({
'user': 'username123',
'company': 'Masonite'
},
validate.required(['user', 'company']),
validate.equals_masonite('company')
)
Just put the dictionary as the first argument and then each rule being its own argument.

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:
$ python craft rule:enclosure AcceptedTerms
You will then see a file generated like this inside app/rules:
from masonite.validation import RuleEnclosure
​
...
​
class AcceptedTerms(RuleEnclosure):
​
def rules(self):
""" ... """
return [
# Rules go here
]

Creating the Rule Enclosure

You can then fill the list with rules:
from masonite.validation import required, accepted
​
class LoginForm(RuleEnclosure):
​
def rules(self):
""" ... """
return [
required(['email', 'terms']),
accepted('terms')
]
You can then use the rule enclosure like this:
from masonite.request import Request
from masonite.response import Response
from app.rules.LoginForm import AcceptedTerms
​
def show(self, request: Request, response: Response):
"""
Incoming Input: {
'user': 'username123',
'email': '[email protected]',
'terms': 'on'
}
"""
errors = request.validate(AcceptedTerms)
​
if errors:
request.session.flash('errors', errors)
return response.back()
You can also use this in addition to other rules:
from app.rules.LoginForm import AcceptedTerms
from masonite.validations import email
from masonite.request import Request
from masonite.response import Response
​
def show(self, request: Request, response: Response):
"""
Incoming Input: {
'user': 'username123',
'email': '[email protected]',
'terms': 'on'
}
"""
errors = request.validate(
AcceptedTerms,
email('email')
)
​
if errors:
return response.back().with_errors(errors)

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:
from masonite.validation import MessageBag
# ...
def show(self, request: Request):
errors = request.validate(
email('email')
) #== <masonite.validation.MessageBag>

Getting All Errors:

You can easily get all errors using the all() method:
errors.all()
"""
{
'email': ['Your email is required'],
'name': ['Your name is required']
}
"""

Checking for any errors

errors.any() #== True

Checking if the bag is Empty

This is just the opposite of the any() method.
errors.empty() #== False

Checking For a Specific Error

errors.has('email') #== True

Getting the first Key:

errors.all()
"""
{
'email': ['Your email is required'],
'name': ['Your name is required']
}
"""
errors.first()
"""
{
'email': ['Your email is required']
}
"""

Getting the Number of Errors:

errors.count() #== 2

Converting to JSON

errors.json()
"""
'{"email": ["Your email is required"],"name": ["Your name is required"]}'
"""

Get the Amount of Messages:

errors.amount('email') #== 1

Get the Messages:

errors.get('email')
"""
['Your email is required']
"""

Get the Errors

errors.errors()
"""
['email', 'name']
"""

Get all the Messages:

errors.messages()
"""
['Your email is required', 'Your name is required']
"""

Merge a Dictionary

You can also merge an existing dictionary into the bag with the errors:
errors.merge({'key': 'value'})

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:
"""
{
'domain': 'http://google.com',
'email': '[email protected]'
'user': {
'id': 1,
'email': '[email protected]',
'status': {
'active': 1,
'banned': 0
}
}
}
"""
errors = request.validate(
​
validate.required('user.email'),
validate.truthy('user.status.active')
​
)
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:
"""
{
'domain': 'http://google.com',
'email': '[email protected]'
'user': {
'id': 1,
'email': '[email protected]',
'addresses': [{
'id': 1, 'street': 'A Street',
'id': 2, 'street': 'B Street'
}]
}
}
"""
Here is an example to make sure that street is a required field:
errors = request.validate(
​
validate.required('user.addresses.*.street'),
validate.integer('user.addresses.*.id'),
​
)

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.
"""
{
'terms': 'off',
'active': 'on',
}
"""
validate.accepted(['terms', 'active'], messages = {
'terms': 'You must check the terms box on the bottom',
'active': 'Make sure you are active'
})
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:
"""
{
'domain': 'http://google.com',
'email': '[email protected]'
'user': {
'id': 1,
'email': '[email protected]',
'status': {
'active': 1,
'banned': 0
}
}
}
"""
errors = request.validate(
​
validate.required('user.email', raises=True),
validate.truthy('user.status.active')
​
)
Now if the required rule fails it will throw a ValueError. You can catch the message like so:
try:
errors = request.validate(
​
validate.required('user.email', raises=True),
validate.truthy('user.status.active')
​
)
except ValueError as e:
str(e) #== 'user.email is required'

Custom Exceptions

You can also specify which exceptions should be thrown with which key being checked by using a dictionary:
try:
errors = request.validate(
​
validate.required(['user.email', 'user.id'], raises={
'user.id': AttributeError,
'user.email': CustomException
}),
​
)
except AttributeError as e:
str(e) #== 'user.id is required'
except CustomException as e:
str(e) #== 'user.email is required'
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:
# Normal
errors = request.validate(
validate.required(['email', 'username', 'password', 'bio']),
validate.accepted('terms'),
validate.length('bio', min=5, max=50),
validate.strong('password')
)
​
# With Strings
errors = request.validate({
'email': 'required',
'username': 'required',
'password': 'required|strong',
'bio': 'required|length:5..50'
'terms': 'accepted'
})
These rules are identical so use whichever feels more comfortable.

Available Rules

​accepted​
​active_domain​
​after_today​
​before_today​
​
​confirmed​
​contains​
​date​
​different​
​
​distinct​
​does_not​
​email​
​equals​
​
​exists​
​file​
​greater_than​
​image​
​
​in_range​
​ip​
​is_future​
​is_list​
​
​is_in​
​is_past​
​isnt​
​json​
​
​length​
​less_than​
​matches​
​none​
​
​numeric​
​one_of​
​phone​
​postal_code​
​
​regex​
​required​
​required_if​
​required_with​
​
​string​
​strong​
​timezone​
​truthy​
​
​uuid​
​video​
​when​
​
​

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.
"""
{
'terms': 'on'
}
"""
validate.accepted('terms')

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.
"""
{
'domain': 'http://google.com',
'email': '[email protected]'
}
"""
validate.active_domain(['domain', 'email'])

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.
"""
{
'date': '2019-10-20', # Or date in the future
}
"""
validate.after_today('date')
You may also pass in a timezone for this rule:
"""
{
'date': '2019-10-20', # Or date in the future
}
"""
validate.after_today('date', tz='America/New_York')

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.
"""
{
'date': '2019-10-20', # Or date in the past
}
"""
validate.before_today('date')
You may also pass in a timezone for this rule:
"""
{
'date': '2019-10-20', # Or date in the past
}
"""
validate.before_today('date', tz='America/New_York')

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.
"""
{
'password': 'secret',
'password_confirmation': 'secret'
}
"""
validate.confirmed('password')

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:
"""
{
'description': 'Masonite is an amazing framework'
}
"""
validate.contains('description', 'Masonite')

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.
"""
{
'date': '1975-05-21T22:00:00'
}
"""
validate.date('date')

Different

Used to check that value is different from another field value. It is the opposite of matches validation rule.
"""
{
'first_name': 'Sam',
'last_name': 'Gamji'
}
"""
validate.different('first_name', 'last_name')

Distinct

Used to check that an array value contains distinct items.
"""
{
'users': ['mark', 'joe', 'joe']
}
"""
validate.distinct('users') # would fail
"""
{
'users': [
{
'id': 1,
'name': 'joe'
},
{
'id': 2,
'name': 'mark'
},
]
}
"""
validate.distinct('users.*.id') # would pass

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.
"""
{
'age': 15,
'email': '[email protected]',
'terms': 'on'
}
"""