1 of 82

development

Introduction and Installation

You are browsing the development version of the documentation for an upcoming version of Masonite. It is subject to change.

Stop using old frameworks with just a few confusing features. Masonite is the developer focused dev tool with all the features you need for the rapid development you deserve. Masonite is perfect for beginners getting their first web app deployed or advanced developers and businesses that need to reach for the full fleet of features available.

Masonite works hard to be fast and easy from install to deployment so developers can go from concept to creation in as quick and efficiently as possible. Use it for your next SaaS! Try it once and you’ll fall in love.

Some Notable Features Shipped With Masonite

Mail support for sending emails quickly.
Queue support to speed your application up by sending jobs to run on a queue or asynchronously.
Notifications for sending notifications to your users simply and effectively.
Task scheduling to run your jobs on a schedule (like everyday at midnight) so you can set and forget your tasks.
Events you can listen for to execute listeners that perform your tasks when certain events happen in your app.
A BEAUTIFUL Active Record style ORM called Masonite ORM. Amazingness at your fingertips.
Many more features you need which you can find in the docs!

These, among many other features, are all shipped out of the box and ready to go. Use what you need when you need it.

Requirements

In order to use Masonite, you’ll need:

Python 3.7+
Latest version of OpenSSL
Pip3

All commands of python and pip in this documentation is assuming they are pointing to the correct Python 3 versions. For example, anywhere you see the python command ran it is assuming that is a Python 3.7+ Python installation. If you are having issues with any installation steps just be sure the commands are for Python 3.7+ and not 2.7 or below.

Linux

If you are running on a Linux flavor, you’ll need the Python dev package and the libssl package. You can download these packages by running:

Debian and Ubuntu based Linux distributions

terminal

$ sudo apt install python3-dev python3-pip libssl-dev build-essential python3-venv

Or you may need to specify your python3.x-dev version:

terminal

$ sudo apt-get install python3.7-dev python3-pip libssl-dev build-essential python3-venv

Enterprise Linux based distributions (Fedora, CentOS, RHEL, ...)

terminal

# dnf install python-devel openssl-devel

Installation

Masonite excels at being simple to install and get going. If you are coming from previous versions of Masonite, the order of some of the installation steps have changed a bit.

Firstly, open a terminal and head to a directory you want to create your application in. You might want to create it in a programming directory for example:

$ cd ~/programming
$ mkdir myapp
$ cd myapp

If you are on windows you can just create a directory and open the directory in the Powershell.

Activating Our Virtual Environment (optional)

Although this step is technically optional, it is highly recommended. You can create a virtual environment if you don't want to install all of masonite's dependencies on your systems Python. If you use virtual environments then create your virtual environment by running:

terminal

$ python -m venv venv
$ source venv/bin/activate

or if you are on Windows:

terminal

$ python -m venv venv
$ ./venv/Scripts/activate

The python command here is utilizing Python 3. Your machine may run Python 2 (typically 2.7) by default for UNIX machines. You may set an alias on your machine for Python 3 or simply run python3 anytime you see the python command.

For example, you would run python3 -m venv venv instead of python -m venv venv

Installation

First install the Masonite package:

$ pip install masonite

Then start a new project:

$ project start .

This will create a new project in the current directory.

If you want to create the project in a new directory (e.g. my_project) you must provide the directory name with project start my_project.

Then install Masonite dependencies:

$ project install

If you have created the project in a new directory you must go to this directory before running project install.

Once installed you can run the development server:

$ python craft serve

Congratulations! You’ve setup your first Masonite project! Keep going to learn more about how to use Masonite to build your applications.

Prologue

Creating A Blog Tutorial

This section of the documentation will contain various tutorials. These are guides that are designed to take you from beginning to end on building various types of projects with Masonite. We may not explain things in much detail for each section as this part of the documentation is designed to just get you familiar with the inner workings of Masonite.

Since this section of the documentation is designed to just get you up and coding with Masonite, any further explanations that should be presented are inside various "hint blocks." Once you are done with the tutorial or simply want to learn more about a topic it is advised that you go through each hint block and follow the links to dive deeper into the reference documentation which does significantly more explaining.

Hint Blocks

You will see various hint blocks throughout the tutorials. Below are examples of what the various colors represent.

You'll see hint blocks that are green which you should follow if you want to learn more information about the topic currently being discussed.

You'll also see hint blocks that are blue. These should not be ignored and typically contain background information you need to further understand something.

Installation

Creating a Blog

In this tutorial we will walk through how to create a blog. We will touch on all the major systems of Masonite and it should give you the confidence to try the more advanced tutorials or build an application yourself.

Routing

Typically your first starting point for your Masonite development flow will be to create a route. All routes are located in routes/web.py and are extremely simple to understand. They consist of a request method and a route method. Routing is simply stating what incoming URI's should direct to which controllers.

For example, to create a GET request route it will look like:

We'll talk more about the controller in a little bit.

Creating our Route:

We will start off by creating a view and controller to create a blog post.

A controller is a simply a class that inherits from Masonite's Controller class and contains controller methods. These controller methods will be what our routes will call so they will contain most of our application's business logic.

Think of a controller method as a function in the views.py file if you are coming from the Django framework

Let's create our first route now. We can put all routes inside routes/web.py and inside the ROUTES list. You'll see we have a route for the home page. Let's add a route for creating blogs.

You'll notice here we have a BlogController@show string. This means "use the blog controller's show method to render this route". The only problem here is that we don't yet have a blog controller.

Creating a Controller

All controllers are located in the app/controllers directory by default and Masonite promotes a 1 controller per file structure. This has proven efficient for larger application development because most developers use text editors with advanced search features such as Sublime, VSCode or Atom. Switching between classes in this instance is simple and promotes faster development. It's easy to remember where the controller exactly is because the name of the file is the controller.

You can of course move controllers around wherever you like them but the craft command line tool will default to putting them in separate files. If this seems weird to you it might be worth a try to see if you like this opinionated layout.

Creating Our First Controller

Like most parts of Masonite, you can scaffold a controller with a craft command:

This will create a controller in app/controllers directory that looks like this:

Simple enough, right? You'll notice we have a show method we were looking for. These are called "controller methods" and are similiar to what Django calls a "view."

But also notice we now have our show method that we specified in our route earlier.

Returning a View

We can return a lot of different things in our controller but for now we can return a view from our controller. A view in Masonite are html files or "templates". They are not Python objects themselves like other Python frameworks. Views are what the users will see (or view).

This is important as this is our first introduction to Masonite's IOC container. We specify in our parameter list that we need a view class and Masonite will inject it for us.

For now on we won't focus on the whole controller but just the sections we are worried about. A ... means there is code in between that we are not worried about:

Notice here we "type hinted" the View class. This is what Masonite calls "Auto resolving dependency injection". If this doesn't make sense to you right now don't worry. The more you read on the more you will understand.

Creating Our View

You'll notice now that we are returning the blog view but it does not exist yet.

All views are in the templates directory. We can create a new file called templates/blog.html.

We can put some text in this file like:

Let's run the migration for the first time:

and then run the server

and open up http://localhost:8000/blog. You will see "This is a blog" in your web browser.

Authentication

Most applications will require some form of authentication. Masonite comes with a craft command to scaffold out an authentication system for you. This should typically be ran on fresh installations of Masonite since it will create controllers, routes, and views for you.

For our blog, we will need to setup some form of registration so we can get new users to start posting to our blog. We can create an authentication system by running the craft command:

We should get a success message saying that some new assets were created. You can check your controllers folder and you should see a few new controllers there that should handle registrations.

You can then add the authentication routes to your project:

We will check what was created for us in a bit.

Database Setup

In order to register these users, we will need a database. By default, Masonite uses SQLite. If you want to use a different database you can change the options that start with DB_ in your .env file. For running MySQL or Postgres you will need to have those databases setup already.

We have already run the migration command before, which was:

If you want to use MySQL, open up the .env file in the root of your project and change the DB_DATABASE to mysql. Also, feel free to change the DB_DATABASE name to something else.

Migrating

Once you have set the correct credentials, we can go ahead and migrate the database. Out of the box, Masonite has a migration for a users table which will be the foundation of our user. You can edit this user migration before migrating but the default configuration will suit most needs just fine and you can always add or remove columns at a later date.

This will create our users table for us along with a migrations table to keep track of any migrations we add later.

Creating Users

Now that we have the authentication and the migrations all migrated in, let's create our first user. Remember that we ran craft auth so we have a few new templates and controllers.

Go ahead and run the server:

Migrations

We have looked at running migrations but let's look at how to create a new migration.

Now that we have our authentication setup and we are comfortable with migrating our application, let's create a new migration where we will store our posts.

Our posts table should have a few obvious columns that we will simplify for this tutorial part.

Craft Command

This command simply creates the start of a migration file that we will use to create the posts table. By convention, table names should be plural (and model names should be singular but more on this later).

This will create a migration in the databases/migrations folder. Let's open that up and starting on line 6 we should see something that looks like:

Lets add a title, an author, and a body to our posts tables.

Now we can migrate this migration to create the posts table

Models

Now that we have our tables and migrations all done and we have a posts table, let's create a model for it.

Models in Masonite are a bit different than other Python frameworks. Masonite uses an Active Record ORM. Models and migrations are separate in Masonite. Our models will take shape of our tables regardless of what the table looks like.

Creating our Model

Again, we can use a craft command to create our model:

Notice we used the singular form for our model. By default, Masonite ORM will check for the plural name of the class in our database (in this case posts) by assuming the name of the table is the plural word of the model name. We will talk about how to specify the table explicitly in a bit.

The model created now resides inside app/models/Post.py and when we open it up it should look like:

Simple enough, right? Like previously stated, we don't have to manipulate the model. The model will take shape of the table as we create or change migrations.

Table Name

Again, the table name that the model is attached to is the plural version of the model name but if you called your table something different such as "user_posts" instead of "posts" we can specify the table name explicitly:

Mass Assignment

Masonite ORM by default protects against mass assignment as a security measure so we will explicitly need to set what columns we would like to be fillable (this way we can pass the column names into the create and update methods later).

Relationships

The relationship is pretty straight forward here. Remember that we created a foreign key in our migration. We can create that relationship in our model like so:

Because of how Masonite does models, some models may rely on each other so it is typically better to perform the import inside the relationship like we did above to prevent any possibilities of circular imports.

Designing Our Blog

Let's setup a little HTML so we can learn a bit more about how views work. In this part we will setup a really basic template in order to not clog up this part with too much HTML but we will learn the basics enough that you can move forward and create a really awesome blog template (or collect one from the internet).

Now that we have all the models and migrations setup, we have everything in the backend that we need to create a layout and start creating and updating blog posts.

We will also check if the user is logged in before creating a template.

The Template For Creating

The URL for creating will be located at /blog/create and will be a simple form for creating a blog post

Notice here we have a {{ csrf_field }} below the <form> open tag. Masonite comes with CSRF protection so we need a token to render the hidden field with the CSRF token.

Now we need to make sure the user is logged in before creating this so let's change up our template a bit:

auth() is a view helper function that either returns the current user or returns None.

Static Files

For simplicity sake, we won't be styling our blog with something like Bootstrap but it is important to learn how static files such as CSS works with Masonite so let's walk through how to add a CSS file and add it to our blog.

Firstly, head to storage/static/ and make a blog.css file and throw anything you like in it. For this tutorial we will make the html page slightly grey.

Now we can add it to our template like so right at the top:

That's it. Static files are really simple. It's important to know how they work but for this tutorial we will ignore them for now and focus on more of the backend.

Javascript files are the same exact thing:

The Controller For Creating And The Container

Notice that our action is going to /blog/create so we need to direct a route to our controller method. In this case we will direct it to a store method.

Let's open back up the routes/web.py file and create a new route. Just add this to the ROUTES list:

and create a new store method on our controller:

Now notice above in the form we are going to be receiving 2 form inputs: title and body. So let's import the Post model and create a new post with the input.

Also notice we used an input() method. Masonite does not discriminate against different request methods so getting input on a GET or a POST request are done exactly the same way by using this input method.

Go ahead and run the server using craft serve again and head over to http://localhost:8000/blog and create a post. This should hit the /blog/create route with the POST request method and we should see "post created".

Showing Our Posts

Lets go ahead and show how we can show the posts we just created. Now that we are more comfortabale using the framework, in this part we will create 2 new templates to show all posts and an individual post.

Creating The Templates

Let's create 2 new templates.

templates/posts.html
templates/single.html

Let's start with showing all posts

Creating The Controller

Let's create a controller for the posts to separate it out from the BlogController.

Great! So now in our show method we will show all posts and then we will create a single method to show a specific post.

Show Method

Let's get the show method to return the posts view with all the posts:

Posts Route

We need to add a route for this method:

