Migrate to brezel/api 2.x

Follow any previous migration guides first!

A version bump of multiple major versions might cause problems!

Upgrade to 1.x first (including your production environment!)! Only then move to 2.0.

brezel/api 2.0 brings a lot of underlying changes. Functionally, not much is different, but technically, a lot is new.

We now use PHP 8.4 and Laravel 11 with a bunch of new packages running on an optimized and linted codebase.

Migration steps

To update your project to brezel/api 2.0, follow these steps:

1. Install PHP 8.4 on your development machine
2. Copy over the latest (or the one referenced with “2.0” if you are reading this in the future) project structure (esp. the content of composer.json. Keep your name and version if you want, but the rest is needed) from brezel/brezel. The important bits are (but not limited to):
   • composer.json: copy it over entirely, then adjust name and version and any extra dependencies YOU need specifically. Normally, you don’t need to change any deps related stuff.
   • .env.example: copy it over entirely. Adjust your .env file accordingly.
   • .gitignore: Copy over the entire file
   • gitlab-ci.yml & gitlab folder: Copy them over and re-build your pipelines to be based on the new standards
   • bootstrap/, server.php, bakery.php: Copy over the entire folder and files
   • bin/: Copy over the entire folder
   • In general: In a perfect world, only system/, src/, public/ and potentially app/ (when extending recipes) should contain any custom stuff. The rest is scaffolding and should be copied over / adjusted to be nearly the same as the original. This includes all JS related things (vite.config.js, package.json and so on).
3. Update your project to the latest brezel/api 2.x version by bumping it in your composer.json.
   • You might need to delete vendor/ and composer.lock first.
4. Update your .env file to match the new .env.example file!
5. Run your brezel as usual, and test if everything works.
   • As for the Websocket (brotcast) server: We now ship a new one based on Laravel Reverb. Start it with php bakery brotcast:start (or just regenerate the supervisor config with php bakery make:supervisor and run it).
6. Schedule downtime with your Customer (~2h, minimum)
7. Install PHP 8.4 and set up everything on your production environment (see https://wiki.brezel.io/deploy/virtual_server/ for further instructions)
8. Use the new brotcast service based on Laravel Reverb
   • Adjust your .env and the supervisor config to use the new, shipped-with-brezel, brotcast service. More info in the deployment guide linked above.
   • You can uninstall the old docker based brotcast service once you switched.
9. Run / deploy as normal
   • Make sure to test important parts of your application to ensure that everything works as expected.