UserFrosting 5 is the culmination of two years of work. It is a complete rewrite of the backend PHP code. And by complete, we really mean complete. No class was left untouched! The key points are :
The Slim migration itself is a big deal. While brining UF to a more modern era, it had the most impact on the core changes applied to the UserFrosting framework. Most changes were made in response to the new Slim 4 requirements and changes. It also required the use of a new Dependency Injector, which itself really brought UserFrosting 5 to a whole new level. You should really check out PHP-DI, it's awesome!
Basically, UserFrosting 5 uses updated dependencies, all of existing code have been updated to new standard and new test coverage should provide better long term stability.
UserFrosting 5 is not a drop-in replacement for UserFrosting 4. The whole backend has been rewritten, with a new container, new sprinkle system, etc. which will require most sprinkle and app to be updated manually.
UserFrosting 5 keeps the same frontend as UserFrosting 4. But the bases have been set for the future, with Webpack Encore and the current AdminLTE theme have been separated in it's own Sprinkle, all of which provides the necessary tools for Vue.js or other similar frontend in the future.
The database structure is 99% identical to UserFrosting 4. One migration have been added, but it's a simple, optional even, modification. This means your data shouldn't be impacted by the upgrade.
With the release of PHP 8 in november 2020 some major updates where made to the system requirements. UserFrosting 5 now requires :
While any version of PHP 8 is supported, we recommend you use the latest version.
This is where all the magic happened. The new structure introduced in UserFrosting 5 makes it even more easier to separate your code from UserFrosting's code. This also makes it easier for new developer to get started with UserFrosting. Upgrading will also be easier, as everything is now managed by Composer. Requesting a new major version will required to edit your composer.json file. Finally, default pages and content are not part of the Core Sprinkle anymore. This makes easier to overwrite default pages.
The old directory structure looked like this:
├── app/
├── cache/
├── database/
├── logs/
├── sessions/
├── sprinkles/
├── account/
├── admin/
├── core/
└── yourSprinkle/
├── assets/
├── config/
├── locale/
├── routes/
├── schema/
├── src/
├── Bakery/
├── Controllers/
├── Database/
├── [...]
└── Sprunje/
├── templates/
├── tests/
├── composer.json
└── asset-bundles.json
├── storage/
├── system/
├── tests/
├── .env
├── defines.php
└── sprinkles.json
├── public/
├── vendor/
└── composer.jsonThe new structure looks like this:
├── app/
├── assets/
├── cache/
├── config/
├── database/
├── locale/
├── logs/
├── schema/
├── src/
├── Bakery/
├── Controllers/
├── Database/
├── [...]
├── Routes/
├── Sprunje/
└── yourSprinkle.php
├── storage/
├── templates/
├── tests/
└── .env
├── public/
├── vendor/
├── account/
├── admin/
└── core/
├── composer.json
├── package.json
└── webpack.config.jsAs you see, since /vendor should be omitted from version control (your Github Repository), the new structure is much more cleaner! This doesn't means your code can't be distributed and added as a sprinkle in another UserFrosting powered app. Community Sprinkle are still a thing! This new structure even makes it easier to develop them!
All bundled Sprinkles are now managed by Composer, and directly required in your project's composer.json. Gone is the app/sprinkles directory. Your app now sits in /app directly and other Sprinkles will now be loaded into the vendor/ directory, like any other dependencies.
Gone is also app/sprinkles.json. To register sprinkles, we now use Sprinkle Recipe. Recipes makes it easier for sprinkle to define other sprinkle as dependencies. In fact, recipe also makes it easier for Sprinkles to register any class and resources they need. UserFrosting 4 used to rely on naming convention and auto-discovery, which was prone to errors. Registering resources also makes the structure more adaptable, as there's no naming convention anymore for classes : The structure of /src can be whatever you want! You can read more about Sprinkle Recipe here.
Finally, as mentioned before, the AdminLTE Theme has been moved to it's own Sprinkle. This will make it easier to switch theme in the future, but also means some reference will need to be updated.
Routes used to be in sprinkles/routes. While still technically PHP files, they were not part of any namespace, and were included using the require() method. Routes are now namespaced, same as any other class in src/.
It also means routes file are not directly overwritten anymore, similar to template files. They're not real classes, and must be mapped, or in case of UserFrosting 5, injected properly.
As mentioned in previous paragraphs, UserFrosting 5 now uses PHP-DI a. This brings a ton of new features and capability. The best way to understand how it affect your code in UserFrosting 5, head over to the Dependency Injection Chapter.
Now that we've cover the basics changes, follow on to the next pages to the steps required to bring your app up to date with UserFrosting 5.