Posts View

Our posts view can be very simple:

Go ahead and run the server and head over to http://localhost:8000/posts route. You should see a basic representation of your posts. If you only see 1, go to http://localhost:8000/blog to create more so we can show an individual post.

Showing The Author

Remember we made our author relationship before. Masonite ORM will take that relationship and make an attribute from it so we can display the author's name as well:

Let's repeat the process but change our workflow a bit.

Single Post Route

Next we want to just show a single post. We need to add a route for this method:

Notice here we have a @id string. We can use this to grab that section of the URL in our controller in the next section below. This is like a route URL capture group.

Single Method

Let's create a single method so we show a single post.

We use the param() method to fetch the id from the URL. Remember this key was set in the route above when we specified the @id

For a real application we might do something like @slug and then fetch it with request().param('slug').

Single Post View

We just need to display 1 post so lets just put together a simple view:

Go ahead and run the server and head over the http://localhost:8000/post/1 route and then http://localhost:8000/post/2 and see how the posts are different.

Updating and Deleting Posts

By now, all of the logic we have gone over so far will take you a long way so let's just finish up quickly with updating and deleting posts. We'll assume you are comfortable with what we have learned so far so we will run through this faster since this is just more of what were doing in the previous parts.

Update Controller Method

Let's just make an update method on the PostController:

Since we are more comfortable with controllers we can go ahead and make two at once. We made one that shows a view that shows a form to update a post and then one that actually updates the post with the database.

Create The View

templates/update.html

Create The Routes:

Remember we made 2 controller methods so let's attach them to a route here:

That should be it! We can now update our posts.

Delete Method

Let's expand a bit and make a delete method.

Make the route:

Notice we used a GET route here, It would be much better to use a POST method but for simplicity sake will assume you can create one by now. We will just add a link to our update method which will delete the post.

Update the Template

We can throw a delete link right inside our update template:

Great! You now have a blog that you can use to create, view, update and delete posts! Go on to create amazing things!

Release Cycle

Masonite uses SEMVER versioning schema and your requirements should be fixed on any one of these requirements depending on your dependency manager:

masonite>=4,<5
masonite~=4

This will allow your application to stay up to date for all minor releases of the framework.

Major Releases

Masonite currently has an 8 month release cycle. Roughly 8 months we will come out with a new major release. Masonite follows a SEMVER versioning schema

Major releases almost always contain some form of breaking changes. You should only upgrade to major versions after careful local upgrades and testing.

Minor Versions

Minor versions come with new features and could release every few days or every few months depending on how many features are being added to the codebase and when those features are ready to be released.

Minor version updates will never come with breaking changes. You should always stay up to date with the latest minor versions of the framework.

Patch Versions

Patch versions are small fixes or security releases.

Patch version updates will never come with breaking changes. You should always stay up to date with the latest patch versions of the framework.

Contributing Guide

When contributing to Masonite, please first discuss the change you wish to make via a GitHub issue. Starting with a GitHub issue allows all contributors and maintainers to have a chance to give input on the issue. It creates a public forum to discuss the best way to implement the issue, fix, or improvement. It also creates an open discussion on if the issue will even be permitted to be in the project.

Please note we have a code of conduct, please follow it in all your interactions with the project. You can find it in this in this documentation as well as all of Masonite's repositories.

Getting Started

The framework has 2 main parts: The "masonite" repo and the "cookie-cutter" repo.

The MasoniteFramework/cookie-cutter repository is the main repository that will install when creating new projects using the project start command. This is actually a full Masonite project. When you run project start it simply reaches out to this GitHub repo, fetches the zip and unzips it on your computer. Not much development will be done in this repository and won't be changed unless something requires changes in the default installation project structure.

The MasoniteFramework/core repository is deprecated and development has been moved into MasoniteFramework/masonite. This repository contains all the development of Masonite and contains all the releases for Masonite. If you need to fix a bug or add a new feature then this is the repository to fork and make your changes from.

The MasoniteFramework/craft is deprecated. This was where the craft CLI tool lived that has since been moved into the masonite repository.

This repo is simple and will be able to be installed following the installation instruction in the README.

Fork the MasoniteFramework/cookie-cutter repo.
Clone that repo into your computer:
- git clone http://github.com/your-username/cookie-cutter.git
Checkout the current release branch (example: develop)
- git checkout -b develop
You should now be on a develop local branch.
Run git pull origin develop to get the current release version.
From there simply create your feature branches (<feature|fix>-<issue-number>) and make your desired changes.
Push to your origin repository:
- git push origin change-default-orm
Open a pull request and follow the PR process below

Editing the Masonite repository

The trick to this is that we need it to be pip installed and then quickly editable until we like it, and then pushed back to the repo for a PR. Do this only if you want to make changes to the core Masonite package

To do this just:

Fork the MasoniteFramework/masonite repo,
Clone that repo into your computer:
- git clone http://github.com/your-username/masonite.git
Activate your masonite virtual environment (optional)
- Go to where you installed masonite and activate the environment
While inside the virtual environment, cd into the directory you installed core.
Run pip install -e . from inside the masonite directory. This will install masonite as a pip package in editable mode. Any changes you make to the codebase will immediately be available in your project. You may need to restart your development server.
Any changes you make to this package just push to your feature branch on your fork and follow the PR process below.

Comments

Comments are a vital part of any repository and should be used where needed. It is important not to overcomment something. If you find you need to constantly add comments, you're code may be too complex. Code should be self documenting (with clearly defined variable and method names)

Types of comments to use

There are 3 main type of comments you should use when developing for Masonite:

Module Docstrings

All modules should have a docstring at the top of every module file and should look something like:

Notice there are no spaces before and after the sentence.

Method and Function Docstrings

All methods and functions should also contain a docstring with a brief description of what the module does

For example:

Methods and Functions with Dependencies

Most methods will require some dependency or parameters. You must specify them like this:

And if your dependencies are objects it should give the path to the module:

Code Comments

Code comments should be left to a MINIMUM. If your code is complex to the point that it requires a comment then you should consider refactoring your code instead of adding a comment. If you're code MUST be complex enough that future developers may not understand it, add a # comment above it

For normal code this will look something like:

Pull Request Process

Please read this process carefully to prevent pull requests from being rejected.

You should open an issue before making any pull requests. Not all features will be added to the framework and some may be better off as a third party package or not be added at all. It wouldn't be good if you worked on a feature for several days and the pull request gets rejected for reasons that could have been discussed in an issue for several minutes.
Ensure any changes are well commented and any configuration files that are added have docstring comments on the variables it's setting. See the comments section above.
Update the MasoniteFramework/docs repo (and the README.md inside MasoniteFramework/masonite repo if applicable) with details of changes to the UI. This includes new environment variables, new file locations, container parameters, new feature explanations etc.
Name your branches in the form of <feature|fix>/<issue-number>. For example if you are doing a bug fix and the issue number is 576 then name your branch fix/576. This will help us locate the branches on our computers at later dates. If it is a new feature name it feature/576.
You must add unit testing for any changes made before the PR will be merged. If you are unsure how to write unit tests of the repositories listed above, you may open the pull request anyway and we will add the tests together.
The PR must pass the GitHub actions that run on pull requests. The Pull Request can be merged in once you have a successful review from two other collaborators, or one review from a maintainer.

Branching

Branching is also important. Depending on what fixes or features you are making you will need to branch from (and back into) the current branch. Branching for Masonite simple:

1) All of Masonite repositories, packages, etc. follow the same basic branching flow.

2) Each repository has: a current release branch, previous release branches, a master branch and a develop branch.

3) The current release branch is what the current release is on. So for example, Masonite is on version 2.3 so the current release branch will be 2.3.

4) Previous release branches are the same thing but instead are just previous versions. So if Masonite is currently on 4.0 then the previous release branches could be 3.0, 2.1, 2.2, etc.

5) The master branch is a staging branch that will eventually be merged into the current release branch. Here is where all non breaking changes will be staged (new non breaking features and bug fixes).

6) The develop branch is a staging branch to the next major version. So for example, Masonite will be on version 4.0. If you have an idea for a feature but it will break the existing feature then you will branch from (and back into) the develop branch. This branch will eventually be merged into 4.1 branch and become apart of the next major version when that is released.

Examples:

For example, if you want to make a new feature and you know it will not break anything (like adding the ability to queue something) then you will branch from the master branch following the Pull Request flow from above. The PR will be open to the master branch. This feature will then be merged into the current release branch and be released as a new minor version bump (4.1.0).

Bug fixes that do not break anything is the same process as above.

New features will be the same process but be branched off of the develop branch. You will make your change and then open a pull request to the develop branch. This is a long running branch and will be merged once the next major version of Masonite is ready to be released.

Code of Conduct

Our Pledge

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.

Our Standards

Examples of behavior that contributes to creating a positive environment include:

Using welcoming and inclusive language
Being respectful of differing viewpoints and experiences
Gracefully accepting constructive criticism
Focusing on what is best for the community
Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

The use of sexualized language or imagery and unwelcome sexual attention or advances
Trolling, insulting/derogatory comments, and personal or political attacks
Public or private harassment
Publishing others' private information, such as a physical or electronic
address, without explicit permission
Other conduct which could reasonably be considered inappropriate in a
professional setting

Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.

Scope

This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at joe@masoniteproject.com. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.

Attribution

How To Contribute

Introduction

There are plenty of ways to contribute to open source. Many of which don't even rely on writing code. A great open source project should have excellent documentation, a thriving community and have as little bugs as possible. Below I will explain how to contribute to this project in different ways both including and exluding code contributions.

This is not an exhaustive list and not the only ways to contribute but they are the most common. If you know of other ways to contribute then please let us know.

Contributing to Development

Become a Feature Maintainer

Feature maintainers must already have significant contributions to development of the repository they are trying to be a Feature Maintainer for. Although they do not have to be contributors to the actual feature they plan to maintain.

Comment the Code

If you don't want to touch the code and instead want to just look at it and figure it out, contribute some comments! Comments are an excellent way for future developers to read and understand the framework. Masonite strives on being extremely commented. Although most of the code itself does not need to be commented, some of the classes, modules, methods and functions do (although a lot of them already are).

Comments don't affect the working code so if you want to get used to contributing to open source or you just don't quite understand what a class method is doing or you are afraid of contributing and breaking the project (there are tests) then contributing comments is right for you!

Write Tests

Contribute to Tutorials

Plus there will be fantastic tutorials out there for beginners to find and watch and you could also build a following off the back of Masonite.

Fix the Documentation

Report Bugs

Squash Bugs

Build a Community

If you have a large following on any social media or no following at all, you can contribute by trying to build up a following around Masonite. Any open source project requires an amazing community around the framework. You can either build up a community personally and be the leader of that community or you can simply send them to Masonite's GitHub repository where we can build up a community around there.

Build Community Software Around Masonite

Answer Questions from the Community

Questions will come in eventually either through the GitHub issues or through websites like StackOverflow. You could make it a priority to be the first to answer these peoples questions or if you don't know the answer you can redirect one of the core maintainers or contributors to the question so we can answer it further.

Review Code on Pull Requests

Discuss Issues

Every now and then will be a requires discussion label on an issue or pull request. If you see this label then be sure to add your thoughts on an issue. All issues are open for discussion and Masonite strives off of developer input so feel free to enter a discussion.

Create Packages

Every framework needs great packages and we as the maintainers of Masonite can only do so much with coming out with great packages and maintaining the framework at the same time. We look forward to our community coming out with awesome additions to the Masonite ecosystem. If you have any issues then be sure to open in the gitter chatroom on the Github homepage.

The Basics

Controllers

Controllers are a place where most of your business logic will be. Controllers are where you put the responses you see in the web browser. Responses can be dictionaries, lists, views or any class that can render a response.

Introduction

You may use a craft command to create a new basic controller or simply make a new controller manually. Controllers are classes with methods that are mapped to a route.

Your route may look something like this:

In this case this route will call the WelcomeController classes show method.

To create a basic controller via a craft command simply run:

This will create a new controller class to get you setup quickly. This controller class will look like a basic class like this:

You may start building your controller out and adding the responses you need.

Note that the controllers inherit Masonite base Controller class. This is required for Masonite to pick up your controller class in routes.

Dependency Injection

Responses

Controllers can have different response types based on what you need to return.

JSON

If you want to return a JSON response you can return a dictionary or a list:

This will return an application/json response.

Strings

You can return strings:

Views

If you want to return a view you can resolve the view class and use the render method:

Models

If you are using Masonite ORM, you can return a model directly:

Redirects

If you want to return a redirect you can resolve the response class and use the redirect method:

Other

You can return any class that contains a get_response() method. This method needs to return any one of the above response types.

Request Parameters

If you had a parameter in your route, you may fetch it by specifying the parameter in the controller's method:

Since the id parameter is in the route we can fetch the value of this parameter by specifying it in the controller method signature:

Another way to fetch route parameters is through the request class:

Controller Locations

The default registered controllers location is app/controllers and is defined in project Kernel.py configuration file:

Setting locations

You can override the registered controllers location in Kernel.py file by editing the default binding controllers.location.

Adding locations

You can multiple additional controller locations with add_controller_locations:

The best place to do this is in your Kernel.py file in the register_routes() method.

You should do it before registering routes, else registering routes will fail as Masonite will fail to resolve controller classes.

Middleware

Middleware is an extremely important aspect of web applications as it allows you to run important code either before or after every request or even before or after certain routes. In this documentation we'll talk about how middleware works, how to consume middleware and how to create your own middlewar

Getting Started

Middleware classes are placed inside the Kernel class. All middleware are just classes that contain a before method and after method.

There are four types of middleware in total:

Middleware ran before every request
Middleware ran after every request
Middleware ran before certain routes
Middleware ran after certain routes

Configuration

We have one of two configuration attributes we need to work with. These attributes both reside in our Kernel file and are http_middleware and route_middleware.

http_middleware is a simple list which should contain your middleware classes. This attribute is a list because all middleware will simply run in succession one after another, similar to Django middleware

In our Kernel file this type of middleware may look something like:

from masonite.middleware import EncryptCookies

class Kernel:

    http_middleware = [
        EncryptCookies
    ]

Middleware will run on every inbound request to the application whether or not a route was found or not.

Route Middleware

Route middleware is also simple but instead of a list, it is a dictionary with a custom name as the key and a list of middleware. This is so we can specify the middleware based on the key in our routes file.

In our config/middleware.py file this might look something like:

from app.middleware.RouteMiddleware import RouteMiddleware
class Kernel:

  #..

  route_middleware = {
      "web": [
          SessionMiddleware, 
          HashIDMiddleware,
          VerifyCsrfToken,
      ],
  }

By default, all routes inside the web.py file will run the web middleware list

Middleware Parameters

You can pass parameters from your routes to your middleware in cases where a middleware should act differently depending on your route.

You can do this with a : symbol next to your route middleware name and then pass in those parameters to the before and after middleware methods.

For example, we may be creating a middleware for request throttling and in our routes we have something like this:

Get('/feeds', 'FeedController').middleware('throttle:2,100')

notice the throttle:2,100 syntax. The 2 and the 100 will then be passed into the before and after methods of your middleware:

class ThrottleMiddleware:

    def before(self, request, response, minutes, requests):
        # throttle requests

    def after(self, request, response, 
             minutes, requests):
        # throttle requests

Request Parameters

Similiar to the way we can pass values to a middleware using the : splice we can also use the @ in the value to pass the value of the parameter.

For example, we may create a route and a middleware like this

Get('/dashboard/@user_id/settings', 'FeedController').middleware('permission:@user_id')

If we go to a route like /dashboard/152/settings then the value of 152 will be passed to the middleware before and after methods.

Creating Middleware

Middleware:

can live anywhere in your project,
Inherit from Masonite's base middleware class
Contain a before and after method that accepts request and response parameters

from masonite.middleware import Middleware

class AuthenticationMiddleware(Middleware):
    """Middleware class
    """

    def before(self, request, response):
        #..
        return request

    def after(self, request, response):
        #..
        return request

It's important to note that in order for the request lifecycle to continue, you must return the request class. If you do not return the request class, no other middleware will run after that middleware.

That's it! Now we just have to make sure our route picks this up. If we wanted this to execute after a request, we could use the exact same logic in the after method instead.

Consuming Middleware

If we are using a route middleware, we'll need to specify which route should execute the middleware. To specify which route we can just append a .middleware() method onto our routes. This will look something like:

Route.get('/dashboard', 'DashboardController@show').name('dashboard').middleware('auth')
Route.get('/login', 'LoginController@show').name('login')

Response

The request and the response in Masonite work together to form a well formed response that a browser can read and render. The Response class is responsible for what data is returned and how it is formatted. In this case, a response can have cookies and headers. The Request class can also have cookies and headers. In most times, generally, when you have to fetch headers or cookies you should do so on the request class and when you set cookies and headers you should do so on the response class.

Cookies

Cookies on the response class are attached to the response and rendered as part of the response headers. Any incoming cookies you would likely fetch from the request class but you can fetch them from the response if you have a reason to:

from masonite.response import Response

def show(self, response: Response):
    response.cookie("key")

You can also set cookies on the response:

from masonite.response import Response

def show(self, response: Response):
    response.cookie("Accepted-Cookies", "True")

You can also delete cookies:

from masonite.response import Response

def show(self, response: Response):
    response.delete_cookie("Accepted-Cookies")

Redirecting

You can redirect the user to any number of URL's.

First you can redirect to a simple URL:

from masonite.response import Response

def show(self, response: Response):
    return response.redirect('/home')

You can redirect back to where the user came from:

from masonite.response import Response

def show(self, response: Response):
    return response.back()

If using the back method as part of a form request then you will need to use the back view helper as well:

<form>
  {{ csrf_field }}
  {{ back() }}
  <input type="text">
  ...
</form>

You can also redirect to a route by its name:

from masonite.response import Response

def show(self, response: Response):
    return response.redirect(name='users.home')

This will find a named route users.home like:

Route.get('/dashboard/@user_id', 'DashboardController@show').name('users.home')

You may also pass parameters to a route if the URL requires it:

from masonite.response import Response

def show(self, response: Response):
    return response.redirect(name='users.home', params={"user_id", 1})

Finally you may also pass query string parameters to the url or route to redirect:

def show(self, response: Response):
    return response.redirect(name='users.home', params={"user_id", 1}, query_params={"mode": "preview"})
#== will redirect to /dashboard/1?mode=preview

with_success

You can redirect by flashing a success message into session:

def show(self, response: Response):
    return response.redirect('/home').with_success("Preferences have been saved !")

with_errors

You can redirect by flashing an error message or errors messages into session:

def show(self, request: Request, response: Response):
    return response.redirect('/home').with_errors("This account is disabled !")

You can directly use validation errors:

def show(self, request: Request, response: Response):
    errors = request.validate({
        "name": required
    })
    return response.redirect('/home').with_errors(errors)

with_input

You can redirect by flashing form input into session, to re-populate the form when there are errors:

def show(self, request: Request, response: Response):
    errors = request.validate({
        "name": required
    })
    return response.redirect('/home').with_errors(errors).with_input()

Headers

Response headers are any headers that will be found on the response. Masonite takes care of all the important headers for you but there are times where you want to set you own custom headers.

Most incoming headers you want to get can be found on the request class but if you need to get any headers on the response:

from masonite.response import Response

def show(self, response: Response):
	response.header('key')

Any responses you want to be returned should be set on the response class:

from masonite.response import Response

def show(self, response: Response):
	response.header('X-Custom', 'value')

This will set the header on the response.

Status

You can set the status on the response simply:

from masonite.response import Response

def show(self, response: Response):
	response.status(409)

Downloading

You can also very simply download assets like images, PDF's or other files:

def show(self, response: Response):
  return response.download("invoice-2021-01", "path/to/invoice.pdf")

This will set all the proper headers required and render the file in the browser.

When setting the name, the file extension will be picked up from the file type. This example will download the invoice as the name invoice-2021-01.pdf

If you want to force download it, or automatically download the file when the response in rendered, you can add a force parameter and set it to True:

def show(self, response: Response):
    return response.download("invoice-2021-01", "path/to/invoice.pdf", force=True)

Request

The request and the response in Masonite work together to form a well formed response that a browser can read and render. The Request class is used to fetch any incoming cookies, headers, URL's, paths, request methods and other incoming data.

Cookies

Although both the request and response classes have headers and cookies, in most instances, when fetching cookies and headers, it should be fetched from the Request class. When setting headers and cookies it should be done on the response class.

To get cookies you can do so simply:

This will fetch the cookie from the incoming request headers.

You can also set cookies on the request:

Note that setting cookies on the request will NOT return the cookie as part of the response and therefore will NOT keep the cookie from request to request.

Headers

Although both the request and response classes have headers and cookies, in most instances, when fetching cookies and headers, it should be fetched from the Request class. When setting headers and cookies it should be done on the response class.

To get a request header you can do so simply:

You can also set a header on the request class:

Note that setting headers on the request will NOT return the header as part of the response.

Paths

You can get the current request URI:

You can get the current request method:

You can check if the current path contains a glob style schema:

You can get the current subdomain from the host:

You can get the current host:

Inputs

Inputs can be from any kind of request method. In Masonite, fetching the input is the same no matter which request method it is.

To fetch an input we can do:

If an input doesn't exist you can pass in a default:

To fetch all inputs from request we can do:

Or we can only fetch some inputs:

To fetch all inputs from request we can do:

Getting Dictionary Input

If your input is a dictionary you can access nested data in two ways. Take this code example:

You can either access it normally:

Or you can use dot notation to fetch the value for simplicity:

You can also use a * wildcard to get all values from a dictionary list.:

Route Params

Route parameters are parameters specified in a route and captured from the URL:

If you have a route like this:

You can get the value of the @user_id parameter like this:

User

As a convenient way to fetch the user, you can do so directly on the request class if a user is logged in:

If the user is not authenticated then this will be set to None

IP Address

You can fetch the IP address (ipv4) from which the request has been made by adding the IpMiddleware to the HTTP middlewares of the project:

Then you can use the ip() helper:

IP address is retrieved from various HTTP request headers in the following order:

HTTP_CLIENT_IP
HTTP_X_FORWARDED_FOR
HTTP_X_FORWARDED
HTTP_X_CLUSTER_CLIENT_IP
HTTP_FORWARDED_FOR
HTTP_FORWARDED
REMOTE_ADDR

The first non-private and non-reserved IP address found by resolving the different headers will be returned by the helper.

The headers used and their order can be customized by overriding the IpMiddleware and changing the headers attribute:

Static Files

Masonite tries to make static files extremely easy and comes with whitenoise out of the box. Whitenoise wraps the WSGI application and listens for certain URI requests that can be registered in your configuration files and serves those assets.

Configuration

All configurations that are specific to static files can be found in config/filesystem.py. In this file you'll find a constant file called STATICFILES which is simply a dictionary of directories as keys and aliases as the value.

The directories to include as keys are simply the location of your static file locations as a relative path starting from the base of your application. For example, if your css files are in storage/assets/css then put that folder location as the key. For the value, put the alias you want to use in your templates. For this example, we will use css/ as the alias.

For this setup, our STATICFILES constant should look like:

Now in our templates we can use:

Which will get the storage/assets/css/style.css file.

Static Template Function

All templates have a static function that can be used to assist in getting locations of static files. You can specify the driver and locations you want using the driver name or dot notation.

Take this for example:

this will render:

You can also make the config location a dictionary and use dot notation:

and use the dot notation like so:

Serving "Root" Files

Sometimes you may need to serve files that are normally in the root of your application such as a robots.txt or manifest.json. These files can be aliased in your STATICFILES directory in config/filesystem.py. They do not have to be in the root of your project but instead could be in a storage/root or storage/public directory and aliased with a simple /.

For example a basic setup would have this as your directory:

and you can alias this in your STATICFILES constant:

You will now be able to access localhost:8000/robots.txt and you will have your robots.txt served correctly and it can be indexed by search engines properly.

Thats it! Static files are extremely simple. You are now a master at static files!

Views

Views in Masonite are a great way to return HTML in your controllers. Views have a hierarchy, lots of helpers and logical controls, and a great way to separate out your business logic from your presentation logic.

Getting Started

By default, all templates for your views are located in the templates directory. To create a template, simply create a .html file inside this directory which we will reference to later.

<!-- Template in templates/welcome.html -->
<html>
    <body>
        <h1>Hello, {{ name }}</h1>
    </body>
</html>

Then inside your controller file you can reference this template:

from masonite.views import View

class WelcomeController(Controller):

  def show(self, view: View):
    view.render('welcome', {
    	"name": "Joe"
    })

The first argument here is the name of your template and the second argument should be a dictionary of variables you reference inside your template.

If you have a template inside another directory you can use dot notation to reference those template names

from masonite.views import View

class WelcomeController(Controller):

  # Template is templates/greetings/welcome.html
  def show(self, view: View):
    view.render('greeting.welcome', {
    	"name": "Joe"
    })

View sharing is when you want a variable to be available in all templates that are rendered. This could be the authenticated user, a copyright year, or anything else you want shared between templates.

View sharing requires you to add a dictionary:

from masonite.facades import View

View.share({
  'copyright': '2021'
})

Then inside your template you can do:

<div>
  Copyright {{ copyright }}
</div>

from masonite.facades import View

