1 of 88

v2.2 LTS

Introduction and Installation

Any developers that are using or have used Masonite

If you can take 5 minutes to complete this survey it would be very much appreciated. Just very simple questions that we can use to make Masonite an even better framework then it already is!

Click here to start the survey

The modern and developer centric Python web framework that strives for an actual batteries included developer tool with a lot of out of the box functionality with an extremely extendable architecture. Masonite is perfect for beginner developers getting into their first web applications as well as experienced devs that need to utilize the full potential of Masonite to get their applications done.

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.

If you are more of a visual learner you can watch Masonite related tutorial videos at MasoniteCasts.com

Some Notable Features Shipped With Masonite

Easily send emails with the Mail Provider and the SMTP and Mailgun drivers.
Send websocket requests from your server with the Broadcast Provider and Pusher and Ably drivers.
IOC container and auto resolving dependency injection.
Service Providers to easily add functionality to the framework.
Extremely simple static files configured and ready to go.
Active Record style ORM called Orator.
An extremely useful command line tool called craft commands.
Extremely extendable.

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.4+
Latest version of OpenSSL
Pip3

All commands of python and pip in this documentation is assuming they are pointing to the corresponding Python 3 versions. If you are having issues with any installation steps just be sure the commands are for Python 3.4+ 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-get install python-dev libssl-dev python3-pip

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

terminal

$ sudo apt-get install python3.6-dev libssl-dev python3-pip

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

terminal

# dnf install python-devel openssl-devel

Installation

Be sure to join the Slack Channel for help or guidance.

Masonite excels at being simple to install and get going. We use a simple command line tool that will become your best friend. You’ll never want to develop again without it. We call them craft commands.

We can download our craft command line tool by just running:

terminal

$ pip install masonite-cli --user

If you already have craft installed, Masonite 2.2 requires masonite-cli>=2.2.0 so you may have to run with the upgrade flag too.

terminal

$ pip install masonite-cli --upgrade

If you are having installation issues, be sure to read the Known Installation Issues documentation.

Creating Our Project

Great! We are now ready to create our first project. We should have the new craft command. We can check this by running:

terminal

$ craft

This should show a list of command options. If it doesn't then you may have installed the masonite cli incorrectly. Try uninstalling it and be sure when you install it you install it with a --user flag like pip install masonite-cli --user.

We are currently only interested in the craft new command. To create a new project just run:

terminal

$ craft new project_name
$ cd project_name

This will get the latest Masonite project template and unzip it for you. We just need to go into our new project directory and install the dependencies in our requirements.txt file.

Activating Our Virtual Environment (optional)

You can optionally 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 pythoncommand 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 python3anytime you see the pythoncommand.

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

Installing Our Dependencies

Now lets install our dependencies. We can do this simply by using a craft command:

terminal

$ craft install

This command is just a wrapper around the pipcommand. This installs all the required dependencies of Masonite, creates a .env file for us, generates a new secret key, and puts that secret key in our .env file. After it’s done we can just run the server by using another craft command:

Running The Server

After it’s done we can just run the server by using another craft command:

terminal

$ craft serve

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

The Masonite CLI (also known as craft) will try to find all the commands in your project but may not be able to. In this case you will need to call craft directly using something like:

terminal

$ python craft serve

You can learn more about craft by reading The Craft Command documentation or continue on to learning about how to create web application by first reading the Routing documentation

Masonite has romantic versioning instead of semantic versioning. Because of this, all minor releases (2.0.x) will contain bug fixes and fully backwards compatible feature releases. Be sure to always keep your application up to date with the latest minor release to get the full benefit of Masonite's romantic versioning.

Creating a Blog

Preface

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

This tutorial will assume you have already installed Masonite. If you haven't, be sure to read the Installation guide to get a fresh install of Masonite up and running. Once you have one up and running or if you already have it running, go ahead and continue on.

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 Get

Get('/url', 'Controller@method')

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

You can read more about routes in the Routing documentation

Creating our Route:

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

