Masonite is the rapid application Python development framework that strives for beautiful and elegant syntax, actual batteries included with a lot of out of the box functionality, and extremely extendable. 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. Try it once and you’ll fall in love.

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.

• Extremely simple static files configured and ready to go

• Create job classes to push to your queues

• Active Record style ORM called Orator

• An extremely useful command line tool called craft commands

These are all shipped out of the box and ready to go. Use what you need when you need it and forget what you don't.

Requirements

In order to use Masonite, you’ll need:

• Python 3.4+

• Pip

Linux

If you are running on a Linux flavor, you’ll need a few extra packages. You can download these packages by running:

$ sudo apt-get install libmysqlclient-dev python-dev

Or you may need to specify your python version

$ sudo apt-get install python3.6-dev

Installation

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

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

$ pip install masonite-cli

You may have to use sudo if you are on a UNIX machine

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

$ craft

This should show a list of command options. We are currently only interested in the craft new command. To create a new project just run:

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

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:

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

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

$ craft install

Let this install all the required dependencies of Masonite. After it’s done we can just run the server by using another craft command:

$ craft serve

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

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 and have as little bugs as possible. Below I will explain how to contribute to this project in different ways.

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 and work and read the documentation starting with the , then the and finally the .

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

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

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

Fix the Documentation

Report Bugs

Squash Bugs

Build a Community

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

Build Community Software Around Masonite

Answer Questions from the Community

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

Review Code on Pull Requests

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.FEATURE/BUGFIX.

This means that a framework version of 1.3.20 will have breaking changes with version 1.4.0.

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 and therefore will follow normal SemVer. 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.

Cycle

Masonite is currently on a 1 month major release cycle. This means that once every month will be a new 1.x release. This 1 month release cycle will continue until Masonite has reached a release that is stable enough to move far into the future with that releases architecture.

Once this stable release has been achieved, Masonite will move to a 6 month major release cycle with minor releases as often as every few days to as much as every few months.

Scheduled Releases

• v1.3 - February 2018

• v1.4 - March 2018

• v1.5 - April 2018

• v1.6 - May 2018

• v2.0 - June 2018

• v2.1 - December 2018

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 cli repository where the craft command tool is located.

Major 1 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.

Whenever the MasoniteFramework/cli 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.

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.

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

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 either a Get() route or a Post() route. At the bare minimum, a route will look like:

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:

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:

It’s important here to recognize that we initialized the controller but only passed a reference to the method and did not actually call the method. This is so Masonite can pass parameters into the method when it executes the route.

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.

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:

It is good convention to name your routes since route url’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:

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

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:

Change Controller Modules

Controllers are defaulted to the app/http/controllers directory but you may wish to completely change the directory for a certain route. We can change this by using the .module() method:

This will look for the controller in thirdparty.package.users module instead of the normal app.http.controllers module.

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:

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:

Route Parameter Options

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.

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:

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

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. To do this we can use the .domain() method on our routes like so:

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 to any subdomain. For this we can pass in an asterisk instead.

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:

Controllers

Introduction

Controllers are a vital part of Masonite and is mainly what differs it from other Python frameworks that implement the MVC structure differently. Controllers are simply classes with methods. These methods take a self parameter which is the normal self that Python class 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 function the exact same way.

Controllers have an added benefit over straight function based views as the developer has access to to a full class they can manipulate however they want but are also not limiting like Django's class based views. They provide a lot of flexibility.

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

$ craft controller DashboardController

When we run this command we now have a new class under app/http/controllers/DashboardController 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 but you can obviously name this class wherever you like.

Defining a Controller Method

Controller methods are very similar to function based views in a Django application except this is just a normal class method. Our controller methods at a minimum should look like:

def show(self):
    pass

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.

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

def show(self, Request):
    print(Request) # Grabbed the Request object from the container

This might look magical to you so be sure the read about the IOC container in the Service Container documentation.

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.

Static Files

Introduction

Masonite tries to make static files extremely easy and comes with whitenoise out of the box. White noise 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 they 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:

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

Now in our templates we can use:

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

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

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

Masonite is the rapid application Python development framework that strives for beautiful and elegant syntax, actual batteries included with a lot of out of the box functionality, and extremely extendable. 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. Try it once and you’ll fall in love.

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.

• Extremely simple static files configured and ready to go

• Create job classes to push to your queues

• Active Record style ORM called Orator

• An extremely useful command line tool called craft commands

These are all shipped out of the box and ready to go. Use what you need when you need it and forget what you don't.

Requirements

In order to use Masonite, you’ll need:

• Python 3.4+

• Pip

Linux

If you are running on a Linux flavor, you’ll need a few extra packages. You can download these packages by running:

$ sudo apt-get install libmysqlclient-dev python-dev

Or you may need to specify your python version

$ sudo apt-get install python3.6-dev

Installation

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

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

$ pip install masonite-cli

You may have to use sudo if you are on a UNIX machine

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

$ craft

This should show a list of command options. We are currently only interested in the craft new command. To create a new project just run:

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

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:

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

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

$ craft install

Let this install all the required dependencies of Masonite. After it’s done we can just run the server by using another craft command:

$ craft serve

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

Helper Functions

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.

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.

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

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

Request

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

is exactly the same as:

View

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

is exactly the same as:

Auth

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

is exactly the same as:

This will return None if there is no user.

Container

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

is exactly the same as:

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.

is exactly the same as:

Resolve

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

is exactly the same as:

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

Service Providers

Introduction

Service Providers are the key building blocks to Masonite. The only thing they do is register things into the Service Container, or retrieve things from the Service Container. You can read more about the Service Container in the documentation. If you look inside the config/application.py file, you will find a PROVIDERS list which contains all the Service Providers involved in building the framework.

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

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.

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 container where classes are loaded into it by key-value pairs, and then can be retrieved by either the key or value. That's it.

The container is contained inside the App class which is instantiated throughout in the beginning of the framework and passed through various parts of the project such as controllers, middleware and drivers.

We can create easily create service providers using a craft command:

$ craft provider DashboardProvider This will create a new service provider in app/providers/DashboardServiceProvider.py. Inside our new service provider we will have a register method and a boot method. It's important to know what each one does. We'll discuss both in a little bit.

Configuration