class AppProvider(Provider):

    def register(self):
        View.share({'copyright': '2021'})

View Composing

Similiar to view sharing, view composing allows you to share templates between specific templates

View.composer('dashboard', {'copyright': '2021'})

You may also pass a list of templates:

View.composer(['dashboard', 'dashboard/users'], {'copyright': '2021'})

from masonite.facades import View

class AppProvider(Provider):

    def register(self):
        View.composer('dashboard', {'copyright': '2021'})

Helpers

There are quite a few built in helpers in your views. Here is an extensive list of all view helpers:

Request

You can get the request class:

<p> Path: {{ request().path }} </p>

Asset

You can get the location of static assets:

You can create a path to an asset by using the asset helper:

...
<img src="{{ asset('s3', 'profile.jpg') }}" alt="profile">
...

this will render a URL like this:

<img src="https://s3.us-east-2.amazonaws.com/bucket/profile.jpg" alt="profile">

See your filesystems.py configuration for how how to set the paths up.

CSRF Field

You can create a CSRF token hidden field to be used with forms:

<form action="/some/url" method="POST">
    {{ csrf_field }}
    <input ..>
</form>

CSRF Token

You can get only the token that generates. This is useful for JS frontends where you need to pass a CSRF token to the backend for an AJAX call

<p> Token: {{ csrf_token }} </p>

Current User

You can also get the current authenticated user. This is the same as doing request.user().

<p> User: {{ auth().email }} </p>

This will now submit this form as a PUT request.

Route

You can get a route by it's name by using this method:

<form action="{{ route('route.name') }}" method="POST">
    ..
</form>

If your route contains variables you need to pass then you can supply a dictionary as the second argument.

<form action="{{ route('route.name', {'id': 1}) }}" method="POST">
    ..
</form>

or a list:

<form action="{{ route('route.name', [1]) }}" method="POST">
    ..
</form>

Back

This is useful for redirecting back to the previous page. If you supply this helper then the request.back() method will go to this endpoint. It's typically good to use this to go back to a page after a form is submitted with errors:

<form action="/some/url" method="POST">
    {{ back(request().path) }}
</form>

Now when a form is submitted and you want to send the user back then in your controller you just have to do:

def show(self, response: Response):
    # Some failed validation
    return response.back()

Session

You can access the session here:

<p> Error: {{ session().get('error') }} </p>

Config

This allows you to easily fetch configuration values in your templates:

<h2> App Name: {{ config('application.name') }}</h2>

Gets a cookie:

<h2> Token: {{ cookie('token') }}</h2>

Url

Get the URL to a location:

<form action="{{ url('/about', full=True) }}" method="POST">

</form>

DD

To help in debugging, you can use the dd() helper

{{ dd(variable) }}

View Filters

Jinja2 allows adding filters to your views. Before we explain how to add filters to all of your templates, let's explain exactly what a view filter is.

Filters can be attached to view variables in order to change and modify them. For example you may have a variable that you want to turn into a slug and have something like:

{{ variable|slug }}

In Masonite, this slug filter is simply a function that takes the variable as an argument and would look like a simple function like this:

def slug(variable):
    return variable.replace(' ', '-')

That's it! It's important to note that the variable it is filtering is always passed as the first argument and all other parameters are passed in after so we could do something like:

{{ variable|slug('-') }}

and then our function would look like:

def slug(variable, replace_with):
    return variable.replace(' ', replace_with)

Adding Filters

from masonite.facades import View


class AppProvider(Provider):

    def register(self):
        View.('slug', self.slug)

    @staticmethod
    def slug(item):
        return item.replace(' ', '-')

View Tests

View tests are simply custom boolean expressions that can be used in your templates. We may want to run boolean tests on specific objects to assert that they pass a test. For example we may want to test if a user is an owner of a company like this:

<div>
    

<div data-gb-custom-block data-tag="if"></div>

        hey boss
    

<div data-gb-custom-block data-tag="else">

        you are an employee
    

</div>

</div>

The code is simple and looks something like this:

from masonite.facades import View


def a_company_owner(user):
    # Returns True or False
    return user.owner == 1

class AppProvider(Provider):

    def register(self):
        # template alias
        View.test('a_company_owner', a_company_owner)

That's it! Now we can use the a_company_owner in our templates just like the first code snippet above!

Notice that we only supplied the function and we did not instantiate anything. The function or object we supply needs to have 1 parameter which is the object or string we are testing.

Adding Environments

Environments in views are directories of templates. If you are development packages or building a modular based application, you may have to register different directories for templates. This will allow Masonite to locate your views when referencing them to render. A good place to do this is inside a service provider's register method.

There are 2 separate kinds of loaders.

The first loader is a "package" loader. This is used when registering a package. To do this you can simply register it with the package module path. This will work for most directories that are packages.

from masonite.facades import View

View.add('module_name/directory')

The other loader is a FileSystem loader. This should be used when the directory path is NOT a module but rather just a file system path:

from jinja2.loaders import FileSystemLoader
from masonite.facades import View

View.add(
    os.path.join(
        os.getcwd(), 'package_views'
    )
, loader=FileSystemLoader)

View Syntax

Jinja2

Below are some examples of the Jinja2 syntax which Masonite uses to build views.

Line Statements

It's important to note that Jinja2 statements can be rewritten with line statements and line statements are preferred in Masonite. In comparison to Jinja2 line statements evaluate the whole line, thus the name line statement.

So Jinja2 syntax looks like this:

<div data-gb-custom-block data-tag="if">

    <p>do something</p>

</div>

This can be rewritten like this with line statement syntax:

@if expression
    <p>do something</p>
@endif

It's important to note though that these are line statements. Meaning nothing else can be on the line when doing these. For example you CANNOT do this:

<form action="@if expression: 'something' @endif">

</form>

But you could achieve that with the regular formatting:

<form action="

<div data-gb-custom-block data-tag="if"> 'something' </div>">

</form>

Whichever syntax you choose is up to you.

Note that if you are using an @ symbol that should not be rendered with Masonite then this will throw an error. An example being when you are using @media tags in CSS. In this case you will need to wrap this statement inside `` and `

` blocks.

Variables

You can show variable or string text by using {{ }} characters:

<p>
    {{ variable }}
</p>
<p>
    {{ 'hello world' }}
</p>

If statement

If statements are similar to python but require an endif!

Line Statements:

@if expression
    <p>do something</p>
@elif expression
    <p>do something else</p>
@else
    <p>above all are false</p>
@endif

Using alternative Jinja2 syntax:

<div data-gb-custom-block data-tag="if"></div>

    <p>do something</p>

<div data-gb-custom-block data-tag="elif"></div>

    <p>do something else</p>

<div data-gb-custom-block data-tag="else">

    <p>above all are false</p>

</div>

For Loops

For loop look similar to the regular python syntax.

Line Statements:

@for item in items
    <p>{{ item }}</p>
@endfor

Using alternative Jinja2 syntax:

<div data-gb-custom-block data-tag="for">

    <p>{{ item }}</p>

</div>

Include statement

An include statement is useful for including other templates.

Line Statements:

@include 'components/errors.html'

<form action="/">

</form>

Using alternative Jinja2 syntax:

<div data-gb-custom-block data-tag="include" data-0='components/errors.html'></div>

<form action="/">

</form>

Any place you have repeating code you can break out and put it into an include template. These templates will have access to all variables in the current template.

Extends

This is useful for having a child template extend a parent template. There can only be 1 extends per template:

Line Statements:

@extends 'components/base.html'

@block content
    <p> read below to find out what a block is </p>
@endblock

Using alternative Jinja2 syntax:

<div data-gb-custom-block data-tag="extends" data-0='components/base.html'></div>

<div data-gb-custom-block data-tag="block">

    <p> read below to find out what a block is </p>

</div>

Blocks

Blocks are sections of code that can be used as placeholders for a parent template. These are only useful when used with the extends above. The "base.html" template is the parent template and contains blocks, which are defined in the child template "blocks.html".

Line Statements:

<!-- components/base.html -->
<html>
    <head>
        @block css
        <!-- block named "css" defined in child template will be inserted here -->
        @endblock
    </head>

<body>
    <div class="container">
        @block content
        <!-- block named "content" defined in child template will be inserted here -->
        @endblock
    </div>

@block js
<!-- block named "js" defined in child template will be inserted here -->
@endblock

</body>
</html>

<!-- components/blocks.html -->
@extends 'components/base.html'

@block css
    <link rel=".." ..>
@endblock

@block content
    <p> This is content </p>
@endblock

@block js
    <script src=".." />
@endblock

Using alternative Jinja2 syntax:

<!-- components/base.html -->
<html>
    <head>
        

<div data-gb-custom-block data-tag="block">

        <!-- block named "css" defined in child template will be inserted here -->
        

</div>

    </head>

<body>
    <div class="container">
        

<div data-gb-custom-block data-tag="block">

        <!-- block named "content" defined in child template will be inserted here -->
        

</div>

    </div>

<div data-gb-custom-block data-tag="block">

<!-- block named "js" defined in child template will be inserted here -->

</div>

</body>
</html>

<!-- components/blocks.html -->

<div data-gb-custom-block data-tag="extends" data-0='components/base.html'></div>

<div data-gb-custom-block data-tag="block">

    <link rel=".." ..>

</div>

<div data-gb-custom-block data-tag="block">

    <p> This is content </p>

</div>

<div data-gb-custom-block data-tag="block">

    <script src=".." />

</div>

As you see blocks are fundamental and can be defined with Jinja2 and line statements. It allows you to structure your templates and have less repeating code.

The blocks defined in the child template will be passed to the parent template.

Environments

Environment variables in Masonite are defined in a .env file and should contain all environment variables needed for your project.

You can have multiple environment files that are loaded when the server first starts. It is often helpful to have different variable values depending on the environment where the application is running (locally, during tests or on a production server).

Also it might be useful to have more global environment variables that can be shared across your team for 3rd party services like Stripe or Mailgun and then have more developer specific values like database connections or different storage drivers for development.

We'll walk through how to configure your environments in this documentation.

Security

Environment variables should be set on a project per project basis inside your .env file.

Never commit any of your .env files into source control ! It would be a security risk in the event someone gained access to your repository since sensitive credentials and data would get exposed.

That is why .env and .env.* are in the project .gitignore file by default, so you should not worry about accidentally committing those files to source control.

Getting Started

In a fresh Masonite installation, a .env.example file located at project root directory will define minimum and common configuration values for a Masonite application. During the installation process, this file will be copied to .env file.

If you have installed Masonite but do not see this .env file then you can create it manually and copy and paste the contents of .env-example file.

Loading Order

Environment files are loaded in this order:

Masonite will load the .env file located at your project root into the Python environment.
Masonite will look for an APP_ENV variable inside the already loaded .env. If it is defined it will try to load the .env.{APP_ENV} file corresponding to this environment name.

For example, if APP_ENV is set to local, Masonite will additionally load the .env.local environment file.

.env

APP_ENV=local

When the server is ready all those variables will be loaded into the current environment ready to be accessed in the different Masonite configuration files or directly with env() helper.

Defining Variables

If some variables contain spaces you should put variable content into double quotes:

APP_NAME="Masonite test project"

Reading Variables

os.getenv()

You can use Python standard os.getenv() method to get an environment variable value. It looks like:

import os

is_debug = os.getenv("APP_DEBUG") #== "True" (str)

Notice that this method does not cast types, so here we got a string instead of a boolean value.

env()

You can also use Masonite helper env to read an environment variable value. It looks like:

from masonite import env

is_debug = env("APP_DEBUG", False) #== True (bool)

Note that you can provide a default value if the environment variable is not defined. Default value is "". For convenience this helper is casting types. Here are different examples of variables type casting:

Env Var Value

Casts to (type)

5432

5432 (int)

true

True (bool)

None (None)

"" (str)

True

True (bool)

false

False (bool)

False

False (bool)

smtp

smtp (string)

If you do not wish to cast the value then you can provide a third parameter cast=False:

from masonite import env

env('APP_DEBUG', False, cast=False) #== "False" (str)

Getting Current Environment

The current Masonite environment is defined through the APP_ENV variable located in your .env file. You can access it easily through the Masonite app environment() helper:

APP_ENV=local

app.environment() #== local

When running tests the environment will be set to testing. You can use is_running_tests() helper to check if environment is testing:

app.is_running_tests() #== True if running tests

You can also check if the environment is a production environment with:

app.is_production() #== True if APP_ENV=production

Debug Mode

The debug mode is controlled by the APP_DEBUG environment variable used in config/application.py configuration file. When crafting a new project, the debug mode is enabled (APP_ENV=True). It should stay enabled for local development.

When debug mode is enabled all exceptions (or routes not found) are rendered as an HTML debug error page containing a lot of information to help you debug the problem. When disabled, the default 500, 404, 403 error pages are rendered.

You can check if debug mode is enabled through the Masonite app is_debug() helper or with the config helper:

app.is_debug() #== True

from masonite.configuration import config

config("application.debug") #== True

Never deploy an application in production with debug mode enabled ! This could lead to expose some sensitive configuration data and environment variables to the end user.

Configuration

Configuration files in Masonite are gathered in one folder named config in default projects.

Each feature can have some options in its own file named after the feature. For example you will find mail related options in config/mail.py file.

Getting Started

The Configuration class is responsible for loading all configuration files before the application starts.

It will load all files located at path defined through config.location binding which default to config/.

Then values are accessed based on the file they belong to and a dotted path can be used to access nested options.

Given the following config/mail.py file:

Accessing mail will return a dictionary with all the options.
Accessing mail.from_email will return the FROM_EMAIL value
Accessing mail.drivers.smtp.port will return the port value for smtp driver.

Getting Value

To read a configuration value one can use the Config facade:

or the config helper:

Setting Value

Setting configuration values is achieved through projet configuration files.

Overriding Value

However, you can override on the fly a configuration value with the Config facade:

This should be done sparingly as this could have unexpected side effects depending at which time you override the configuration option.

This is mostly useful during tests, when you want to override a configuration option to test a specific behaviour:

Error Handling

Masonite error handling is based on the ExceptionHandler class which is responsible for handling all exceptions thrown by your application.

Global Exception Handler

Debug Mode

When disabled, the default errors/500.html, errors/404.html, errors/403.html error pages are rendered depending on error type.

Never deploy an application in production with debug mode enabled ! This could lead to expose some sensitive configuration data and environment variables to the end user.

Lifecycle

When an exception is raised it will be caught by the ExceptionHandler. Then the following cycle will happen:

In Development

A masonite.exception.SomeException event will be fired.
A specific ExceptionHandler will be used if it exists for the given exception.
Exceptionite will then handle the error by rendering it in the console
- and with the Exceptionite JSON response if accepted content is application/json
- else with the Exceptionite HTML error page

In Production

A masonite.exception.SomeException event will be fired.
A specific ExceptionHandler will be used if it exists for the given exception. In this case the default ExceptionHandler won't process the exception anymore.
Else this exception has not been yet handled and will be handled as an HTTP exception with 500 Server Error status code.

Report Exceptions

To report an exception you should simply raise it as any Python exceptions:

def index(self, view:View):
    user = User.find(request.param("id"))
    if not user:
        raise RouteNotFoundException("User not found")

There are different type of exceptions.

Simple Exceptions

HTTP Exceptions

HTTP exceptions are standard exceptions using frequently used HTTP status codes such as 500, 404 or 403.

Those exceptions will be rendered by the HTTPExceptionHandler with the corresponding status code and the corresponding default error template if it exists in errors/. (Note that in debug mode this template won't be rendered and the default Exceptionite error page will be rendered instead).

The following HTTP exceptions are bundled into Masonite:

AuthorizationException (403)
RouteNotFoundException (404)
ModelNotFoundException (404)
MethodNotAllowedException (405)

In a default Masonite project, existing errors views are errors/404.html, errors/403.html and errors/500.html. Those views can be customized.

You can also build a custom HTTP exception by setting is_http_exception=True to it and by defining the get_response(), get_status() and get_headers() methods:

class ExpiredToken(Exception):
    is_http_exception = True

    def __init__(self, token):
        super().__init__()
        self.expired_at = token.expired_at

    def get_response(self):
        return "Expired API Token"

    def get_status(self):
        return 401

    def get_headers(self):
        return {
            "X-Expired-At": self.expired_at
        }

When the above exception is raised, Masonite will look for the error view errors/401.html in the default project views folder and will render it with a 401 status code. The content of get_response() method will be passed as the message context variable to the view.

If this view does not exist the HTML response will be directly the content of the get_response() method with a 401 status code.

Renderable Exceptions

If you want more flexibility to render your exception without using the HTTPExceptionHandler above, you can just add a get_response() method to it. This method will be given as first argument of response.view(), so that you can render simple string or your own view template.

class CustomException(Exception):

    def __init__(self, message=""):
        super().__init__(message)
        self.message = message

    def get_response(self):
        return self.message

Here when raising this exception in your code, Masonite will know that it should render it by calling the get_response() method and here it will render as a string containing the message raised.

Note that you can also set an HTTP status code by adding - as for HTTP exceptions - the get_status() method to the exception.

class CustomException(Exception):

    def __init__(self, message=""):
        super().__init__(message)
        self.message = message

    def get_response(self):
        return self.message

    def get_status(self):
        return 401

Existing Exception Handlers

Existing Exception Handlers are:

HTTPExceptionHandler
DumpExceptionHandler

You can build your own Exception Handlers to override the way Masonite handles an exception that is thrown or to add new behaviours.

Adding New Handlers

A handler is a simple class with a handle() method that Masonite will call when a specific exception is thrown by the application.

As an example, you could handle specifically ZeroDivisionError exceptions that could be thrown by your application. It will look like this:

class DivideException:

    def __init__(self, application)
        self.application = application

    def handle(self, exception):
        self.application.make('response').view({
            "error": str(exception),
            "message": "You cannot divide by zero"
        }, status=500)

The name of the class can be whatever you like. In the handle method you should manually return a response by using the response class.

You will then need to register the class to the container using a specific key binding. The key binding will be {exception_name}Handler. You can do this in your Kernel file.

To register a custom exception handler for our ZeroDivisionError we would create a binding that looks like this:

from app.exceptions.DivideException import DivideException

self.application.bind(
    "ZeroDivisionErrorHandler",
    DivideException(self.application)
)

You can add this binding in your AppProvider or in Kernel.py.

Now when your application throws a ZeroDivisionError, Masonite will use your handler rather than Masonite's own exception handlers.

Catch All Exceptions

If you want to hook up an error tracking service such as Sentry or Rollbar you can do this through event listeners: each time an exception is raised, a masonite.exception.{TheExceptionType} is fired, allowing to run any custom logic.

class SentryListener:

    def handle(self, exception_type: str, exception: Exception):
        # process the exception with Sentry
        # ...

class AppProvider(Provider):

    def register(self):
        self.application.make("event").listen("masonite.exception.*", [SentryListener])

Logging

Logging is a pretty crucial part of any application. Logging allows you to see errors your application is throwing as well as allow you to log your own messages in several different alert levels.

Masonite Logging currently contains the ability to log to a file, syslog and slack.

Configuration

To enable logging in your application, ensure that LoggingProvider is added to your application providers:

# config/providers.py
from masonite.providers import LoggingProvider

PROVIDERS = [
  # ...
  LoggingProvider
]

Features

API Development

Adding API Support to your Masonite project is very simple. Masonite comes with supporting for returning JSON responses already but there are a few API features for authenticating and authorizing that are helpful.

Default projects don't come with these features so you'll have to simply register them.

Getting Started

Provider

First, register the ApiProvider in your project by adding the service provider to your PROVIDERS list:

This will register some required classes used for API development.

You should now create an api.py file for adding your API routes to:

You will then have to add a binding to the container for the location of this file. You can do so in your Kernel.py file inside the register_routes method:

Any routes inside this file will be grouped inside an api middleware stack.

Model and Migrations

Next, you must choose a model you want to be responsible for authentication. This is typically your User model. You will have to inherit the AuthenticatesTokens class onto this model:

This will allow the model to save tokens onto the table.

Next you will add a column to the models table for saving the token. Here we are naming it api_token but this is configurable by adding a __TOKEN_COLUMN__ attribute to your model. Your migration file should look like this:

Then migrate your migrations by running:

Configuration

Next, you can create a new API config file. You can do so simply by running the install command:

This will create a new api.py config file in your configuration directory that looks like this:

This will attempt to import your user model but if you have a different model or if its in a different location you can change it in that model.

This command will also generate a secret key, you should store that secret key in an environment variable called JWT_SECRET. This will be used as a salt for encoding and decoding the JWT token.

The authenticates key is used as a check to check against the database on every request to see if the token is set on the user. By default, the database is not called to check if the token is assigned to a user. One of the benefits of JWT is the need to not have to make a database call to validate the user but if you want that behavior, you can set this option to True

Routes

You should add some routes to your web.py file which can be used to authenticate users to give them JWT tokens:

The above parameters are the defaults already so if you don't want to change them then you don't have to specify them.

Middleware

Since the routes in your api.py file are wrapped in an api middleware, you should add a middleware stack in your route middleware in your Kernel file:

This middleware will allow any routes set on this stack to be protected by JWT authorization.

By default, all routes in the routes/api.py file already have the api middleware stack on them so there is no need to specify the stack on all your API routes.

Once these steps are done, you may now create your API's

Creating Your API

Once the setup is done, we may start building the API.

Route Resources

One of the ways to build an API is using controller and route resources.

A controller resource is a controller with several methods on them used to specify each action within an entity in the application (like users).

To create a controller resource you can run the controller command with an -a flag:

This will create a controller with the following methods:

index
show
store
update
destroy

You can then create a route resource:

This will create the below routes which will match up with your API Controller methods:

Authentication

The routes we added earlier contain 2 authentication methods. The /api/auth route can be used to get a new authentication token:

First, send a POST request with a username and password to get back a JWT token:

You should then send this token with either a token input or a Authorization header:

Reauthentication

If you do not set a value for the expires key in the configuration file then your JWT tokens will not expire and will be valid forever.

If you do set an expiration time in your configuration file then the JWT token will expire after that amount of minutes. If the token expires, you will need to reauthenticate to get a new token. This can be done easily by sending the old token to get back a new one:

You can do this by sending a POST request to /api/reauth with a token input containing the current JWT token. This will check the table for the token and if found, will generate a new token.

Versions

One of the issues with JWT tokens is there is little that can be done to invalidate JWT tokens. Once a JWT token is valid, it is typically valid forever.

One way to invalid JWT tokens, and force users to reauthenticate, is to specify a version. A JWT token authenticated will contain a version number if one exists. When the JWT token is validated, the version number in the token will check against the version number in the configuration file. If they do not match then the token is considered invalid and the user will have to reauthenticate to get back a new token.

Loading Users

Since we store the active api_token on the table we are able to retrieve the user using the LoadUserMiddleware and a new guard route middleware stack:

First add the guard middleware stack and add the LoadUserMiddleware to the api stack.

Lastly, in your route or route groups you can specify the guard middleware and specify the guard name:

Authentication

Masonite makes authentication really simply.

Authentication Scaffold Command

Masonite comes with a command to scaffold out a basic authentication system. You may use this as a great starting point for adding authentication to your application. This command will create controllers, views, and mailables for you.

If you would like to implement your own authentication from scratch you can skip to the sections below.

First run the command to add the news files:

python craft auth

Then add the authentication routes to your routes file:

from masonite.authentication import Auth

ROUTES = [
  # routes
]

ROUTES += Auth.routes()

You may then go to the /login or /register route to implement your authentication.

Configuration

The configuration for Masonite's authentication is quite simple:

from app.User import User

GUARDS = {
    "default": "web",
    "web": {"model": User},
    "password_reset_table": "password_resets",
    "password_reset_expiration": 1440,  # in minutes. 24 hours. None if disabled
}

The default key here is the guard to use for authentication. The web dictionary is the configuration for the web guard.

You can attempt a login by using the Auth class and using the attempt method:

from masonite.authentication import Auth
from masonite.request import Request

def login(self, auth: Auth, request: Request):
  user = auth.attempt(request.input('email'), request.input("password"))

If the attempt succeeds, the user will now be authenticated and the result of the attempt will be the authenticated model.

If the attempt fails then the result will be None.

If you know the primary key of the model, you can attempt by the id:

from masonite.authentication import Auth
from masonite.request import Request

def login(self, auth: Auth, request: Request):
  user = auth.attempt_by_id(1)

You can logout the current user:

from masonite.authentication import Auth
from masonite.request import Request

def logout(self, auth: Auth):
  user = auth.logout()

User

You can get the current authenticated user:

from masonite.authentication import Auth
from masonite.request import Request

def login(self, auth: Auth, request: Request):
  user = auth.user() #== <app.User.User>

If the user is not authenticated, this will return None.

Routes

You can register several routes quickly using the auth class:

from masonite.authentication import Auth

ROUTES = [
  #..
]

ROUTES += Auth.routes()

This will register the following routes:

URI

Description

GET /login

Displays a login form for the user

POST /login

Attempts a login for the user

GET /home

A home page for the user after a login attempt succeeds

GET /register

Displays a registration form for the user

POST /register

Saved the posted information and creates a new user

GET /password_reset

Displays a password reset form

POST /password_reset

Attempts to reset the users password

GET /change_password

Displays a form to request a new password

POST /change_password

Requests a new password

Guards

Guards are encapsulated logic for logging in, registering and fetching users. The web guard uses a cookie driver which sets a token cookie which is used later to fetch the user.

You can switch the guard on the fly to attempt authentication on different guards:

from masonite.authentication import Auth
from masonite.request import Request

def login(self, auth: Auth, request: Request):
  user = auth.guard("custom").attempt(request.input('email'), request.input("password")) #== <app.User.User>

Authorization

Masonite also provides a simple way to authorize user actions against a given resource. This is achieved with two concepts: gates and policies. Gates are as the name suggests an authorization check that you will be able to invoke to verify user access. Policies are a way to groupe authorization logic around a model.

Gates

Gates are simple callable that will define if a user is authorized to perform a given action. A handy Gate facade is available to easily manipulate gates.

Registering Gates

Gates receive a user instance as their first argument and may receive additionals arguments such as a Model instance. You needs to define Gates in boot() method of your service provider.

In the following example we are adding gates to verify if a user can create and update posts. Users can create posts if they are administrators and can update posts they have created only.

from masonite.facades import Gate

class MyAppProvider(Provider):

    def boot(self):
        Gate.define("create-post", lambda user: user.is_admin)
        Gate.define("update-post", lambda user, post: post.user_id == user.id)

You can then check if a gate exists or has been registed by using has() which is returning a boolean:

Gate.has("create-post")

If a unknown gate is used a GateDoesNotExist exception will be raised.

Authorizing Actions

Then anywhere (often in a controller) in your code you can use those gates to check if the current authenticated user is authorized to perform the given action defined by the gate.

Gates exposes different methods to perform verification: allows(), denies(), none(), any(), authorize() inspect().

allows(), denies(), none() and any() return a boolean indicating if user is authorized

if not Gate.allows("create-post"):
    return response.redirect("/")

# ...
post = Post.find(request.input("id"))
if Gate.denies("update-post", post):
    return response.redirect("/")

# ...
Gate.any(["delete-post", "update-post"], post)

# ...
Gate.none(["force-delete-post", "restore-post"], post)

authorize() does not return a boolean but will raise an AuthorizationException exception instead that will be rendered as an HTTP response with a 403 status code.

Gate.authorize("update-post", post)
# if we reach this part user is authorized
# else an exception has been raised and be rendered as a 403 with content "Action not authorized".

Finally for better control over the authorization check you can analyse the response with inspect():

response = Gate.inspect("update-post", post)
if response.allowed():
     # do something
else:
     # not authorized and we can access message
     Session.flash("errors", response.message())

Via the User Model

Authorizes class can be added to your User model to allow quick permission checks:

from masonite.authentication import Authenticates
from masonite.authorization import Authorizes

class User(Model, Authenticates, Authorizes):
    #..

A fluent authorization api will now be available on User instances:

user.can("delete-post", post)
user.cannot("access-admin")
user.can_any(["delete-post", "force-delete-post"], post)

All of those methods receive the gate name as first argument and then some additional arguments if required.

With a given user

You can use the for_user() method on the Gate facade to make the verification against a given user instead of the authenticated user.

from masonite.facades import Gate

user = User.find(1)
Gate.for_user(user).allows("create-post")

Gate Hooks

During the gate authorization process, before and after hooks can be triggered.

A before hook can be added like this:

# here admin users will always be authorized based on the boolean value of this response
Gate.before(lambda user, permission : user.role == "admin")

The after hook works the same way:

Gate.after(lambda user, permission, result : user.role == "admin")

If the after callback is returning a value it will take priority over the gate result check.

Policies

Policies are classes that organize authorization logic around a specific model.

Creating Policies

You can run the craft command:

$ python craft policy AccessAdmin

You can also create a policy with a set of predefined gates by using the --model flag:

$ python craft policy Post --model

A model policy comes with common actions that we can perform on a model:

from masonite.authorization import Policy


class PostPolicy(Policy):
    def create(self, user):
        return False

    def view_any(self, user):
        return False

    def view(self, user, instance):
        return False

    def update(self, user, instance):
        return False

    def delete(self, user, instance):
        return False

    def force_delete(self, user, instance):
        return False

    def restore(self, user, instance):
        return False

You are free to add any other methods on your policies:

from masonite.authorization import Policy


class PostPolicy(Policy):
    #.. 

    def publish(self, user):
        return user.email == "admin@masonite.com"

Registering Policies

Then in your service provider (as for defining gates) you should register the policies and bind them with a model:

from masonite.facades import Gate
from app.models.Post import Post
from app.models.User import User

from app.policies.PostPolicy import PostPolicy
from app.policies.UserPolicy import UserPolicy

class MyAppProvider(Provider):

    #..

    def register(self):
        Gate.register_policies(
            [(Post, PostPolicy), (User, UserPolicy)],
        )

An example policy for the Post model may look like this:

from masonite.authorization import Policy

class PostPolicy(Policy):
    def create(self, user):
        return user.email == "idmann509@gmail.com"

    def view(self, user, instance):
        return True

    def update(self, user, instance):
        return user.id == instance.user_id

If an unknown policy is used then a PolicyDoesNotExist exception will be raised.

Authorizing Actions

You can then use the Gate facade methods to authorize actions defined in your policies. With the previously defined PostPolicy we could make the following calls:

from masonite.facades import Gate

post = Post.find(1)
Gate.allows("update", post)
Gate.denies("view", post)
Gate.allows("force_delete", post)

The create() or view_any() methods do not take a model instance, that is why the model class should be provided so that Gate mechanism can infer from which policy those methods are belonging to.

Gate.allows("create", Post)
Gate.allows("view_any", Post)

Broadcasting

Masonite comes with a powerful way to broadcast events in your application. These events can be listened to client-side using Javascript.

These can be things like a new notification which you can show on the frontend without reloading the page.

Configuration

Server Side

You should create an account on Pusher Channels and then create a Pusher application on your account and get the related credentials (client, app_id, secret) and the cluster location name and put this into the broadcast pusher options.

Finally make sure you install the pusher python package

Client Side

Include the pusher-js script tag on your page

Create a Pusher instance configured with your credentials

Now you're ready to subscribe to channels and listen for channels events.

Creating Events

Broadcast events are simple classes that inherit from CanBroadcast. You may use any class, including the Masonite Event classes.

A broadcast event will look like this:

Note that the event name emitted to the client will be the name of the class. Here it would be UserAdded.

Broadcasting Events

You can broadcast the event using the Broadcast facade or by resolving Broadcast class from container.

You can broadcast easily without creating a Broadcast event

Or you can broadcast the event class created earlier

You may broadcast on multiple channels as well:

This type of broadcasting will emit all channels as public. For private and presence channels, keep reading.

Listening For Events

To listen for events on client-side you must first subscribe to the channel the events are emitted on

Then you can listen for events

Channel Types

Different channel types are included in Masonite.

Public Channels

Inside the event class you can specify a Public channel. These channels allow anyone with a connection to listen to events on this channel:

Private Channels

Private channels require authorization from the user to connect to the channel. You can use this channel to emit only events that a user should listen in on.

Private channels are channels that start with a private- prefix. When using private channels, the prefix will be prepended for you automatically.

Private channels can only be broadasting on if users are logged in. When the channel is authorized, it will check if the user is currently authenticated before it broadcasts. If the user is not authenticated it will not broadcast anything on this channel.

This will emit events on the private-channel_name channel.

Routing

On the frontend, when you make a connection to a private channel, a POST request is triggered by the broadcast client to authenticate the private channel. Masonite ships with this authentication route for you. All you need to do is add it to your routes:

This will create a route you can authenticate you private channel on the frontend. The authorization route will be /broadcasting/authorize but you can change this to anything you like:

You will also need to add the /pusher/user-auth route to the CSRF exemption.

The reason for this is that the broadcast client will not send the CSRF token along with the POST authorization request.

Authorizing

The default behaviour is to authorize everyone to access any private channels.

If you want to customize channels authorization logic you can add your own broadcast authorization route with a custom controller. Let's imagine you want to authenticate channels per users, meaning that user with ID 1 will be able to authenticate to channel private-1, user with ID 2 to channel private-2 and so on.

First you need to remove Broadcast.routes() from your routes and add your own route

Then you need to create a custom controller to implement your logic

Presence Channels

Presence channels work exactly the same as private channels except you can see who else is inside this channel. This is great for chatroom type applications.

For Presence channels, the user also has to be authenticated.

This will emit events on the presence-channel_name channel.

Routing

Authorizing

Examples

To get started more easily with event broadcasting in Masonite, two small examples are available here:

Sending public app releases notification

To do this we need to create a NewRelease Broadcast event and trigger this event from the backend.

On the frontend we need to listen to releases channel and subscribe to NewRelease events to display an alert box with the release message.

Sending private alerts to admin users

Let's imagine our User model has two roles basic and admin and that we want to send alerts to admin users only. The basic users should not be authorized to subscribe to the alerts.

To achieve this on the backend we need to:

create a custom authentication route to authorize admin users only on channel private-admins
create a AdminUserAlert Broadcast event
trigger this event from the backend.

Let's first create the authentication route and controller

On the frontend we need to listen to private-admins channel and subscribe to AdminUserAlert events to display an alert box with the message.

You're ready to start broadcasting events in your app !

Caching

Masonite provides a powerful caching feature to keep any data cached that may be needless or expensive to fetch on every request. Masonite caching allows you to save and fetch data, set expiration times and manage different cache stores.

We'll walk through how to configure and use cache in this documentation.

Configuration

Cache configuration is located at config/cache.py file. In this file, you can specify different cache stores with a name via the STORES dictionary and the default to use in your application with the default key.

Masonite is configured to use the File cache driver by default, named local.

For production applications, it is recommended to use a more efficient driver such as Memcached or Redis.

File Cache

File cache driver is storing data by saving it on the server's filesystem. It can be used as is without third party service.

Location where Masonite will store cache data files defaults to storage/framework/cache in project root directory but can be changed with location parameter.

Redis

Redis cache driver is requiring the redis python package, that you can install with:

Then you should define Redis as default store and configure it with your Redis server parameters:

Memcached

Memcached cache driver is requiring the pymemcache python package, that you can install with:

Then you should define Memcached as default store and configure it with your Memcached server parameters:

Using the Cache

Storing Data

Two methods are available: add and put.

add

You can easily add cache data using theadd method. This will either fetch the data already in the cache, if it is not expired, or it will insert the new value.

If age key exists in the cache AND it is not expired, then "21" will be added to the cache and returned. If the age key does not exist or is not expired then it will return whatever data is in the cache for that key.

put

The put method will put data into the cache regardless of if it exists already. This is a good way to overwrite data in the cache:

You can specify the number of seconds that the cache should be valid for. Do not specify any time or specify None to keep the data forever.

You may also cache lists and dictionaries which will preserve the data types:

Getting Data

You can get cache data from the cache. If the data is expired then this will either return None or the default you specify:

This will either fetch the correct age data from the cache or return the default value of 40.

Checking Data Exists

You can also see if a value exists in the cache (and it is not expired):

Forgetting Data

If you want to forget an item in the cache you can:

This will remove this item from the cache.

Increment / Decrement Value

You can increment and decrement a value if it is an integer:

Remembering

Remembering is a great way to save something to a cache using a callable:

Flushing the Cache

To delete everything in the cache you can simply flush it:

Compiling Assets

Masonite uses Laravel Mix which provides a really simple way to handle asset compiling even greater than simple SASS and LESS. You don't need to be an expert in either Laravel Mix or NPM to compile assets, though.

Getting Started

To get started we can simply run NPM install:

This will install everything you need to start compiling assets.

Configuration

The configuration settings will be made inside your webpack.mix.js file located in the root of your project.

You can see there is already an example config setup for you that looks like this:

This will move these 2 files, resources/js/app.js and resources/css/app.css and compile them both into the storage/compiled directory.

Installing TailwindCSS

Installing Vue

Compiling

Now that we have our compiled assets configured we can now actually compile them.

You can do so by running:

This will compile the assets and put them in the directories you put in the configuration file.

You can also have NPM wait for changes and recompile when changes are detected in frontend files. This is similiar to an auto reloading server. To do this just run:

Versioning

Laravel Mix can take care of file hashing when releasing assets to production, by adding a hash suffix to your assets to automatically bust cache when loading assets. To enable this you can add the following in your webpack.mix.js file:

After Laravel Mix compiled your assets you won't be able to know the exact filename (because of the hash) you should use in your views to reference your assets. You can use Masonite mix() helper to resolve the correct file path to your assets.

Commands

Commands in Masonite are generally designed to make your development life easier. Commands can range from creating controllers and models to installing packages and publishing assets.

Available commands for Masonite can be displayed by running:

This will show a list of commands already available for Masonite.

Every command has a documentation screen which describes the command's available arguments and options. In order to view a command documentation, prefix the name of the command with help. For example, to see help of serve command you can run:

Creating Commands

Commands can be created with a simple command class inheriting from Masonite Command class:

Command's name, description and arguments are parsed from the Command docstring.

Name and Description

The docstring should start with the description of the command

and then after a blank line you can define the command name.

Positional Arguments

After the name of the command in the docstring should come the arguments. Arguments are defined with one indent and enclosed into brackets.

Positional (mandatory) arguments are defined without dashes (- or --).

Here is how to define a positional argument called name with a description:

Inside the command, positional arguments can be retrieved with self.argument(arg_name)

Optional Arguments

Optional arguments are defined with dashes and can be used in any order in the command call. An optional argument --force can have a short name --f.

Here is how to define two optional arguments iterations and force with a description:

Notice how we provided the short version for the force argument but not for the iterations arguments

Now the command can be used like this:

If the optional argument is requiring a value you should add the = suffix:

Here when using iterations, the user should provide a value.

If the argument may or may not have a value, you can use the suffix =? instead.

Finally if a default value should be used when no value is provided, add the suffix ={default}:

Inside the command, optional arguments can be retrieved with self.option(arg_name)

Printing Messages

You can print messages to console with different formatting:

self.info("Info Message"): will output a message in green
self.warning("Warning Message"): will output a message in yellow
self.error("Error Message"): will output a message in bold red
self.comment("Comment Message"): will output a message in light blue

Advanced

Masonite Command class is inheriting Cleo Command class so you should be able to use all Cleo features when creating commands.

Registering Commands

add() method takes one or multiple commands:

When you run python craft you will now see the command you added.

CSRF Protection

Introduction

CSRF protection typically entails setting a unique token to the user for that page request that matches the same token on the server. This prevents any person from submitting a form without the correct token. There are many online resources that teach what CSRF does and how it works but Masonite makes it really simple to use.

Getting Started

The CSRF features for Masonite are located in the CsrfProvider Service Provider and the CsrfMiddleware. If you do not wish to have CSRF protection then you can safely remove both of these.

The CsrfProvider simply loads the CSRF features into the container and the CsrfMiddleware is what actually generates the keys and checks if they are valid.

Templates

By default, all POST requests require a CSRF token. We can simply add a CSRF token in our forms by adding the {{ csrf_field }} tag to our form like so:

This will add a hidden field that looks like:

If this token is changed or manipulated, Masonite will throw an InvalidCsrfToken exception from inside the middleware.

If you attempt a POST request without the {{ csrf_field }} then you will receive a InvalidCsrfException exception. This just means you are either missing the Jinja2 tag or you are missing that route from the exempt class attribute in your middleware.

You can get also get the token that is generated. This is useful for JS frontends where you need to pass a CSRF token to the backend for an AJAX call

AJAX / Vue / Axios

For ajax calls, the best way to pass CSRF tokens is by setting the token inside a parent template inside a meta tag like this:

And then you can fetch the token and put it wherever you need:

You can then pass the token via the X-CSRF-TOKEN header instead of the __token input for ease of use.

Exempting Routes

Not all routes may require CSRF protection such as OAuth authentication or various webhooks. In order to exempt routes from protection we can add it to the exempt class attribute in the middleware located at app/http/middleware/CsrfMiddleware.py:

Now any POST routes that are to your-domain.com/oauth/github are not protected by CSRF and no checks will be made against this route. Use this sparingly as CSRF protection is crucial to application security but you may find that not all routes need it.

Exempting Multiple Routes

You can also use * wildcards for exempting several routes under the same prefix. For example you may find yourself needing to do this:

This can get a bit repetitive so you may specify a wildcard instead:

Facades

Overview

you can do:

To import any built-in facades you can import them from the masonite.facades namespace:

Built-in Facades

Masonite ships with several facades you can use out of the box:

Auth
Broadcast
Config
Dump
Gate
Hash
Loader
Mail
Notification
Queue
Request
Response
Session
Storage
View
Url

Creating Your Own Facades

To create your own facade is simple:

Then import and use your facade:

To benefit from code intellisense/type hinting when using Facade (e.g. in VSCode editor) you should create a .pyi file just next to your facade file class to add type hinting to your new facade.

Then in this facade you should declare your typed methods. Here is a partial example of the Mail facades types hints:

Notice that:

methods code is not present, but replaced with ....
methods do not receive self as first argument. Because when calling the facade we don't really instantiate it (even if we get an instance of the object bound to the container). This allow to have the correct type hint behaviour.

Filesystem and Uploading

Masonite comes with a simple way to upload files to different file systems.

In Masonite, a Filesystem is a place where assets are stored. These locations could be somewhere local on the server or in a cloud storage service like Amazon S3.

Configuration

The configuration for the filesystem feature is broken up into "disks". These "disks" or connection configurations can be any name you want.

Here is an example configuration:

Default

The default configuration is the name of the disk you want to be used as the default when using the Filesystem features.

Local Driver

The local driver is used for local filesystems like server directories. All files are stored and managed "locally" on the server.

S3 Driver

The S3 driver is used for connecting to Amazon's S3 cloud service.

Uploading Files

Uploading files is simple. You will have to use the Masonite Storage class.

The first and most simplest method is taking a file and putting text into it. For this we can use the put method

Uploading Form Files

When uploading files from a form you will find the put_file method more useful:

The put_file method will return the relative path to the file so you can save it to the database and fetch it later.

By default, a file name will be auto generated for you using a UUID4 string. You can specify your own name by using a name parameter:

You do not need to specify the extension in the name as the extension will be pulled from the resource object.

Asset Helper

Displaying Files

When uploading images to something like an AWS bucket, you may want to display the images. You may use a combination of the asset helper and setting a path in your filesystem config. This mainly just provides a nice interface for combining 2 strings

When using Amazon S3, you will need to set your bucket permissions and policies appropriately.

First, set a path in your filesystem config:

Then in your templates you can use the asset helper:

The signature is:

Multiple Paths

You may also specify multiple paths as a dictionary:

Then inside your asset helper you can use dot notation to specify the path you want to use:

Architecture

Security

Masonite ORM

Testing

Extending

Official Packages

How-to Guides

What's New

Upgrade Guide

Notifications

Masonite has a simple yet powerful notification feature which is used to send notifications from your application. Here is a brief overview of what you can do with notifications:

Send E-mail, Slack and SMS notifications
Store notifications in a database so they may be displayed in your web interface.
Queue notifications
Broadcast notifications

Creating a Notification

To create and send a notification with Masonite, you must first build a Notification class. This class will act as the settings for your notification such as the delivery channels and the content of the notification for those different channels (mail, slack, sms, ...).

The first step of building a notification is running the command:

$ python craft notification Welcome

This will create your notification and it will look something like this:

class Welcome(Notification, Mailable):

    def to_mail(self, notifiable):
        return (
            self.to(notifiable.email)
            .subject("Welcome to our site!")
            .from_("admin@example.com")
            .text(f"Hello {notifiable.name}")
        )

    def via(self, notifiable):
        return ["mail"]

Each notification class has a via method that specify on which channels the notification will be delivered. Notifications may be sent on the mail, database, broadcast, slack and vonage channels. More details on this later. When sending the notification it will be automatically sent to each channel.

via method should returns a list of the channels you want your notification to be delivered on. This method receives a notifiable instance.

class WelcomeNotification(Notification, Mailable):
    ...
    def via(self, notifiable):
        """Send this notification by email, Slack and save it in database."""
        return ["mail", "slack", "database"]

Sending a Notification

Basic

You can send your notification inside your controller easily by using the Notification class:

from masonite.notification import NotificationManager
from app.notifications.Welcome import Welcome

class WelcomeController(Controller):

    def welcome(self, notification: NotificationManager):
        notification.route('mail', 'sam@masonite.com').send(Welcome())

If the notification needs to be delivered to multiple channels you can chain the different routes:

notification.route('mail', 'sam@masonite.com').route('slack', '#general').send(Welcome())

database channel cannot be used with those notifications because no Notifiable entity is attached to it.

To notifiables

from masonite.notification import NotificationManager
from app.notifications.Welcome import Welcome

class WelcomeController(Controller):

    def welcome(self, notification: NotificationManager):
        user = self.request.user()
        notification.send(user, Welcome())

        # send to all users
        users = User.all()
        notification.send(users, Welcome())

Or you can use a handy notify() method:

user = self.request.user()
user.notify(Welcome())

Using Notifiables

ORM Models can be defined as Notifiable to allow notifications to be sent to them. The most common use case is to set User model as Notifiable as we often need to send notifications to users.

To set a Model as Notifiable, just add the Notifiable mixin to it:

from masonite.notification import Notifiable

class User(Model, Notifiable):
    # ...

You can now send notifications to it with user.notify() method.

Routing

Then you can define how notifications should be routed for the different channels. This is always done by defining a route_notification_for_{driver} method.

For example, with mail driver you can define:

from masonite.notification import Notifiable

class User(Model, Notifiable):
    ...
    def route_notification_for_mail(self):
        return self.email

This is actually the default behaviour of the mail driver so you won't have to write that but you can customize it to your needs if your User model don't have email field or if you want to add some logic to get the recipient email.

Queueing Notifications

If you would like to queue the notification then you just need to inherit the Queueable class and it will automatically send your notifications into the queue to be processed later. This is a great way to speed up your application:

from masonite.notification import Notification
from masonite.queues import Queueable

class Welcome(Notification, Queueable):
    # ...

Channels

Mail

You should define a to_mail method on the notification class to specify how to build the email notification content.

class Welcome(Notification, Mailable):

    def to_mail(self, notifiable):
        return (
            self.to(notifiable.email)
            .subject("Welcome to our site!")
            .from_("admin@example.com")
            .text(f"Hello {notifiable.name}")
        )

    def via(self, notifiable):
        return ["mail"]

If you want to override the mail driver for a given notification you can do:

class Welcome(Notification, Mailable):

    def to_mail(self, notifiable):
        return (
            self.to(notifiable.email)
            .subject("Welcome to our site!")
            .from_("admin@example.com")
            .text(f"Hello {notifiable.name}")
            .driver("mailgun")
        )

    def via(self, notifiable):
        return ["mail"]

Slack

You should define a to_slack method on the notification class to specify how to build the slack notification content.

from masonite.notification.components import SlackComponent

class Welcome(Notification):

    def to_slack(self, notifiable):
        return SlackComponent().text('Masonite Notification: Read The Docs!, https://docs.masoniteproject.com/') \
            .channel('#bot') \
            .as_user('Masonite Bot') \

    def via(self, notifiable):
        return ["slack"]

Options

SlackComponent takes different options to configure your notification:

Method

Description

Example

.text()

The text you want to show in the message

.text('Welcome to Masonite!')

.to()

The channel you want to broadcast to. If the value you supply starts with a # sign then Notifications will make a POST request with your token to the Slack channel list API and get the channel ID. You can specify the channel ID directly if you don't want this behavior

.to('#general') .to('CHSUU862')

.send_from()

The username you want to show as the message sender. You can also specify either the url or icon that will be displayed as the sender.

.as_current_user()

This sets a boolean value to True on whether the message should show as the currently authenticated user.

.as_current_user()

.link_names()

This enables finding and linking channel names and usernames in message.

.link_names()

.can_reply()

This auhtorizes replying back to the message.

.can_reply()

.without_markdown()

This will not parse any markdown in the message. This is a boolean value and requires no parameters.

.without_markdown()

.unfurl_links()

This enable showing message attachments and links previews. Usually slack will show an icon of the website when posting a link. This enables that feature for the current message.

.unfurl_links()

.as_snippet()

Used to post the current message as a snippet instead of as a normal message. This option has 3 keyword arguments. The file_type, name, and title. This uses a different API endpoint so some previous methods may not be used.

.as_snippet(file_type='python', name='snippet', title='Awesome Snippet')

.token()

Override the globally configured token.

.token('xoxp-359926262626-35...')

Notifications can be sent to a Slack workspace in two ways in Masonite:

Incoming Webhooks

Web API

This token should have at minimum the channels:read, chat:write:bot, chat:write:user and files:write:user permission scopes. If your token does not have these scopes then parts of this feature will not work.

Then you can define this token globally in config/notifications.py file as SLACK_TOKEN environment variable. Or you can configure different tokens (with eventually different scopes) per notifications.

Advanced Formatting

$ pip install slackblocks

Then you can import most of the blocks available in Slack documentation and start building your notification. You need to use the block() option. Once again you can chain as many blocks as you want.

from masonite.notification.components import SlackComponent
from slackblocks import HeaderBlock, ImageBlock, DividerBlock

class Welcome(Notification):
    def to_slack(self, notifiable):
        return SlackComponent() \
            .text('Notification text') \
            .channel('#bot') \
            .block(HeaderBlock("Header title")) \
            .block(DividerBlock()) \
            .block(ImageBlock("https://path/to/image", "Alt image text", "Image title"))

Some blocks or elements might not be yet available in slackblocks, but most of them should be there.

Routing to notifiable

You should define the related route_notification_for_slack method on your notifiable to return either

class User(Model, Notifiable):

    def route_notification_for_slack(self):
        """Examples for Incoming Webhooks."""
        # one webhook
        return "https://hooks.slack.com/services/..."
        # multiple webhooks
        return ["https://hooks.slack.com/services/...", "https://hooks.slack.com/services/..."]

class User(Model, Notifiable):

    def route_notification_for_slack(self):
        """Examples for Slack Web API."""
        # one channel name
        return "#general"
        # multiple channel name
        return ["#users", "#general"]
        # one channel ID
        return "C1234567890"

Routing to anonymous

To send a Slack notification without having a notifiable entity you must use the route method

notification.route("slack", "#general").notify(Welcome())

The second parameter can be a channel name, a channel IDor a webhook URL.

When specifying channel names you must keep # in the name as in the example. Based on this name a reverse lookup will be made to find the corresponding Slack channel ID. If you want to avoid this extra call, you can get the channel ID in your Slack workspace (right click on a Slack channel > Copy Name > the ID is at the end of url)

SMS

$ pip install vonage

Then you should configure the VONAGE_KEY and VONAGE_SECRET credentials in notifications.py configuration file:

# config/notifications.py

VONAGE = {
  "key": env("VONAGE_KEY"),
  "secret": env("VONAGE_SECRET"),
  "sms_from": "1234567890"
}

You can also define (globally) sms_from which is the phone number or name that your SMS will be sent from. You can generate a phone number for your application in the Vonage dashboard.

You should define a to_vonage method on the notification class to specify how to build the sms notification content.

from masonite.notification.components import Sms

class Welcome(Notification):

    def to_vonage(self, notifiable):
        return Sms().text("Welcome!")

    def via(self, notifiable):
        return ["vonage"]

Options

If the SMS notification contains unicode characters, you should call the unicode method when constructing the notification

Sms().text("Welcome unicode message!").set_unicode()

The global sms_from number can be overriden inside the notification class:

Sms().text("Welcome!").sms_from("+123 456 789")

Routing to notifiable

You should define the related route_notification_for_vonage method on your notifiable to return a phone number or a list of phone numbers to send the notification to.

class User(Model, Notifiable):

    def route_notification_for_vonage(self):
        return self.phone
        # or return [self.mobile_phone, self.land_phone]

Routing to anonymous

To send a SMS notification without having a notifiable entity you must use the route method

notification.route("vonage", "+33612345678").notify(Welcome())

Saving notifications

Notifications can be stored in your application database when sent to Notifiable entities. The notification is stored in a notifications table. This table will contain information such as the notification type as well as a JSON data structure that describes the notification.

To store a notification in the database you should define a to_database method on the notification class to specify how to build the notification content that will be persisted.

class Welcome(Notification):

    def to_database(self, notifiable):
        return {"data": "Welcome {0}!".format(notifiable.name)}

    def via(self):
        return ["mail", "database"]

This method should return str, dict or JSON data (as it will be saved into a TEXT column in the notifications table). You also need to add database channel to the via method to enable database notification storage.

Initial setup

Before you can store notifications in database you must create the database notifications table.

$ python craft notification:table

Then you can migrate your database

$ python craft migrate

The ORM Model describing a Notification is DatabaseNotification and has the following fields:

id is the primary key of the model (defined with UUID4)
type will store the notification type as a string (e.g. WelcomeNotification)
read_at is the timestamp indicating when notification has been read
data is the serialized representation of to_database()
notifiable is the relationship returning the Notifiable entity a notification belongs to (e.g. User)
created_at, updated_at timestamps

Querying notifications

A notifiable entity has a notifications relationship that will returns the notifications for the entity:

user = User.find(1)
user.notifications.all() # == Collection of DatabaseNotification belonging to users

You can directly get the unread/read notifications:

user = User.find(1)
user.unread_notifications.all() # == Collection of user unread DatabaseNotification
user.read_notifications.all() # == Collection of user read DatabaseNotification

Managing notifications

You can mark a notification as read or unread with the following mark_as_read and mark_as_unread methods

user = User.find(1)

for notification in user.unread_notifications.all():
    notification.mark_as_read()

Finally, keep in mind that database notifications can be used as any Masonite ORM models, meaning you can for example make more complex queries to fetch notifications, directly on the model.

from masonite.notification import DatabaseNotification

DatabaseNotification.all()
DatabaseNotification.where("type", "WelcomeNotification")

Broadcasting Notifications

If you would like to broadcast the notification then you need to:

inherit the CanBroadcast class and specify the broadcast_on method
define a to_broadcast method on the notification class to specify how to build the notification content that will be broadcasted

class Welcome(Notification, CanBroadcast):

    def to_broadcast(self, notifiable):
        return f"Welcome {notifiable.name} !"

    def broadcast_on(self):
        return "channel1"

    def via(self, notifiable):
        return ["broadcast"]

Broadcasting to notifiables

By default notifications will be broadcasted to channel(s) defined in broadcast_on method but you can override this per notifiable by implementing route_notification_for_broadcast method on your notifiable:

class User(Model, Notifiable):

    def route_notification_for_broadcast(self):
        return ["general", f"user_{self.id}"]

Broadcasting to anonymous

notification.route("broadcast", "channel1").notify(Welcome())

Adding a new driver

Masonite ships with a handful of notification channels, but you may want to write your own drivers to deliver notifications via other channels. Masonite makes this process simple.

Creating the driver

Two methods need to be implemented in order to create a notification driver: send and queue.

from masonite.notification.drivers import BaseDriver

class VoiceDriver(BaseDriver):

    def send(self, notifiable, notification):
        """Specify here how to send the notification with this driver."""
        data = self.get_data("voice", notifiable, notification)
        # do something

get_data() method will be available and will return the data defined in the to_voice() method of the notification.

Registering the driver

As any drivers it should be registered, through a custom provider for example:

from masonite.providers import Provider

class VoiceNotificationProvider(Provider):

    def register(self):
        self.application.make("notification").add_driver("voice", VoiceDriver(self.application))

Then you could scaffold this code into a new Masonite package so that community can use it 😉 !

Advanced Usage

Dry run

You can enable dry notifications to avoid notifications to be sent. It can be useful in some cases (background task, production commands, development, testing...)

user.notify(WelcomeNotification(), dry=True)
# or
notification.send(WelcomeNotification(), dry=True)

Ignoring errors

When fail_silently parameter is enabled, notifications sending will not raise exceptions if an error occurs.

user.notify(WelcomeNotification(), fail_silently=True)
# or
notification.send(WelcomeNotification(), fail_silently=True)

Overriding channels

Channels defined in via() method of the notification can be overriden at send:

class Welcome(Notification):
    def to_mail(self, notifiable):
        #...

    def to_slack(self, notifiable):
        #...

    def to_database(self, notifiable):
        #...

    def via(self):
        """Default behaviour is to send only by email."""
        return ["mail"]

Using channels parameter we can send to other channels (if correctly defined in notification class):

user.notify(Welcome(), channels=["slack", "database"])
# or
notification.send(Welcome(), channels=["slack", "database"])

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

$ 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:

$ 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': 'user@example.com',
        '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': 'user@example.com',
        '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': '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.

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

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

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

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

"""
{
  'date': '1975-05-21T22:00:00'
}
"""
validate.date('date')

Different

"""
{
  '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': 'user@email.com',
  'terms': 'on'
}
"""
validate.does_not(
    validate.exists('user')
).then(
    validate.accepted('terms'),
)

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

Equals

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

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

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

File

Used to make sure that value is a valid file.

"""
{
  'document': '/my/doc.pdf'
}
"""
validate.file('document')

Additionally you can check file size, with different file size formats:

validate.file('document', 1024) # check valid file and max size is 1 Kilobyte (1024 bytes)
validate.file('document', '1K') # check valid file and max size is 1 Kilobyte (1024 bytes), 1k or 1KB also works
validate.file('document', '15M') # check valid file and max size is 15 Megabytes

Finally file type can be checked through a MIME types list:

validate.file('document', mimes=['jpg', 'png'])

You can combine all those file checks at once:

validate.file('document', mimes=['pdf', 'txt'], size='4MB')

Greater_than

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

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

Image

Used to make sure that value is a valid image.

"""
{
  'avatar': '/my/picture.png'
}
"""
validate.image('avatar')

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

validate.image('avatar', size="2MB")

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_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_list

Used to make sure the value is a list (a Python list instance)

"""
{
  'tags': [1,3,7]
}
"""
validate.is_list('tags')

* notation can also be used

"""
{
  'name': 'Joe',
  'discounts_ref': [1,2,3]
}
"""
validate.is_list('discounts_ref.*')

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

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

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.

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)

Matches

Used to make sure the value matches another field value

"""
{
  'user1': {
    'role': 'admin'
  },
  'user2': {
    'role': 'admin'
  }
}
"""
validate.matches('user1.role', 'user2.role')

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

One_of

Sometimes you will want only one of several fields to be required. At least one of them need to be required.

"""
{
  'user': 'Joe',
  'email': 'user@example.com,
  'phone': '123-456-7890'
}
"""
validate.one_of(['user', 'accepted', 'location'])

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:

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

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:

"""
{
  'zip': '123456'
}
"""
validate.postal_code('zip', "US,IN,GB")

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

"""
{
  'username': 'masonite_user_1'
}
"""
validate.regex('username', pattern='^[a-z0-9_-]{3,16}$'))

Required

"""
{
  'age': 25,
  'email': 'user@email.com',
  'first_name': ''
}
"""
validate.required(['age', 'email'])
validate.required('first_name')  # would fail
validate.required('last_name')  # would fail

Required If

Used to make sure that value is present and not empty only if an other field has a given value.

"""
{
  'first_name': 'Sam',
  'last_name': 'Gamji'
}
"""
validate.required_if('first_name', 'last_name', 'Gamji')

Required With

Used to make sure that value is present and not empty onlyf if any of the other specified fields are present.