A controller is a simple class that holds controller methods. These controller methods will be what our routes will call so they will contain all 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 = [
    Get('/', 'WelcomeController@show').name('welcome'),

    # Blog Routes
    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.

Let's create the BlogController in the next step: Part 2 - Creating Our First Controller

Creating a Controller

All controllers are located in the app/http/controllers directory and Masonite promotes 1 controller per file. 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:

$ craft controller Blog

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

"""A BlogController Module."""

from masonite.request import Request
from masonite.view import View
from masonite.controllers import Controller


class BlogController(Controller):
    """BlogController Controller Class."""

    def __init__(self, request: Request):
        """BlogController Initializer

        Arguments:
            request {masonite.request.Request} -- The Masonite Request class.
        """
        self.request = request

    def show(self, view: View):
        pass

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 Python'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 stuff in between code that we are not worried about:

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

Notice here we annotated 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.

Be sure to learn more about the Service Container.

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 resources/templates directory. We can create a new file called resources/templates/blog.html or we can use another craft command:

$ craft view blog

This will create that template we wanted above for us.

We can put some text in this file like:

This is a blog

and then run the server

$ 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:

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

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

Database Setup

In order to register these users, we will need a database. Hopefully you already have some kind of local database setup like MySQL or Postgres but we will assume that you do not. In this case we can just use SQLite.

Now we just need to change a few environment variables so Masonite can create the SQLite database.

These environment variable can be found in the .env file in the root of the project. Open that file up and you should see a few lines that look like:

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

Go ahead and change those setting to your connection settings by adding sqlite to the DB_CONNECTION variable and whatever you want for your database which will be created for you when you migrate. We will call it blog.db:

DB_CONNECTION=sqlite
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=blog.db
DB_USERNAME=root
DB_PASSWORD=root

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.

$ 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:

$ craft serve

and head over to http://localhost:8000/register and fill out the form. You can use whatever name and email you like but for this purpose we will use:

Username: demo
Email: demo@email.com
Password: password

Migrations

Now that we have our authentication setup and we are comfortable with migrating our migrations, 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. Let's walk through how we create migrations with Masonite.

Craft Command

Not surprisingly, we have a craft command to create migrations. You can read more about Database Migrations here but we'll simplify it down to the command and explain a little bit of what's going on:

$ craft migration create_posts_table --create posts

This command simply creates the start of a migration that will 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()

This should be fairly straight forward but if you want to learn more, be sure to read the Database Migrations documentation.

Now we can migrate this migration to create the posts table

$ 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 Orator which is an Active Record implementation of an ORM. This bascially means we will not be building our model and then translating that into a migration. 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:

$ craft model Post

Notice we used the singular form for our model. By default, Orator will check for the plural name of the class in our database (in this case posts) by simply appending an "s" onto the model. We will talk about how to specify the table explicitly in a bit.

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

"""A Post Database Model."""
from config.database 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 (by appending an "s") but if you called your table something different such as "blog" instead of "blogs" we can specify the table name explicitly:

"""A Post Database Model."""
from config.database import Model

class Post(Model):
    __table__ = 'blog'

Mass Assignment

Orator 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:

"""A Post Database Model."""
from config.database 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:

"""A Post Database Model."""
from config.database import Model
from orator.orm import belongs_to

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

    @belongs_to('author_id', 'id')
    def author(self):
        from app.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.

We won't go into much more detail here about different types of relationships but to learn more, read the ORM documentation.

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 this strange {{ csrf_field }} looking text. Masonite comes with CSRF protection so we need a token to render with the CSRF field.

Now because we have a foreign key in our posts table, 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.

Masonite uses Jinja2 templating so if you don't understand this templating, be sure to read their documentation.

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 files work 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>

For more information on static files, checkout the Static Files documentaton.

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 routes/web.py and create a new route. Just add this to the ROUTES list:

from masonite.routes import Get, Post
...

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

Notice that we now used request: Request here. This is the Request object. Where did this come from? This is the power and beauty of Masonite and your first introduction to the Service Container. The Service Container is an extremely powerful implementation as allows you to ask Masonite for an object (in this case Request) and get that object. This is an important concept to grasp so be sure to read the documentation further.

Read more about the Service Container here.

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 doesn't matter. You will always use this input method.

Go ahead and run the server using craft serve 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. In this part we will create 2 new templates to show all posts and a specific post.

Creating The Templates

Let's create 2 new templates.

$ craft view posts
$ craft view single

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.

$ 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.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:

Get('/posts', 'PostController@show')

Posts View

Our posts view can be very simple:

{% 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. Orator 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:

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.

Single Method

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

from app.Post import Post
from masonite.request import Request
from masonite.view 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 a 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 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

$ craft view update

<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:

Get('/post/@id/update', 'PostController@update'),
Post('/post/@id/update', 'PostController@store'),

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

Delete Method

Let's expand a bit and made 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:

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!

Prologue

Contributing Guide

Introduction

When contributing to this repository, please first discuss the change you wish to make via an issue or in the Masonite Slack channel.

Please note we have a code of conduct, please follow it in all your interactions with the project. You can find it in the base of the core project directory.

Getting Started

The framework has three main parts.

This MasoniteFramework/masonite repository is the main repository that will install when creating new projects using the craft new command. This is actually a full Masonite project. Not much development will be done in this repository and won't be changed unless new releases of Masonite require changes in the default installation project.

The MasoniteFramework/core repository is where the main masonite pip package lives. This is where the from masonite ... module lives.

The MasoniteFramework/craft repository where the craft command lives. This is the actual command itself and is installed when you run pip install masonite-cli --user.

Getting the Masonite repository up and running to be edited

You can read about how the framework flows, works and architectural concepts here

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

Fork the MasoniteFramework/masonite repo.
Clone that repo into your computer:
- git clone http://github.com/your-username/masonite.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 core 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/core repo,
Clone that repo into your computer:
- git clone http://github.com/your-username/core.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 . from inside the masonite-core directory. This will install masonite as a pip package.
Any changes you make to this package just push it to your feature branch on your fork and follow the PR process below.

This repository has a barebones skeleton of a sample project in order to aid in testing all the features of Masonite against a real project. If you install this as editable by passing the --editable flag then this may break your project because it will override the modules in this package with your application modules.

Editing the craft repository (`craft` commands)

Craft commands make up a large part of the workflow for Masonite. Follow these instructions to get the masonite-cli package on your computer and editable.

Fork the MasoniteFramework/craft repo,
Clone that repo into your computer:
- git clone http://github.com/your-username/craft.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 cli
Run pip install --editable . from inside the masonite-cli directory. This will install craft (which contains the craft commands) as a pip package but also keep a reference to the folder so you can make changes freely to craft commands while not having to worry about continuously reinstalling it.
Any changes you make to this package just push it 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 dependency are object 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.
    """
    pass

Code Comments

If you're code MUST be complex enough that future developers will 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

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 done 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 a docstring comments on the variables it's setting.
Update the README.md and MasoniteFramework/docs repo with details of changes to the interface, this includes new environment variables, new file locations, container parameters 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 systems at later dates. If it is a new feature name it feature-576.
You must add unit testing for any changes made. Of the three repositories listed above, only the craft and core repos require unit testing.
Increase the version numbers in any example files and the README.md to the new version that this Pull Request would represent. The versioning scheme we use is RomVer.
The PR must pass the Travis CI build. The Pull Request can be merged in once you have a successful review from two other collaborators, or one review from a maintainer or Masonite creator.

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 idmann509@gmail.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

This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at http://contributor-covenant.org/version/1/4

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

Of course the project requires contributions to the main development aspects but it's not the only way. But if you would like to contribute to development then a great way to get started is to simply read through this documentation. Get acquainted with how the framework works, how Controllers and Routing work and read the Architectural Concepts documentation starting with the Request Lifecycle, then the Service Providers and finally the Service Container.

It would also be good to read about the Release Cycle to get familiar with how Masonite does releases (SemVer and RomVer).

Become a Feature Maintainer

Feature Maintainers are people who are in charge of specific features (such as Caching or Creating Packages). These developers will be in charge of reviewing PR's and merging them into the development branch and also have direct contact with the repository owner to discuss.

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

The Masonite pip packages require testing (The main repository does not). If you want to search through all the tests in the tests directories of those repositories and write additional tests and use cases then that will be great! There are already over 100 tests but you can always write more. With more testing comes more stability. Especially as people start to contribute to the project. Check the tests that are already there and write any use cases that are missing. These tests can be things such as special characters in a url or other oddities that may not have been thought of when using TDD for that feature.

Contribute to Tutorials

Once familiar with the project (by either contributing or by building application using the framework) it would be excellent if you could write or record tutorials and put them on Medium or YouTube. In order for the framework to be successful, it needs to have a plethora of documentation even outside of this documentation. It needs to have notoriety and if people are seeing the framework pop up in their favorite locations they will be more inclined to use the framework and contribute to it as well.

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

This documentation is fantastic but there are spots where it could be improved. Maybe we haven't explained something fully or something just doesn't make sense to you. Masonite uses Gitbook.com to host it's documentation and with that you are able to comment directly on the documentation which will start a discussion between you and the documentation collaborators. So if you want to cycle through the documentation page by page and get acquainted with the framework but at the same time contribute to the documentation, this is perfect for you.

Report Bugs

If you just don't want to contribute code to the main project you may instead simply report bugs or improvements. You can go ahead and build any of your applications as usual and report any bugs you encounter to the GitHub.com issues page.

Squash Bugs

Look at the issues page on GitHub.com for any issues, bugs or enhancements that you are willing to fix. If you don't know how to work on them, just comment on the issue and Joseph Mancuso or other core contributors will be more than happy explaining step by step on how you can go about fixing or developing that issue.

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

Another idea is to use Masonite to build applications such as a screencast website like LaraCasts.com or an official Masonite website or even a social network around Masonite. Every great framework needs it's "ecosystem" so you may be apart of that by building these applications with the Masonite branding and logos. Although copying the branding requires an OK from Joseph Mancuso, as long as the website was built with Masonite and looks clean it shouldn't be a problem at all.

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

Most pull requests will sit inside GitHub for a few days while it gets quality tested. The main develop branch pull requests could sit there for as long as 6 months and will only be merged in on releases. With that being said, you can look at the file changes of these pull requests and ensure they meet the community guidelines, the API is similar to other aspects of the project and that they are being respectful and following pull requests rules in accordance with the Contributing Guide documentation.

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.

Release Cycle

Introduction

The Masonite framework itself follows the RomVer versioning schema which is PARADIGM.MAJOR.MINOR although all Masonite packages follow the SemVer versioning schema which is MAJOR.MINOR.BUGFIX.

This means that a framework version of 1.3.20 may have breaking changes with version 1.4.0. Masonite uses a 6 month major release cycle in order to maintain it's state as a modern Python web framework. Each release is a solid and stable release and upgrading typically takes minimal time.

Reasoning for RomVer over SemVer

The Masonite main repository (the MiraFramework/masonite repository) contains only the basic file structure of the application. All of the core framework functionality is inside the MasoniteFramework/core repository which can be updated as much as every day or once per month.

Because MiraFramework/masonite does not require major updates, we can follow RomVer nicely and keep the versioning number artificially lower. Any major updates to this repsository will likely just be file structure changes which should rarely happen unless there are major architectural changes.

Releases and Release Cycles

Masonite is currently on a 6 month major release cycle. This means that once six months will be a new 2.x release.

Releases are planned to be upgradable from the previous release in 30 minutes or less. If they break that requirement then they should be considered for the next Paradigm release (the x.0.0 release)

Scheduled Releases

Creating Releases

Masonite is made up of three different repositories. There is

The main repository where development is done on the repo that installs on developer's systems.
The core repository which is where the main Masonite pip package is located.
The craft repository where the craft command tool is located.

Major 6 month releases will be released on or after the release date when all repositories are able to be released at the same time, as well as passing all tests.

The core repository is uploaded to PyPi under the new release. At this time, everyone could theoretically install the package. Once core is released, craft is updated for any minor changes it may require. Once these two repositories are completed, the masonite repository is updated and finally released. Once this repo is released to the latest version, all future projects will default to the latest version of Masonite.

After that we will bump the version of Masonite in the documentation and verify and update any documentation that is not up to standard.

Whenever the MasoniteFramework/craft and MasoniteFramework/core repositories are released on Github, Travis CI will run tests and automatically deploy to PyPi. These major version numbers should correspond to the version of Masonite they support. For example, if the MasoniteFramework/masonite releases to version 1.4, MasoniteFramework/core should bump up to 1.4.x regardless of changes.

Main Repository and New Projects

The main repository which is MasoniteFramework/masonite does not have a corresponding PyPi package and is only for installing new Masonite projects. See the craft new command under The Craft Command documentation. The craft new command will download a zip of the latest release of Masonite, unzip it and rename the folder. Once the next release for this repository is ready, it will be released but marked as a Pre-release and therefore will not be installable by the default craft new command.

This is so developers and maintainers will be able to test the new pre release with their applications. Once all QA tests have passed, it will be marked as a normal release and therefore all new applications created from there on out will be the new release.

Developers will still have the option of doing something like: craft new project_name --version 1.6 and installing that version of Masonite.

Once all three repositories are ready for release, they will all be released on GitHub under the respective new version numbers.

Known Installation Issues

Introduction

There are no known Masonite specific issues known and if there are then there should be an issue open for them on GitHub. With that being said, some users may experience some difficulties with installing Masonite simply because their computer environment is not the norm, they have never setup Python and may have configured it incorrectly or they have not used Python in a while and have an old version.

Before you get started reading through this FAQ make sure you have:

Python 3.4+
Pip3

Ensure you are installing masonite-cli with pip3 and not pip.

I ran pip install masonite-cli but it gave me a permission error?

You are likely running this command on a UNIX based machine like Mac or Linux. In that case you should either run it again with a sudo command or a user command flag:

$ pip install masonite-cli --user

$ pip install --user masonite-cli

I pip installed masonite-cli but running craft doesn't work?

If you ran:

$ pip install masonite-cli --user

and then run:

$ craft

and get something like:

-bash: craft: command not found

then try closing your terminal and reopening it. If that doesn't work then you may be running a pip version connecting to Python 2.7. Try uninstalling it and reinstalling it using pip3:

$ pip uninstall masonite-cli
$ pip3 install masonite-cli

If that does not work then you may have to run sudo:

$ pip3 uninstall masonite-cli
$ sudo pip3 install masonite-cli

I'm getting this weird ModuleNotFound idna issue when running the craft new command

You may get a strange error like:

pkg_resources.DistributionNotFound: The 'idna<2.7,>=2.5' distribution was not found and is required by requests

The simple fix may just be to run:

pip install --upgrade requests

If that doesn't work we can just go back to the lower idna version:

pip install idna==2.6

If that does not fix the issue then continue reading.

If the above fix did not work then this likely means you installed masonite-cli using the Python 2.7 pip command. Out of the box, all Mac and Linux based machines have Python 2.7. If you run:

$ python --version

you should get a return value of:

Python 2.7.14

But if you run:

$ python3 --version

you should get a return value of:

Python 3.6.5

Now pip commands are similar:

$ pip --version
pip 10.0.1 /location/of/installation (python 2.7)

$ pip3 --version
pip 10.0.1 /location/of/installation (python 3.6)

Notice here we are using 2 different Python installations.

So if you are getting this error you should uninstall masonite-cli from pip and reinstall it using pip3:

$ pip uninstall masonite-cli
$ pip3 install masonite-cli

You may have to run sudo to remove and install it and you may need to close your terminal to get it work if you are using a UNIX machine.

I installed masonite-cli successfully but the craft command is not showing up

If you installed everything successfully and running:

$ craft

Shows an error that it can't be found then try closing your terminal and opening it again. This should refresh any commands that were recently installed

If you still have errors and on a UNIX based machine try running:

$ sudo pip3 install masonite-cli

I'm getting a module urlib has no attribute urlopen

You likely ran:

$ craft new project_name

and hit this weird snag that throws this ambiguous error. You might think this is because of a Python version issue but craft is designed to work on Python 2.7 and 3.4+ (although 2.7 and not thoroughly tested) and you're years of Python experience would make you right but this is special. If you are getting this error then that means you are likely on a UNIX machine, Mac right?

The problem is that your machine does not have sufficient permissions to access these external calls from the command line because your machine does not have permission to do so. You will have to give you machine the command to do so by running:

$ /Applications/Python\ 3.6/Install\ Certificates.command

or whatever your Python 3 version is in the middle. Now try running:

$ craft new project_name

and it should work great!

Deprecation

Introduction

This page contains all deprecated code that may be removed in future versions of Masonite. These helpers are available to use for the remainder of the 2.1 lifetime but will be removed in either the next version (2.2) or the version after.

About Deprecation

Some code inside Masonite becomes obsolete as new features become available. In order to make maintaining the codebase easier and clutter free, Masonite will start emitting deprecation warnings during minor releases of the current release.

For example if you upgrade from 2.1.20 to 2.1.21, you may start seeing deprecation warnings inside your console. You can safely ignore these warnings and your code will still work fine but may not work when upgrading to the next major version (for example from 2.1 to 2.2).

What to do

When you see these deprecation warnings, you will see a link as well that comes to this page. You should scroll down this page for examples on how to get your code up to date and not in a deprecated state. You should do this as soon as it becomes convenient for you to do so.

Deprecated Code

No code is scheduled for deprecation as of yet. This can change with future versions of Masonite

What's New

Masonite 1.3

Introduction

Masonite 1.3 comes with a plethora of improvements over previous versioning. This version brings new features such as Queue and Mail drivers as well as various bug fixes.

Fixed infinite redirection

Previously when a you tried to redirect using the Request.redirect() method, Masonite would sometimes send the browser to an infinite redirection. This was because masonite was not resetting the redirection attributes of the Request class.

Fixed browser content length

Previously the content length in the request header was not being set correctly which led to the gunicorn server showing a warning that the content length did not match the content of the output.

Changed how request input data is retrieved

Previously the Request class simply got the input data on both POST and GET requests by converting the wsgi.input WSGI parameter into a string and parsing. All POST input data is now retrieved using FieldStorage which adds support for also getting files from multipart/formdata requests.

Added Upload drivers

You may now simply upload images to both disk and Amazon S3 storage right out of the box. With the new UploadProvider service provider you can simply do something like:

<html>
  <body>
      <form action="/upload" method="POST" enctype="multipart/formdata">
        <input type="file" name="file">
      </form>
  </body>
</html>

def show(self, Upload):
    Upload.store(Request.input('file'))

As well as support for Amazon S3 by setting the DRIVER to s3.

Added several helper functions

These helper functions are added functions to the builtin Python functions which can be used by simply calling them as usual:

def show(self):
    return view('welcome')

Notice how we never imported anything from the module or Service Container. See the Helper Functions documentation for a more exhaustive list

Added a way to have global template variables

Very often you will want to have a single variable accessible in all of your views, such as the Request object or other class. We can use the new View class for this and put it in it's own service provider:

def boot(self, View, Request):
    View.share({'request': Request})

Middleware is now resolved by the container

You can now specify anything that is in the container in your middleware constructor and it will be resolved automatically from the container

Added new domain method to the Get and Post classes

Specify the subdomain you want to target with your route. It's common to want to have separate routes for your public site and multi-tenant sites. This will now look something like:

Get().domain('test').route('/dashboard', 'DashboardController@show')

Which will target test.example.com/dashboard and not example.com/dashboard. Read more about subdomains in the Routing documentation.

Added new module method to Get and Post routes

By default, masonite will look for routes in the app/http/controllers namespace but you can change this for individual routes:

Get().module('thirdpary.routes').route('/dashboard', 'DashboardController@show')

This will look for the controller in the thirdparty.routes module.

Added Queues and Jobs

Masonite now ships with a QueueManager class which can be used to build queue drivers. Masonite ships with an async driver which sends jobs to a background thread. These queues can process Jobs which ca be created with the new craft job command. See the Queues and Jobs documentation for more information.

Masonite 1.4

Introduction

Masonite 1.4 brings several new features to Masonite. These features include caching, template caching, websocket support with Masonite calls Broadcasting and much more testing to make Masonite as stable as possible. If you would like to contribute to Masonite, please read the Contributing Guide and the How To Contribute documentation.

If you are upgrading from Masonite 1.3 then please read the Masonite 1.3 to 1.4 documentation.

Broadcast Support

We recognize that in order for frameworks to keep up with modern web application, they require real time broadcasting. Masonite 1.4 brings basic broadcasting of events to masonite and comes with two drivers out of the box: pusher and ably. If you'd like to create more drivers then you can do so easily by reading the About Drivers documentation. If you do create a driver, please consider making it available on PyPi so others can install it into their projects or open an issue on GitHub and make to add it to the built in drivers.

Caching

Masonite now has a built in caching class that you can use to either cache forever or cache for a specific amount of time.

Template Caching

Templates may have a lot of logic that are only updated every few minutes or even every few months. With template caching you can now cache your templates anywhere from every few seconds to every few years. This is an extremely powerful caching technique that will allow your servers to run less intensively and easily increase the performance of your application.

If a page gets hit 100 times every second then you can cache for 5, 10 or 15 seconds at a time to lessen the load on your server.

This feature only activates if you have the CacheProvider loaded in your PROVIDERS list. If you try to use these features without that provider then you will be hit with a RequiredContainerBindingNotFound exception letting you know you are missing a required binding from a service provider. This provider comes out of the box in Masonite 1.4.

PEP 8 Standards

We have also updated the code to closely conform to PEP 8 standards.

Added a New Folder and Configuration File

Because of the caching features, we have added a bootstrap/cache folder where all caching will be put but you can change this in the new config/cache.py file.

Added Contracts

Masonite 1.4 brings the idea of contracts which are very similar to interfaces in other languages. Contracts ensure that a driver or manager inherits has the same functionality across all classes of the same type.

Added CSRF Protection

Cross-Site Request Forgery is a crucial security milestone to hit and Masonite 1.4 brings that ability. With a new Service Provider and middleware, we can now add a simple {{ csrf_field }} to our forms and ensure we are protected from CSRF attacks.

Changed Managers

Managers were very redundant before this release so we made it much easier to create managers with 2 simple class attributes instead of the redundant method. Managers are used to manage features and drivers to Masonite.

Middleware is now resolved by the container

Now the constructor of all middleware is resolved by the container. This means you may use the IOC dependency injection techniques like controller methods and drivers.

Fixed unused imports

There were two unused imports in the models that Masonite created. These have been removed completely.

Masonite 1.5

Introduction

Masonite 1.5 is focused on a few bug fixes and changes to several core classes in order to expand on the support of third party package integration.

Masonite Entry

Masonite 1.5 is releasing also with a new official package for adding RESTful API's to your project. This package used API Resources which are classes that can add a plethora of capabilities to your API endpoints. You can read more about it at the Masonite Entry documentation.

HTTP Methods

Masonite 1.5 also adds additional support HTTP methods like PUT, PATCH and DELETE. More information about these new routes can be found under the Routing documentation

Moving Dependencies

Nearly all dependencies have been moved to the core Masonite package. The only thing inside the project that is installed using craft new is the WSGI server (which is waitress by default) and Masonite itself. This will improve the ability to change and update dependencies.

Changing Form Request Methods

HTML forms only support GET and POST so there is no the ability to add any other HTTP methods like PUT and PATCH which will change the actual request method on submission. You can read more about this in the Requests documentation.

Added Shorthand Route Helpers

You can now use functions for routes instead of the classes. These new functions are just wrappers around the classes itself. Read more about this under the Routing documentation.

Removed API from core

In Masonite 1.4 and below was the Api() route which added some very basic API endpoints. All references to API's have been removed from core and added to the new Masonite Entry official package.

If you would like to use API's you will have to use the Masonite Entry package instead.

Headers

You can now get and set any header information using the new Request.header method. This also allows third party packages to manipulate header information. Read more about this in the Requests documentation.

Cookies

You can now delete cookies using the delete_cookie method as well as set expiration dates for them. See the Requests documentation for more information.

Caching Driver Update

The Cache driver now has an update method which can update a cache value by key. This is useful if you want to change a key value or increment it. Storing a cache file also now auto creates that directory. Read more about this in the Caching documentation.

An All New Craft Command

Craft commands have been built from the ground up with the cleo package. It's an excellent package that is built around the extendability of commands by using primarily classes (instead of decorator functions). Read more under The Craft Command documentation

Adding Commands

It is now possible to add craft commands to craft. You can read more about how under The Craft Command documentation

Adding Migration Directories

You can now add more migration directories by adding it to the container with a key ending in MigrationDirectory. This will add the directory to the list of directory that run when migrate commands are ran. You can read more about this in the Creating Packages documentation.

Added Sessions

You can now add data to sessions using the new Sessions feature which comes with a memory and cookie driver for storing data.

Craft Auto Adds Site Packages

In previous versions, Masonite has not been able to fetch the site packages directory if you were in a virtual environment because virtual environment directories are dynamically named depending on who created it. We have found a way to detect the virtual environment and the site packages directory so now there is no need to add the site packages directory manually to the packages configuration file

Masonite 1.6

Introduction

Masonite 1.6 brings mostly minor changes to the surface layer of Masonite. This release brings a lot of improvements to the engine of Masonite and sets up the framework for the release of 2.0.

HttpOnly Cookies

Previously, all cookies were set with an HttpOnly flag when setting cookies. This change came after reading several articles about how cookies can be read from Javascript libraries, which is fine, unless those Javascript libraries have been compromised which could lead to a malicious hacker sending your domain name and session cookies to a third party. There is no the ability to turn the HttpOnly flag off when setting cookies by creating cookies like:

request().cookie('key', 'value', http_only=False)

Moved Commands

Because craft is it's own tool essentially and it needs to work across Masonite versions, all commands have been moved into the Masonite repository itself. Now each version of Masonite maintains it's own commands. The new craft version is 2.0

pip install masonite-cli==2.0 --user

Drivers Can Now Change To Other Drivers

Before, you had to use the Manager class associated with a driver to switch a driver. For example:

def show(self, Upload, UploadManager):
    Upload.store(...) # default driver
    UploadManager.driver('s3').store(...) # switched drivers

Now you can switch drivers from the driver itself:

def show(self, Upload):
    Upload.store(...) # default driver
    Upload.driver('s3').store(...) # switched drivers

New Absolute Controllers Syntax

This version has been fine tuned for adding packages to Masonite. This version will come along with a new Masonite Billing package. The development of Masonite Billing has discovered some rough spots in package integrations. One of these rough spots were adding controllers that were not in the project. For example, Masonite Billing allows adding a controller that handles incoming Stripe webhooks. Although this was possible before this release, Masonite 1.6 has added a new syntax:

ROUTES = [
    ...
    # Old Syntax:
    Get().route('/url/here', 'Controller@show').module('billing.controllers')

    # New Syntax:
    Get().route('/url/here', '/billing.controllers.Controller@show')
    ...
]

Notice the new forward slash in the beginning where the string controller goes.

Changed How Controllers Are Created

Previously, controllers were created as they were specified. For example:

$ craft controller DashboardController

created a DashboardController. Now the "Controller" part of the controller is appended by default for you. Now we can just specify:

$ craft controller Dashboard

to create our DashboardController. You may was to actually just create a controller called Dashboard. We can do this by specifying a flag:

$ craft controller Dashboard -e

short for "exact"

Added Resource Controllers

It's also really good practice to create 1 controller per "action type." For example we might have a BlogController and a PostController. It's easy to not be sure what action should be in what controllers or what to name your actions. Now you can create a "Resource Controller" which will give you a list of actions such as show, store, create, update etc etc. If what you want to do does not fit with an action you have then you may want to consider making another controller (such as an AuthorController)

You can now create these Resource Controllers like:

craft controller Dashboard -r

Added Global Views

Just like the global controllers, some packages may require you to add a view that is located in their package (like the new exception debug view in 1.6) so you may now add views in different namespaces:

def show(self):
    return view('/masonite/views/index')

This will get a template that is located in the masonite package itself.

Added Route Groups

You can now group routes based on a specific string prefix. This will now look like:

routes/web.py

from masonite.helpers.routes import get, group
ROUTES = [
    get('/home', ...)
    group('/dashboard', [
        get('/user', ...)
        get('/user/1')
    ])
]

which will compile down into /dashboard/user and /dashboard/user/1

Changed Container Resolving

The container was one of the first features coded in the 1.x release line. For Masonite 1.6 we have revisited how the container resolves objects. Before this release you had to put all annotation classes in the back of the parameter list:

from masonite.request import Request

def show(self, Upload, request: Request):
    pass

If we put the annotation in the beginning it would have thrown an error because of how the container resolved.

Now we can put them in any order and the container will grab each one and resolve it.

from masonite.request import Request

def show(self, Upload, request: Request, Broadcast):
    pass

This will now work when previously it did not.

Resolving Instances

The container will now resolve instances of classes as well. It's a common paradigm to "code to an interface and not an implementation." Because of this paradigm, Masonite comes with contracts that act as interfaces but in addition to this, we can also resolve instances of classes.

For example, all Upload drivers inherit the UploadContract contract so we can simply resolve the UploadContract which will return an Upload Driver:

from masonite.contracts.UploadContract import UploadContract

def show(self, upload: UploadContract):
    upload.store(...)

Notice here that we annotated an UploadContract but got back the actual upload driver.

Container Collection

You can now search the container and "collect" objects from it by key using the new collect method:

app.collect('Sentry*Hook')

which will find all keys in the container such as SentryExceptionHook and SentryWebHook and make a new dictionary out of them.

Removed Some Dependencies

A complaint a few developers pointed out was that Masonite has too many dependencies. Masonite added Pusher, Ably and Boto3 packages by default which added a bit of overhead, especially if developers have no intentions on real time event broadcasting (which most applications probably won't). These dependencies have now been removed and will throw an exception if they are used without the required dependencies.

Framework Hooks

Masonite 1.6 + will slowly be rolling out various framework hooks. These hooks will allow developers and third party packages to integrate into various events that are fired throughout the framework. Currently there is the abilitity to tie into the exception hook which will call any objects loaded into the container whenever an exception is hit. This is great if you want to add things like Sentry into your project. Other hooks will be implemented such as View, Mail and Upload Hooks.

Masonite 2.0

Masonite 2 brings an incredible new release to the Masonite family. This release brings a lot of new features to Masonite to include new status codes, database seeding, built in cron scheduling, controller constructor resolving, auto-reloading server, a few new internal ways that Masonite handles things, speed improvements to some code elements and so much more. We think developers will be extremely happy with this release.

Upgrading from Masonite 1.6 to Masonite 2.0 shouldn't take very long. On an average sized project, this upgrade should take around 30 minutes. We'll walk you through the changes you have to make to your current project and explain the reasoning behind it.

Checkout the Upgrade Guide for Masonite 1.6 to 2.0

Controller Constructors

Controller constructors are now resolved by the container so this removed some redundancy within your code and any duplicated auto resolving can now be directly in your constructor:

from masonite.request import Request

class YourController:
    def __init__(self, request: Request):
        self.request = Request
    
    def show(self):
        print(self.request) # <class masonite.request.Request>

Read more in the Controllers documentation.

Tinker Command

There is a new command that starts a Python shell and imports the container for you already. Test it out to verify that objects are loaded into your container correctly. It's a great debugging tool.

$ craft tinker

Read more in The Craft Command Introduction documentation.

Show Routes Command

Masonite 2 ships with an awesome little helper command that allows you to see all the routes in your application

$ craft show:routes

Read more in The Craft Command Introduction documentation.

Server Reloading

A huge update to Masonite is the new --reload flag on the serve command. Now the server will automatically restart when it detects a file change. You can use the -r flag as a shorthand:

$ craft serve -r

Read more in The Craft Command Introduction documentation.

Autoloading

An incredible new feature is autoloading support. You can now list directories in the new AUTOLOAD constant in your config/application.py file and it will automatically load all classes into the container. This is great for loading command and models into the container when the server starts up.

You can also use this class as a standalone class in your own service providers.

Updated Libraries

Updated all libraries to the latest version with the exception of the Pendulum library which latest version is a breaking change and therefore was left out. The breaking change would not be worth it to add the complexity of upgrading so you may upgrade on a per project basis.

Removed Importing Duplicate Class Names

Previously you had to import classes like:

from masonite.drivers.UploadDriver import UploadDriver

Now you can simply specify:

from masonite.drivers import UploadDriver

Because of this change we no longer need the same duplicated class names in the PROVIDERS list either.

Read more about changing duplicated class names under the Duplicate Class Names documentation.

Redirection Provider

Removed the need for the redirection provider completely. You need to remove this from your PROVIDERS list.

Redirection

Renamed Request.redirectTo to Request.redirect_to

Also removed the .send() method and moved the dictionary into a parameter:

def show(self):
    return request().redirect('/dashboard/@id', {'id': '5'})

Read more in the Requests documentation.

Request Only

Added a new Request.only method to fetch only specific inputs needed.

Get Request Method

Added a new Request.get_request_method() method to the Request class.

New Argument in Request.all

You can now completely remove fetching of any inputs that Masonite handles internally such as __token and __method when fetching any inputs. This is also great for building third party libraries:

Request.all(internal_variables=False)

Made several changes to the CSRF Middleware

Because of the changes to internal framework variables, there are several changes to the CSRF middleware that comes in every application of Masonite.

Be sure to read the changes in the Upgrade Guide 1.6 to 2.0.

Added Scheduler to Masonite

Added a new default package to Masonite that allows scheduling recurring tasks:

Read about Masonite Scheduler under the Task Scheduling documentation.

Added Database Seeding Support

It's important during development that you have the ability to seed your database with dummy data. This will improve team development with Masonite to get everyones database setup accordingly.

Read more in the Database Seeding documentation.

Added a New Static File Helper

Now all templates have a new static function in them to improve rendering of static assets

Read more in the Static Files documentation.

Added a New Password Helper

You can use the password helper to hash passwords more simply than using straight bcrypt:

from masonite.helpers import password

password('secret') # returns bcrypt password

Read more in the Encryption documentation.

Added Dot Notation To Upload Drivers And Dictionary Support To Driver Locations.

You can now specify which location in your drivers you want to upload to using a new dot notation:

Upload.store(request().input('file'), 'disk.uploads')

This will use the directory stored in:

DRIVERS = {
  'disk': {
    'uploads': 'storage/uploads',
    'profiles': 'storage/static/users/profiles/images'
  },
  ...
}

Read more in the Uploading documentation.

Added Status Code Provider

Masonite 2 removes the bland error codes such as 404 and 500 errors and replaces them with a cleaner view. This also allows you to add custom error pages.

Read more in the Status Codes documentation.

Added Explicitly Imported Providers

Providers are now explicitly imported at the top of the file and added to your PROVIDERS list which is now located in config/providers.py. This completely removes the need for string providers and boosts the performance of the application sustantially

Masonite 2.1

Introduction

Masonite 2.1 introduces a few new changes that are designed to correct course for the 2.x family and ensure we can go far into the 2.x family without having to make huge breaking changes. It was questionable whether we should break from the 2.x family and start a new 3.x line. The biggest question was removing (actually disabling) the ability to resolve parameters and go with the more favorable annotation resolving. That could have made Masonite a 3.x line but we have ultimately decided to go with the 2.1 as a course correction. Below you will find all changes that went into making 2.1 awesome. Nearly all of these changes are breaking changes.

All classes in core now have docstrings

It is much easier to contribute to Masonite now since nearly classes have awesome docstrings explaining what they do, their dependencies and what they return.

Auto Resolving Parameters

We have completely removed parameter resolving. We can no longer resolve like this:

def show(self, Request):
    return Request.redirect('/')

in favor of the more explicit:

from masonite.request import Request

def show(self, request: Request):
    return request.redirect('/')

This is a bit of a big change and will be most of the time spent on refactoring your application to upgrade to Masonite 2.1. If you already used the more explicit version then you won't have to worry about this change. It is still possible to resolve parameters by passing that keyword argument to your container to activate that feature:

container = App(resolve_parameters=True)

This should help with upgrading from 2.0 to 2.1 until you have refactored your application. Then you should deactivate this keyword argument so you can be in line with future 2.x releases.

You can choose to keep it activated if that is how you want to create applications but it won't be officially supported by packages, future releases or in the documentation.

Class Middleware

All middleware are now classes:

HTTP_MIDDLEWARE = [
    LoadUserMiddleware,
    CsrfMiddleware,
    ResponseMiddleware,
]

this is different from the previous string based middleware

HTTP_MIDDLEWARE = [
    'app.http.middleware.LoadUserMiddleware.LoadUserMiddleware',
    'app.http.middleware.CsrfMiddleware.CsrfMiddleware',
    'app.http.middleware.JsonResponseMiddleware.JsonResponseMiddleware',
]

Removed the Payload Input

Previously when getting an incoming JSON response, we had to get the values via the payload input like so:

from masonite.request import Request

def show(self, request: Request):
    return request.input('payload')['id']

which was kind of strange in hindsight. Now we can just straight up use the input:

from masonite.request import Request

def show(self, request: Request):
    return request.input('id')

Again this is only a change for incoming JSON responses. Normal form inputs remain the same.

Removed the facades module.

Previously we had a facades module but it was being unused and we didn't see a future for this module so we moved the only class in this module to it's own class. All instances of:

from masonite.facades.Auth import Auth

now become:

from masonite.auth import Auth

Provider Refactoring

Route Provider

Moved parameter parsing into if statement

We also noticed that for some reason we were parsing parameters before we found routes but we only ever needed those parameters inside our routes so we were parsing them whether we found a route or not. We moved the parsing of parameters into the if statement that executes when a route is found.

When we say "parsing route parameters" we mean the logic required to parse this:

/dashboard/@user/@id

into a usable form to use on the request class this:

from masonite.request import Request

def show(self, request: Request):
    request.param('user')
    request.param('id')

StartResponse Provider

This provider has been completely removed for the more recommended ResponseMiddleware which will need to be added to your HTTP middleware list:

from masonite.middleware import ResponseMiddleware
..
HTTP_MIDDLEWARE=[
    ...
    ResponseMiddleware,
]

Moved parameter parsing into if statement

When we say "parsing route parameters" we mean the logic required to parse this:

/dashboard/@user/@id

into a usable form to use on the request class this:

from masonite.request import Request

def show(self, request: Request):
    request.param('user')
    request.param('id')

StartResponse Provider

This provider has been completely removed for the more recommended ResponseMiddleware which will need to be added to your HTTP middleware list:

from masonite.middleware import ResponseMiddleware
..
HTTP_MIDDLEWARE=[
    ...
    ResponseMiddleware,
]

Moved parameter parsing into if statement

When we say "parsing route parameters" we mean the logic required to parse this:

/dashboard/@user/@id

into a usable form to use on the request class this:

from masonite.request import Request

def show(self, request: Request):
    request.param('user')
    request.param('id')

Added ability use dot notation for views

You can now optionally use . instead of / in your views:

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

Moved the CsrfMiddleware into core and extended it

We moved the CSRF middleware completely into the core framework and allow developers to extend from it now. This will allow us to fix any security bugs that are apart of the CSRF feature.

You may see this pattern a lot in the future which is only extending classes from the core framework so we can hot fix things much better.

Completely cleaned the project

Masonite now has a plethora of docstrings on each and every class by default to really give the developer an understanding about what each default class is actually doing and what it is dependent on.

Masonite is also much more PEP 8 compliant. We removed all instances of triple single quotes: ''' for the more preferred and PEP 8 compliant double quotes """ for docstrings.

We also cleaned a lot of the classes generated by the auth command since those were pretty ugly.

Removed Helper functions by default

We also removed all instances of helper functions by default since it was confusing developers and was throwing red squiggly marks for text editors. They are still available to be used but they will not be known to developers unless they discover them in the documentation. Now all default code explicitly resolves via the container and helper functions can be used on the developers own terms.

Helper functions are still available but you will need to use them on your own terms.

Added seeds by default

Now every application has a basic seeding structure setup which is the same as if running the craft seed command. This is to promote more use of this awesome feature which can be used in migration files for quick seeding of databases for development.

Added code to init.py file in migrations and seeds

We were previously not able to import code into our migration files or database seeders because the command line tool would not pick up our current working directory to import classes into. Now the migrations module and seeds module have 3 lines of code:

import os
import sys
sys.path.append(os.getcwd())

this helpers when running the command line to import code into these modules.

Route Printing

In development you would see a message like:

GET Route: /dashboard

When you hit a route in development mode. Well you would also hit it in production mode too since that was never turned off. Although this is likely fine, it would slow down the framework significantly under load since it takes a bit of resources to print something that didn't need to be printed. This enables a bit of a performance boost.

Added migrate:status Command

This command gets the statuses of all migrations in all directories. To include third party migration directories that are added to your project.

Added `simple` container bindings

Sometimes you do not need to bind an object to any key, you just want the object in the container. For this you can now do simple bindings like this:

app.simple(Obj())

Added a new global mail helper

This new mail helper can be used globally which points to the default mail driver:

def show(self):
    mail_helper().to(..)

Removed the need for `|safe` filters on built in template helpers.

We no longer need to do:

{{ csrf_field|safe }}

We can now simply do:

{{ csrf_field }}

Improved setting status codes

Previously we had to specify the status code as a string:

def show(self, request: Request):
    request.status('500 Internal Server Error')

in order for these to be used properly. Now we can just specify the status code:

def show(self, request: Request):
    request.status(500)

Added several new methods to service providers

There is quite a bit of things to remember when binding various things into the container. For example when binding commands, the key needs to be postfixed with Command like ModelCommand. Now we can do things like:

def register(self):
    self.commands(Command1(), Command2())

Along with this there are several other methods to help you bind things into the container without having to remember all the special rules involved, if any.

Added View Routes

We now have View Routes on all instances of the normal HTTP classes:

Get().view('/url', 'some/template', {'key': 'value'})

Renamed cache_exists to exists

We previously used this method on the Cache class like so:

def show(self, Cache):
    Cache.cache_exists('key')

Now we removed the cache_ prefix and it is just:

from masonite import Cache

def show(self, cache: Cache):
    cache.exists('key')

Added without method to request class

We can now use the .without() method on the request class which returns all inputs except the ones specified:

def show(self, request: Request):
    request.without('key1', 'key2')

Added port to database

Previously the port was missing from the database configuration settings. This was fine when using the default connection but did not work unless added to the config.

Added ability to use a dictionary for setting headers.

Instead of doing something like:

def show(self, request: Request):
    request.header('key1', 'value1')
    request.header('key2', 'value2')

We can now use a dictionary:

def show(self, request: Request):
    request.header({
        'key1': 'value1',
        'key2': 'value2'
    })

Added a new Match route

We can now specify a route with multiple HTTP methods. This can be done like so:

from masonite.routes import Match

Match(['GET', 'POST']).route('/url', 'SomeController@show')

Added Masonite Events into core

Core can now emit events that can be listened to through the container.

Added ability to set email verification

Now you can setup a way to send email verifications into your user signup workflow simply but inherting a class to your User model.

Request redirection set status codes

Now all redirections set the status code implicitly instead of explicitly needing to set them.

Added craft middleware command

Now you can use craft middleware MiddlewareName in order to scaffold middleware like other classes.

View can use dot notation

All views can optionally use dot notation instead of foward slashes:

return view.render('some/template/here')

is the same as:

return view.render('some.template.here')

Added Swap to container

We can now do container swapping which is swapping out a class when it is resolved. In other words we may want to change what objects are returned when certain objects are resolved. These objects do not have to be in the container in the first place.

Added a new env function

You can now use a env function to automatically type cast your environment variables turning a numeric into an int:

from masonite import env

env('DB_PORT', '5432') #== 5432 (int)

Added ability to resolve with paramaters at the same time

You can now resolve from a container with a parameter list in addition to custom parameters.

Added password reset to auth command

In addition to all the awesome things that craft auth generates, we now generate password reset views and controllers as well for you

Route Compiler

Fixed an issue where custom route compilers was not working well with request parameters

Added Database Seeders

All new 2.1 projects have a seeder setup so you can quickly make some mock users to start off your application. All users have a randomly generated email and the password of "secret".

You can run seeders by running:

$ craft seed:run

Made HTTP Prefix to None by Default

When setting headers we had to set the http_prefix to None more times then not. So it is set by default.

This:

def show(self, request: Request):
    request.header('Content-Type', 'application/xml', http_prefix=None)

can change to:

def show(self, request: Request):
    request.header('Content-Type', 'application/xml')

Getting a header returns blank string rather than None

Originally the code:

def show(self, request: Request):
    request.header('Content-Type') #== ''

would return None if there was no header. Now this returns a blank string.

Added Maintenance Mode

There is now an up and down command so you can put that in your application in a maintenance state via craft commands:

$ craft down

$ craft up

There is also a new MaintenanceModeMiddleware:

from masonite.middleware import MaintenanceModeMiddleware

HTTP_MIDDLEWARE = [
    ...
    MaintenanceModeMiddleware,
    ...
]

Removed Store Prepend method

We removed the store_prepend() method on the upload drivers for the filename keyword arg on the store method.

So this:

upload.store_prepend('random-string', request.input('file'))

now becomes:

upload.store(request.input('file'), filename='random-string')

Masonite 2.2

Route Prefixes

Previously you had to append all routes with a / character. This would look something like:

You can now optionally prefix this without a / character:

URL parameters can now optionally be retrieved from the controller definition

Previously we had to do something like:

Now we can optionally get the parameter from the method definition:

Added a storage manager and disk storage drivers

This is used as a wrapper around I/O operations. It will also be a wrapper around the upload drivers and moving files around and other file management type operations

Async driver now can be specified whether to use threading or processing

We can now specify directly in the configuration file whether or not the threading or multiprocessing for the async type operations.

Added new HTTP Verbs

We added 4 new HTTP verbs: HEAD, CONNECT, OPTIONS, TRACE. You import these and use them like normal:

JSON error responses

If the incoming request is a JSON request, Masonite will now return all errors as JSON

Rearranged Drivers into their own folders

This is more of an internal change for Core itself.

Craft serve command defaults to auto-reloading

Before we had to specify that we wanted the server to auto-reload by specifying a -r flag:

Now we can just specify the serve command it will default to auto-reloading:

You can now specify it to NOT auto-reload by passing in 1 of these 2 commands:

Added Accept('*') to drivers

By default you can only upload image files because of security reasons but now you can disable that by doing an accept('*') option:

Added much more view helpers

All Tests are now unittests

We moved from pytest to unittests for test structures.

Added a better way to run database tests

Added a new DatabaseTestcase so we can properly setup and teardown our database. This works for sqlite databases by default to prevent your actual database from being destroyed.

The back view helper now defaults to the current path

Before in templates we had to specify a path to go back to but most of the time we wanted to go back to the current path.

Instead of:

We can now do:

Added a completely new validation library

We built a new validation library from scratch and completely ripped out the old validation code. Any current validation code will need to be updated to the new way.

Auth class does not need the request class.

Previously we needed to pass in the request object to the Auth class like this:

Now we have it a bit cleaner and you can just resolve it and the request class will be injected for you

Completely changed how classes are resolved on the backend

You may not notice anything but now if you bind a class into the container like this:

It will be resolved when you resolve it:

This is why the Auth class no longer needs to accept the request class. Masonite will inject the request class for you when you resolve the class.

This works with all classes and even your custom classes to help manage your application dependencies

Added new register method to the `Auth` class.

You can now do something like:

Changed all regex compiling to be done before the server starts

Previously, each route's regex was being compiled when Masonite checked for it but we realized this was redundant. So now all route compiling is done before the server starts.

This has given Masonite a bit of a speed boost.

Container Remembering

Masonite now has the ability to remember the previous container bindings for each object. This can speed of resolving your code by 10-15x. This is disabled by default as it is still not clear what kind of issues this can cause.

This is scheduled to be set by default in the next major version of Masonite

Added a new `with_errors()` method in order to cut down on setting an errors session.

Now instead of doing this:

we can now shorten down the flashing of errors and do:

Upgrade Guide

Masonite 1.3 to 1.4

Introduction

Masonite 1.4 brings several new features and a few new files. This is a very simple upgrade and most of the changes were done in the pip package of Masonite. The upgrade from 1.3 to 1.4 should take less than 10 minutes

Requirements.txt File

This requirement file has the masonite>=1.3,<=1.3.99 requirement. This should be changed to masonite>=1.4,<=1.4.99. You should also run pip install --upgrade -r requirements.txt to upgrade the Masonite pip package.

New Cache Folder

There is now a new cache folder under bootstrap/cache which will be used to store any cached files you use with the caching feature. Simply create a new bootstrap/cache folder and optionally put a .gitignore file in it so your source control will pick it up.

New Cache and Broadcast Configuration

3 New Service Providers

Masonite comes with a lot of out of the box functionality and nearly all of it is optional but Masonite 1.4 ships with three new providers. Most Service Providers are not ran on every request and therefore does not add significant overhead to each request. To add these 3 new Service Providers simple add these to the bottom of the list of framework providers:

Note however that if you add the CsrfProvider then you will also need the CSRF middleware which is new in Masonite 1.4. Read the section below to add the middleware

CSRF and CSRF Middleware

Masonite 1.4 adds CSRF protection. So anywhere there is any POST form request, you will need to add the {{ csrf_field }} to it. For example:

Lastly, put that middleware into the HTTP_MIDDLEWARE list inside config/middleware.py like so:

Changes to Database Configuration

should now be:

with this change

Masonite 1.4 to 1.5

Introduction

Masonite 1.5 doesn't bring many file changes to Masonite so this upgrade is fairly straight forward and should take less than 10 minutes.

Requirements.txt

All requirements are now gone with the exception of the WSGI server (waitress) and the Masonite dependency. You should remove all dependencies and only put:

Site Packages Configuration

If you have added your site packages directory to our packages configuration file, you can now remove this because Craft commands can now detect your site packages directory in your virtual environment.

Api Removal

Remove the masonite.providers.ApiProvider.ApiProvider from the PROVIDERS list as this has been removed completely in 1.5

You'll also have to add a new RESOURCES = [] line to your routes/api.py file for the new Masonite Entry package if you choose to use it.

Craft Commands

This release works with the new craft command release. Upgrade to version masonite-cli / 1.1+. <1.1 will only work with Masonite 1.4 and below.

Simply run:

You may have to run sudo if you are using a UNIX machine.

Sessions

Masonite 1.5 now has sessions that can be used to hold temporary data. It comes with the cookie and memory drivers. Memory stores all data in a class which is lost when the server restarts and the cookie driver sets cookies in the browser.

There is a new config/session.py file you can copy and paste:

As well as add the SessionProvider inside your PROVIDERS list just below the AppProvider:

Finished

That's it! You have officially upgrades to Masonite 1.5

Masonite 1.5 to 1.6

Introduction

Not much has changed in the actual project structure of Masonite 1.6 so we just need to make some minor changes to our existing 1.5 project

Requirements.txt

We just have to change our Masonite dependency version in this file:

Bootstrap/start.py

Masonite 1.6 now wraps the majority of the application in a try and catch block so we can add exception handling such as the new debug view and other exception features down the road such as Sentry and other error logging.

In the middle of the file (line 45 if you have not made changes to this file) we can simply wrap the application:

This will also display an exception view whenever an exception is it.

Finished

That's all the changes we have to make for our project.

Masonite 1.6 to 2.0

Upgrading from Masonite 1.6 to Masonite 2.0 shouldn't take very long although it does have the largest amount of changes in a single release. On an average sized project, this upgrade should take around 30 minutes. We'll walk you through the changes you have to make to your current project and explain the reasoning behind it

Application and Provider Configuration

Masonite 2 adds some improvements with imports. Previously we had to import providers and drivers like:

Masonite 2 brings a more explicit way of declaring Service Providers in your application. You'll need to take your current PROVIDERS list inside the config/application.py file and move it into a new config/providers.py file.

Now all Service Providers should be imported at top of the file and added to the list:

String providers will still work but it is not recommended and will not be supported in current and future releases of Masonite.

WSGI changes

There are a few changes in the wsgi.py file and the bootstrap/start.py file.

In the wsgi.py file we should add a new import at the top:

Then change the code logic of bootstrapping service providers from:

to:

and change the logic in bootstrap/start.py to:

Notice here we split the providers list when the server first boots up into two lists which significantly lowers the overhead of each request.

This change should significantly boost speed performances as providers no longer have to be located via pydoc. You should see an immediate decrease in the time it takes for the application to serve a request. Rough time estimates say that this change should increase the request times by about 5x as fast.

Duplicate Class Names

Again, with the addition of the above change, any place you have a duplicated class name like:

You can change it to:

Redirection

Renamed Request.redirectTo to Request.redirect_to. Be sure to change any of these instances accordingly.

All instances of:

should be changed to:

Redirect Send Method

Also removed the .send() method completely on the Request class so all instances of:

Need to be changed to:

CSRF Middleware

Some variable internals have changed to prepend a double underscore to them to better symbolize they are being handled internally. Because of this we need to change any instances of csrf_token to __token in the CSRF Middleware file.

Autoloading

Simply add a new AUTOLOAD constant in your config/application.py file. This is the entire section of the autoload configuration.

By default this points to the app directory where models are stored by default but if you moved your models to other directories like app/models or app/admin/models then add those directories to your list:

RedirectionProvider

Because of a minor rewrite of the Request class, we now do not need the RedirectionProvider. You can remove the RedirectionProvider completely in your PROVIDERS list.

StatusCodeProvider

There is a new status code provider which adds support for adding custom status codes and rendering better default status code pages such as 400 and 500 error pages. This should be added right above the StartResponseProvider:

.env File

The .env got a small upgrade and in order to make the APP_DEBUG variable consistent, it should be set to either True or False. Previously this was set to something like true or false.

Masonite 2 also removed the APP_LOG_LEVEL environment variable completely.

Finished

That's it! You're all done upgrading Masonite 1.6 to Masonite 2.0. Build something awesome!

Masonite 2.0 to 2.1

Introduction

Masonite 2.1 is a fantastic release. It works out a lot of the kinks that were in 2.0 as well as brings several new syntactically good looking code generation

Masonite CLI

For 2.1 you will need masonite-cli>=2.1.0.

Make sure you run:

Middleware

Middleware has been changed to classes so instead of doing this in your config/middleware.py file:

You will now import it directly:

Auto resolving parameters has been removed

This is likely the biggest change in 2.0. Before 2.1 you were able to fetch by key when resolving by doing something like:

We have removed this by default and now you much explicitly import your classes in order to interact with the container resolving:

If you truly do not like this change you can modify your container on a per project basis by adding this to your container constructor in wsgi.py:

Just know this is not recommended and Masonite may or may not remove this feature entirely at some point in the future.

Resolving Mail, Queues and Broadcasts

Previously we were able to do something like this:

Since we never actually created a class from this and you were not able to explicitly resolve this, we utilized the new container swapping in order to swap a class out for this container binding.

All instances above should be changed to:

Don't forgot to also do your boot methods on your Service Providers as well:

As well as all your middleware and custom code:

Resolving your own code

You may have classes you binded personally to the container like this:

To get this in line for 2.1 you will need to use Container Swapping in order to be able to resolve this. This is actually an awesome feature.

First go to your provider where you binded it to the container:

and add a container swap right below it by swapping it with a class:

now you can use that class to resolve:

Removed Masonite Facades

Completely removed the masonite.facades module and put the only class (the Auth class) in the masonite.auth module.

So all instances of:

need to be changed to:

Removed the StartResponseProvider

The StartResponseProvider was not doing anything crazy and it could be achieved with a simple middleware. This speeds up Masonite slightly by offsetting where the response preparing takes place.

Simply remove the StartResponseProvider from your PROVIDERS list:

As well as put the new middleware in the HTTP middleware

JSON Payloads

In 2.0 you had to fetch incoming JSON payloads like this:

So now all instances of the above can be used normally:

Moved CSRF Middleware into core

CSRF middleware now lives in core and allows you to override some methods or interact with the middleware with class attributes:

Replace your current CSRF Middleware with this new one:

If you made changes to the middleware to prevent middleware from being ran on every request you can now set that as a class attribute:

This also allows any security issues found with CSRF to be handled on all projects quickly instead of everyone having to patch their applications individually.

Added cwd imports to migrations and seeds

In migrations (and seeds) you will need to put this import inside a __init__.py file in order to allow models to be imported into them

Bootstrap File

There was a slight change in the bootstrap/start.py file around line 60.

This line:

Needs to be changed to:

Response Binding

You no longer should bind directly to the Response key in the container. You should use the new Response object.

All instances of:

should now be:

and any instance of:

should be changed to:

Restructuring some sample code would be changing this:

to this:

Cache Exists name change

The Cache.cache_exists() has been changed to just Cache.exists(). You will need to make changes accordingly:

Environment Variables

Although not a critical upgrade, it would be a good idea to replace all instances of retrieval of environment variables with the new masonite.env function.

Change all instances of this:

with the new env function:

What this will do is actually type cast accordingly. If you pass a numeric value it will cast it to an int and if you want a boolean if will cast True, true, False, false to booleans like this:

if you don't want to cast the value you can set the cast parameter to False

Removed Store Prepend method

We removed the store_prepend() method on the upload drivers for the filename keyword arg on the store method.

So this:

now becomes:

Masonite 2.1 to 2.2

Introduction

Welcome to the upgrade guide to get your Masonite 2.1 application working with Masonite 2.2. We'll be focusing on all the breaking changes so we can get all your code working on a Masonite 2.2 release cycle.

Masonite 2.2 is jam packed with amazing new features and most of which are backwards compatible so upgrading from Masonite 2.1 to 2.2 is really simple.

We'll go through each section that your application will need to be upgraded and how it can be done.

Each upgrade will have an impact rating from LOW to HIGH. The lower the rating, the less likely it will be that your specific application needs the upgrade.

Getting Started

First let's upgrade Masonite to 2.2 first so we can see any exceptions that will be raised.

Let's upgrade by doing:

You can also add it to your requirements.txt or Pipfile.

Removing route helpers

Impact: MEDIUM

In Masonite 2.1, route helpers were deprecated and you likely started receiving deprecation warnings. In Masonite 2.2, these were removed. You may have had routes that looks like this:

You will now need to remove all these and use the class based ones. To make this easier we can just import the get and post helpers and alias them like this:

Changed Validation

Impact: MEDIUM

Masonite 2.2 completely removes the validation library that shipped with Masonite in favor of a brand new one that was built specifically for Masonite.

Validation Provider

You'll need to add a new validation provider if you want your application to have the new validation features.

Add it by importing it into config/providers.py and add it to your PROVIDERS list:

Replacing Validation Code

Masonite 2.2 completely removed the validation package from 2.1 and created an even better all new validation package. You'll have to remove all your validation classes and use the new validation package.

For example you may have had a validation class that looked like this:

and used it inside your views like this:

This is now completely changed to use a better and more sleeker validation. The above validation can now be written like this:

Auth class now auto resolves it's own request class

Masonite 2.2 changes a bit how the masonite.auth.Auth class resolves out of the container and how it resolves its own dependencies.

Now instead of doing something like:

You'll need to move this into the parameter list so it can be resolved:

There should be quite a bit of these in your application if you have used this class or you have used the built in craft auth scaffold command.

Resolving Classes

Impact: MEDIUM

The behavior for resolving classes has now been changed. If you bind a class into the container like this:

It previously would have resolved and gave back the class:

This will now resolve from the container when you resolve it as a parameter list. This means that you will never get back a class inside places like controllers.

Now the above code would look something like this:

notice it now returns an object. This is because Masonite will check before it resolves the class if the class itself needs to be resolved (if it is a class). If SomeClass requires the request object, it will be passed automatically when you resolve it.

Testing

Masonite 2.2 focused a lot on new testing aspects of Masonite and has some big rewrites of the package internally.

UnitTest class

The UnitTest class has been completely removed in favor of the new masonite.testing.TestCase method.

An import that looked like this:

Should now look like this:

Pytest VS Unittest

All classes have now been changed to unittest classes. This will still work with pytest and you can still run python -m pytest. The only thing that changes is the structure of the setup_method(). This has been renamed to setUp().

A class like this:

Should now look like this:

Method naming

Previously all methods were snake_case but to continue with the unittest convention, all testing methods are camelCase.

A method like:

Now becomes:

Again this is to prevent developers from needing to switch between snake_case and camelCase when using Masonite methods and unittest methods.

Route method

The route method that looked something like this:

Has now been replaced with the method name of the route. So to get a GET route you would do:

or a POST route:

So be sure to update all methods of self.route() with the correct request methods.

Loading Routes

In 2.1 you had to manually load your routes in like this:

this is no longer required and routes will be found automatically. There is no longer a self.routes() method.

JSON method

The JSON method signature has changed and you now should specify the request method as the first parameter.

A previous call that looked like this:

should become:

User

Previously you logged a user in by using the user method but now you can using the actingAs method before you call the route:

A method like this:

Should now be:

The Basics

Controllers

Introduction

Controllers are a vital part of Masonite and is mainly what differs it from other Python frameworks which all implement the MVC structure differently. Controllers are simply classes with methods. These methods take a self parameter which is the normal self that Python methods require. Controller methods can be looked at as "function based views" if you are coming from Django as they are simply methods inside a class and work in similar ways.

Controllers have an added benefit over straight function based views as the developer has access to a full class they can manipulate however they want. In other words, controller methods may utilize class attributes, private methods and class constructors to break up and abstract logic. They provide a lot of flexibility.

Creating a Controller

Its very easy to create a controller with Masonite with the help of our craft command tool. We can simply create a new file inside app/http/controllers, name the class the same name as the file and then create a class with methods. We can also use the craft controller command to do all of that for us which is:

When we run this command we now have a new class in app/http/controllers/DashboardController.py called DashboardController. By convention, Masonite expects that all controllers have their own file since it’s an extremely easy way to keep track of all your classes since the class name is the same name as the file. This is very opionated but you can obviously put this class wherever you like.

Notice that we passed in Dashboard but created a DashboardController. Masonite will always assume you want to append Controller to the end.

Exact Controllers

Remember that Masonite will automatically append Controller to the end of all controllers. If you want to create the exact name of the controller then you can pass a -e or --exact flag.

This will create a Dashboard controller located in app/http/controllers/Dashboard.py

Resource Controllers

Resource controllers are controllers that have basic CRUD / resource style methods to them such as create, update, show, store etc. We can create a resource controller by running:

this will create a controller that looks like:

Defining a Controller Method

Controller methods are very similar to function based views in a Django application. Our controller methods at a minimum should look like:

If you are new to Python, all controller methods must have the self parameter. The self parameter is the normal python self object which is just an instance of the current class as usual. Nothing special here.

Container Resolving

All controller methods and constructors are resolved by the container so you may also retrieve additional objects from the container by specifying them as a parameter in the method:

or by specifying them in the constructor:

If you need a class in multiple controller methods then it is recommended to put it into the constructor in order to keep the controller DRY.

It’s important to note that unlike other frameworks, we do not have to specify our route parameters as parameters in our controller method. We can retrieve the parameters using the request.param('key') class method.

Returning JSON

You can return JSON in a few different ways. The first way is returning a dictionary which will then be parsed to JSON:

you may return a list:

Or you may even return a model instance or collection. Take these 2 code snippets as an example:

Returning a paginated response directly will include the collection data, along with results metadata.

Query parameters accepted are: 'page_size' and 'page'. These will be handled directly as part of the response, there is no need to pass them in explicitly.

Orator classes LengthAwarePaginator and Paginator will return slightly different responses.

LengthAwarePaginator:

returns:

Paginator:

returns:

Passing Route Parameters

Optionally you can pass route parameters along with your resolving code. This is useful to keep a nice clean codebase.

For example, these two code snippets are the same:

And this:

You can specify parameters along with any other container resolving.

Helper Functions

Built in global helper functions were removed by default in v2.1 though they are not deprecated and you can use them as you wish.

Introduction

Masonite works on getting rid of all those mundane tasks that developers either dread writing or dread writing over and over again. Because of this, Masonite has several helper functions that allows you to quickly write the code you want to write without worrying about imports or retrieving things from the Service Container. Many things inside the Service Container are simply retrieved using several functions that Masonite sets as builtin functions which we call "Built in Helper Functions" which you may see them referred to as.

These functions do not require any imports and are simply just available which is similiar to the print() function. These functions are all set inside the HelpersProvider Service Provider.

You can continue to use these helper functions as much as you like but most developers use these to quickly mock things up and then come back to refactor later.

It may make more sense if we take a peak at this Service Provider:

masonite.providers.HelpersProvider

class HelpersProvider(ServiceProvider):

    wsgi = False

    def register(self):
        pass

    def boot(self, view: View, request: Request):
        ''' Add helper functions to Masonite '''
        builtins.view = view.render
        builtins.request = request.helper
        builtins.auth = request.user
        builtins.container = self.app.helper
        builtins.env = os.getenv
        builtins.resolve = self.app.resolve

        view.share({'request': request.helper, 'auth': request.user})

Notice how we simply just add builtin functions via this provider.

Built In Helpers

The below list of helpers are "builtin" helpers meaning they are global in the same way that the print method is global. These helpers can be used without any imports.

Request

The Request class has a simple request() helper function.

def show(self):
    request().input('id')

is exactly the same as:

def show(self, request: Request):
    request.input('id')

Notice we didn't import anything at the top of the file, nor did we inject anything from the Service Container.

View

The view() function is just a shortcut to the View class.

def show(self):
    return view('template_name')

is exactly the same as:

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

Mail

Instead of resolving the mail class you can use the mail helper:

def show(self):
    mail_helper().to(..)

is exactly the same as:

from masonite import Mail

def show(self, mail: Mail):
    mail.to(..)

Auth

The auth() function is a shortcut around getting the current user. We can retrieve the user like so:

def show(self):
    auth().id

is exactly the same as:

def show(self, request: Request):
    request.user().id

This will return None if there is no user so in a real world application this may look something like:

def show(self):
    if auth():
        auth().id

This is because you can't call the .id attribute on None

Container

We can get the container by using the container() function

def show(self):
    container().make('User')

is exactly the same as:

def show(self, request: Request):
    request.app().make('User')

Env

We may need to get some environment variables inside our controller or other parts of our application. For this we can use the env() function.

def show(self):
    env('S3_SECRET', 'default')

is exactly the same as:

import os

def show(self):
    os.environ.get('S3_SECRET', 'default')

Resolve

We can resolve anything from the container by using this resolve() function.

def some_function(request: Request):
    print(request)

def show(self):
    resolve(some_function)

is exactly the same as:

def some_function(request: Request):
    print(request)

def show(self, request: Request):
    request.app().resolve(some_function)

That's it! These are simply just functions that are added to Python's builtin functions.

Die and Dump

Die and dump is a common way to debug objects in PHP and other programming languages. Laravel has the concept of dd() which dies and dumps the object you need to inspect.

dd() is essentially adding a break point in your code which dumps the properties of an object to your browser.

For example we can die and dump the user we find:

from app.User import User

def show(self):
    dd(User.find(7))

If we then go to the browser and visit this URL as normal then we can now see the object fully inspected which will kill the script wherever it is in place and throw an exception but instead of showing the normal debugger it will use a custom exception handler and show the inspection of the object instead:

Non Built In Helpers

There are several helper methods that require you to import them in order to use them. These helpers are not global like the previous helpers.

Config

The config helper is used to get values in the config directory. For example in order to get the location in the config/storage.py file for example.

This function can be used to retrieve values from any configuration file but we will use the config/storage.py file as an example.

With a config/storage.py file like this:

config/storage.py

DRIVERS = {
    's3': {
        'client': 'Hgd8s...'
        'secret': 'J8shk...'
        'location': {
            'west': 'http://west.amazon.com/..'
            'east': 'http://east.amazon.com/..'            
        }
    }
}

We can get the value of the west key in the location inner dictionary like so:

from masonite.helpers import config

def show(self):
    west = config('storage.drivers.s3.location.west')

Instead of importing the dictionary itself:

from config import storage

def show(self):
    west = storage.DRIVERS['s3']['location']['west']

Note the use of the lowercase storage.drivers.s3 instead of storage.DRIVERS.s3. Either or would work because the config function is uppercase and lowercase insensitive.

Optional

This helper that allows you to wrap any object in this helper and call attributes or methods on it even if they don't exist. If they exist then it will return the method, if it doesn't exist it will return None.

Take this example where we would normally write:

def show(self):
    user = User.find(1)
    if user and user.id == 5:
        # do code
        ...

We can now use this code snippet instead:

def show(self):
    if optional(User.find(1)).id == 5:
        # do code
        ...

Compact

Compact is a really nice helper that allows you to stop making those really repetitive dictionary statements in your controller methods

take this for example:

def show(self, view: View):
    posts = Post.all()
    users = User.all()
    articles = Articles.all()
    return view.render('some.template', {'posts': posts, 'users': users, 'articles': articles})

Notice how our Python variables are exactly the same as what we want our variables to be in our template.

With the compact function, now you can do:

from masonite.helpers import compact

def show(self, view: View):
    posts = Post.all()
    users = User.all()
    articles = Articles.all()
    return view.render('some.template', compact(posts, users, articles))

You can also pass in a dictionary which will update accordingly:

from masonite.helpers import compact

def show(self, view: View):
    posts = Post.all()
    users = User.all()
    user_blogs = Blog.where('user_id', 1).get()
    return view.render('some.template', compact(posts, users, {'blogs': user_blogs}))

Collect

You can use the same Collection class that orator uses when returning model collections. This can be used like so:

from masonite.helpers import collect

def show(self):
    collection = collect([1,2,3])

    if collection.first() == 1:
        # do action

You have access to all the methods on a normal collection object.

Requests

Learn more by reading the Validation documentation.

Requests

Introduction

The Request class is initialized when the server first starts and is modified on every request. This means that the Request class acts as a singleton and is not reinitialized on every request. This presents both pros and cons during developing Masonite. It's great to not have to worry about a new object being instantiated every time but the con is that some attributes need to be reset at the end of the request.

The Request class is loaded into the IOC container first so any Service Provider will have access to it. The IOC container allows all parts of the framework to be resolved by the IOC container and auto inject any dependencies they need.

Read more about the IOC container in the Service Container documentation.

Getting Started

The Request class is bound into the IOC container once when the server is first started. This takes the WSGI environment variables generated by your WSGI server as a parameter. Because of this, we reload the WSGI values on every request but the actual Request object does not change. In other words, the memory address of the Request object is always the same but the class attributes will change of every request. This is done already for you by the Masonite framework itself. This Request class is bound and initialized inside the AppProvider Service Provider. We grab this request object by simply passing in Request into the parameters of anything resolved by the Service Container such as middleware, drivers and controller methods like so:

def show(self, request: Request):
    request #== <masonite.request.Request>

Masonite is smart enough to know that we need the Request class and it will inject it into our method for us.

Helper Function

Masonite ships with a HelpersProvider Service Provider which adds several helper functions. One of these helper functions is the request() function. This function will return the request object. Because of this, these two pieces of code are identical:

def show(self, request: Request):
    request.input('username')

def show(self):
    request().input('username')

Notice we didn't import anything at the top of our file and also didn't retrieve any objects from the IOC container. Masonite helper functions act just like any other built in Python function.

Read more about helper functions in the Helper Functions documentation.

Usage

The Request has several helper methods attached to it in order to interact with various aspects of the request.

In order to get the current request input variables such as the form data during a POST request or the query string during a GET request looks like:

def show(self, request: Request):
    request.input('username')

There is no difference between any HTTP methods (GET, POST, PUT, etc) when it comes to getting input data. They are all retrieved through this .input() method so there is no need to make a distinction if the request is GET or POST

Method Options

Input Data

We can get all the request input variables such as input data from a form request or GET data from a query string. Note that it does not matter what HTTP method you are using, the input method will know what input data to get dependent on the current HTTP method (GET, POST, PUT, etc)

This will return all the available request input variables for that request as a dictionary.

# GET: /dashboard?user=Joe&status=1

def show(self, request: Request):
    return request.all() # {'user': 'Joe', 'status': '1'}

This method will get all of the request input variables to include any internal framework variables completely handled internally such as __token and __method. You can exclude them by passing in False into the method or specifying it explicitly:

# GET: /dashboard?user=Joe&status=1&__token=837674634

def show(self, request: Request):
    return request.all(internal_variables=False) # {'user': 'Joe', 'status': '1'}

To get a specific input:

# GET: /dashboard?firstname=Joe

def show(self, request: Request):
    return request.input('firstname') # Joe

Input Cleaning

Input data will be cleaned of HTML tags and other security measures. This may cause unwanted return values if you are expecting something like a JSON string. If you want to opt to not clean the input you can specify that as a keyword argument:

request.input('firstname', clean=False) # Joe

To check if some request input data exists:

# GET: /dashboard?firstname=Joe

def show(self, request: Request):
    return request.has('firstname') # True

Getting Dictionary Input

If your input is a dictionary you have two choices how you want to access the dictionary. You can either access it normally:

request.input('payload')['user']['address'] # 123 Smith Rd

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

request.input('payload.user.address') # 123 Smith Rd

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

"""
Payload: 
"user": {
    "id": 1,
    "addresses": [
        {"id": 1, 'street': "A Street"},
        {"id": 2, 'street': "B Street"}
    ] 
}
"""

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

Only

You can only get a certain set of parameters if you have a need to do so. This can be used like:

# GET: /dashboard?firstname=Joe&lastname=Mancuso&active=1

def show(self, request: Request):
    return request.only('firstname', 'active') # {'firstname': 'Joe', 'active': '1'}

Without

We can specify a set of parameters to exclude from the inputs returned. For example:

# GET: /dashboard?firstname=Joe&lastname=Mancuso&active=1

def show(self, request: Request):
    return request.without('lastname') # {'firstname': 'Joe', 'active': '1'}

Notice it returned everything besides lastname.

URL Parameters

To get the request parameter retrieved from the url. This is used to get variables inside: /dashboard/@firstname for example.

# Route: /dashboard/@firstname
# GET: /dashboard/Joe

def show(self, request: Request):
    return request.param('firstname') # Joe

JSON Payloads

Sometimes you may want to handle incoming JSON requests. This could be form external API's like Github.

Masonite will detect that an incoming request is a JSON request and put the cast the JSON to a dictionary and load it into the payload request input. For example if you have an incoming request of:

{
    "name": "Joe",
    "email": "Joe@email.com"
}

Then we can fetch this input in a controller using the normal input() method like so:

def show(self, request: Request):
    request.input('name') # Joe

Cookies

You may also set a cookie in the browser. The below code will set a cookie named key to the value of value.

By default, all cookies are encrypted with your secret key which is generated in your .env file when you installed Masonite. This is a security measure to ensure malicious Javascript code cannot fetch cookies if they are somehow retrieved. All cookies are set with the HTTP_ONLY flag meaning that Javascript cannot read them although you can turn this off using a parameter.

Creating

def show(self, request: Request):
    return request.cookie('key', 'value')

Not Encrypting

If you choose to not encrypt your values and create cookies with the plain text value then you can pass a third value of True or False. You can also be more explicit if you like:

def show(self, request: Request):
    return request.cookie('key', 'value', encrypt=False)

Expirations

All cookies are set as session cookies. This means that when the user closes out the browser completely, all cookies will be deleted.

def show(self, request: Request):
    return request.cookie('key', 'value', expires="5 minutes")

This will set a cookie thats expires 5 minutes from the current time.

HttpOnly

Again, as a security measure, all cookies automatically are set with the HttpOnly flag which makes it unavailable to any Javascript code. You can turn this off:

def show(self, request: Request):
    return request.cookie('key', 'value', http_only=False)

This will now allow Javascript to read the cookie.

Reading

You can get all the cookies set from the browser

def show(self, request: Request):
    return request.get_cookies()

You can get a specific cookie set from the browser

def show(self, request: Request):
    return request.get_cookie('key')

Again, all cookies are encrypted by default so if you set a cookie with encryption then this method will decrypt the cookie. If you set a cookie in plain text then you should pass the False as the second parameter here to tell Masonite not to decrypt your plain text cookie value.:

def show(self, request: Request):
    return request.get_cookie('key', decrypt=False)

This will return the plain text version of the cookie.

If Masonite attempts to decrypt a cookie but cannot then Masonite will assume that the secret key that encrypted it was changed or the cookie has been tampered with and will delete the cookie completely.

If your secret key has been compromised then you may change the key at anytime and all cookies set on your server will be removed.

Deleting

You may also delete a cookie. This will remove it from the browser.

def show(self, request: Request):
    return request.delete_cookie('key')

User

You can also get the current user from the request. This requires the LoadUserMiddleware middleware which is in Masonite by default. This will return an instance of the current user.

def show(self, request: Request):
    return request.user()

Routes

You can also get a route URL via the route name. Let's say we have a route like this:

Get('/dashboard').name('dashboard')

We can get the URL from the route name like so:

def show(self):
    request().route('dashboard') # /dashboard

Route Parsing

if we have route parameters like this:

Get('/dashboard/@user').name('dashboard.user')

then we can pass in a dictionary:

def show(self, request: Request):
    request.route('dashboard.user', {'user': 1}) # /dashboard/1

You may also pass a list if that makes more sense to you:

def show(self, request: Request):
    request.route('dashboard.user', [1]) # /dashboard/1

This will inject that value for each parameter in order. For example if we have this route:

Get('/dashboard/@user/@id/@slug').name('dashboard.user')

then we can use:

def show(self, request: Request):
    request.route('dashboard.user', [1, 2, 'some-slug']) 
    # /dashboard/1/2/some-slug

Contains

We can also check if a route contains a specific pattern:

# GET /dashboard/user/1
def show(self, request: Request):
    request.contains('/dashboard/*/1') #== True

You can also use this in a template and pass in a show parameter to return a string instead. This is useful if you want to show active status classes depending on the current route:

<a href=".." class="{{ request().contains('/dashboard/*/edit', show='active')">
<a href=".." class="{{ request().contains('/dashboard/*/create', show='active')">

Current URL

We can get the current url with:

def show(self, request: Request):
    return request.path #== /dashboard/user

Redirection

You can specify a url to redirect to

def show(self, request: Request):
    return request.redirect('/home')

If the url contains http than the route will redirect to the external website

def show(self, request: Request):
    return request.redirect('http://google.com')

You can redirect to a named route

def show(self, request: Request):
    return request.redirect_to('dashboard')

You can also use the name parameter on the redirect method:

def show(self, request: Request):
    return request.redirect(name="dashboard")

You can also redirect to a specific controller. This will find the URL that is attached to the controller method

def show(self, request: Request):
    return request.redirect(controller="WelcomeController@show")

Sometimes your routes may require parameters passed to it such as redirecting to a route that has a url like: /url/@firstname:string/@lastname:string.

Redirecting to a named route with URL parameters:

def show(self, request: Request):
    return request.redirect_to('dashboard', {'firstname': 'Joseph', 'lastname': 'Mancuso'})

Redirecting to a url in your application with URL parameters:

def show(self, request: Request):
    return request.redirect('dashboard/@id', {'id': '1'})

Redirecting Back

There will be plenty of times you will need to redirect back to where the user came just came from. In order for this work we will need to specify where we need to go back to. We can use the back method for this.

Form Back Redirection

Masonite will check for a __back input and redirect to that route. We can specify one using the back() view helper function:

<form action="{{ route('dashboard.create') }}" method="POST">
    {{ csrf_field }}
    {{ back() }}
</form>

By default the back helper will return the current path so you can easily go back to the previous page after the form is submitted.

You can also specify a path to go back to:

<form action="{{ route('dashboard.create') }}" method="POST">
    {{ csrf_field }}
    {{ back('/another/path') }}
</form>

Redirecting Back

After submitting the form you can redirect back to wherever the back template method was pointing to using the back() method:

def show(self, request: Request):
    ...
    return request.back()

This will also flash the current inputs to the session. You can then get the inputs using the {{ old('key') }} template helper:

<form>
  <input type="text" name="email" value="{{ old ('email') }}">
  ...
</form>

Redirecting Back With Errors

You can redirect back with validation error message or redirect back with input value:

def show(self, request: Request):
    errors = request.validate(
        required(['email', 'password'])
    )

    if errors:
        return request.back().with_errors(errors)

Redirecting Back With Inputs

When redirecting back there are times where you will also want to flash the inputs to the session. With this you can simply use the back() method but if you want a bit more control you can use the with_input() method.

def show(self, request: Request):
    errors = request.validate(
        required(['email', 'password'])
    )

    if errors:
        return request.redirect('/dashboard/errors').with_input()

You can then get the inputs using the {{ old('key') }} template helper:

<form>
  <input type="text" name="email" value="{{ old ('email') }}">
  ...
</form>

Default Back URL

We can also specify a default route just in case a form submitted does not specify one using a form helper:

def show(self, request: Request):
    return request.back(default='/hit/route')

This will check for the __back input and if it doesn't exist it will use this default route. This is the same as a redirect if you don't use the back() helper.

Encryption Key

You can load a specific secret key into the request by using:

request.key(key)

This will load a secret key into the request which will be used for encryptions purposes throughout your Masonite project.

Note that by default, the secret key is pulled from your configuration file so you do NOT need to supply a secret key, but the option is there if you need to change it for testing and development purposes.

Headers

You can also get and set any headers that the request has.

You can get all WSGI information by printing:

def show(self, request: Request):
    print(request.environ)

This will print the environment setup by the WSGI server. Use this for development purposes.

You can also get a specific header:

def show(self, request: Request):
    request.header('AUTHORIZATION')

This will return whatever the HTTP_AUTHORIZATION header if one exists. If that does not exist then the AUTHORIZATION header will be returned. If that does not exist then None will be returned.

We can also set headers:

def show(self, request: Request):
    request.header('AUTHORIZATION', 'Bearer some-secret-key')

Masonite will automatically prepend a HTTP_ to the header being set for standards purposes so this will set the HTTP_AUTHORIZATION header. If you do not want the HTTP prefix then pass a third parameter:

request.header('AUTHORIZATION', 'Bearer some-secret-key')

This will set the AUTHORIZATION header instead of the HTTP_AUTHORIZATION header.

You can also set headers with a dictionary:

request.header({
    'AUTHORIZATION': 'Bearer some-secret-key',
    'Content-Type': 'application/json'
})

Status Codes

Masonite will set a status code of 404 Not Found at the beginning of every request. If the status code is not changed throughout the code, either through the developer or third party packages, as it passes through each Service Provider then the status code will continue to be 404 Not Found when the output is generated. You do not have to explicitly specify this as the framework itself handles status codes. If a route matches and your controller method is about to be hit then Masonite will set 200 OK and hit your route. This allows Masonite to specify a good status code but also allows you to change it again inside your controller method.

You could change this status code in either any of your controllers or even a third party package via a Service Provider.

For example, the Masonite Entry package sets certain status codes upon certain actions on an API endpoint. These can be 429 Too Many Requests or 201 Created. These status codes need to be set before the StartProvider is ran so if you have a third party package that sets status codes or headers, then they will need to be placed above this Service Provider in a project.

If you are not specifying status codes in a package and simple specifying them in a controller then you can do so freely without any caveats. You can set status codes like so:

request.status('429 Too Many Requests')

You can also use an integer which will find the correct status code for you:

request.status(429)

This snippet is exactly the same as the string based snippet above.

This will set the correct status code before the output is sent to the browser. You can look up a list of HTTP status codes from an online resource and specify any you need to. There are no limitations to which ones you can use.

Get Request Method Type

You can get the request method simply:

# PUT: /dashboard

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

Changing Request Methods in Forms

Typically, forms only have support for GET and POST. You may want to change what HTTP method is used when submitting a form such as PATCH.

This will look like:

<form action="/dashboard" method="POST">
    <input type="hidden" name="request_method" value="PATCH">
</form>

or you can optionally use a helper method:

<form action="/dashboard" method="POST">
    {{ request_method('PATCH') }}
</form>

When the form is submitted, it will process as a PUT request instead of a POST request.

This will allow this form to hit a route like this:

from masonite.routes import Patch

ROUTES = [
    Patch().route('/dashboard', 'DashboardController@update')
]

Validation

There is a convenient helper method you can use the validate the request. You can import the Validator class and use validation like so:

from masonite.request import Request
from masonite.validation import Validator

def show(self, request: Request, validate: Validator):
    errors = request.validate(
      validate.required('user')
    )

    if errors:
      return request.back().with_errors(errors)

Routing

Introduction

Masonite Routing is an extremely simple but powerful routing system that at a minimum takes a url and a controller. Masonite will take this route and match it against the requested route and execute the controller on a match.

All routes are created inside routes/web.py and are contained in a ROUTES constant. All routes consist of some form of HTTP route classes (like Get() or Post()). At the bare minimum, a route will look like:

routes/web.py

Get('/url/here', 'WelcomeController@show')

Most of your routes will consist of a structure like this. All URI’s should have a preceding /. Routes that should only be executed on Post requests (like a form submission) will look very similar:

routes/web.py

Post('/url/here', 'WelcomeController@store')

Notice the controller here is a string. This is a great way to specify controllers as you do not have to import anything into your web.py file. All imports will be done in the backend. More on controllers later.

If you wish to not use string controllers and wish to instead import your controller then you can do so by specifying the controller as well as well as only passing a reference to the method. This will look like:

routes/web.py

...
from app.http.controllers.DashboardController import DashboardController


ROUTES = [
    Get('/url/here', DashboardController.show)
]

It’s important here to recognize that we didn't initialize the controller or the method, we did not actually call the method. This is so Masonite can pass parameters into the constructor and method when it executes the route, typically through auto resolving dependency injection.

Route Options

There are a few methods you can use to enhance your routes. Masonite typically uses a setters approach to building instead of a parameter approach so to add functionality, we can simply attach more methods.

HTTP Verbs

There are several HTTP verbs you can use for routes:

routes/web.py

from masonite.routes import Get, Post, Put, Patch, Delete, Match, Options, Trace, Connect

Get(..)
Post(..)
Put(..)
Patch(..)
Delete(..)
Match(..)
Options(..)
Trace(..)
Connect(..)

Route Groups

Some routes may be very similar. We may have a group of routes under the same domain, uses the same middleware or even start with the same prefixes. In these instances we should group our routes together so they are more DRY and maintainable.

We can add route groups like so:

from masonite.routes import RouteGroup, Get

ROUTES = [

    RouteGroup([
        Get('/url1', ...),
        Get('/url2', ...),
        Get('/url3', ...),
    ]),

]

This alone is great to group routes together that are similar but in addition to this we can add specific attributes to the entire group like adding middleware:

ROUTES = [

    RouteGroup([
        Get('/url1', ...),
        Get('/url2', ...),
        Get('/url3', ...),
    ], middleware=('auth', 'jwt')),

]

In the case you are only using one middleware:

ROUTES = [

    RouteGroup([
        Get('/url1', ...),
        Get('/url2', ...),
        Get('/url3', ...),
    ], middleware=('auth',)),

]

The , at the end of 'auth' ensures that it's treated as a tuple and not as an array of strings.

In this instance we are adding these 2 middleware to all of the routes inside the group. We have access to a couple of different methods. Feel free to use some or all of these options:

ROUTES = [

    RouteGroup([
        Get('/url1', ...).name('create'),
        Get('/url2', ...).name('update'),
        Get('/url3', ...).name('delete'),
    ], 
    middleware=('auth', 'jwt'),
    domain='subdomain',
    prefix='/dashboard',
    name='post.',
    add_methods=['OPTIONS']
    ),

]

The prefix parameter will prefix that URL to all routes in the group as well as the name parameter. The code above will create routes like /dashboard/url1 with the name of post.create. As well as adding the domain and middleware to the routes.

All of the options in a route group are named parameters so if you think adding a groups attribute at the end is weird you can specify them in the beginning and add the routes parameter:

RouteGroup(middleware=('auth', 'jwt'), name='post.', routes = [
    Get('/url1', ...).name('create'),
    Get('/url2', ...).name('update'),
    Get('/url3', ...).name('delete'),
]),

Multiple Route Groups

Even more awesome is the ability to nest route groups:

ROUTES = [

    RouteGroup([
        Get('/url1', ...).name('create'),
        Get('/url2', ...).name('update'),
        Get('/url3', ...).name('delete'),
        RouteGroup([
            Get('/url4', ...).name('read'),
            Get('/url5', ...).name('put'),
        ], prefix='/users', name='user.'),
    ], prefix='/dashboard', name='post.', middleware=('auth', 'jwt')),

]

This will go to each layer and generate a route list essentially from the inside out. For a real world example we refactor routes from this:

ROUTES = [
    Get().domain('www').route('/', 'WelcomeController@show').name('welcome'),
    Post().domain('www').route('/invite', 'InvitationController@send').name('invite'),
    Get().domain('www').route('/dashboard/apps', 'AppController@show').name('app.show').middleware('auth'),
    Get().domain('www').route('/dashboard/apps/create', 'AppController@create').name('app.create').middleware('auth'),
    Post().domain('www').route('/dashboard/apps/create', 'AppController@store').name('app.store'),
    Post().domain('www').route('/dashboard/apps/delete', 'AppController@delete').name('app.delete'),
    Get().domain('www').route('/dashboard/plans', 'PlanController@show').name('plans').middleware('auth'),
    Post().domain('www').route('/dashboard/plans/subscribe', 'PlanController@subscribe').name('subscribe'),
    Post().domain('www').route('/dashboard/plans/cancel', 'PlanController@cancel').name('cancel'),
    Post().domain('www').route('/dashboard/plans/resume', 'PlanController@resume').name('resume'),

    Post().domain('*').route('/invite', 'InvitationController@subdomain').name('invite.subdomain'),
    Get().domain('*').route('/', 'WelcomeController@subdomain').name('welcome'),
]

ROUTES = ROUTES + [
    Get().domain('www').route('/login', 'LoginController@show').name('login'),
    Get().domain('www').route('/logout', 'LoginController@logout'),
    Post().domain('www').route('/login', 'LoginController@store'),
    Get().domain('www').route('/register', 'RegisterController@show'),
    Post().domain('www').route('/register', 'RegisterController@store'),
    Get().domain('www').route('/home', 'HomeController@show').name('home'),
]

into this:

ROUTES = [

    RouteGroup([
        # Dashboard Routes
        RouteGroup([
            # App Routes
            RouteGroup([
                Get('', 'AppController@show').name('show'),
                Get('/create', 'AppController@create').name('create'),
                Post('/create', 'AppController@store').name('store'),
                Post('/delete', 'AppController@delete').name('delete'),
            ], prefix='/apps', name='app.'),

            Get('/plans', 'PlanController@show').name('plans'),
            Post('/plans/subscribe', 'PlanController@subscribe').name('subscribe'),
            Post('/plans/cancel', 'PlanController@cancel').name('cancel'),
            Post('/plans/resume', 'PlanController@resume').name('resume'),
        ], prefix="/dashboard", middleware=('auth',)),

        # Login and Register Routes
        Get('/login', 'LoginController@show').name('login'),
        Get('/logout', 'LoginController@logout'),
        Post('/login', 'LoginController@store'),
        Get('/register', 'RegisterController@show'),
        Post('/register', 'RegisterController@store'),
        Get('/home', 'HomeController@show').name('home'),

        # Base Routes
        Get('/', 'WelcomeController@show').name('welcome'),
        Post('/invite', 'InvitationController@send').name('invite'),
    ], domain='www'),


    # Subdomain invitation routes
    Post().domain('*').route('/invite', 'InvitationController@subdomain').name('invite.subdomain'),
    Get().domain('*').route('/', 'WelcomeController@subdomain').name('welcome'),
]

This will likely be the most common way to build routes for your application.

View Routes

You can also use View routes which is just a method on the normal route class:

ROUTES = [
    Get().view('/template', 'some/template', {'key': 'value'})
]

You can use this view method with any route class.

Redirect Route

You can also redirect right from the routes list using a Redirect route class:

from masonite.routes import Redirect

ROUTES = [
    Redirect('/old/route', '/new/route', status=302, methods=['GET', 'POST'])
]

You do not have to specify the last 2 parameters. The default is a 302 response on GET methods.

Match Routes

You may have noticed above that we have a Match route class. This can match several incoming request methods. This is useful for matching a route with both PUT and PATCH.

Match(['PUT', 'PATCH']).route(...)

The request methods are not case sensitive. They will be converted to uppercase on the backend. So ['Put', 'Patch'] will work just fine

Named Routes

We can name our routes so we can utilize these names later when or if we choose to redirect to them. We can specify a route name like so:

routes/web.py

Get('/dashboard', 'DashboardController@show').name('dashboard')

It is good convention to name your routes since route URI's can change but the name should always stay the same.

Route Middleware

Middleware is a great way to execute classes, tasks or actions either before or after requests. We can specify middleware specific to a route after we have registered it in our config/middleware.py file but we can go more in detail in the middleware documentation. To add route middleware we can use the middleware method like so:

routes/web.py

Get('/dashboard', 'DashboardController@show').middleware('auth', 'anothermiddleware')

This middleware will execute either before or after the route is executed depending on the middleware.

Read more about how to use and create middleware in the Middleware documentation.

Deeper Module Controllers

All controllers are located in app/http/controllers but sometimes you may wish to put your controllers in different modules deeper inside the controllers directory. For example, you may wish to put all your product controllers in app/http/controllers/products or all of your dashboard controllers in app/http/controllers/users. In order to access these controllers in your routes we can simply specify the controller using our usual dot notation:

routes/web.py

Get('/dashboard', 'users.DashboardController@show')

Global Controllers

Controllers are defaulted to the app/http/controllers directory but you may wish to completely change the directory for a certain route. We can use a forward slash in the beginning of the controller namespace:

Get('/dashboard', '/thirdparty.package.users.DashboardController@show')

This can enable us to use controllers in third party packages.

You can also import the class directly and reference the method you want to use:

from app.controllers.SomeController import SomeController

Get('/dashboard', SomeController.show)

Route Parameters

Very often you’ll need to specify parameters in your route in order to retrieve information from your URI. These parameters could be an id for the use in retrieving a certain model. Specifying route parameters in Masonite is very easy and simply looks like:

routes/web.py

Get('/dashboard/@id', 'Controller@show')

That’s it. This will create a dictionary inside the Request object which can be found inside our controllers.

In order to retrieve our parameters from the request we can use the param method on the Request object like so:

app/http/controller/YourController.py

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

Optional Route 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 @ with a ?:

routes/web.py

Get('/dashboard/user/?option', 'Controller@show')

You can also set default values if the route is not hit:

routes/web.py

Get('/dashboard/user/?option', 'Controller@show').default({
    'option': 'settings'
})

Route Compilers

Sometimes you will want to make sure that the route parameter is of a certain type. For example you may want to match a URI like /dashboard/1 but not /dashboard/joseph. In order to do this we simply need to pass a type to our parameter. If we do not specify a type then our parameter will default to matching all alphanumeric and underscore characters.

routes/web.py

Get('/dashboard/@id:int', 'Controller@show')

This will match all integers but not strings. So for example it will match /dashboard/10283 and not /dashboard/joseph

If we want to match all strings but not integers we can pass:

routes/web.py

Get('/dashboard/@id:string', 'Controller@show')

This will match /dashboard/joseph and not /dashboard/128372. Currently only the integer and string types are supported.

These are called "Route Compilers" because they compile the route differently depending on what is specified. If you specify :int or :integer it will compile to a different regex than if you specified :string.

Adding Route Compilers

We can add route compilers to our project by specifying them in a Service Provider.

Make sure you add them in a Service Provider where wsgi is False. We can add them on the Route class from the container using the compile method. A completed example might look something like this:

app/http/providers/RouteCompileProvider.py

from masonite.provider import ServiceProvider
from masonite.routes import Route


class RouteCompilerProvider(ServiceProvider):

    wsgi = False
    ...

    def boot(self, route: Route):
        route.compile('year', r'([0-9]{4})')

We just need to call the compile() method on the Route class and make sure we specify a regex string by preceding an r to the beginning of the string.

Your regex should be encapsulated in a group. If you are not familiar with regex, this basically just means that your regex pattern should be inside parenthesis like the example above.

Subdomain Routing

You may wish to only render routes if they are on a specific subdomain. For example you may want example.com/dashboard to route to a different controller than joseph.example.com/dashboard.

Out of the box this feature will not work and is turned off by default. We will need to add a call on the Request class in order to activate subdomains. We can do this in the boot method of one of our Service Providers that has wsgi=False:

app/providers/UserModelProvider.py

wsgi = False
...
def boot(self, request: Request):
    request.activate_subdomains()

To use subdomains we can use the .domain() method on our routes like so:

routes/web.py

Get().domain('joseph').route('/dashboard', 'Controller@show')

This route will match to joseph.example.com/dashboard but not to example.com/dashboard or test.example.com/dashboard.

It may be much more common to match any subdomain. For this we can pass in an asterisk instead.

routes/web.py

Get().domain('*').route('/dashboard', 'Controller@show')

This will match all subdomains such as test.example.com/dashboard, joseph.example.com/dashboard but not example.com/dashboard.

If a match is found, it will also add a subdomain parameter to the Request class. We can retrieve the current subdomain like so:

app/http/controllers/YourController.py

def show(self, request: Request):
    print(request.param('subdomain'))

Static Files

Introduction

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 resistered in your configuration files.

Configuration

All configurations that are specific to static files can be found in config/storage.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 is simply the location of your static file locations. 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/storage.py

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

...
<img src="{{ static('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...'
  ...
  'location': {
    '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="{{ static('s3.east', 'profile.jpg') }}" alt="profile">
...
<img src="{{ static('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/storage.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/root': '/'
}

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

Introduction

Views contain all the HTML that you’re application will use to render to the user. Unlike Django, views in Masonite are your HTML templates. All views are located inside the resources/templates directory.

All views are rendered with Jinja2 so we can use all the Jinja2 code you are used to. An example view looks like:

resources/templates/helloworld.html

<html>
  <body>
    <h1> Hello {{ 'world' }}</h1>
  </body>
</html>

Creating Views

Since all views are located in resources/templates, we can use simply create all of our views manually here or use our craft command tool. To make a view just run:

terminal

$ craft view hello

This will create a template under resources/templates/hello.html.

Calling Views

The View class is loaded into the container so we can retrieve it in our controller methods like so:

app/http/controllers/YourController.py

from masonite.view import View

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

This is exactly the same as using the helper function above. So if you choose to code more explicitly, the option is there for you.

If this looks weird to you or you are not sure how the container integrates with Masonite, make sure you read the Service Container documentation

Global Views

Some views may not reside in the resources/templates directory and may even reside in third party packages such as a dashboard package. We can locate these views by passing a / in front of our view.

For example as a use case we might pip install a package:

terminal

$ pip install package-dashboard

and then be directed or required to return one of their views:

app/http/controllers/YourController.py

def show(self, view: View):
    return view.render('/package/views/dashboard')

This will look inside the dashboard.views package for a dashboard.html file and return that. You can obviously pass in data as usual.

Caveats

It's important to note that if you are building a third party package that integrates with Masonite that you place any .html files inside a Python package instead of directly inside a module. For example, you should place .html files inside a file structure that looks like:

package/
  views/
    __init__.py
    index.html
    dashboard.html
setup.py
MANIFEST.in
...

ensuring there is a __init__.py file. This is a Jinja2 limitation that says that all templates should be located in packages.

Accessing a global view such as:

app/http/controllers/YourController.py

def show(self, view: View):
    return view.render('/package/dashboard')

will perform an absolute import for your Masonite project. For example it will locate:

app/
config/
databases/
...
package/
  dashboard.html

Or find the package in a completely separate third part module. So if you are making a package for Masonite then keep this in mind of where you should put your templates.

Passing Data to Views

Most of the time we’ll need to pass in data to our views. This data is passed in with a dictionary that contains a key which is the variable with the corresponding value. We can pass data to the function like so:

app/http/controllers/YourController.py

def show(self, view: View, request: Request):
    return view.render('dashboard', {'id': request.param('id')})

Remember that by passing in parameters like Request to the controller method, we can retrieve objects from the IOC container. Read more about the IOC container in the Service Container documentation.

This will send a variable named id to the view which can then be rendered like:

resources/templates/dashboard.html

<html>
  <body>
    <h1> {{ id }} </h1>
  </body>
</html>

View Syntax

Views use Jinja2 for it's template rendering. You can read about Jinja2 at the official documentation here.

Masonite also enables Jinja2 Line Statements by default which allows you to write syntax the normal way:

{% extends 'nav/base.html' %}

{% block content %}
    {% for element in variables %}
        {{ element }}
    {% endfor %}

    {% if some_variable %}
        {{ some_variable }}
    {% endif %}

{% endblock %}

Or using line statements with the @ character:

@extends 'nav/base.html'

@block content
    @for element in variables
        {{ element }}
    @endfor

    @if some_variable
        {{ some_variable }}
    @endif

@endblock

The choice is yours on what you would like to use but keep in mind that line statements need to use only that line. Nothing can be after after or before the line.

Adding Environments

This section requires knowledge of Service Providers and how the Service Container works. Be sure to read those documentation articles.

You can also add Jinja2 environments to the container which will be available for use in your views. This is typically done for third party packages such as Masonite Dashboard. You can extend views in a Service Provider in the boot method. Make sure the Service Provider has the wsgi attribute set to False. This way the specific Service Provider will not keep adding the environment on every request.

from masonite.view import View

wsgi = False

...

def boot(self, view: View):
    view.add_environment('dashboard/templates')

By default the environment will be added using the PackageLoader Jinja2 loader but you can explicitly set which loader you want to use:

from jinja2 import FileSystemLoader
from masonite.view import View
...
wsgi = False

...

def boot(self, view: View):
    view.add_environment('dashboard/templates', loader=FileSystemLoader)

The default loader of PackageLoader will work for most cases but if it doesn't work for your use case, you may need to change the Jinja2 loader type.

Using Dot Notation

If using a / doesn't seem as clean to you, you can also optionally use dots:

def show(self, view: View):
    view.render('dashboard.user.show')

if you want to use a global view you still need to use the first /:

def show(self, view: View):
    view.render('/dashboard.user.show')

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>

Static

You can get the location of static assets:

If you have a configuration file like this:

config/storage.py

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

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

this will render:

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

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>

Request Method

On forms you can typically only have either a GET or a POST because of the nature of html. With Masonite you can use a helper to submit forms with PUT or DELETE

<form action="/some/url" method="POST">
    {{ request_method('PUT') }}
    <input ..>
</form>

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>

Another cool feature is that if the current route already contains the correct dictionary then you do not have to pass a second parameter. For example if you have a 2 routes like:

Get('/dashboard/@id', 'Controller@show').name('dashboard.show'),
Get('/dashhboard/@id/users', 'Controller@users').name('dashhboard.users')

If you are accessing these 2 routes then the @id parameter will be stored on the user object. So instead of doing this:

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

You can just leave it out completely since the id key is already stored on the request object:

<form action="{{ route('dashboard.users') }}" 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, request: Request):
    # Some failed validation
    return request.back()

Old

The request.back() method will also flash the current inputs to the session so you can get them when you land back on your template. You can get these values by using the old() method:

<form>
  <input type="text" name="email" value="{{ old('email') }}">
  ...
</form>

Session

You can access the session here:

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

Learn more about session in the Session documentation.

Sign

You can sign things using your secret token:

<p> Signed: {{ sign('token') }} </p>

Unsign

You can also unsign already signed string:

<p> Signed: {{ unsign('signed_token') }} </p>

Encrypt

This is just an alias for sign

Decrypt

This is just an alias for unsign

Config

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

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

Optional

Allows you to fetch values from objects that may or may not be None. Instead of doing something like:

{% if auth() and auth().name == 'Joe' %}
    <p>Hello!</p>
{% endif %}

You can use this helper:

{% if optional(auth()).name == 'Joe' %}
    <p>Hello!</p>
{% endif %}

DD

This is the normal dd helper you use in your controllers

Hidden

You can use this helper to quickly add a hidden field

<form action="/" method="POST">
    {{ hidden('secret' name='secret-value') }}
</form>

Exists

Check if a template exists

{% if exists('auth/base') %}
    {% extends 'auth/base.html' %}
{% else %}
    {% extends 'base.html' %}
{% endif %}

Gets a cookie:

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

Url

Get the URL to a location:

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

</form>

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:

{% if expression %}
    <p>do something</p>
{% endif %}

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="{% if expression %} 'something' {% endif %}">

</form>

Whichever syntax you choose is up to you.

Variables

You can show variable 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:

{% if expression %}
    <p>do something</p>
{% elif %}
    <p>do something else</p>
{% else %}
    <p>above all are false</p>
{% endif %}

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:

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

Include statement

An include statement is useful for including other templates.

Line Statements:

@include 'components/errors.html'

<form action="/">

</form>

Using alternative Jinja2 syntax:

{% include 'components/errors.html' %}

<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:

{% extends 'components/base.html' %}

{% block content %}
    <p> read below to find out what a block is </p>
{% endblock %}

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>
        {% 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 %}

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.

The Craft Command

Introduction

The craft command tool is a powerful developer tool that lets you quickly scaffold your project with models, controllers, views, commands, providers, etc. which will condense nearly everything down to its simplest form via the craft namespace. No more redundancy in your development time creating boilerplate code. Masonite condenses all common development tasks into a single namespace.

For example, In Django you may need to do something like:

$ django-admin startproject
$ python manage.py runserver
$ python manage.py migrate

The craft tool condenses all commonly used commands into its own namespace

$ craft new
$ craft serve
$ craft migrate

All scaffolding of Masonite can be done manually (manually creating a controller and importing the view function for example) but the craft command tool is used for speeding up development and cutting down on mundane development time.

Commands

When craft is used outside of masonite directory, it will only show a few commands such as the new and install commands. Other commands such as commands for creating controllers or models are loaded in from the Masonite project itself.

Many commands are loaded into the framework itself and fetched when craft is ran in a Masonite project directory. This allows version specific Masonite commands to be efficiently handled on each subsequent version as well as third party commands to be loaded in which expands craft itself.

The possible commands for craft include:

Tinker Command

You can "tinker" around with Masonite by running:

$ craft tinker

This command will start a Python shell but also imports the container by default. So we can call:

Type `exit()` to exit.
>>> app
<masonite.app.App object at 0x10cfb8d30>
>>> app.make('Request')
<masonite.request.Request object at 0x10d03c8d0>
>>> app.collect("Mail*Driver")
{'MailSmtpDriver': <class 'masonite.drivers.MailSmtpDriver.MailSmtpDriver'>,
'MailMailgunDriver': <class 'masonite.drivers.MailMailgunDriver.MailMailgunDriver'>
}
>>> exit()

And play around the container. This is a useful debugging tool to verify that objects are loaded into the container if there are any issues.

Show Routes Command

Another useful command is the show:routes command which will display a table of available routes that can be hit:

$ craft show:routes

This will display a table that looks like:

========  =======  =======  ========  ============
Method    Path     Name     Domain    Middleware
========  =======  =======  ========  ============
GET       /        welcome
GET       /home    home
GET       /user 
POST      /create  user   
========  =======  =======  ========  ============

Application Information

If you are trying to debug your application or need help in the Slack channel, it might be beneficial to see some useful information information about your system and environment. In this case we have a simple command:

$ craft info

This will give some small details about the current system which could be useful to someone trying to help you. Running the command will give you something like this:

Environment Information
-------------------------  ------------------
System Information         MacOS x86_64 64bit
System Memory              8 GB
Python Version             CPython 3.6.5
Virtual Environment        ✓
Masonite Version           2.0.6
Craft Version              2.0.7
APP_ENV                    local
APP_DEBUG                  True

Feel free to contribute any additional information you think is necessary to the command in the core repository.

Creating an Authentication System

To create an authentication system with a login, register and a dashboard system, just run:

 $ craft auth

This command will create several new templates, controllers and routes so you don’t need to create an authentication system from scratch, although you can. If you need a custom authentication system, this command will scaffold the project for you so you can go into these new controllers and change them how you see fit.

These new controllers are not apart of the framework itself but now apart of your project. Do not look at editing these controllers as editing the framework source code.

Creating Validators

Validators are classes based on validating form or request input. We can create validators by running:

$ craft validator LoginValidator

Be sure to read the Validation documentation to learn more about validators.

Creating Model Definition Docstrings

Masonite uses Orator which is an active record style ORM. If you are coming from other Python frameworks you may be more familiar with Data Mapper ORM's like Django ORM or SQLAlchemy. These style ORM's are useful since the names of the column in your table are typically the names of class attributes. If you forget what you named your column you can typically just look at the model but if your model looks something like:

class User(Model):
    pass

Then it is not apparent what the tables are. We can run a simple command though to generate a docstring that we can throw onto our model:

$ craft model:docstring table_name

Which will generate something like this in the terminal:

"""Model Definition (generated with love by Masonite)

id: integer default: None
name: string(255) default: None
email: string(255) default: None
password: string(255) default: None
remember_token: string(255) default: None
created_at: datetime(6) default: CURRENT_TIMESTAMP(6)
updated_at: datetime(6) default: CURRENT_TIMESTAMP(6)
customer_id: string(255) default: None
plan_id: string(255) default: None
is_active: integer default: None
verified_at: datetime default: None
"""

We can now copy and paste that onto your model and change whatever we need to:

class User(Model):
    """Model Definition (generated with love by Masonite)

    id: integer default: None
    name: string(255) default: None
    email: string(255) default: None
    password: string(255) default: None
    remember_token: string(255) default: None
    created_at: datetime(6) default: CURRENT_TIMESTAMP(6)
    updated_at: datetime(6) default: CURRENT_TIMESTAMP(6)
    customer_id: string(255) default: None
    plan_id: string(255) default: None
    is_active: integer default: None
    verified_at: datetime default: None
    """
    pass

You can also specify the connection to use using the --connection option.

$ craft model:docstring table_name --connection amazon_db

Creating Controllers

If you wish to scaffold a controller, just run:

$ craft controller Dashboard

This command will create a new controller under app/http/controllers/DashboardController.py. By convention, all controllers should have an appended “Controller” and therefore Masonite will append "Controller" to the controller created.

You can create a controller without appending "Controller" to the end by running:

$ craft controller Dashboard -e

This will create a app/http/controllers/Dashboard.py file with a Dashboard controller. Notice that "Controller" is not appended.

-e is short for --exact. Either flag will work.

You may also create resource controllers which include standard resource actions such as show, create, update, etc:

$ craft controller Dashboard -r

-r is short for --resource. Either flag will work.

You can also obviously combine them:

$ craft controller Dashboard -r -e

Creating a New Project

If you’d like to start a new project, you can run:

$ craft new project_name

This will download a zip file of the MasoniteFramework/masonite repository and unzip it into your current working directory. This command will default to the latest release of the repo.

You may also specify some options. The --version option will create a new project depending on the releases from the MasoniteFramework/masonite repository.

$ craft new project_name --version 1.3.0

Or you can specify the branch you would like to create a new project with:

$ craft new project_name --branch develop

After you have created a new project, you will have a requirements.txt file with all of the projects dependencies. In addition to this file, you will also have a .env-example file which contains a boilerplate of a .env file. In order to install the dependencies, as well as copy the example environment file to a .env file, just run:

$ craft install

The craft install command will also run craft key --store as well which generates a secret key and places it in the .env file.

Creating Migrations

All frameworks have a way to create migrations in order to manipulate database tables. Masonite uses a little bit of a different approach to migrations than other Python frameworks and makes the developer edit the migration file. This is the command to make a migration for an existing table:

$ craft migration name_of_migration --table users

If you are creating a migration for a table that does not exist yet which the migration will create it, you can pass the --create flag like so:

$ craft migration name_of_migration --create users

These two flags will create slightly different types of migrations.

Migrating

After your migrations have been created, edited, and are ready for migrating, we can now migrate them into the database. To migrate all of your unmigrated migrations, just run:

$ craft migrate

Rolling Back and Rebuilding Migrations

You can also refresh and rollback all of your migrations and remigrate them.

This will essentially rebuild your entire database.

$ craft migrate:refresh

You can also rollback all migrations without remigrating

$ craft migrate:reset

Lastly, you can rollback just the last set of migrations you tried migrating

$ craft migrate:rollback

Models

If you'd like to create a model, you can run:

$ craft model ModelName

This will scaffold a model under app/ModelName and import everything needed.

If you need to create a model in a specific folder starting from the app folder, then just run:

$ craft model Models/ModelName

This will create a model in app/Models/ModelName.py.

Model Shortcuts

You can also use the -s and -m flags to create a seed or model at the same time.

$ craft model ModelName -s -m

This is a shortcut for these 3 commands:

$ craft model ModelName
$ craft seed ModelName
$ craft migration create_tablename_table --create tablename

Creating a Service Provider

Service Providers are a really powerful feature of Masonite. If you'd like to create your own service provider, just run:

$ craft provider DashboardProvider

This will create a file at app/providers/DashboardProvider.py

Read more about Service Providers under the Service Provider documentation.

Creating Views

Views are simply html files located in resources/templates and can be created easily from running the command:

$ craft view blog

This command will create a template at resources/templates/blog.html

You can also create a view deeper inside the resources/templates directory.

$ craft view auth/home

This will create a view under resources/templates/auth/home.html but keep in mind that it will not create the directory for you. If the auth directory does not exist, this command will fail.

Creating Jobs

Jobs are designed to be loaded into queues. We can take time consuming tasks and throw them inside of a Job. We can then use this Job to push to a queue to speed up the performance of our application and prevent bottlenecks and slowdowns.

$ craft job SendWelcomeEmail

Jobs will be put inside the app/jobs directory. See the Queues and Jobs documentation for more information.

Running Queues

Masonite has a queue feature that allows you to load the jobs you create in the section above and run them either asyncronously or send them off to a message broker like RabbitMQ. You may start the worker by running:

$ craft queue:work

You'll need to read the documentation in the Queues and Jobs documentation for futher info on how to setup this feature.

Packages

You may create a PyPi package with an added integrations.py file which is specific to Masonite. You can learn more about packages by reading the Creating Packages documentation. To create a package boilerplate, just run:

$ craft package name_of_package

Creating Commands

You can scaffold out basic command boilerplate:

$ craft command Hello

This will create a app/commands/HelloCommand.py file with the HelloCommand class.

Running the WSGI Server

You can run the WSGI server by simply running:

$ craft serve

This will set the server to auto-reload when you make file changes.

You can also set it to not auto-reload on file changes:

$ craft serve --dont-reload

or the shorthand

$ craft serve -d

If you have unmigrated migrations, Masonite will recommend running craft migrate when running the server.

Live Reloading

The serve command also has a live reloading option which will refresh any connected browsers so you can more quickly prototype your jinja templates.

This is not a great tool for changing Python code and any Python code changes may still require a browser refresh to see the changes.

$ craft serve --live-reload

Host and Port

You can bind to a host using -b and/or a port using -p

$ craft serve -b 127.0.0.1 -p 8080

Reloading Interval

Masonite comes with a pretty quick auto reloading development server. By default there will be a 1 second delay between file change detection and the server reloading. This is a fairly slow reloading interval and most systems can handle a much faster interval while still properly managing the starting and killing of process PID's.

You can change the interval to something less then 1 using the -i option:

$ craft serve -r -i .1

You will notice a considerably faster reloading time on your machine. If your machine can handle this interval speed (meaning your machine is properly starting and killing the processes) then you can safely proceed using a lower interval during development.

Encryption

Masonite comes with a way to encrypt data and by default, encrypts all cookies set by the framework. Masonite uses a key to encrypt and decrypt data. Read the Encryption documentation for more information on encryption.

To generate a secret key, we can run:

$ craft key

This will generate a 32 bit string which you can paste into your .env file under the KEY setting.

You may also pass the --store flag which will automatically add the key to your .env file:

$ craft key --store

This command is ran whenever you run craft install

Great! You are now a master at the craft command line tool.

Testing

You can also scaffold out basic test cases. You can do this by running:

$ craft test NameOfTest

This will scaffold the test in the base tests/ directory and you can move it to wherever you like from there.

Publish

Masonite has the concept of publishing where you can publish specific assets to a developers application. This will allow them to make tweaks to better fit your package to their needs.

You can publish a specific provider by running:

$ craft provider ProviderName

You can also optionally specify a tag:

$ craft provider ProviderName --tag name

You should read more about publishing at the publishing documentation page.

Creating Commands

Introduction

It's extremely simple to add commands to Masonite via the craft command tool and Service Providers. If you have been using Masonite for any amount of time you will learn that commands are a huge part of developing web applications with Masonite. We have made it extremely easy to create these commands and add them to craft to build really fast personal commands that you might use often.

Masonite uses the Cleo package for creating and consuming commands so for more extensive documentation on how to utilize commands themselves, how to get arguments and options, and how to print colorful text to the command line.

Getting Started

You can create commands by using craft itself:

This will create a app/commands/HelloCommand.py file with boilerplate code that looks like this:

Let's create a simple hello name application which prints "hello your-name" to the console.

Where it says command:name inside the docstring we can put hello and inside the argument we can put name like so:

Inside the handle method we can get the argument passed by specifying self.argument('name'). Simply put:

That's it! Now we just have to add it to our craft command.

Adding Our Command To Craft

We can add commands to craft by creating a Service Provider and registering our command into the container. Craft will automatically run all the register methods on all containers and retrieve all the commands.

Let's create a Service Provider:

This will create a provider in app/providers/HelloProvider.py that looks like:

Let's import our command and register it into the container. Also because we are only registering things into the container, we can set wsgi = False so it is not ran on every request and only before the server starts:

Make sure you instantiate the command. Also the command name needs to end in "Command". So binding HelloCommand will work but binding Hello will not. Craft will only pick up commands that end in Command. This is also case sensitive so make sure Command is capitalized.

Adding The Service Provider

Like normal, we need to add our Service Provider to the PROVIDERS list inside our config/providers.py file:

That's it! Now if we run:

We will see our new hello command:

and if we run:

We will see an output of:

Architectural Concepts

Request Lifecycle

Introduction

Lifecycle Overview

With that being said, not all Service Providers need to be ran on every request and there are good times to load objects into the container. For example, loading routes into the container does not need to be ran on every request. Mainly because they won't change before the server is restarted again.

Now the entry point when the server is first ran (with something like craft serve) is the wsgi.py file in the root of the directory. In this directory, all Service Providers are registered. This means that objects are loaded into the container first that typically need to be used by any or all Service Providers later. All Service Providers are registered regardless on whether they require the server to be running (more on this later).

Now it's important to note that the server is not yet running we are still in the wsgi.py file but we have only hit this file, created the container, and registered our Service Providers.

Right after we register all of our Service Providers, we break apart the provider list into two separate lists. The first list is called the WSGIProviders list which are providers where wsgi=True (which they are by default). We will use this list of a smaller amount of providers in order to speed up the application since now we won't need to run through all providers and see which ones need to run.

While we are in the loop we also create a list of providers where wsgi=False and boot those providers. These boot methods may contain things like Manager classes creating drivers which require all drivers to be registered first but doesn't require the WSGI server to be running.

Also, more importantly, the WSGI key is binded into the container at this time. The default behavior is to wrap the WSGI application in a Whitenoise container to assist in the straight forwardness of static files.

This behavior can be changed by swapping that Service Provider with a different one if you do not want to use Whitenoise.

Once all the register methods are ran and all the boot methods of Service Providers where wsgi is false, and we have a WSGI key in the container, we can startup the server by using the value of the WSGI key.

We then make an instance of the WSGI key from the container and set it to an application variable in order to better show what is happening. Then this is where the WSGI server is started.

The Server

Now that we have the server running, we have a new entry point for our requests. This entry point is the app function inside bootstrap/start.py.

Now all wsgi servers set a variable called environ. In order for our Service Providers to handle this, we bind it into the container to the Environ key.

Next we run all of our Service Providers where wsgi is true now (because the WSGI server is running).

WSGI Service Providers

The Request Life Cycle is now going to hit all of these providers. Although you can obviously add any Service Providers you at any point in the request, Masonite comes with 5 providers that should remain in the order they are in. These providers have been commented as # Framework Providers. Because the request needs to hit each of these in succession, they should be in order although you may put any amount of any kind of Service Providers in between them.

We enter into a loop with these 5 Service Providers and they are the:

App Provider

This Service Provider registered objects like the routes, request class, response, status codes etc into the container and then loads the environment into these classes on every request so that they can change with the environment. Remember that we registered these classes when the server first started booting up so they remain the same class object as essentially act as singletons Although they aren't being reinstantiated with the already existing object, they are instantiated once and die when the server is killed.

Session Provider

If one of the middleware has instructed the request object to redirect, the view that is ready to execute, will not execute.

For example, if the user is planned on going to the dashboard view, but middleware has told the request to redirect to the login page instead then the dashboard view, and therefore the controller, will not execute at all. It will be skipped over. Masonite checks if the request is redirecting before executing a view.

Also, the request object can be injected into middleware by passing the Request parameter into the constructor like so:

This provider loads the ability to use sessions, adds a session helper to all views and even attaches a session attribute to the request class.

Route Provider

This provider takes the routes that are loaded in and makes the response object, static codes, runs middleware and other route displaying specific logic. This is the largest Service Provider with the most logic. This provider also searches through the routes, finds which one to hit and exectues the controller and controller method.

Status Code Provider

This provider is responsible for showing the nice HTTP status codes you see during development and production. This Service Provider also allows custom HTTP error pages by putting them into the resources/templates/errors directory.

Nothing too special about this Service Provide. You can remove this if you want it to show the default WSGI server error.

Start Response

This Service Provider collects a few classes that have been manipulated by the above Service Providers and constructs a few headers such as the content type, status code, setting cookies and location if redirecting.

Leaving the Providers

Once these 5 providers have been hit (and any you add), we have enough information to show the output. We leave the Service Provider loop and set the response and output which are specific to WSGI. The output is then sent to the browser with any cookies to set, any new headers, the response, status code, and everything else you need to display html (or json) to the browser.

Service Container

Introduction

The Service Container is an extremely powerful feature of Masonite and should be used to the fullest extent possible. It's important to understand the concepts of the Service Container. It's a simple concept but is a bit magical if you don't understand what's going on under the hood.

Getting Started

The Service Container is just a dictionary where classes are loaded into it by key-value pairs, and then can be retrieved by either the key or value through resolving objects. That's it.

Think of "resolving objects" as Masonite saying "what does your object need? Ok, I have them in this dictionary, let me get them for you."

The container holds all of the frameworks classes and features so adding features to Masonite only entails adding classes into the container to be used by the developer later on. This typically means "registering" these classes into the container (more about this later on).

This allows Masonite to be extremely modular.

There are a few objects that are resolved by the container by default. These include your controller methods (which are the most common and you have probably used them so far) driver and middleware constructors and any other classes that are specified in the documentation.

There are four methods that are important in interacting with the container: bind, make and resolve

Bind

In order to bind classes into the container, we will just need to use a simple bind method on our app container. In a service provider, that will look like:

This will load the key value pair in the providers dictionary in the container. The dictionary after this call will look like:

The service container is available in the Request object and can be retrieved by:

Simple Binding

Sometimes you really don't care what the key is for the object you are binding. For example you may be binding a Markdown class into the container but really don't care what the key binding is called. This is a great reason to use simple binding which will set the key as the object class:

Make

In order to retrieve a class from the service container, we can simply use the make method.

That's it! This is useful as an IOC container which you can load a single class into the container and use that class everywhere throughout your project.

Singleton

You can bind singletons into the container. This will resolve the object at the time of binding. This will allow the same object to be used throughout the lifetime of the server.

Has

You can also check if a key exists in the container by using the has method:

You can also check if a key exists in the container by using the in keyword.

Collecting

You may want to collect specific kinds of objects from the container based on the key. For example we may want all objects that start with "Exception" and end with "Hook" or want all keys that end with "ExceptionHook" if we are building an exception handler.

Collect By Key

We can easily collect all objects based on a key:

This will return a dictionary of all objects that are binded to the container that start with anything and end with "ExceptionHook" such as "SentryExceptionHook" or "AwesomeExceptionHook".

We can also do the opposite and collect everything that starts with a specific key:

This will collect all keys that start with "Sentry" such as "SentryWebhook" or "SentryExceptionHandler."

Lastly, we may want to collect things that start with "Sentry" and end with "Hook"

This will get keys like "SentryExceptionHook" and "SentryHandlerHook"

Collecting By Object

You can also collect all subclasses of an object. You may use this if you want to collect all instances of a specific class from the container:

Resolve

This is the most useful part of the container. It is possible to retrieve objects from the container by simply passing them into the parameter list of any object. Certain aspects of Masonite are resolved such as controller methods, middleware and drivers.

For example, we can hint that we want to get the Request class and put it into our controller. All controller methods are resolved by the container. Masonite 2.1 only supports annotations resolving by default:

In this example, before the show method is called, Masonite will look at the parameters and look inside the container for the Request object.

Masonite will know that you are trying to get the Request class and will actually retrieve that class from the container. Masonite will search the container for a Request class regardless of what the key is in the container, retrieve it, and inject it into the controller method. Effectively creating an IOC container with dependency injection. capabilities Think of this as a get by value instead of a get by key like the earlier example.

Pretty powerful stuff, eh?

Resolving Instances

Another powerful feature of the container is it can actually return instances of classes you annotate. For example, all Upload drivers inherit from the UploadContract which simply acts as an interface for all Upload drivers. Many programming paradigms say that developers should code to an interface instead of an implementation so Masonite allows instances of classes to be returned for this specific use case.

Take this example:

Notice that we passed in a contract instead of the upload class. Masonite went into the container and fetched a class with the instance of the contract.

Resolving Parameters

This feature should not be used and you should instead use the more explicit form of resolving in the section above.

You can technically still resolve parameters with your container like you could in previous versions of Masonite. Resolving a parameter looked like this:

Although this was removed in 2.1+, you may still enable it on a per project basis. To enable it, go to your wsgi.py file and add this to the constructor of your App class towards the top of the file:

Your project will now resolve parameters as well. Resolving parameters looks for the key in the container instead of the class.

Resolving your own code

The service container can also be used outside of the flow of Masonite. Masonite takes in a function or class method, and resolves it's dependencies by finding them in the service container and injecting them for you.

Because of this, you can resolve any of your own classes or functions.

Remember not to call it and only reference the function. The Service Container needs to inject dependencies into the object so it requires a reference and not a callable.

This will fetch all of the parameters of randomFunction and retrieve them from the service container. There probably won't be many times you'll have to resolve your own code but the option is there.

Resolving With Additional Parameters

Sometimes you may wish to resolve your code in addition to passing in variables within the same parameter list. For example you may want to have 3 parameters like this:

You can resolve and pass parameter at the same time by adding them to the resolve() method:

Masonite will go through each parameter list and resolve them, if it does not find the parameter it will pull it from the other parameters specified. These parameters can be in any order.

Using the container outside of Masonite flow

If you need to utilize a container outside the normal flow of Masonite like inside a command then you can import the container directly.

This would look something like:

Container Swapping

Sometimes when you resolve an object or class, you want a different value to be returned.

Using a value:

We can pass a simple value as the second parameter to the swap method which will be returned instead of the object being resolved. For example this is used currently when resolving the Mail class like this:

but the class definition for the Mail class here looks like this:

How does it know to resolve the smtp driver instead? It's because we added a container swap. Container swaps are simple, they take the object as the first parameter and either a value or a callable as the second.

For example we may want to mock the functionality above by doing something like this in the boot method of a Service Provider:

Notice that we specified which class should be returned whenever we resolve the Mail class. In this case we want to resolve the default driver specified in the projects configurations.

Using a callable

Instead of directly passing in a value as the second parameter we can pass in a callable instead. The callable MUST take 2 parameters. The first parameter will be the annotation we are trying to resolve and the second will be the container itself. Here is an example of how the above would work with a callable:

Notice that the second parameter is a callable object. This means that it will be called whenever we try to resolve the Mail class.

Remember: If the second parameter is a callable, it will be called. If it is a value, it will simply be returned instead of the resolving object.

Container Hooks

Sometimes we might want to run some code when things happen inside our container. For example we might want to run some arbitrary function about we resolve the Request object from the container or we might want to bind some values to a View class anytime we bind a Response to the container. This is excellent for testing purposes if we want to bind a user object to the request whenever it is resolved.

We have three options: on_bind, on_make, on_resolve. All we need for the first option is the key or object we want to bind the hook to, and the second option will be a function that takes two arguments. The first argument is the object in question and the second argument is the whole container.

The code might look something like this:

Notice that we create a function that accepts two values, the object we are dealing with and the container. Then whenever we run on_make, the function is ran.

We can also bind to specific objects instead of keys:

This then calls the same attribute but anytime the Request object itself is made from the container. Notice everything is the same except line 6 where we are using an object instead of a string.

We can do the same thing with the other options:

Strict and Overriding

By default, Masonite will not care if you override objects from the container. In other words you can do this:

Without issue. Notice we are binding twice to the same key. You can change this behavior by specifying 2 values in the constructor of the App class:

Override

If override is False, it will not override values in the container. It will simply ignore them if you are trying to bind twice to the same key. If override is True, which it is by default, you will be allowed to override keys in the container with new values by binding them.

Strict

Strict will throw an exception if you try binding a key to the container. So with override being False it simply ignored binding a key to the container that already exists, setting strict to True will actually throw an exception.

Remembering

Container remembering is an awesome feature where the container will remember the objects you passed in and instead of resolving the object over and over again which could possibly be expensive, it will pass in the previous objects that were passed in by storing and retrieving them from a separate remembering list the container builds.

Once an object is resolved for the first time, a new dictionary is built containing that object and it's dependencies. The second time that object is resolved, instead of inspecting the object to see which dependencies it should pass in, Masonite will inject the ones from the remembering dictionary.

This can speed up resolving your code by 10 - 15x. A significant speed improvement.

You can enable this on a per application basis by setting the remembering parameter to True on your container class. This can be found in your wsgi.py file:

Service Providers

Introduction

You may create your own service provider and add it to your providers list to extend Masonite, or even remove some providers if you don't need their functionality. If you do create your own Service Provider, consider making it available on PyPi so others can install it into their framework.

Creating a Provider

We can create a Service Provider by simply using a craft command:

This will create a new Service Provider under our app/providers/DashboardProvider.py. This new Service Provider will have two simple methods, a register method and a boot method. We'll explain both in detail.

Service Provider Execution

There are a few architectural examples we will walk through to get you familiar with how Service Providers work under the hood. Let's look at a simple provider and walk through it.

We can see that we have a simple provider that registers the User model into the container. There are three key features we have to go into detail here.

WSGI

First, the wsgi = False just tells Masonite that this specific provider does not need the WSGI server to be running. When the WSGI server first starts, it will execute all service providers that have wsgi set to False. Whenever a provider only binds things into the container and we don't need things like requests or routes, then consider setting wsgi to False. the ServiceProvider class we inherited from sets wsgi to True by default. Whenever wsgi is True then the service provider will fire the boot method on every request.

Register

In our register method, it's important that we only bind things into the container. When the server is booted, Masonite will execute all register methods on all service providers. This is so the boot method will have access to the entire container.

Boot

The boot method will have access to everything that is registered in the container and is actually resolved by the container. Because of this, we can actually rewrite our provider above as this:

This will be exactly the same as above. Notice that the boot method is resolved by the container.

Provider Methods

Service providers have several methods we can use to help us bind objects into the container.

Commands

We can simply bind commands into the container:

Middleware

We can also bind http and route middleware into the container:

Notice that the route middleware accepts a dictionary and the http middleware accepts a list

Migrations

We can add directories that have migrations easily as well:

Routes

We can also add routes:

Assets

We can also add any directories that have asset files:

Great! It's really that simple. Just this knowledge will take you a long way. Take a look at the other service providers to get some inspiration on how you should create yours. Again, if you do create a Service Provider, consider making it available on PyPi so others can install it into their framework.

Advanced

Autoloading

Introduction

With Masonite 2, we can use the builtin autoloader in order to load classes into the container in a much simpler way.

Configuration

The configuration variable for autoloading is inside the config/application.py file which contains a list of directories:

Out of the box, Masonite will autoload all classes that are located in the app directory which unsurprisingly contains all of the application models.

How It Works

Masonite will go through each directory listed and convert it to a module. For example if given the directory of app/models it will convert that to app.models and fetch that module. It will use inspection to go through the entire module and extract all classes imported or defined.

If your code looks something like:

Then the autoloader will fetch three classes: the belongs_to class, the Model class and the User class. The autoloader will then check if the module of the classes fetched are actually apart of the module being autoloaded.

In other words the modules of the above classes are: orator.orm, config.database and app respectively. Remember that we are just autoloaded the app module so it will only bind the app.User class to the container with a binding of the class name: User and the actual object itself: <class app.User.User>.

All of this autoloading is done when the server is first started but before the WSGI server is ready to start accepting requests so there are no performance hits for this.

Usage

Since the app directory is autoloaded, and our User model is in that directory, the User model will be loaded into the container when the server starts.

All bindings into the Service Container will be the name of the object as the key and the actual object as the value. So the User model will be accessed like:

There is no reason to add models into the container unless your specific use case requires it but this is just an example.

Other Directories

You don't have to keep your models in the app directory. Feel free to move them anywhere but they will not be autoloaded outside the app directory by default. In order to autoload other directories we can add them to the AUTOLOAD variable.

For example if we have an app directory structure like:

Then we can edit our AUTOLOAD variable like so:

And then be able to do:

Being that the container is useful as an IOC container, another use case would be if a third party library needed some models to manipulate and then bind them back into the container. An example of this type of library would be one that needs to change the models methods in order to capture query operations and send them to a dashboard or a report.

Exceptions

The autoload class will raise a few exceptions so you should be aware of them in order to avoid confusion when these exceptions are raised.

InvalidAutoloadPath

This exception will be thrown if any of your autoload paths end with a forward slash like the first element in this list:

Notice the path is now app/ and not app. This will throw an exception when the server first starts.

AutoloadContainerOverwrite

This exception will be thrown when one of your classes are about to overwrite a container binding that is outside of your search path. The search path being the directories you specified in the AUTOLOAD constant.

For example, you may have a model called Request like so:

Without this exception, your application will overwrite the binding of the Masonite Request class.

When Masonite goes to autoload these classes, it will detect that the Request key has already been bound into the container (by Masonite itself). Masonite will then detect if that Request object in the container is within the search path. In other words it will check for a Request class inside the current module you are autoloading.

If the object is outside of the module you are autoloading then it will throw this exception. In this instance, it will throw an exception because the Request key in the container is the <class masonite.request.Request> class which is outside of the app module (and inside the masonite.request module).

If you find yourself hitting this exception then move the object outside of a directory being autoloaded and into a separate directory outside of the autoloader and then you can manually bind into the container with a different key, or simply rename the class to something else. When using models, you can rename the model to whatever you like and then specify a __table__ attribute to connect the model to the specific table.

Annotations

Although it is useful to get the model by the actual container key name, it might not be as practical or even the best way to fetch models from the container.

The recommended approach is to simply fetch the class itself by using annotations so you can adjust the variable name and ensure consistency throughout your application.

Autoload Class

You may also want to autoload classes yourself. This may be useful if building a package and needing to get all classes from a certain location or even all instances from a certain directory.

Class Instances

This might in useful in the Masonite scheduling feature to grab all the classes that are subclasses of the Task class.

Autoloading class instances could look something like:

This will fetch all the classes in the app/models directory that are instances of the Model class. The classes attribute contains a dictionary of all the classes it found.

Class Collecting

If you don't want to get classes that are instances of another class then we can simply collect classes:

Getting Only Application Classes

You may have noticed that this autoload class will actually capture all classes found. These classes include the classes that were imported as well.

The default autoload in the config file only loads application specific classes.

We can only get application specific classes by passing a parameter in:

This will check the namespace on the class found and make sure it is apart of the path that is being searched.

Instantiating Classes

The classes that the autoloader finds are just classes themselves which are uninstantiated. This is great for fetching models but won't be good for fetching other objects like commands. Commands need to be instantiated when they go into the container by design so they can be found by Masonite and cleo.

We can tell the autoloader to instantiate the class by passing another parameter. This will simply instantiate the object without passing any parameters in.

If your class needs parameters then you should collect the classes and instantiate each one individually.

You can see that now all the objects found are instantiated.

Creating a Mail Driver

Introduction

Because of Masonite's Service Container, It is extremely easy to make drivers that can be used by simply adding your service provider.

Getting Started

Masonite comes shipped with a Service Provider called MailProvider which loads a few classes into the container as well as boots the default mail driver using the MailManager. This manager class will fetch drivers from the container and instantiate them. We can look at the MailProvider class which will gives us a better explanation as to what's going on:

We can see here that because we are only binding things into the container and we don't need the WSGI server to be running, we set wsgi = False. Service Providers that set wsgi to False will only run when the server starts and not on every request.

We can see here that we are binding a few drivers into the container and then binding the MailManager on boot. Remember that our boot method has access to everything that has been registered into the container. The register methods are executed on all providers before the boot methods are executed.

Mail Manager

The MailManager here is important to understand. When the MailManager is instantiated, it accepts the container as a parameter. When the MailManager is instantiated, it fires a create_driver method which will grab the driver from the configuration file and retrieve a MailXDriver from the container. The create_driver method is a very simple method:

Notice that when the driver is created, it tries to get a Mail{0}Driver from the container. Therefore, all we need to do is register a MailXDriver into the container ('X' being the name of the driver) and Masonite will know to grab that driver.

Creating a Driver

So now we know that we need a MailXDriver so let's walk through how we could create a maildrill email driver.

We can simply create a class which can become our driver. We do not need to inherit anything, although Masonite comes with a BaseMailDriver to get you started faster and all drivers should inherit from it for consistency reasons. You can make your driver from a normal class object but it will be harder and won't be considered in Pull Requests.

Let's create a class anywhere we like and inherit from BaseMailDriver:

Great! We are almost done. We just have to implement one method on this class and that's the send method. All other methods like to and template are inherited from the BaseMailDriver class. You can find out how to send an email using Maildrill and implement it in this send method.

We can look at other drivers for inspiration but let's look at the MailMailgunDriver class now:

If you are wondering where the self.message_body and self.config are coming from, check the BaseMailDriver. All driver constructors are resolved by the service container so you can grab anything you need from the container to make your driver work. Notice here that we don't need a constructor because we inherited it from the BaseMailDriver

Registering Your Mail Driver

Our AppProvider class might look something like this:

Great! Our new driver is registered into the container. It is now able to be created with Masonite's MailManager class. We can retrieve your new driver by doing:

Configuration

If we want the MailManager to use our new driver by default, change the DRIVER in our config/mail.py file. In addition, you may have the users of your driver require a special dictionary entry to the DRIVERS dictionary:

This way, users can easily swap drivers by simply changing the driver in the config file.

That's it! We just extended our Masonite project and created a new driver. Consider making it available on PyPi so others can install it!

v2.2 LTS

Introduction and Installation

Some Notable Features Shipped With Masonite

Requirements

Linux

Debian and Ubuntu based Linux distributions

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

Installation

Creating Our Project

Activating Our Virtual Environment (optional)

Installing Our Dependencies

Running The Server

Creating a Blog

Preface

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

Showing The Author

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

Prologue

Contributing Guide

Contributing Guide

Introduction

Getting Started

Getting the Masonite repository up and running to be edited

Editing the Masonite core repository

Editing the craft repository (craft commands)

Comments

Types of comments to use

Module Docstrings

Method and Function Docstrings

Methods and Functions with Dependencies

Code Comments

Pull Request Process

Code of Conduct

Our Pledge

Our Standards

Our Responsibilities

Scope

Enforcement

Attribution

How To Contribute

Introduction

Contributing to Development

Editing the craft repository (`craft` commands)