Once you create your service provider, you'll have to add it to your PROVIDERS list inside your config/application.py file. This should be a string to the location of the class:

Register

The register methods on all service providers are executed first, then all the boot methods are executed after. Because of this, the register method should only be used to load things into the container.

Boot

The boot method is executed on all service providers after the register methods on all service providers have been called. Because of this, the boot method will have access to everything inside the container and is resolved by Masonite's container.

Binding

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 injected into the Request object and can be retrieved by:

Using the container

The container can be used in two ways: making and resolving.

Making

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.

Resolving

This is the most useful part of the container. It is possible to retrieve objects from the container by simply passing them into the parameters. 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.

In this example, Masonite will look inside the container for a key called Request and return that value from the container. Request is already loaded into the container for you out of the box.

Another way to resolve classes is by using Python 3 annotations:

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.

Pretty powerful stuff, eh?

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.

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.

Publishing Packages

Introduction

Publishing packages are a great way for third party packages to integrate into Masonite. They are extremely easy to setup even on existing pip packages. Publishing packages allows any package to create configuration files, routes, controllers, and other integrations that make developing with your packages amazing. You can read about this in the Creating Packages documentation to learn more about how you can integrate your existing packages or future packages with Masonite.

NOTE: Virtual Environment

If you are in a virtual environment,craft publishwill not have access to your virtual environment dependencies. In order to fix this, we can add our site packages to ourconfig/packages.pyconfig file

If you attempt to publish your package without your virtual environment's site_packages file being inside config/packages.py, you will encounter a ModuleNotFound error that says it cannot find the integrations file located with the package you are trying to install. This is because Masonite does not have knowledge of your virtual environments dependencies, only your system dependencies.

If you are in a virtual environment then go to yourconfig/packages.pyfile and add your virtual environments site_packages folder to theSITE_PACKAGESlist. YourSITE_PACKAGESlist may look something like:

SITE_PACKAGES = [
    'venv/lib/python3.6/site-packages'
]

This will allowcraft publishto find our dependencies installed on our virtual environment. Read the Publishing Packages documentation for more information.

Once done, all future packages that you pip install will be available through the publish command. This configuration should be done as soon as your virtual environment is created so you don't encounter any errors while trying to publish packages.

Creating Commands

Introduction

Creating a command is quite simple with Masonite and allows other developers to use your package in the command line similiar to a craft command by running craft-vendor. In this documentation we'll talk about how to create a package that can expand the craft tool by using craft-vendor which comes with the masonite-cli pip package.

Virtual Environments

It's important to note that craft-vendor does not have access to your virtual environment by default, only your system packages. What we can do is add our virtual environment's site_packages directory to our config/packages.py config file which should look something like:

SITE_PACKAGES = [
    'venv/lib/python3.6/site-packages'
]

This will take those paths and temporarily add it to the sys.path for the duration of the craft-vendor command.

Getting Started

The craft command comes with a package helper and can be used to create the boilerplate for Masonite packages. We can use this boilerplate to quickly create a package that can be used on the masonite command line. Lets create our boiler plate now by navigating to a directory we would like to build our package in and run:

$ craft package testpackage

This will create a file structure like:

testpackage/
    __init__.py
    integration.py
MANIFEST.in
setup.py

You can ignore the integration file for now as we won't be using it in this tutorial. This integration file is used to scaffold other Masonite projects (like adding configuration files, controllers, routes etc.)

Commands module

All Masonite packages that would like users to interact with their package via the command line will need a commands module. Let's create one now and make our package structure look like:

testpackage/
    __init__.py
    integration.py
    commands/
        __init__.py
        testpackage.py
MANIFEST.in
setup.py

Craft Vendor Commands

The craft-vendor command is separate from our normal craft command but is primarily for running third party package commands. This is apart of the masonite-cli package.

How the craft-vendor command works is there are three possible commands that can be ran after someone installs your package:

$ craft-vendor testpackage
$ craft-vendor testpackage submodule
$ craft-vendor testpackage submodule function_name

Running craft-vendor testpackage

This allows for some flexibility in how your commands can be ran. Lets start by explaining how the first command will interact with your package.

$ craft-vendor testpackage

When the user runs this command, craft-vendor will look for a package called testpackage. Once it is found, it will look into the commands module and look for a file called testpackage, and then a function in that file called testpackage and execute that function. In this instance, we might have a structure like:

testpackage/
    __init__.py
    integration.py
    commands/
        __init__.py
        testpackage.py
MANIFEST.in
setup.py

and then inside testpackage/commands/testpackage will look like:

def testpackage():
    print('you have just ran the craft-vendor testpackage command')

Running craft-vendor testpackage payment

When the user runs this command, it will find the package called testpackage, look inside the commands module and for a file called payments.py and execute a function called payments. In this instance, we might have a structure like:

testpackage/
    __init__.py
    integration.py
    commands/
        __init__.py
        testpackage.py
        payments.py
MANIFEST.in
setup.py

and then inside testpackage/commands/payments.py will look like:

def payments():
    print('you have just ran the craft-vendor testpackage payments command')

Running craft-vendor testpackage payment stripe

Lastly, When the user runs this command, it will find the package called testpackage, look inside the commands module and for a file called payments.py and execute a function called stripe. In this instance, we might have a structure like:

testpackage/
    __init__.py
    integration.py
    commands/
        __init__.py
        testpackage.py
        payments.py
MANIFEST.in
setup.py

and then inside testpackage/commands/payments.py will look like:

def stripe():
    print('you have just ran the craft-vendor testpackage payments stripe command')

Uploading to PyPi

If you have never set up a package before then you'll need to check how to make a .pypirc file. This file will hold our PyPi credentials.

To upload to PyPi we just have to think of an awesome name for our package and put it in the setup.py file. Now that you have a super awesome name, we'll just need to run:

$ python setup.py sdist upload

which should upload your package with your credentials from your .pypirc file. Make sure you click the link above and see how to make one.

Working With Our Package

We can either test our package locally or upload our package to PyPi.

To test our package locally, if you use virtual environments, just go to your Masonite project and activate your virtual environment. Navigate to the folder where you created your package via the command line and run:

$ pip install .

If you want to be able to make changes without having to constantly reinstall your package then run

$ pip install --editable .