"""
{
  'first_name': 'Sam',
  'last_name': 'Gamji'
  'email': 'samgamji@lotr.com'
}
"""
validate.required_with('email', ['last_name', 'nick_name'])

String

Used to make sure the value is a string

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

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.

"""
{
  'email': 'user@email.com'
  'password': 'SeCreT!!'
}
"""
validate.strong('password', length=8, special=2, uppercase=3)

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

Uuid

"""
{
  'doc_id': 'c1d38bb1-139e-4099-8a20-61a2a0c9b996'
}
"""
# check value is a valid UUID4
validate.uuid('doc_id')
# check value is a valid UUID3
validate.uuid('doc_id', 3)  # or '3'

Video

Used to make sure that value is a valid video file.

"""
{
  'document': '/my/movie.mp4'
}
"""
validate.video('document')

Valid video types are defined by all MIME types starting with video/. For more details you can check mimetypes Python package which gives known MIME types with mimetypes.types_map.

Additionally you can check video size as with basic file validator

validate.video('document', size="2MB")

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

development

Introduction and Installation

Some Notable Features Shipped With Masonite

Requirements

Linux

Installation

Activating Our Virtual Environment (optional)

Installation

Prologue

Creating A Blog Tutorial

Hint Blocks

Installation

Creating a Blog

Routing

Creating our Route:

Creating a Controller

Creating Our First Controller

Returning a View

Creating Our View

Authentication

Database Setup

Migrating

Creating Users

Migrations

Craft Command

Models

Creating our Model

Table Name

Mass Assignment

Relationships

Designing Our Blog

The Template For Creating

Static Files

The Controller For Creating And The Container

Showing Our Posts

Creating The Templates

Creating The Controller

Show Method

Posts Route

Posts View

Single Post Route

Single Method

Single Post View

Updating and Deleting Posts

Update Controller Method

Create The View

Create The Routes:

Delete Method

Make the route:

Update the Template

Release Cycle

Major Releases

Minor Versions

Patch Versions

Contributing Guide

Getting Started

Getting the Masonite cookie-cutter repository up and running to be edited

Editing the Masonite repository

Comments

Types of comments to use

Module Docstrings

Method and Function Docstrings

Methods and Functions with Dependencies

Code Comments

Pull Request Process

Branching

Examples:

Code of Conduct

Our Pledge

Our Standards

Our Responsibilities

Scope

Enforcement

Attribution

How To Contribute

Introduction

Contributing to Development

Become a Feature Maintainer

Comment the Code

Write Tests