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.

• Service Providers to easily add functionality to the framework.

• Extremely simple static files configured and ready to go.

• Active Record style ORM called Orator.

• An extremely useful command line tool called craft commands.

• Extremely extendable.

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

Requirements

In order to use Masonite, you’ll need:

• Python 3.4+

• Pip

Linux

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

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

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

$ sudo apt-get install python3.6-dev libssl-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

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. If it doesn't then try closing your terminal and reopening it or running it with sudo if you are on a UNIX machine. 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

or if you are on Windows:

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

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

$ craft install

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

$ craft serve

Congratulations! You’ve setup your first Masonite project! Keep going to learn more about how to use Masonite to build your applications. You can learn more about craft by reading The Craft Command documentation.

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 Controllers and Routing work and read the Architectural Concepts documentation starting with the Request Lifecycle, then the Service Providers and finally the Service Container.

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

Become a Feature Maintainer

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

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

Comment the Code

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

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

Write Tests

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

Contribute to Tutorials

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

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

Fix the Documentation

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

Report Bugs

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

Squash Bugs

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

Build a Community

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

Build Community Software Around Masonite

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

Answer Questions from the Community

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

Review Code on Pull Requests

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

Discuss Issues

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

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.

Releases and Release Cycles

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.

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

Scheduled Releases

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

Main Repository and New Projects

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

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

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

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

Introduction

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

Fixed infinite redirection

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

Fixed browser content length

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

Changed how request input data is retrieved

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

Added Upload drivers

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

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

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

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

Added several helper functions

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

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

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

Added a way to have global template variables

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

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

Middleware is now resolved by the container

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

Added new domain method to the Get and Post classes

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

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

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

Added new module method to Get and Post routes

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

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

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

Added Queues and Jobs

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

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 MasoniteFramework/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 `MasoniteFramework/core repository where the main masonite pip package lives.

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

• The MasoniteFramework/craft repository where the craft command lives

Getting this repository up and running to be edited

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

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

• Fork the MasoniteFramework/masonite repo.

• Clone that repo into your computer:

  • git clone http://github.com/your-username/masonite.git

• Checkout the current release branch (example: develop)

• 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 craft repository (craft commands)

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

• Fork the MasoniteFramework/craft repo,

• Clone that repo into your computer:

  • git clone http://github.com/your-username/craft.git

• Activate your masonite virtual environment (optional)

  • Go to where you installed masonite and activate the environment

• While inside the virtual environment, cd into the directory you installed cli

• Run pip install --editable . from inside the masonite-cli directory. This will install craft (which contains the craft commands) as a pip package but also keep a reference to the folder so you can make changes freely to craft commands while not having to worry about continuously reinstalling it.

• Any changes you make to this package just push it to your feature branch on your fork and follow the PR process below.

Comments

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

Types of comments to use

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

Module Docstrings

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

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

Method and Function Docstrings

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

For example:

def some_function(self):
    ''' This is a function that does x action. 
        Then give an exmaple of when to use it 
    '''
    ... code ...

Code Comments

If you're code MUST be complex enough that future developers will not understand it, add a # comment above it

For normal code this will look something like:

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

perform_some_complex_task()

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

'''
|--------------------------------------------------------------------------
| A Heading of The Setting Being Set
|--------------------------------------------------------------------------
|
| A quick description
|
'''

SETTING = 'some value'

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. You should open an issue before making any pull requests. Not all features will be added to the framework and some may be better off as a third party package. It wouldn't be good if you worked on a feature for several days and the pull request gets rejected for reasons that could have been discussed in an issue.

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

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

4. You must add unit testing for any changes made. Of the three repositories listed above, only the craft and core repos require unit testing.

5. Increase the version numbers in any example files and the README.md to the new version that this Pull Request would represent. The versioning scheme we use is SemVer for both core and craft or RomVer for the main Masonite repo.

6. The PR must pass the Travis CI build. The Pull Request can be merged in once you have a successful review from two other collaborators, or 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

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

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.

• Service Providers to easily add functionality to the framework.

• Extremely simple static files configured and ready to go.

• Active Record style ORM called Orator.

• An extremely useful command line tool called craft commands.

• Extremely extendable.

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

Requirements

In order to use Masonite, you’ll need:

• Python 3.4+

• Pip

Linux

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

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

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:

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

This should show a list of command options. If it doesn't then try closing your terminal and reopening it or running it with sudo if you are on a UNIX machine. We are currently only interested in the craft new command. To create a new project just run:

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:

or if you are on Windows:

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

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

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

Introduction

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

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

Broadcast Support

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

Caching

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

Template Caching

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

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

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

PEP 8 Standards

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

Added a New Folder and Configuration File

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

Added Contracts

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

Added CSRF Protection

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

Changed Managers

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

Middleware is now resolved by the container

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

Fixed unused imports

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

Introduction

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

Masonite Entry

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

HTTP Methods

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

Moving Dependencies

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

Changing Form Request Methods

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

Added Shorthand Route Helpers

Removed API from core

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

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

Headers

Cookies

Caching Driver Update

An All New Craft Command

Adding Commands

Adding Migration Directories

Added Sessions

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

Craft Auto Adds Site Packages

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

Introduction

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

Requirements.txt File

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

New Cache Folder

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

New Cache and Broadcast Configuration

Masonite 1.4 brings a new config/cache.py and config/broadcast.py files. These files can be found on the page and can be copied and pasted into your project. Take a look at the new file and the file. Just copy and paste those configuration files into your project.

3 New Service Providers

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

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

CSRF and CSRF Middleware

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

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

Changes to Database Configuration

should now be:

with this change

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:

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:

Route Options

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

HTTP Verbs

There are several HTTP verbs you can use for routes:

HTTP Helpers

If the syntax is a bit cumbersome, you just want to make it shorter or you like using shorthand helper functions, then you can also use these:

These return instances of their respective classes so you can append on to them:

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 URI's can change but the name should always stay the same.

Route Middleware

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

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.

You may also start the controller string with a / which will look for the controller as a global package:

Which will look for the package in the exact same way as before.

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:

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 work in similar ways.

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. In other words, controller methods may utilize class attributes or private methods to break up logic. 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 in app/http/controllers/DashboardController.py called DashboardController. By convention, Masonite expects that all controllers have their own file since it’s an extremely easy way to keep track of all your classes since the class name is the same name as the file 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

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.

Introduction

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

Requirements.txt

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

waitress==1.1.0
masonite>=1.5,<=1.5.99

Site Packages Configuration

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

Api Removal

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

If you are using the Api() route inside routes/api.py for API endpoints then remove this as well. You will need to implement API endpoints using the new Official Masonite Entry package instead.

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

Craft Commands

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

Simply run:

$ pip install --upgrade masonite-cli

Sessions

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

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

''' Session Settings '''

'''
|--------------------------------------------------------------------------
| Session Driver
|--------------------------------------------------------------------------
|
| Sessions are able to be linked to an individual user and carry data from
| request to request. The memory driver will store all the session data
| inside memory which will delete when the server stops running.
|
| Supported: 'memory', 'cookie'
| 
'''

DRIVER = 'memory'

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

PROVIDERS = [
    # Framework Providers
    'masonite.providers.AppProvider.AppProvider',

    # New Provider
    'masonite.providers.SessionProvider.SessionProvider',
    'masonite.providers.RouteProvider.RouteProvider',
    ....
]

Finished

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

Introduction

Views contain all the HTML that you’re application will use to render to the user. Unlike Django, views in Masonite are your HTML templates. All views are located inside resources/templatesdirectory.

All views are rendered with Jinja2 so we can use all the Jinja2 code you are used to. An example view looks like:

<html>
  <body>
    <h1> Hello {{ 'world' }}</h1>
  </body>
</html>

Creating Views

Since all views are located in resources/templates, we can use simply create all of our views manually here or use our craft command tool. To make a view just run:

$ craft view hello

This will create a template under resources/templates/hello.html.

Calling Views

Helper Function

There are several ways we can call views in our controllers. The first recommended way is using the view() function. Masonite ships with a HelpersProvider Service Provider. This provider will add several new built in functions to your project. These helper functions can be used as shorthand for several commonly used classes such as the View and Request class. See the Helper Functions documentation for more information.

One of the helper functions is the view() function which is accessible like any other built in Python function.

We can call views in our controllers like so:

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

This will return the view located at resources/templates/dashboard.html. We can also specify a deeper folder structure like so:

def show(self):
    return view('profiles/dashboard')

This will look for the view at resources/templates/profiles/dashboard.html

From The Container

The View class is loaded into the container so we can retrieve it in our controller methods like so:

def show(self, View):
    return View('dashboard')

This is exactly the same as using the helper function above. So if you choose to code more explicitly, the option is there for you.

Passing Data to Views

A lot of the time we’ll need to pass in data to our views. This data is passed in with a dictionary that contains a key which is the variable with the corresponding value. We can pass data to the function like so:

def show(self, Request):
    return view('dashboard', {'id': Request.param('id')})

This will send a variable named id to the view which can then be rendered like:

<html>
  <body>
    <h1> {{ id }} </h1>
  </body>
</html>

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

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:

class HelpersProvider(ServiceProvider):

    wsgi = False

    def register(self):
        pass

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

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

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

Request

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

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

is exactly the same as:

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

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

View

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

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

is exactly the same as:

def show(self, View):
    return View('template_name')

Auth

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

def show(self):
    auth().id

is exactly the same as:

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

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

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

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

Container

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

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

is exactly the same as:

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

Env

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

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

is exactly the same as:

import os

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

Resolve

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

def some_function(Request):
    print(Request)

def show(self):
    resolve(some_function)

is exactly the same as:

def some_function(Request):
    print(Request)

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

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

Introduction

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

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

Getting Started

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

def show(self, Request):
    # Request is the instance of the Request class
    pass

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

Helper Function

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

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

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

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

Usage

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

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

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

Method Options

Input Data

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

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

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

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

To get a specific input:

# GET: /dashboard?firstname=Joe

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

To check if some request input data exists:

# GET: /dashboard?firstname=Joe

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

Incoming JSON Requests

All data can be retrieved as usual by using the input method above for incoming requests like form requests. Masnoite will handle application/json requests slightly differently. When the incoming request is JSON, masonite will load the JSON into a payload input which will return a dictionary representation of the JSON string.

def show(self, Request):
    return Request.input('payload') # returns {'id': 1, ...}

URL Parameters

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

# GET: /dashboard/Joe

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

Cookies

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

Creating

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

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

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

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

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

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

Reading

You can get all the cookies set from the browser

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

You can get a specific cookie set from the browser

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

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

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

This will return the plain text version of the cookie.

Deleting

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

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

User

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

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

Redirection

You can specify a url to redirect to

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

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

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

You can redirect to a named route

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

You can also go back to a named route specified from the form input back. This will get the request input named back and redirect to that named route. This is great if you want to redirect the user to a login page and then back to where they came from. Just remember during your form submission that you need to supply a back input.

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

This is equivalent to:

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

You can also specify the input parameter that contains the named route

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

Sometimes your routes may require parameters passed to it such as redirecting to a route that has a url like: /url/@firstname:string/@lastname:string. For this you can use the send method. Currently this only works with named routes.

def show(self, Request):
    return Request.back().send({'firstname': 'Joseph', 'lastname': 'Mancuso'})

    return Request.redirectTo('dashboard').send({'firstname': 'Joseph', 'lastname': 'Mancuso'})

Encryption Key

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

Request.key(key)

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

Headers

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

You can get all WSGI information by printing:

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

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

You can also get a specific header:

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

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

We can also set headers:

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

Request.header('AUTHORIZATION', 'Bearer some-secret-key', http_prefix=None)

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

Status Codes

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

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

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

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

Request.status('429 Too Many Requests')

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

Changing Request Methods in Forms

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

This will look like:

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

or you can optionally use a helper method:

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

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

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

from masonite.routes import Patch

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

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

Lifecycle Overview

First Things

All of Masonite is bootstrapped via and is centralized via a . The Request class in binded into the container inside the AppProvider Service Provider which is inside the Masonite pip package. The Request class is initialized and registered into the container before the WSGI server starts. Because of this, the Request class is the same instance throughout the life of the server. In other words, the Request class is a singleton for the life of the WSGI server and is not re-instantiated on each request. On each request, the WSGI server will load the environ variable (the WSGI request details) into the request class which changes the behavior of requests accordingly such as what the URI is or what the request method type is.

Initialization

The request object is initialized in the AppProvider Service Provider and simply takes the environ variable as a dependency 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 documentation.

Requests in Middleware

If one of the middleware has instructed the request object to redirect, the view that is ready to execute, will not execute.

For example, if the user is planned on going to the dashboard view, but middleware has told the request to redirect to the login page instead then the dashboard view, and therefore the controller, will not execute at all. It will be skipped over. Masonite checks if the request is redirecting before executing a view.

Also, the request object can be injected into middleware by passing the Request parameter into the constructor like so:

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

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.

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.

Introduction

It's extremely simple to add commands to Masonite via the craft command tool and Service Providers. If you have been using Masonite for any amount of time you will learn that commands are a huge part of developing web applications with Masonite. We have made it extremely easy to create these commands and add them to craft to build really fast personal commands that you might use often.

Masonite uses the Cleo package for creating and consuming commands so for more extensive documentation on how to utilize commands themselves, how to get arguments and options, and how to print colorful text to the command line.

Getting Started

You can create commands by using craft itself:

This will create a app/commands/HelloCommand.py file with boiler plate code that looks like this:

Let's create a simple hello name application which prints "hello your-name" to the console.

Where it says command:name inside the docstring we can put hello and inside the argument we can put name like so:

Inside the handle method we can get the argument passed by specifying self.argument('name'). Simply put:

That's it! Now we just have to add it to our craft command.

Adding Our Command To Craft

We can add commands to craft by creating a Service Provider and registering our command into the container. Craft will automatically run all the register methods on all containers and retrieve all the commands.

Let's create a Service Provider:

This will create a provider in app/providers/HelloProvider.py that looks like:

Let's import our command and register it into the container. Also because we are only registering things into the container, we can set wsgi = False so it is not ran on every request and only before the server starts:

Adding The Service Provider

Like normal, we need to add our Service Provider to the PROVIDERS list inside our config/application.py file:

That's it! Now if we run:

We will see our new hello command:

and if we run:

We will see an output of:

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 contain a before method and/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:

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.

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 method 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 from the Service Container, we can do something like:

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:

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:

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:

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.

Introduction

The craft command tool is a powerful developer tool that lets you quickly scaffold your project with models, controllers, views, commands, providers, etc. which will condense nearly everything down to it’s simplest form via the craft namespace. No more redundancy in your development time creating boilerplate code. Masonite condenses all common development tasks into a single namespace.

For example, In Django you may need to do something like:

The craft tool condenses all commonly used commands into its own namespace

All scaffolding of Masonite can be done manually (manually creating a controller and importing the view function for example) but the craft command tool is used for speeding up development and cutting down on mundane development time.

Commands

The possible commands for craft include:

Creating an Authentication System

To create an authentication system with a login, register and a dashboard system, just run:

This command will create several new templates, controllers and routes so you don’t need to create an authentication system from scratch, although you can. If you need a custom authentication system, this command will scaffold the project for you so you can go into these new controllers and change them how you see fit.

These new controllers are not apart of the framework itself but now apart of your project. Do not look at editing these controllers as editing the framework source code.

Creating Controllers

If you wish to scaffold a controller, just run:

This command will create a new controller under app/http/controller. By convention, all controllers should have an appended “Controller”. For example in order to make a dashboard controller, you should run craft controller DashboardController and not craft controller Dashboard although you can name your controllers however you like.

Creating a New Project

If you’d like to start a new project, you can run:

This will download a zip file of the MasoniteFramework/masonite repository and unzip it into your current working directory. This command will default to the latest release of the repo.

You may also specify some options. The --version option will create a new project depending on the releases from the MasoniteFramework/masonite repository.

Or you can specify the branch you would like to create a new project with:

After you have created a new project, you will have a requirements.txt file with all of the projects dependencies. In addition to this file, you will also have a .env-example file which contains a boiler plate of a .env file. In order to install the dependencies, as well as copy the example environment file to a .env file, just run:

The craft install command will also run craft key --store as well which generates a secret key and places it in the .env file.

Creating Migrations

All frameworks have a way to create migrations in order to manipulate database tables. Masonite uses a little bit of a different approach to migrations than other Python frameworks and makes the developer edit the migration file. This is the command to make a migration for an existing table:

If you are creating a migration for a table that does not exist yet which the migration will create it, you can pass the --create flag like so:

These two flags will create slightly different types of migrations.

Migrating

After your migrations have been created, edited, and are ready for migrating, we can now migrate them into the database. To migrate all of your unmigrated migrations, just run:

Rolling Back and Rebuilding Migrations

You can also refresh and rollback all of your migrations and remigrate them.

You can also rollback all migrations without remigrating

Lastly, you can rollback just the last set of migrations you tried migrating

Models

If you'd like to create a model, you can run:

This will scaffold a model under app/ModelName and import everything needed.

If you need to create a model in a specific folder starting from the app folder, then just run:

This will create a model in app/Models/ModelName.py.

Creating a Service Provider

Service Providers are a really powerful feature of Masonite. If you'd like to create your own service provider, just run:

This will create a file at app/providers/DashboardProvider.py

Creating Views

Views are simply html files located in resources/templates and can be created easily from running the command:

This command will create a template at resources/templates/blog.html

You can also create a view deeper inside the resources/templates directory.

This will create a view under resources/templates/auth/home.html but keep in mind that it will not create the directory for you. If the auth directory does not exist, this command will fail.

Creating Jobs

Jobs are designed to be loaded into queues. We can take time consuming tasks and throw them inside of a Job. We can then use this Job to push to a queue to speed up the performance of our application and prevent bottlenecks and slowdowns.

Packages

Creating Commands

You can scaffold out basic command boilerplate:

This will create a app/commands/HelloCommand.py file with the HelloCommand class.

Running the WSGI Server

You can run the WSGI server by simply running:

Encryption

To generate a secret key, we can run:

This will generate a 32 bit string which you can paste into your .env file under the KEY setting.

You may also pass the --store flag which will automatically add the key to your .env file:

This command is ran whenever you run craft install

Great! You are now a master at the craft command line tool.

Introduction

The Service Container is an extremely powerful feature of Masonite and should be used to the fullest extent possible. It's important to understand the concepts of the Service Container. It's a simple concept but is a bit magical if you don't understand what's going on under the hood.

Getting Started

The Service Container is just a dictionary where classes are loaded into it by key-value pairs, and then can be retrieved by either the key or value through resolving objects. That's it.

The container holds all of the frameworks classes and features so adding features to Masonite only entails adding classes into the container to be used by the developer later on. This typically means "registering" these classes into the container (more about this later on).

This allows Masonite to be extremely modular.

There are a few objects that are resolved by the container by default. These include your controller methods (which are the most common and you have probably used them so far) driver and middleware constructors and any other classes that are specified in the documentation.

There are four methods that are important in interacting with the container: bind, make and resolve

Bind

In order to bind classes into the container, we will just need to use a simple bind method on our app container. In a service provider, that will look like:

This will load the key value pair in the providers dictionary in the container. The dictionary after this call will look like:

The service container is available in the Request object and can be retrieved by:

Make

In order to retrieve a class from the service container, we can simply use the make method.

That's it! This is useful as an IOC container which you can load a single class into the container and use that class everywhere throughout your project.

Resolve

This is the most useful part of the container. It is possible to retrieve objects from the container by simply passing them into the 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, before the show method is called, Masonite will look at the parameters and look inside the container for a key with the same name. In this example we are looking for Request so Masonite will look for a key inside the provider dictionary called Request and inject that value from the container into our method for us. 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. Think of this as a get by value instead of a get by key like the earlier example.

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 for you.

Because of this, you can resolve any of your own classes or functions.

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.

Introduction

Creating packages is very simple for Masonite. You can get a package created and on PyPi is less than 5 minutes. With Masonite packages you'll easily be able to integrate and scaffold all Masonite projects with ease. Masonite comes with several helper functions in order to create packages which can add configuration files, routes, controllers, views, commands and more.

Getting Started

As a developer, you will be responsible for both making packages and consuming packages. In this documentation we'll talk about both. We'll start by talking about how to make a package and then talk about how to use that package or other third party packages.

Masonite, being a Python framework, can obviously utilize all Python packages that aren’t designed for a specific framework. For example, Masonite can obviously use a library like requests but can’t use Django Rest Framework.

Similarly to how Django Rest Framework was built for Django, you can also build packages specific to Masonite. Although you can just as simply build packages for both, as long as you add some sort of Service Provider to your package that can integrate your library into Masonite.

About Packages

There are several key functions that Masonite uses in order to create applications. These include primarily: routes, controllers, views, and craft commands. Creating a package is simple. Conveniently Masonite comes with several helper functions in order to create all of these.

You can easily create a command like craft mypackage:install and can scaffold out and install controllers, routes, etc into a Masonite project.

You do not have to use this functionality and instead have the developer copy and paste things that they need to from your documentation but having a great setup process is a great way to promote developer happiness which is what Masonite is all about.

Creating a Package

Like other parts of Masonite, in order to make a package, we can use a craft command. The craft package command will scaffold out a simple PyPi package and is fully able to be uploaded directly to PyPi.

This should be done in a separate folder outside of your project.

Let's create our package:

$ craft package testpackage

This will create a file structure like:

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

Creating a Config Package

Lets create a simple package that will add or append a config file from our package and into the project.

First lets create a config file inside testpackage/snippets/configs/services.py. We should now have a project structure like:

testpackage/
    __init__.py
    integration.py
    snippets/
        configs/
            services.py
MANIFEST.in
setup.py

Great! inside the services.py lets put a configuration setting. This configuration file will be directly added into a Masonite project so you can put doctrings or flagpole comments directly in here:

TESTPACKAGE_PAYMENTS = {
    'stripe': {
        'some key': 'some value',
        'another key': 'another value'
    }
}

Perfect! Now we'll just need to tell PyPi to include this file when we upload it to PyPi. We can do this in our MANIFEST.in file.

include testpackage/snippets/configs/*

Creating an Install Command

It's great (and convenient) to add craft commands to a project so developers can use your package more efficiently. You can head over the Creating Commands to learn how to create a command. It only involves a normal command class and a Service Provider.

Head over to that documentation page and create an InstallCommand and an InstallProvider. This step should take less than a few minutes. Once those are created we can continue to the adding package helpers below.

Adding Migration Directories

Masonite packages allow you to add new migrations to a project. For example, this could be used to add a new package_subscriptions table if you are building a package that works for subscribing users to Stripe.

Inside the Service Provider you plan to use for your package we can register our directory:

from masonite.provider import ServiceProvider

package_directory = os.path.dirname(os.path.realpath(__file__))

class ApiProvider(ServiceProvider):

    def register(self):
        self.app.bind(
            'TestPackageMigrationDirectory',
            os.path.join(package_directory, '../migrations')
        )

Masonite will find any keys in the container that end with MigrationDirectory and will add it to the list of migrations being ran whenever craft migrate and craft migrate:* commands are ran.

The package_directory variable contains the absolute path to the current file so the migration directory being added should also be an absolute path to the migration directory as demonstrated here. Notice the ../migrations syntax. This is going back one directory and into a migration directory there.

Package Helpers

Almost done. Now we just need to put our masonite.package helper functions in our install command. The location we put in our create_or_append_config() function should be an absolute path location to our package. To help with this, Masonite has put a variable called package_directory inside the integration.py file. Our handle method inside our install command should look something like:

import os
from cleo import Command
from masonite.packages import create_or_append_config


package_directory = os.path.dirname(os.path.realpath(__file__))

class InstallCommand(Command):
    """
    Installs needed configuration files into a Masonite project

    testpackage:install
    """

    def handle(self):
        create_or_append_config(
            os.path.join(
                package_directory,
                '../testpackage/snippets/configs/services.py'
            )
        )

This will append the configuration file that has the same name as our package configuration file. In this case the configuration file we are creating or appending to is config/services.py because our packages configuration file is services.py. If we want to append to another configuration file we can simply change the name of our package configuration file.

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 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 testpackage:install command. If we run that we should have a new configuration file under config/services.py.

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 pick a great name for our package 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 our package with our credentials in our .pypirc file. Make sure you click the link above and see how to make once.

If python doesn’t default to Python 3 or if PyPi throws errors than you may need to run:

$ python3 setup.py sdist upload

Consuming a package.

Now that your package is on PyPi we can just run:

$ pip install super_awesome_package

Then add your Service Provider to the PROVIDERS list:

PROVIDERS = [
    ...
    # New Provider
    'testpackage.providers.InstallProvider.InstallProvider',
]

and then run:

$ craft testpackage:install

Remember our Service Provider added the command automatically to craft.

Again, not all packages will need to be installed or even need commands. Only packages that need to scaffold the project or something similar need one. This should be a judgment call on the package author instead of a requirement.

You will know if a package needs to be installed by reading the packages install documentation that is written by the package authors.

Helper Functions

These helper functions are used inside the install commands or anywhere else in your package where you need to scaffold a Masonite project.

The location specified as parameters here are absolute path locations. You can achieve this by using the package_directory variable in your integration.py file.

To achieve an absolute path location, this will look like:

location = os.path.join(
            package_directory, 'snippets/configs/services.py'
        )

All helper functions are located in the masonite.packages module. To use these functions you’ll need to import the function to be used like:

from masonite.packages import create_or_append_config

Creating Configuration Files

create_or_append_config(location) will create a configuration file based on a configuration file from your package.

Creating Web Routes

append_web_routes(location) will append web routes to the routes/web.py file. Your web routes should have a += to the ROUTES constant and should look something like:

ROUTES += [
    # your package routes here
]

Creating Api Routes

append_api_routes(location) will append api routes to a masonite project under routes/api.py. Your api routes should have a += to the ROUTES constant and should look something like:

ROUTES += [
    # your package routes here
]

Creating Controllers

create_controller(location) will take a controller from your package and append it under the app.http.controllers namespace by default.

You can also optionally add a to parameter to specify which directory you want to install the controller into. The directory will automatically be created.

create_controller(
    os.path.join(
        package_directory, 'snippets/controller/ControllerHere.py'
    ),
    to = 'app/http/controllers/Vendor/Package'
)

This will create the controller in app.http.controller.Vendor.Package.ControllerHere.py

Introduction

It's common to want to use a Service Provider to add new methods to a class. For example, you may want to add a is_authenticated method to the Request class. Your package and Service Provider may be for a better authentication system.

You may easily extend classes that inherit from the Extendable class. Many of the built in classes inherit from it.

Usage

You have a few options for adding methods to any of the core classes. You can extend a class with functions, classes and class methods. Typical usage may look like:

def is_authenticated(self):
    return self

def show(self, Request):

    Request.extend(is_authenticated)

    print(Request.is_authenticated()) # returns the Request class

Usage is very simple and has several options for extending a class. Notice that we don't call the function but we pass the reference to it.

Extending a function

This will simply add the function as a bound method to the Request class

def is_authenticated(self):
    return self

def show(self, Request):

    Request.extend(is_authenticated)

    print(Request.is_authenticated()) # returns the Request class

Extending a class method

We can also extend a class method which will take the method given and add it as a bound method.

class Authentication:

    def is_authenticated(self):
        return self

def show(self, Request):

    Request.extend(Authentication.is_authenticated)

    print(Request.is_authenticated()) # returns the Request class