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

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

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

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:

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:

or if you are on Windows:

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:

Then start a new project:

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:

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:

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:

from masonite.routes import Route

ROUTES = [
    Route.get('/url', 'Controller@method')
]

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.

ROUTES = [
    Route.get('/', 'WelcomeController@show').name('welcome'),

    # Blog Routes
    Route.get('/blog', 'BlogController@show')
]

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:

$ python craft controller Blog

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

from masonite.controllers import Controller
from masonite.views import View


class BlogController(Controller):
    def show(self, view: View):
        return view.render("")

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:

from masonite.view import View
# ...
def show(self, view: View):
    return view.render('blog')

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:

This is a blog

Let's run the migration for the first time:

$ python craft migrate

and then run the server

$ python craft serve

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:

$ python craft auth

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:

from masonite.authentication import Auth

ROUTES = [
    Route.get('/', 'WelcomeController@show').name('welcome'),

    # Blog Routes
    Route.get('/blog', 'BlogController@show')
]

ROUTES += Auth.routes()

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:

$ python craft migrate

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.

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=masonite
DB_USERNAME=root
DB_PASSWORD=

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.

$ python craft migrate

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:

$ python craft serve

Username: demo
Email: demo@email.com
Password: password!!11AA

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

$ python craft migration create_posts_table --create posts

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:

def up(self):
    """
    Run the migrations.
    """
    with self.schema.create('posts') as table:
        table.increments('id')
        table.timestamps()

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

def up(self):
    """
    Run the migrations.
    """
    with self.schema.create('posts') as table:
        table.increments('id')
        table.string('title')

        table.integer('author_id').unsigned()
        table.foreign('author_id').references('id').on('users')

        table.string('body')
        table.timestamps()

Now we can migrate this migration to create the posts table

$ python craft migrate

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:

$ python craft model Post

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:

"""Post Model."""
from masoniteorm.models import Model

class Post(Model):
    pass

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:

"""Post Model."""
from masoniteorm.models import Model

class Post(Model):
    __table__ = 'user_posts'

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

"""A Post Database Model."""
from masoniteorm.models import Model

class Post(Model):
    __fillable__ = ['title', 'author_id', 'body']

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:

"""Post Model."""
from masoniteorm.models import Model
from masoniteorm.relationships import belongs_to

class Post(Model):
    __fillable__ = ['title', 'author_id', 'body']

    @belongs_to('author_id', 'id')
    def author(self):
        from app.models.User import User
        return User

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

<form action="/blog/create" method="POST">
    {{ csrf_field }}

    <input type="name" name="title">
    <textarea name="body"></textarea>
</form>

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:

@if auth()
    <form action="/blog/create" method="POST">
        {{ csrf_field }}

        <label> Title </label>
        <input type="name" name="title"><br>

        <label> Body </label>
        <textarea name="body"></textarea>

        <input type="submit" value="Post!">
    </form>
@else
    <a href="/login">Please Login</a>
@endif

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.

html {
    background-color: #ddd;
}

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

<link href="/static/blog.css" rel="stylesheet">
@if auth()
    <form action="/blog/create" method="POST">
        {{ csrf_field }}

        <label> Title </label>
        <input type="name" name="title"><br>

        <label> Body </label>
        <textarea name="body"></textarea>

        <input type="submit" value="Post!">
    </form>
@else
    <a href="/login">Please Login</a>
@endif

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:

<link href="/static/blog.css" rel="stylesheet">
@if auth()
    <form action="/blog/create" method="POST">
        {{ csrf_field }}

        <label> Title </label>
        <input type="name" name="title"><br>

        <label> Body </label>
        <textarea name="body"></textarea>

        <input type="submit" value="Post!">
    </form>
@else
    <a href="/login">Please Login</a>
@endif

<script src="/static/script.js"></script>

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:

from masonite.routes import Route
# ...
ROUTES = [
    # ...
    Route.post('/blog/create', 'BlogController@store')
]

and create a new store method on our controller:

...
def show(self, view: View):
    return view.render('blog')

# New store Method
def store(self):
    pass

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.

from app.models.Post import Post
from masonite.request import Request
# ...

def store(self, request: Request):
    Post.create(
        title=request.input('title'),
        body=request.input('body'),
        author_id=request.user().id
    )

    return 'post created'

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.

$ python craft controller Post

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:

from app.models.Post import Post

...

def show(self, view: View):
    posts = Post.all()

    return view.render('posts', {'posts': posts})

Posts Route

We need to add a route for this method:

Route.get('/posts', 'PostController@show')

Posts View

Our posts view can be very simple:

<!-- templates/posts.html -->
@for post in posts
    {{ post.title }}
    <br>
    {{ post.body }}
    <hr>
@endfor

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:

@for post in posts
    {{ post.title }} by {{ post.author.name }}
    <br>
    {{ post.body }}
    <hr>
