Prologue
What's New
Upgrade Guide
The Basics
The Craft Command
The Craft Command
Architectural Concepts
Advanced
Useful Features
Security
Orator ORM
Managers and Drivers
Official Packages
Masonite Essentials
Tutorials
How-to Guides
Deployment

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.

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
def show(self, request: Request, validate: Validator):
"""
Incoming Input: {
'user': 'username123',
'email': 'user@example.com',
'terms': 'on'
}
"""
errors = request.validate(
validate.required(['user', 'email']),
validate.accepted('terms')
)
if errors:
request.session.flash({'errors': errors})
return request.back()

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:

terminal
$ craft rule equals_masonite

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:

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
$ 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
"""
wsgi = False
...
def boot(self, validator: Validator):
"""Boots services required by the container
"""
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:

$ 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 app.rules.LoginForm import AcceptedTerms
def show(self, request: Request):
"""
Incoming Input: {
'user': 'username123',
'email': 'user@example.com',
'terms': 'on'
}
"""
errors = request.validate(AcceptedTerms)
if errors:
request.session.flash('errors': errors)
return request.back()

You can also use this in addition to other rules:

from app.rules.LoginForm import AcceptedTerms
from masonite.validations import email
def show(self, request: Request):
"""
Incoming Input: {
'user': 'username123',
'email': 'user@example.com',
'terms': 'on'
}
"""
errors = request.validate(
AcceptedTerms,
email('email')
)
if errors:
request.session.flash('errors': errors)
return request.back()

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': 'user@example.com'
'user': {
'id': 1,
'email': 'user@example.com',
'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.

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': 'user@example.com'
'user': {
'id': 1,
'email': 'user@example.com',
'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.

Available Rules

accepted

is_in

truthy

active_domain

isnt

when

after_today

is_past

timezone

before_today

is_future

phone

contains

json

equals

length

email

less_than

exists

none

greater_than

numeric

in_range

required

ip

string

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': 'user@example.com'
}
"""
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')

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')

Equals

Used to make sure a dictionary value is equal to a specific value

"""
{
'age': 25
}
"""
validate.equals('age', 25)

Email

This is useful for verifying that a value is a valid email address

"""
{
'domain': 'http://google.com',
'email': 'user@example.com'
}
"""
validate.email('email')

Exists

Checks to see if a key exists in the dictionary.

"""
{
'email': 'user@example.com',
'terms': 'on'
'age': 18
}
"""
validate.exists('terms')

This is good when used with the when rule:

"""
{
'email': 'user@example.com',
'terms': 'on'
'age': 18
}
"""
validate.when(
validate.exists('terms')
).then(
validate.greater_than('age', 18)
)

Greater_than

This is used to make sure a value is greater than a specific value

"""
{
'age': 25
}
"""
validate.greater_than('age', 18)

In_range

Used when you need to check if an integer is within a given range of numbers

"""
{
'attendees': 54
}
"""
validate.in_range('attendees', min=24, max=64)

Ip

You can also check if the input is a valid IPv4 address:

"""
{
'address': '78.281.291.8'
}
"""
validate.ip('address')

Is_in

Used to make sure if a value is in a specific value

"""
{
'age': 5
}
"""
validate.is_in('age', [2,4,5])

notice how 5 is in the list

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:

"""
{
'age': 5
}
"""
validate.isnt(
validate.is_in('age', [2,4,5])
)

This will produce an error because age it is looking to make sure age is not in the list now.

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.

"""
{
'date': '2019-10-20', # Or date in the future
}
"""
validate.is_future('date')

You may also pass in a timezone for this rule:

"""
{
'date': '2019-10-20', # Or date in the future
}
"""
validate.is_future('date', tz='America/New_York')

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.

"""
{
'date': '2019-10-20', # Or date in the future
}
"""
validate.is_past('date')

You may also pass in a timezone for this rule:

"""
{
'date': '2019-10-20', # Or date in the future
}
"""
validate.is_past('date', tz='America/New_York')

Json

Used to make sure a given value is actually a JSON object

"""
{
'user': 1,
'payload': '[{"email": "user@email.com"}]'
}
"""
validate.json('payload')

Length

Used to make sure a string is of a certain length

"""
{
'user': 1,
'description': 'this is a long description'
}
"""
validate.length('description', min=5, max=35)

Less_than

This is used to make sure a value is less than a specific value

"""
{
'age': 25
}
"""
validate.less_than('age', 18)

None

Used to make sure the value is None

"""
{
'age': 25,
'active': None
}
"""
validate.none('active')

Numeric

Used to make sure a value is a numeric value

"""
{
'age': 25,
'active': None
}
"""
validate.numeric('age')

Phone

You can also use the phone validator to validate the most common phone number formats:

"""
{
'phone': '876-827-9271'
}
"""
validate.phone('phone', pattern='123-456-7890')

The available patterns are:

  • 123-456-7890

  • (123)456-7890

Required

Used to make sure the value is actually available in the dictionary. This will add errors if the key is not present

"""
{
'age': 25,
'email': 'user@email.com'
}
"""
validate.required(['age', 'email'])

String

Used to make sure the value is a string

"""
{
'age': 25,
'email': 'user@email.com'
}
"""
validate.string('email')

Timezone

You can also validate that a value passed in a valid timezone

"""
{
'timezone': 'America/New_York'
}
"""
validate.timezone('timezone')

Truthy

Used to make sure a value is a truthy value. This is anything that would pass in a simple if statement.

"""
{
'active': 1,
'email': 'user@email.com'
}
"""
validate.truthy('active')

When

Conditional rules. This is used when you want to run a specific set of rules only if a first set of rules succeeds.

For example if you want to make terms be accepted ONLY if the user is under 18

"""
{
'age': 15,
'email': 'user@email.com',
'terms': 'on'
}
"""
validate.when(
validate.less_than('age', 18)
).then(
validate.required('terms'),
validate.accepted('terms')
)