This will install your new package into your virtual environment. Go back to your project root so we can run our craft-vendor command. If we run craft-vendor testpackage we should see the respective print message. Try running all three commands and see the different print output. If you are getting an error of ModuleNotFound and you are inside a virtual environment, don't forget to add the site_packages directory to your config/packages.py by following the instructions at the top of this documentation.

Middleware

Introduction

Middleware is an extremely important aspect of web applications as it allows you to run important code either before or after every request or even before or after certain routes. In this documentation we'll talk about how middleware works, how to consume middleware and how to create your own middleware. Middleware is only ran when the route is found and a status code of 200 will be returned.

Getting Started

Middleware classes are placed inside the app/http/middleware by convention but can be placed anywhere you like. All middleware are just classes that take in a request and contain a before method or an after method.

There are four types of middleware in total:

• Middleware ran before every request

• Middleware ran after every request

• Middleware ran before certain routes

• Middleware ran after certain routes

Creating Middleware

Again, middleware should live inside the app/http/middleware folder and should look something like:

class AuthenticationMiddleware(object):
    ''' Middleware class '''

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

    def before(self):
        pass

    def after(self):
        pass

Middleware constructors are resolved by the container so simply pass in whatever you like in the parameter list and it will be injected for you. Read more about this in the Service Container documentation.

If Masonite is running a “before” middleware, that is middleware that should be ran before the request, Masonite will check all middleware and look for a before method and execute that. The same for “after” middleware.

You may exclude either class if you do not wish for that middleware to run before or after.

This is a boilerplate for middleware. It's simply a class with a before and/or after method. Creating a middleware is that simple. Let's create a middleware that checks if the user is authenticated and redirect to the login page if they are not. Because we have access to the request object, we can do something like:

class AuthenticationMiddleware(object):
    ''' Middleware class which loads the current user into the request '''

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

    def before(self):
        if not self.request.user():
            self.request.redirectTo('login')

    def after(self):
        pass

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

Since we are not utilizing the after method, we may exclude it all together. Masonite will check if the method exists before executing it.

Configuration

We have one of two configuration constants we need to work with. These constants both reside in our config/middleware.py file and are HTTP_MIDDLEWARE and ROUTE_MIDDLEWARE.

HTTP_MIDDLEWARE is a simple list which should contain an aggregation of your middleware classes. This constant is a list because all middleware will simply run in succession one after another, similar to Django middleware

Middleware is a string to the module location of your middleware class. If your class is located in app/http/middleware/DashboardMiddleware.py then the value we place in our middleware configuration will be a string: app.http.middleware.DashboardMiddleware.DashboardMiddleware. Masonite will locate the class and execute either the before method or the after method.

In our config/middleware.py file this type of middleware may look something like:

HTTP_MIDDLEWARE = [
    'app.http.middleware.DashboardMiddleware.DashboardMiddleware'
]

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

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

from app.http.middleware.RouteMiddleware import RouteMiddleware

ROUTE_MIDDLEWARE = {
    'auth': 'app.http.middleware.RouteMiddleware.RouteMiddleware'
}

Consuming Middleware

Using middleware is also simple. If we put our middleware in the HTTP_MIDDLEWARE constant then we don't have to worry about it anymore. It will run on every successful request, that is when a route match is found from our web.py file.

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

Get().route('/dashboard', 'DashboardController@show').name('dashboard').middleware('auth')
Get().route('/login', 'LoginController@show').name('login')

This will execute the auth middleware only when the user visits the /dashboard url and as per our middleware will be redirected to the named route of login

Awesome! You’re now an expert at how middleware works with Masonite.

View Composers and Sharing

Introduction

Very often you will find yourself adding the same variables to a view again and again. This might look something like

def show(self):
    return view('dashboard', {'request': request()})

def another_method(self):
    return view('dashboard/user', {'request': request()})

This can quickly become annoying and it can be much easier if you can just have a variable available in all your templates. For this, we can "share" a variable with all our templates with the View class.

The View class is loaded into our container under the ViewClass alias. It's important to note that the ViewClass alias from the container points to the class itself and the View from the container points to the View.render method. By looking at the ViewProvider this will make more sense:

class ViewProvider(ServiceProvider):

    wsgi = False

    def register(self):
        view = View()
        self.app.bind('ViewClass', view)
        self.app.bind('View', view.render)

As you can see, we bind the view class itself to ViewClass and the render method to the View alias.

View Sharing

We can share variables with all templates by simply specifying them in the .share() method like so:

ViewClass.share({'request': request()})

The best place to put this is in a new Service Provider. Let's create one now called ViewComposer.

$ craft provider ViewComposer

This will create a new Service Provider under app/providers/ViewComposer.py and should look like this:

class ViewComposer(ServiceProvider):

    def register(self):
        pass

    def boot(self):
        pass

We also don't need it to run on every request so we can set wsgi to False. Doing this will only run this provider when the server first boots up. This will minimize the overhead needed on every request:

class ViewComposer(ServiceProvider):

    wsgi = False

    def register(self):
        pass

    def boot(self):
        pass

Great!

Since we need the request, we can throw it in the boot method which has access to everything registered into the service container, including the Request class.

class ViewComposer(ServiceProvider):

    wsgi = False

    def register(self):
        pass

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

Lastly we need to load this into our PROVIDERS list inside our config/application.py file.

PROVIDERS = [
    # Framework Providers
    ...
    'masonite.providers.ViewProvider.ViewProvider',
    'masonite.providers.HelpersProvider.HelpersProvider',

    # Third Party Providers

    # Application Providers
    'app.providers.UserModelProvider.UserModelProvider',
    'app.providers.MiddlewareProvider.MiddlewareProvider',
    'app.providers.ViewComposer.ViewComposer', # <- New Service Provider
]

And we're done! When you next start your server, the request variable will be available on all templates.

View Composing

In addition to sharing these variables with all templates, we can also specify only certain templates. All steps will be exactly the same but instead of the .share() method, we can use the .compose() method:

def boot(self, ViewClass, Request):
    ViewClass.compose('dashboard', {'request': Request})

Now anytime the dashboard template is accessed (the one at resources/templates/dashboard.html) the request variable will be available.

We can also specify several templates which will do the same as above but this time with the resources/templates/dashboard.html template AND the resources/templates/dashboard/user.html template:

def boot(self, ViewClass, Request):
    ViewClass.compose(['dashboard', 'dashboard/user'], {'request': Request})

Lastly, we can compose a dictionary for all templates:

def boot(self, ViewClass, Request):
    ViewClass.compose('*', {'request': Request})

Note that this has exactly the same behavior as ViewClass.share()

Uploading

Introduction

Very often you will need to upload user images such as a profile image. Masonite let's you handle this very elegantly and allows you to upload to both the disk, and Amazon S3 out of the box. The UploadProvider Service Provider is what adds this functionality. Out of the box Masonite supports the disk driver which uploads directly to your file system and the s3 driver which uploads directly to your Amazon S3 bucket.

You may build more drivers if you wish to expand Masonite's capabilities. If you do create your driver, consider making it available on PyPi so others may install it into their project.

Read the "Creating an Email Driver" for more information on how to create drivers. Also look at the drivers directory inside the MasoniteFramework/core repository.

Configuration

All uploading configuration settings are inside config/storage.py. The settings that pertain to file uploading are just the DRIVER and the DRIVERS settings.

Driver and DRIVERS Settings

This setting looks like:

DRIVER = os.getenv('STORAGE_DRIVER', 'disk')

This defaults to the disk driver. The disk driver will upload directly onto the file system. This driver simply needs one setting which is the location setting which we can put in the DRIVERS dictionary:

DRIVERS = {
    'disk': {
        'location': 'storage/uploads'
    }
}

This will upload all images to the storage/uploads directory. If you change this directory, make sure the directory exists as Masonite will not create one for you before uploading. Know that the dictionary inside the DRIVERS dictionary should pertain to the DRIVER you set. For example, to set the DRIVER to s3 it will look like this:

DRIVER = 's3'

DRIVERS = {
    'disk': {
        'location': 'storage/uploads'
    },
    's3': {
        'client': os.getenv('S3_CLIENT', 'AxJz...'),
        'secret': os.getenv('S3_SECRET', 'HkZj...'),
        'bucket': os.getenv('S3_BUCKET', 's3bucket'),
    }
}

Some deployment platforms are Ephemeral. This means that either hourly or daily, they will completely clean their file systems which will lead to the deleting of anything you put on the file system after you deployed it. In other words, any user uploads will be wiped. To get around this, you'll need to upload your images to Amazon S3 or other asset hosting services which is why Masonite comes with Amazon S3 capability out of the box.

Uploading

Uploading with masonite is extremely simple. We can use the Upload class which is loaded into the container via the UploadProvider Service Provider. Whenever a file is uploaded, we can retrieve it using the normal Request.input() method. This will look something like:

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

And inside our controller we can do:

def upload(self, Upload):
    Upload.driver('disk').store(Request.input('file_upload'))

That's it! We specified the driver we want to use and just uploaded an image to our file system.

This action will return the file system location. We could use that to input into our database if we want:

>>> Upload.driver('disk').store(Request.input('file_upload'))
storage/uploads/new_upload.png

We may also need to get the filename of the upload. If the request input is a file upload, we have some additional attributes we can use:

>>> Request.input('file_upload')
new_upload.png

Lastly, we may need to prepend the file name with something like a uuid or something or even just a normal string. We can do so by using the storePrepend() method:

>>> Upload.driver('disk').store(Request.input('file_upload'), 'prepend_name_')
prepend_name_newupload.png

Uploading to S3

Uploading to S3 is exactly the same. Simply add your username, secret key and bucket to the S3 setting:

DRIVER = 's3'

DRIVERS = {
    'disk': {
        'location': 'storage/uploads'
    },
    's3': {
        'client': os.getenv('S3_CLIENT', 'AxJz...'),
        'secret': os.getenv('S3_SECRET', 'HkZj...'),
        'bucket': os.getenv('S3_BUCKET', 's3bucket'),
    }
}

Make sure that your user has the permission for uploading to your S3 bucket.

Then in our controller:

def upload(self, Upload):
    Upload.driver('s3').store(Request.input('file_upload'))

How the S3 driver currently works is it uploads to your file system using the disk driver, and then uploads that file to your Amazon S3 bucket. So do not get rid of the disk setting in the DRIVERS dictionary.

Request Lifecycle

Introduction

It's important to know the life cycle of the request so you can understand what is going on under the hood in order to write better software. Whenever you have a better understanding of how your development tools work, you will feel more confident as you'll understand what exactly is going on. This documentation will try to explain in as much detail as needed the flow of the request from initiation to execution. To read about how to use the Request() class, read the Requests documentation.

Lifecycle Overview

First Things

The Request() class is in the Masonite package module and is imported and initialized in bootstrap/start.py . The Request()class is initialized at the top of the WSGI server and takes the WSGI environ variable as a dependency. The Request() class will then parse that environ variable into a usable object for Masonite and pass that around down through the frameworks middleware and controllers. If the route to be executed is an API route, Masonite will load the request into the API class so that it can parse the URI and determine which CRUD operation to perform. After all the middleware, controllers and routes have touched the request object, Masonite will determine if the user, at any point, wants to redirect. See the Requests documentation about how redirecting works.

If the request object will be redirecting to a named route, it will cycle through all the routes, locate the route with the name specified, and execute that route. If the request object will be redirecting to a url, it will simply throw a 302 response and send the URI as the Location header on the response. If the user is not being redirected, meaning the redirect method has never been called on the request object, then the response will be a 200 and the data will show as normal.

Initialization

The request object is initialized at the top of the WSGI server and simply takes the environ variable, which is passed with all WSGI servers and hold information about: the request, server, URI, request method etc. The request object will then parse the environ and store them into certain class attributes. The request object has several methods that assist in extracting these attributes into usable and memorable methods. Read more about how to use the request object in the "Requests" documentation.

Requests in Middleware

The request object is sent into middleware and is subject to change there. Any changes to the request object in middleware classes will change the request object for the rest of there workflow. For example, Masonite comes with a LoadUser middleware which checks the current user and loads them into the request. This is commented out by default since not all projects need to connect to a database.

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, 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 is passed into middleware classes in the constructor so all middleware should load it into the class. Read more about how middleware works in the Middleware documentation.

Requests in the API

Masonite comes with a built in API system for testing and personal development. It is not yet ready for production and lacks several authentication features.

The request object that is loaded in the API class will check the base URI and then execute CRUD operations based on the URI. As a developer, you are not responsible for manipulating the request object in your API classes.

Requests and Redirecting

Towards the end of the request lifecycle, Masonite will check if Masonite should redirect the user. This happens whenever the redirecting methods are exectuted on the request object. If the user wants to redirect to a named route, Masonite will loop through all the routes inside routes/web.py and check all the route names. If a name matches, it will execute that route. If the route requires parameters (such that a route has a @variable in the route URI) then you will need to pass the .send() method when redirecting. More about request redirecting in the Requests documentation.

If the user is redirecting to a normal URL, it will not check any routes. The request will then send a 302 response and redirect the user to the route specified.

Not Redirecting

If the request is not redirecting, then it will return a 200 status code response and simply show the output needed. This output will come from the controller.

Finally, the data returned from the controller is then passed into the return statement so the WSGI server can interpret it.

Email

Introduction

Masonite comes with email support out of the box. Most applications will need to send email upon actions like account creation or notifications. Because email is used so often with software applications, masonite provides mail support with several drivers.

Getting Started

All mail configuration is inside config/mail.py and contains several well documented options. There are several built in drivers you can use but you can make your own if you'd like. You can follow the documentation here at Creating a Mail Driver. If you do make your own, consider making it available on PyPi so others can install it. We may even put it in Masonite by default.

By default, Masonite uses the smtp driver. Inside your .env file, just put your smtp credentials. If you are using Mailgun then switch your driver to mailgun and put your Mailgun credentials in your .env file.

Configuring Drivers

There are two drivers out of the box that masonite uses and there is a tiny bit of configuration for both.

SMTP Driver

The SMTP driver takes several configuration files we can all put in our .env file.

MAIL_DRIVER=smtp
MAIL_FROM_ADDRESS=admin@email.com
MAIL_FROM_NAME=Masonite
MAIL_HOST=smtp.gmail.com
MAIL_PORT=465
MAIL_USERNAME=admin@email.com
MAIL_PASSWORD=password

Because this is SMTP, we can utilize all SMTP services such as mailtrap and gmail.

Thats it! As long as the authentication works, we can send emails. Remember that it is save to put sensitive data in your .env file because it is not committed to source control and it is inside the .gitignore file by default.

Mailgun Driver

Mailgun does not use SMTP and instead uses API calls to their service to send emails. Mailgun only requires 2 configuration settings:

MAIL_DRIVER=mailgun
MAILGUN_SECRET=key-xx
MAILGUN_DOMAIN=sandboxXX.mailgun.org

as well as changing the DRIVER inside config/mail.py

DRIVER = 'mailgun'

Masonite will retrieve the configuration settings for the mailgun driver from the DRIVERS configuration setting which Masonite has by default, you do not have to change this.

DRIVERS = {
    ...
    'mailgun': {
        'secret': os.getenv('MAILGUN_SECRET', 'key-XX'),
        'domain': os.getenv('MAILGUN_DOMAIN', 'sandboxXX.mailgun.org')
    }
}

Sending an Email

The Mail class is loaded into the container via the the MailProvider Service Provider. We can fetch this Mail class via our controller methods:

def show(self, Mail):
    print(Mail) # returns the default mail driver

We can send an email like so:

def show(self, Mail):
    Mail.to('hello@email.com').send('Welcome!')

All mail drivers are managed by the MailManager class and bootstrapped with the MailProvider Service Provider. Let's take a look at that:

class MailProvider(ServiceProvider):

wsgi = False

def register(self):
    self.app.bind('MailConfig', mail)
    self.app.bind('MailSmtpDriver', MailSmtpDriver)
    self.app.bind('MailMailgunDriver', MailMailgunDriver)
    self.app.bind('MailManager', MailManager(self.app))

def boot(self, MailConfig):
    self.app.bind('Mail',     MailManager(self.app).driver(MailConfig.DRIVER))

We can specify which driver we want to use. Although Masonite will use the DRIVER variable in our mail config file by default, we can change the driver on the fly.

You can see in our MailProvider Service Provider that we can use the MailManager class to set the driver. We can use this same class to change the driver:

def show(self, MailManager):
    MailManager.driver('mailgun') # now uses the Mailgun driver

Queues

Sending an email may take several seconds so it might be a good idea to create a Job. Jobs are simply Python classes that inherit from the Queueable class and can be pushed to queues or ran asynchronously. This will look something like:

from app.jobs.SendWelcomeEmail import SendWelcomeEmail

def show(self, Queue):
    Queue.push(SendWelcomeEmail)

Instead of taking seconds to send an email, this will seem immediate and be sent using whatever queue driver is set. The async driver is set by default which requires no additional configuration and simply sends jobs into a new thread to be ran in the background.

Read more about creating Jobs and sending emails asynchronously in the "Queues and Jobs" documentation.

Methods

We can specify which driver we want to use. Although Masonite will use the DRIVER variable in our config file, we can change the driver on the fly.

We can also specify the subject:

Mail.subject('Welcome!').to('hello@email.com').send('Welcome!')

You can specify which address you want the email to appear from:

Mail.send_from('Admin@email.com').to('hello@email.com').send('Welcome!')

Templates

If you don't want to pass a string as the message, you can pass a view template.

Mail.to('idmann509@gmail.com').template('mail/welcome').send()

This will render the view into a message body and send the email as html. Notice that we didn't pass anything into the send message

Database Migrations

Introduction

Database migrations in Masonite is very different than other Python frameworks. Other Python frameworks create migrations based on a model which historically uses Data Mapper type ORM's. Because Masonite uses an Active Record ORM by default, Migrations are completely separated from models. This is great as it allows a seamless switch of ORM's without interfering with migrations. In addition to creating this separation of migrations and models, it makes managing the relationship between models and tables extremely basic with very little magic which leads to faster debugging as well as fewer migration issues.

In this documentation, we'll talk about how to make migrations with Masonite.

Getting Started

Because models and migrations are separated, we never have to touch our model in order to make alterations to our database tables. In order to make a migration we can run a craft command:

This command will create a migration for an existing table. A migration on an existing table will migrate into the database in a certain way so it's important to specify the --table flag in the command.

In order to create a migration file for a new table that doesn't yet exist (but will after the migration) you can instead use the --create flag like so:

This will create a migration that will create a table, as well as migrate the columns you specify.

Migrating Columns

Inside the migration file you will see an up() method and a down() method. We are only interested in the up() method. This method specifies what to do when the migration file is migrated. The down() method is what is executed when the migration is rolled back. Lets walk through creating a blog migration.

We can use in order to build our migration file. First lets run a migration craft command to create a blog table:

This will create a migration file located in databases/migrations . Lets open this file and add some columns.

After we open it we should see something an up() method that looks like this:

Inside our with statement we can start adding columns.

Lets go ahead and add some columns that can be used for a blog table.

Ok let's go ahead and break down what we just created.

Foreign Keys

So adding columns is really straight forward and Orator has some great documentation on their website. In order to add a foreign key, we'll need an unsigned integer column which we specified above called:

This will set up our column index to be ready for a foreign key. We can easily specify a foreign key by then typing

What this does is sets a foreign key on the user_id column which references the id column on the users table. That's it! It's that easy and expressive to set up a foreign key.

Changing Columns

There are two types of columns that we will need to change over the course of developing our application. Changing columns is extremely simple. If you're using MySQL 5.6.6 and below, see the caveat below.

To change a column, we can just use the .change() method on it. Since we need to create a new migration to do this, we can do something like:

and then simply create a new migration but use the .change() method to let Masonite you want to change an existing column instead of adding a new one:

When we run craft migrate it will change the column instead of adding a new one.

Changing Foreign Keys Prior to MySQL 5.6.6

Because of the constraints that foreign keys put on columns prior to MySQL 5.6.6, it's not as straight forward as appending a .change() to the foreign key column. We must first:

• drop the foreign key relationship

• change the column

• recreate the foreign key

We can do this simply like so:

Validation

Introduction

Very often you will find a need to validate forms after you have submitted them. Masonite comes with a very simple and reusable way to validate input data with the Masonite Validator() class. In this documentation, we'll talk about how you can create your own validator to use within your project. Masonite uses the validator.py library for this feature.

Getting Started

The best way to create a reusable validator class within your Masonite project is to create a class and inherit from the Validator class inside the masonite.validator module.

We can make a class called RegistrationValidator(), inherit from masonite.validator.Validator() and put it inside app/validators/RegistrationValidator.py like so:

Awesome! By inheriting from Validator, this will add several key methods to our validator class that we'll need to verify our request input which we'll talk about below.

Starting Our Validations

Since we inherited from Validator, we have access to a validate() method which we can call with self.validate(). Inside this method call, we can use some useful attributes in order to check our request data.

An example of a simple validation will look something like:

Custom Error Messages

By default, Masonite will supply you with a dictionary of errors depending on the validator class. More information on what the default error messages are found below.

Although this is very convenient, you may wish to specify your own error messages. To do so, we can call the self.messages() method after we validate. This will look like:

This will change the default error messages to the defaults provided. If you do not specify a custom error message for a validation field then the default one will display as usual.

Requests

In order to check the input data we receive from a request, such as a form submission, we can use this validator like so:

Notice that we pass in the request inside the constructor of our RequestValidator class. Our class is using the constructor inherited from Masonite's Validator class.

Non Requests

Sometimes we may wish to use our validator class without request data. In order to do this we can just pass a dictionary of values into our .check() method like so:

Notice how we passed a dictionary into our .check() method here and didn't pass the request object in the constructor.

Validator Options

There are a plethora of options that you can use to validate your forms. In addition to validating your request input, we also get a dictionary of errors. In order to get the errors if a validation fails, we can get use the method:

This method will return a dictionary of errors that will be different depending on the validation class used but this method will return None if there are no errors. Below each option will be what the value of .errors() will be as well as how you would use them inside Masonite.

Required

By default, all keys registered for validation are optional. Any key that doesn't exist in the validation will skip any of the missing input data. For example, if a validation is not set for password then it will simply not check any validation on that specific request input. In this case, we can leave our password validation out entirely.

Unlike other validator classes, this class does not need to be instantiated (contain parenthesis at the end). So Required is the correct usage and not Required().

Usage

Error

Truthy

The Truthy() validator class will check whatever is truthy to Python. This includes True, non-0 integers, non-empty lists, and strings

Usage

Error

Equals

This validator will check that a value is equal to the value given.

Usage

Error

Note that all request input data will be a string. so make sure you use Equals('1') and not Equals(1). Just be sure to maintain the data type in your validation.

Range

This validator checks that the dictionary value falls inclusively between the start and end values passed to it.

Error

Pattern

The Pattern validator checks that the dictionary value matches the regex pattern that was passed to it.

Usage

Error

Since Orator returns a collection, we can specify an Orator Collection as well:

Error

Not

This validator negates a validator that is passed to it and checks the dictionary value against that negated validator.

Usage

Error

InstanceOf

This validator checks that the dictionary value is an instance of the base class passed to it, or an instance of one of its subclasses.

Usage

Error

SubclassOf

This validator checks that the dictionary value inherits from the base class passed to it. To be clear, this means that the dictionary value is expected to be a class, not an instance of a class.

Usage

Error

Length

This validator checks that value the must have at least minimum elements and optionally at most maximum elements.

Usage

Error

Compiling Assets

Introduction

Understanding that modern frameworks need to handle modern web applications. Many developers are starting to use third party packages, like Sass, to write CSS. Normally, many people who write Sass in other frameworks will need to run other third party services like Webpack or grunt. Masonite tries to make this as simple as possible and comes with Sass built in. So you just need to write Sass and it will compile into CSS when you run the server.

Getting Started

Now although Masonite comes with the ability to compile Sass, it is deliberately missing the libsass dependency. This dependency takes several minutes to install and therefore was left out of the requirements to speed up the process of creating a new project.

Masonite can compile all of your Sass into CSS files when you run the server. The code needed to compile Sass is already inside the framework although it does not execute without libsass .

In order to activate this feature we can run:

Awesome! We're good to go. All Sass put inside resources/static will compile into resources/compiled .

Configuration

Masonite comes with a configuration file that will allow you to tweak the locations of files that Sass will be looked for, as well as where it will compile into. This setting page can be found in config/storage.py . The configuration constant looks something like:

ImportFrom Setting

