Masonite 2.3 to 3.0
Masonite 2.3 to 3.0
This guide is designed to give you as much information as possible to upgrade your application from Masonite 2.3 to Masonite 3.0.
We will go through each new breaking change in Masonite and code examples on how to upgrade the code to use Masonite 3. If there is any code breaking during the upgrade, please go to our Slack channel and let us know so we can add more information to this documentation.
This document will be broken down into 2 parts, upgrading from Orator to Masonite and upgrading from Masonite 2.3 to 3.0.
Before you go through this document it is highly recommended that you read Whats New in Masonite 3.
Note that there are some large changes from 2.3 to 3.0. Depending on the size of your project it might make more sense to rebuild your project and port your code to a new Masonite 3 app. This guide is for changing your existing projects.
Upgrading Masonite
Requirement Changes
We need to uninstall some packages and install some others
First uninstall masonite and orator and install masonite 3:
That should be all you need to get the requirements up to date.
At this point Masonite will not work because our codebase is not updated to work with Masonite 3
Now we can start changing the application to get our app to run again.
Request init Offset
The request class is now not even initialized until a request is sent. Previously the request class acted as a singleton but it is now a new class that is initialized on every request. Because of this change, any place you previously had been fetching the request class before the request is sent will no longer work. This could be in several places but is likely most common to be in any class __init__
methods that are initialized before a request was sent, like in a service provider where the wsgi
attribute is False
.
Headers On Response
The response headers are now set on the response class. This makes much more sense now. Previously we set them on the request class which really didn't make sense.
Any place in your code where you want a header to be on the response. The code changes may look something like this:
Should now be written as:
HTTP Header Prefix.
Some headers used to have to be prefixed as HTTP_
to be used correctly. This is no longer required. Code where you have done this:
Can be changed to:
Status Codes
Status codes used to be set on the request class but is now set on the response class. The method and uses are the same:
Should be changed to:
New Providers
Because of the request singleton change we had to offset some other instantiation so we added 2 new providers you need to add. The placement of the RequestHelpersProvider
and CsrfProvider
needs to be between the AppProvider
and the RouteProvider
. The change is in the config/providers.py
file.
We also need to add the orm provider from Masonite ORM. It doesn't really matter where add this so we can add it at the bottom of the list somewhere:
WSGI.py File Change
There used to be a bootstrap/start.py
file in Masonite apps. This file contained a method was used to handle the request and response lifecycle. There was no reason to keep the method inside the application since it was such a low level method and was crucial for the framework to work.
So we need to import the method from the Masonite codebase instead of the start.py file. We also renamed the method response_handler
instead of app
Craft File
You may not have to make this change but in some previous versions of Masonite, the craft file that came with new projects was wrong. The file is called craft
and is in the root of your project directory. If the changes with the + sign already exist then your project is correct. If you have the code in strikethrough then make this diff change:
Queue Table
If you use Masonite queues, there are 3 new columns on the queue_jobs
table. Please make a migration and add these 3 columns:
First make the migration
Then add the migration:
Then run the migration
Dropped route helpers
If you used any helper routes inside your web.py file, these have been removed. You will now need to use only route classes:
If you have code inside your web.py
You will need to remove this import and use the class based routes:
This applied for the helpers: get
, post
, put
, patch
, delete
and group
helpers.
Flashed Messages
In previous versions of Masonite, Masonite would set flashed messages for a 2 second expiration time. This caused numerous different issues like what happens when a page redirection took longer than 2 seconds or what happens when the client times are not synced correctly.
Now we have took a "get and delete" approach. So now the flash data is deleted when it is retrieved. This means that flash data can stay in session until it is fetched.
To do this we have a new method for the "get and delete" of flash data.
If you are using the bag()
helper in your templates then this:
If you are using the session()
helper than you will need to take a similiar approach:
Upgrading Orator
For upgrading from Orator to Masonite please read the Orator to Masonite ORM guide
Last updated