@endfor

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:

Route.get('/post/@id', 'PostController@single')

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.

from app.models.Post import Post
from masonite.request import Request
from masonite.views import View
...

def single(self, view: View, request: Request):
    post = Post.find(request.param('id'))

    return view.render('single', {'post': 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:

{{ post.title }}
<br>
{{ post.body }}
<hr>

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:

def update(self, view: View, request: Request):
    post = Post.find(request.param('id'))

    return view.render('update', {'post': post})

def store(self, request: Request):
    post = Post.find(request.param('id'))

    post.title = request.input('title')
    post.body = request.input('body')

    post.save()

    return 'post updated'

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

<form action="/post/{{ post.id }}/update" method="POST">
    {{ csrf_field }}

    <label for="">Title</label>
    <input type="text" name="title" value="{{ post.title }}"><br>

    <label>Body</label>
    <textarea name="body">{{ post.body }}</textarea><br>

    <input type="submit" value="Update">
</form>

Create The Routes:

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

Route.get('/post/@id/update', 'PostController@update'),
Route.post('/post/@id/update', 'PostController@store'),

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

Delete Method

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

from masonite.request import Request
...

def delete(self, request: Request):
    post = Post.find(request.param('id'))

    post.delete()

    return 'post deleted'

Make the route:

Route.get('/post/@id/delete', 'PostController@delete'),

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:

<form action="/post/{{ post.id }}/update" method="POST">
    {{ csrf_field }}

    <label for="">Title</label>
    <input type="text" name="title" value="{{ post.title }}"><br>

    <label>Body</label>
    <textarea name="body">{{ post.body }}</textarea><br>

    <input type="submit" value="Update">

    <a href="/post/{{ post.id }}/delete"> Delete </a>
</form>

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:

"""This is a module to add support for Billing users."""
from masonite.request import Request
...

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:

def some_function(self):
    """This is a function that does x action. 

    Then give an exmaple of when to use it 
    """
    ... code ...

Methods and Functions with Dependencies

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

def route(self, route, output):
    """Load the route into the class. This also looks for the controller and attaches it to the route.

    Arguments:
        route {string} -- This is a URI to attach to the route (/dashboard/user).
        output {string|object} -- Controller to attach to the route.

    Returns:
        self
    """

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

def __init__(self, request: Request, csrf: Csrf, view: View):
    """Initialize the CSRF Middleware

    Arguments:
        request {masonite.request.Request} -- The normal Masonite request class.
        csrf {masonite.auth.Csrf} -- CSRF auth class.
        view {masonite.view.View} -- The normal Masonite view class.

    Returns:
        self
    """
    pass

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:

# This code performs a complex task that may not be understood later on
# You can add a second line like this
complex_code = 'value'

perform_some_complex_task()

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

Routing

Masonite ships with a really powerful routing engine. Routing helps link a browser URL to its controller and controller action.

Creating a Route

Routes are created by importing the Route class and defining the HTTP verb you would like with the URL and the controller you would like to use. These routes need to be wrapped in a ROUTES list inside your routes file.

from masonite.routes import Route

ROUTES = [
	Route.get('/welcome', 'WelcomeController@show')
]

The first parameter is the URL you would like to be available in your application. In the above example, this will allow anybody to go to the /welcome URL.

Available Route Methods

You may choose to define any one of the available verbs:

Route.get('/welcome', 'WelcomeController@show')
Route.post('/welcome', 'WelcomeController@show')
Route.put('/welcome', 'WelcomeController@show')
Route.patch('/welcome', 'WelcomeController@show')
Route.delete('/welcome', 'WelcomeController@show')
Route.options('/welcome', 'WelcomeController@show')
Route.view('/url', 'view.name', {'key': 'value'})
Route.resource('/users', 'UsersController')
Route.api('/users', 'UsersApiController')

In addition to these route verbs you can use built in routes:

Route.redirect('/old', '/new', status=301)
Route.permanent_redirect('/old', '/new')

Controller Binding

There are multiple ways to bind a controller to a route.

String Binding

You can use a string binding defining the controller class and its method {ControllerClass}@{controller_method}:

Route.get('/welcome', 'WelcomeController@show')

Note that this is the prefered way as it will avoid circular dependencies as no import is required in your route file.

Class Binding

You can import your controllers in your route file and provide a class name or a method class:

from app.controllers import WelcomeController

Route.get('/welcome', WelcomeController)

Here as no method has been defined the __call__ method of the class will be bound to this route. It means that you should define this method in your controller:

class WelcomeController(Controller):

    def __call__(self, request:Request):
        return "Welcome"

For convenience, you can provide the method class instead:

from app.controllers import WelcomeController

Route.get('/welcome', WelcomeController.show)

Instance Binding

You can also bind the route to a controller instance:

from app.controllers import WelcomeController

controller = WelcomeController()

Route.get('/welcome', controller)

Here as no method has been defined the __call__ method of the class will be bound to this route. It means that you should define this method in your controller:

class WelcomeController(Controller):

    def __call__(self, request:Request):
        return "Welcome"

Route Options

You may define several available methods on your routes to modify their behavior during the request.

Middlewares

Route.get('/welcome', 'WelcomeController@show').middleware('web')
Route.get('/settings', 'WelcomeController@settings').middleware('auth', 'web')

This will attach the middleware key(s) to the route which will be picked up from your middleware configuration later in the request.

Route.get('/about', 'WelcomeController@about').exclude_middleware('auth', 'custom')

Name

You can specify a name for your route. This is used to easily compile route information in other parts of your application by using the route name which is much more static than a URL.

Route.get('/welcome', 'WelcomeController@show').name('welcome')

Parameters

You can specify the parameters in the URL that will later be able to be retrieved in other parts of your application. You can do this easily by specify the parameter name attached to a @ symbol:

Route.get('/dashboard/@user_id', 'WelcomeController@show')

Optional Parameters

Sometimes you want to optionally match routes and route parameters. For example you may want to match /dashboard/user and /dashboard/user/settings to the same controller method. In this event you can use optional parameters which are simply replacing the @ symbol with a ?:

Route.get('/dashboard/?option', 'WelcomeController@show')

Domain

You can specify the subdomain you want this route to be matched to. If you only want this route to be matched on a "docs" subdomain (docs.example.com):

Route.get('/dashboard/@user_id', 'WelcomeController@show').domain('docs')

Route Compilers

Route compilers are a way to match on a certain route parameter by a specific type. For example, if you only watch to match where the @user_id is an integer. You can do this by appending a : character and compiler name to the parameter:

Route.get('/dashboard/@user_id:string', 'WelcomeController@show')

Available route compilers are:

integer
int (alias for integer)
string
signed
uuid

Creating Route Compilers

You can also create your own route compilers if you want to be able to support specific regex matches for routes.

All route compilers will need to be added to the top of your register_routes() method in your Kernel.py file.

    def register_routes(self):
        Route.set_controller_locations(self.application.make("controllers.location"))
        Route.compile("handle", r"([\@\w\-=]+)")

        #..

Note: The compile methods need to happen before the routes are loaded in this method so make sure it is at the top. You may also put it in any method that appears before the register_routes() method.

Route Groups

Route groups are a great way to group mulitple routes together that have similiar options like a prefix, or multiple routes with the same middleware.

A route uses the group() method that accepts a list of routes and keyword arguments for the options:

ROUTES = [
  Route.group([
    Route.get('/settings', 'DashboardController@settings').name('settings'),
    Route.get('/monitor', 'DashboardController@monitor').name('monitor'),
  ],
  prefix="/dashboard",
  middleware=['web', 'cors'],
  name="dashboard."),
  domain="docs"
]

The prefix and name options will prefix the options set in the routes inside the group. In the above example, the names of the routes would dashboard.settings with a URL of /dashboard/settings and dashboard.monitor and a URL of /dashboard/monitor.

Route Views

Route views are a quick way to return a view quickly without needing to build a controller just to return a view:

ROUTES = [
  Route.view("/url", "view.name", {"key": "value"})
]

You could optionally pass in the methods you want this to be able to support if you needed to:

ROUTES = [
  Route.view("/url", "view.name", {"key": "value"}, method=["get", "post"])
]

List Routes

Application routes can be listed with the routes:list Masonite command. Routes will be displayed in a table with relevant info such as route name, methods, controller and enabled middlewares for this route.

Routes can be filtered by methods:

python craft routes:list -M POST,PUT

Routes can be filtered by name:

python craft routes:list -N users

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:

Route.get('/', 'WelcomeController@show')

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

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

$ python craft controller Welcome

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

from masonite.controllers import Controller
from masonite.views import View


class WelcomeController(Controller):
    def show(self, view: View):
        return view.render("")

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

def __init__(self, request: Request):
  self.request = request

  #..

def show(self, request: Request):
  return request.param('1')

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:

def show(self):
  return {"key": "value"}

This will return an application/json response.

Strings

You can return strings:

def show(self):
  return "welcome"

Views

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

def show(self, view: View):
  return view.render("views.welcome")

Models

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

from app.User import User
#..

def show(self, response: Response):
  return User.find(1)

Redirects

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

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

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:

Route.get('/users/@user_id', 'UsersController@user')

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

def show(self, user_id):
  return User.find(user_id)

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

from masonite.request import Request

def show(self, request: Request):
  return User.find(request.param('user_id'))

Controller Locations

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

self.application.bind("controllers.location", "app/controllers")
# ...
Route.set_controller_locations(self.application.make("controllers.location"))

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:

from masonite.routes import Route

Route.add_controller_locations("app/http/controllers", "other_module/controllers")

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:

from masonite.request import Request
#..

def show(self, request: Request):
  request.cookie('Accepted-Cookies')

This will fetch the cookie from the incoming request headers.

You can also set cookies on the request:

from masonite.request import Request
#..

def show(self, request: Request):
  request.cookie('Accepted-Cookies', 'True')

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:

from masonite.request import Request
#..

def show(self, request: Request):
  request.header('X-Custom')

You can also set a header on the request class:

from masonite.request import Request
#..

def show(self, request: Request):
  request.header('X-Custom', 'value')

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:

from masonite.request import Request
#..

def show(self, request: Request):
  request.get_path() #== /dashboard/1

You can get the current request method:

from masonite.request import Request
#..

def show(self, request: Request):
  request.get_request_method() #== PUT

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

from masonite.request import Request
#..

def show(self, request: Request):
  # URI: /dashboard/1/users
  request.contains("/dashboard/*/users") #== True

You can get the current subdomain from the host:

from masonite.request import Request
#..

def show(self, request: Request):
  # URI: work.example.com
  request.get_subdomain() #== work

You can get the current host:

from masonite.request import Request
#..

def show(self, request: Request):
  # URI: work.example.com
  request.get_host() #== example.com

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:

from masonite.request import Request
#..

def show(self, request: Request):
  # GET /dashboard?user_id=1
  request.input('user_id') #== 1

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

from masonite.request import Request
#..

def show(self, request: Request):
  # GET /dashboard
  request.input('user_id', 5) #== 5

To fetch all inputs from request we can do:

from masonite.request import Request

def show(self, request: Request):
  request.all() #== {"user_id": 1, "name": "John", "email": "john@masoniteproject.com"}

Or we can only fetch some inputs:

To fetch all inputs from request we can do:

from masonite.request import Request

def show(self, request: Request):
  request.only("user_id", "name") #== {"user_id": 1, "name": "John"}

Getting Dictionary Input

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

"""
Request Payload: 
{
"user": {
    "id": 1,
    "addresses": [
        {"id": 1, "street": "A Street"},
        {"id": 2, "street": "B Street"}
    ],
	"name":{
		"first":"user",
		"last":"A"
	}
 }
}
"""

You can either access it normally:

request.input('user')['name']['last'] # A

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

request.input('user.name.last') # A

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

request.input('user.addresses.*.id') # [1,2]

Route Params

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

If you have a route like this:

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

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

from masonite.request import Request
#..

def show(self, request: Request):
  # GET /dashboard?user_id=1
  request.param('user_id') #== 1

User

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

from masonite.request import Request
#..

def show(self, request: Request):
  # GET /dashboard?user_id=1
  request.user() #== <app.User.User>

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:

# Kernel.py
from masonite.middleware import IpMiddleware

class Kernel:
    http_middleware = [
      # ...
      IpMiddleware
    ]

Then you can use the ip() helper:

def show(self, request: Request):
    request.ip()

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:

class CustomIpMiddleware(IpMiddleware):
    headers = [
      "HTTP_CLIENT_IP",
      "REMOTE_ADDR"
    ]

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:

config/storage.py

STATICFILES = {
    'storage/assets/css': 'assets/',
}

Now in our templates we can use:

<img src="/assets/style.css">

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:

config/filesystem.py

....
's3': {
  's3_client': 'sIS8shn...'
  ...
  'path': 'https://s3.us-east-2.amazonaws.com/bucket'
  },
....

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

this will render:

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

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

config/storage.py

....
's3': {
  's3_client': 'sIS8shn...'
  ...
  'path': {
    'east': 'https://s3.us-east-2.amazonaws.com/east-bucket',
    'west': 'https://s3.us-west-16.amazonaws.com/west-bucket'
  },
....

and use the dot notation like so:

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

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:

resources/
routes/
storage/
  static/
  root/
    robots.txt
    manifest.json

and you can alias this in your STATICFILES constant:

config/storage.py

STATICFILES = {
    # folder          # template alias
    'storage/static': 'static/',
    ...
    'storage/public': '/'
}

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.

Then inside your controller file you can reference this template:

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

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:

Then inside your template you can do:

View Composing

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

You may also pass a list of templates:

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:

Asset

You can get the location of static assets:

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

this will render a URL like this:

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:

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

Current User

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

This will now submit this form as a PUT request.

Route

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

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

or a list:

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:

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

Session

You can access the session here:

Config

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

Gets a cookie:

Url

Get the URL to a location:

DD

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

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:

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:

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:

and then our function would look like:

Adding Filters

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:

The code is simple and looks something like this:

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.

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:

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:

This can be rewritten like this with line statement syntax:

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:

But you could achieve that with the regular formatting:

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: