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.
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
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>
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.
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)
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
attributewill be the value (Masonite) - the
keywill be the dictionary key (name) - the
dictionarywill 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)
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.
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 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.
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
]
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)
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>
You can easily get all errors using the
all() method:errors.all()
"""
{
'email': ['Your email is required'],
'name': ['Your name is required']
}
"""
errors.any() #== True
This is just the opposite of the
any() method.errors.empty() #== False
errors.has('email') #== True
errors.all()
"""
{
'email': ['Your email is required'],
'name': ['Your name is required']
}
"""
errors.first()
"""
{
'email': ['Your email is required']
}
"""
errors.count() #== 2
errors.json()
"""
'{"email": ["Your email is required"],"name": ["Your name is required"]}'
"""
errors.amount('email') #== 1
errors.get('email')
"""
['Your email is required']
"""
errors.errors()
"""
['email', 'name']
"""
errors.messages()
"""
['Your email is required', 'Your name is required']
"""
You can also merge an existing dictionary into the bag with the errors:
errors.merge({'key': 'value'})
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.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'),
​
)
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.
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'
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.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.
​ | ||||
​ | ||||
​ | ||||
​ | ||||
​ | ||||
​ | ||||
​ | ||||
​ | ||||
​ | ||||
​ | ||||
​ | ​ |
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')
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'])
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')
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')
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')
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')
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')
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')
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
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.