This setting will look for base .sass and .scss files. Base Sass files are files without a preceding underscore. So style.scss is a base Sass file but _dashboard.scss is not. Once all the base Sass files are found, it will compile them into CSS and put them in the location specifed in the compileTo setting.

IncludePaths Setting

This setting is where Masonite will look for files anytime you want to include using the @include keyword in your sass files. Without the correct location here, Masonite will not find any files you include in your Sass files. This setting can be a list of directory locations.

CompileTo Setting

This setting specifies a single directory you want all of your Sass compiled down into.

This is all setup by default for you and works as soon as you install the libsass dependency.

Encryption

Introduction

Masonite comes with bcrypt out of the box but leaves it up to the developer to actually encrypt things like passwords. You can opt to use any other hashing library but bcrypt is the standard of a lot of libraries and comes with some one way hashing algorithms with no known vulnerabilities. Although, many of hashing algorithms like SHA-1 and MD5 are not secure and you should not use them in your application. You can read the .

Background

Also, we make sure that Javascript cannot read your cookies. It's important to know that although your website may be secure, you are susceptible to attacks if you import third party Javascript packages (since those libraries could be hackable) which can read all cookies on your website and send them to the hacker.

Other frameworks use cryptographic signing which attached a special key to your cookies that prevents manipulation. This does't make sense as a major part of XSS protection is preventing third parties from reading cookies. It doesn't make sense to attach a digital signature to a plaintext cookie if you don't want third parties to see the cookie (such as a session id). Masonite takes one step further and encrypts the entire string and can only be decrypted using your secret key (so make sure you keep it secret).

Secret Key

In your .env file, you will find a setting called KEY=your-secret-key. This is the SALT that is used to encrypt and decrypt your cookies. It is important to change this key sometime before development. Masonite does not currently set this key for you. You can generate new secret keys by running:

This will generate a new key in your terminal which you can copy and paste into your .env file. Your config/application.py file uses this environment variable to set the KEY configuration setting.

Remember to not share this secret key as a loss of this key could lead to someone being able to decrypt any cookies set by your application. If you find that your secret key is compromised, just generate a new key.

Cryptographic Signing

You can use the same cryptographic signing that Masonite uses to encrypt cookies on any data you want. Just import the masonite.sign.Sign class. A complete signing will look something like:

By default, Sign() uses the encryption key in your config/applicaiton.py file. You could also pass in your own key.

Just remember to store the key you generated or you will not be able to decrypt any values that you encrypted.

Using bcrypt

Bcrypt is very easy to use an basically consists of a 1 way hash, and then a check to verify if that 1 way hash matches an input given to it. It's important to note that any values passed to bcrypt need to be in bytes.

Hashing Passwords

Again, all values passed into bcrypt need to be in bytes so we can has a password

Notice that the value passed in from the request was converted into bytes using the bytes() Python function.

Once the password is hashed, we can just safely store it into our database

Do not store unhashed passwords in your database. Also, do not use unsafe encryption methods like MD5 or SHA-1.

Checking Hashed Passwords

In order to check if a password matches it's hashed form, such as trying to login a user, we can use the bcrypt.checkpw() function:

This will return true if the string 'password' is equal to the models password.

More information on bcrypt can be found by reading it's documentation.

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!

About Drivers

Introduction

Drivers are simply extensions to features that are managed by the Manager Pattern. If we have a UploadManager then we might also create a UploadDiskDriver and a UploadS3Driver which will be able to upload to both the file system (disk) and Amazon S3. In the future if we have to upload to Microsoft Azure or Google Cloud Storage then we simply create new drivers like UploadAzureDriver and UploadGoogleStorage which are very simple to create. Drivers can be as small as a single method or have dozens of methods. The Manager Pattern makes it dead simple to expand the functionality of a Manager and add capabilities to Masonite's features.

Creating a Driver

Let's go ahead and create a simple driver which is already in the framework called the UploadDiskDriver.

If you are creating a driver it can live wherever you like but if you are creating it for Masonite core then it should live inside masonite/drivers. For our UploadDiskDriver we will create the file: masonite/drivers/UploadDiskDriver.py.

We should make a class that looks something like:

Simple enough, now we can start coding what our API looks like. In the endgame, we want developers to do something like this from their controllers:

So we can go ahead and make a store method.

Ok great. Now here is the important part. Our Manager for this driver (which is the UploadManager) will resolve the constructor of this driver. This basically means that anything we put in our constructor will be automatically injected into this driver. So for our purposes of this driver, we will need the storage and the application configuration.

Now that we have our configuration we need injected into our class, we can go ahead and build out the store() method.:

Ok great! You can see that our store() method simply takes the file and write the contents of the fileitem to the disk.

Using Our Driver

So now that our driver is created, we can tell our Manager about it. Our manager will know of all drivers that are inside the Service Container. We can create a new service provider which we can use to register classes into our container. Here is an example of what the UploadProvider will look like:

That's it! Drivers are extremely simple and most drivers you create will be a simple class with a single method or two.

Authentication

Introduction

Masonite comes with some authentication out of the box but leaves it up to the developer to implement. Everything is already configured for you by default. The default authentication model is the app/User model but you can change this in the config/auth.py configuration file.

Configuration

There is only a single config/auth.py configuration file which you can use to set the authentication behavior of your Masonite project. If you wish to change the authentication model, to a app/Company model for example, feel free to do in this configuration file.

Authentication Model

Again the default authentication model is the app/User model which out of the box comes with a __auth__ class attribute. This attribute should be set to the column that you want to authenticate with. By default your app/User model will default to the email column but if you wish to change this to another column such as name, you can do so here. This will lead your model to look like:

All models that should be authenticated in addition to specifying a __auth__ attribute also needs to have a password field as well in order to use the out of the box authentication that comes with Masonite.

Authenticating a Model

If you want to authenticate a model, you can use the Auth facade that ships with Masonite. This is simply a class that is used to authenticate models with a .login() method.

In order to authenticate a model this will look like:

This will find a model with the supplied username, check if the password matches using bcrypt and return the model. If it is not found or the password does not match, it will return False.

Again all authenticating models need to have a password column. The column being used to authenticate, such as a username or email field can be specified in the model using the __auth__ class attribute.

Changing The Authentication Column

You may change the column to be authenticated by simply changing the column value of the __auth__ class attribute. This will look something like:

This will look inside the username column and check that column and password. The authentication column is email by default.

Creating an Authentication System

You may of course feel free to roll your own authentication system if you so choose but Masonite comes with one out of the box but left out by default. In order to scaffold this authentication system you can of course use a craft command:

This will create some controllers, views and routes for you. This command should be used primarily on fresh installs of Masonite but as long as the controllers do not have the same names as the controllers being scaffolded, you will not have any issues.

The views scaffolded will be located under resources/templates/auth.

After you have ran the craft auth command, just run the server and navigate to http://localhost:8000/login and you will now have a login, registration and dashboard. Pretty cool, huh?

Retrieving the Authenticated User

Masonite ships with a LoadUser middleware that will load the user into the request if they are authenticated. Masonite uses the token cookie in order to retrieve the user using the remember_tokencolumn in the table.

Using this LoadUser middleware you can retrieve the current user using:

If you wish not to use middleware to load the user into the request you can get the request by again using the Auth class

Checking if the User is Authenticated

If you would like to simply check if the user is authenticated, Request.user() or Auth(Request).user() will return False if the user is not authenticated. This will look like:

Remember that the Request.user() capability is disabled by default because it currently requires a database connection to work. We can enable this feature by simply uncommented the LoadUserMiddleware inside the config/middleware.py file.

Protecting Routes

Masonite ships with an authentication middleware. You can use this middleware as a route middleware to protect certain routes from non authenticated users. This is great for redirecting users to a login page if they attempt to go to their dashboard.

You can use this middleware in your routes file like so:

By default this will redirect to the route named login. If you wish to redirect the user to another route or to a different URI, you can edit the middleware in app/http/middleware/AuthenticationMiddleware.py

Logging Out a User

If you wish to end the session for the user and log them out, you can do so by using the Auth class. This looks like:

This will delete the cookie that was set when logging in. This will not redirect the user to where they need to go. A complete logout view might look like:

Great! You’ve mastered how Masonite uses authentication. Remember that this is just out of the box functionality and you can create a completely different authentication system but this will suffice for most applications.

About Managers

Introduction

Masonite uses an extremely powerful pattern commonly known as the Manager Pattern; also known as the Builder Pattern. Because Masonite uses classes with the XManager namespace, we will call it the Manager Pattern throughout this documentation.

Think of the Manager Pattern as attaching a Manager to a specific feature. This Manager is responsible for instantiating FeatureXDriver classes. For example, we attach a UploadManager to the upload feature. Now the UploadFeature will instantiate UploadXDriver classes.

For an actual example inside Masonite, there are currently two classes for the Upload feature: UploadDiskDriver and UploadS3Driver. Whenever we set the DRIVER in our config/storage.py file to s3, the UploadManager will use the UploadS3Driver to store our files.

This is extremely useful for extending functionality of the managers. If we need to upload to Google, we can just make a UploadGoogleDriver and put it inside the container. If we set our configuration DRIVER to google, our UploadManager will now use that class to store files.

Creating a Manager

Masonite obviously comes with several managers such as the UploadManager and the MailManager. Let's walk through how to create a new manager called the TaskManager.

Managers can live wherever they want but if you are developing a manager for the Masonite core package, they will be placed inside masonite/managers.

Let's create a new file: masonite/managers/TaskManager.py.

Great! Now all managers should inherit from the masonite.managers.Manager class. Our TaskManager should look something like:

Awesome! Inheriting from the Manager class will give our manager almost all the methods it needs. The only thing we need now is to tell this manager how to create drivers. So do to this we need a create_driver() method.

Perfect. Now the logic of this create driver should be pretty straight forward and should be almost identical to all other managers because we are simply instantiating drivers with different namespaces:

Ok so that was a bit of code. Although it's pretty straight forward, let's explain what's happening here.

So if the driver doesn't exist, we need to create a new driver depending on what's inside the configuration file loaded inside the container. This makes sense because we need to create a driver based off of something. If the developer didn't supply us with one then we need to grab it from the configuration file. Since we are using TaskConfig here we will eventually have to load it into the container. In a Service Provider, this might look something like:

So we will need to load that into the Service Container in order for this manager to work. We will create a Service Provider later on but for now just know that that's where we get that configuration from. We also capitalize the string to ensure consistency across drivers.

Next we simply call the TaskXDriver from the container and set that as the driver we want to manage which is done by setting the manage_driver class attribute.

If we cannot find the driver in the container then we have a KeyError and we call the DriverNotFound exception which we imported above. This is only called when the DRIVER we set in our configuration does not have a corresponding driver inside the container. For example if the developer sets DRIVER='todo' and we have not set the TaskTodoDriver

Using Our Manager

Great! We can put this Service Provider in our app/application.py file inside the PROVIDERS list. Once that is inside our providers list we can now use this new Task alias in our controllers like so:

Contributing Guide

Introduction

When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners or contributors of this repository before making a change.

Please note we have a code of conduct, please follow it in all your interactions with the project.

Getting Started

The framework has three main parts.

• This official MiraFramework/masonite repository is where most work will be done, primarily in the develop or release branches. This is the main repository that will install when creating new projects using the craft new command.

• The `MiraFramework/core repository where the main masonite pip package lives.

  • This is where the from masonite ... module lives.

• The MiraFramework/cli repository where the craft command lives

Getting this repository up and running to be edited

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)

• 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 (change-default-orm) 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.

Editing the cli 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/cli repo,

• Clone that repo into your computer:

  • git clone http://github.com/your-username/cli.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 cli (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:

Method and Function Docstrings

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

For example:

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:

Flagpole Comments

Flag pole comments are a fantastic way to give developers an inside to what is really happening and for now should only be reserved for configuration files. A flag pole comment gets its name from how the comment looks

It's important to note that there should have exactly 75 - above and below the header and have a trailing | at the bottom of the comment.

Pull Request Process

1. Ensure any changes are well commented and any configuration files that are added have a flagpole comment on the variables it's setting.

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

3. Must add unit testing for any changes made. Of the three repositories listed above, only the cli and core repos require unit testing.

5. The PR must pass the Travis CI build. The Pull Request can be merged in once you have the sign-off of two other collaborators, or the feature maintainer for your specific feature improvement or the repo owner.

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