AssegaiPHP upgrades

Upgrade Guide

Pick the versions and the parts of your stack you use. We will show the upgrade steps that apply to your app.

Tell us about your app

Choose your upgrade path

From version To version

How customized is your app?

Basic Medium Advanced

A fairly standard app using first-party defaults.

What does your app use?

I use browser sessions

Include guard, login redirect, intended-target, and logout checks.

I use ORM

Include ORM module wiring, repositories, and migrations.

I use Events

Include event wiring and listener checks.

I use RabbitMQ

Include the Common 0.10 driver upgrade and queue checks.

I use Beanstalkd

Include the Common 0.10 driver upgrade and queue checks.

I want OpenSwoole

Include OpenSwoole setup steps and caveats.

I use Windows

Include Windows notes where WSL2 or Linux is the safer path.

Framework Milestone

Current release assegai update --to=0.10 --dry-run

Upgrade from 0.9.x to 0.10.0

0.10.0 completes Core's exception-filter lifecycle and adds an opt-in, application-configured way to redirect unauthenticated browser requests while API routes retain normal 401 responses.

Heads up. Console 0.9.x predates `assegai global update`. Upgrade the global Console package to 0.10.2 with Composer first; after that, the CLI can manage its own future updates.

Before you run the update

Confirm the project runs on PHP 8.4 and commit or back up the current workspace, including `composer.json` and `composer.lock`.
If `assegai --version` reports 0.9.x, run `composer global require assegaiphp/console:^0.10.2 --with-all-dependencies`, then verify the installed version. An older binary cannot self-bootstrap a command it does not contain.
From Console 0.10.1 onward, `assegai global update` and `assegai -g update` update the global package. Use `assegai global update --dry-run` to inspect that Composer operation without changing the installation.
If the project has a local `assegaiphp/console:^0.9` requirement, do not upgrade it independently. The global 0.10 CLI will align that local requirement with Core in the project update transaction.
Run `assegai update --to=0.10 --dry-run` and review every proposed requirement change before approving the update.
Run the command again without `--dry-run` when the plan is correct. A cross-release update asks for interactive approval; automation must pass `--yes`, and a non-interactive run without it stops without applying the update.

What `assegai update` should handle

After approval, align installed 0.9-line Core, ORM, Events, Auth, Collections, Common, Forms, Util, Validation, and any direct project-local Console requirement to `^0.10.0`.
Hydrate missing supported defaults in `assegai.json`.
Run Composer with all dependent packages, updating the application-owned `composer.lock` and installed `vendor/` tree.
Keep independently constrained queue-driver requirements unchanged while including directly installed integrations in Composer resolution.
Restore `assegai.json`, `composer.json`, and `composer.lock` if configuration migration or Composer resolution fails. If a later integration or frontend step fails, keep the completed framework update and report that step separately.

What you still need to do

Review the resulting dependency and lock-file diff. If Composer changed `vendor/` before a failure and the CLI restored the manifests, run `composer install` to reconcile installed packages with the restored lock file.
The updater does not create or rewrite application PHP or `config/auth.php`. Create that file manually only after reviewing the application policy; do not copy scaffold session defaults over customized 0.9 settings in `config/default.php`.
Move framework-owned session cookie settings to `config/auth.php` only when their effective values have been preserved. Existing session settings in `config/default.php` remain supported.
Set `authentication.loginRedirect.url` to the public login route owned by your application.
Review custom exception filters for handler, controller, then global precedence. The first matching filter is terminal and owns the response.
Do not add an auth interceptor for login redirects. Keep the access decision in a guard and the browser response policy in an exception filter.
Leave API-only controllers without `LoginRedirectFilter` so `UnauthorizedException` retains the normal 401 response path.
For a new application rather than an in-place upgrade, use `composer create-project assegaiphp/starter:^0.10 <project-name>` so the scaffold and framework begin on the same release line.
After successful credential verification, restore the intended target once with `Session::pull()` and use a 303 redirect after a login form POST.
Confirm successful login rotates the session identifier and that the stored user does not contain its password field.
Confirm logout destroys the active session and redirects to a public route.

Before you call the upgrade done

Run `assegai --version` and `composer show "assegaiphp/*"` to confirm the intended release lines. Console 0.10.1 normal commands may emit a cached newer-stable-release notice on stderr; quiet mode, global updates, and `ASSEGAI_NO_UPDATE_CHECK=1` suppress it, and failed metadata checks stay silent.
Run `composer validate --strict` and your complete application test suite.
Start the app locally and verify that custom filters emit one response and that lower-precedence filters do not run after a match.
Request a protected API route without the login redirect filter and confirm a 401 response with no `Location` header.
Visit a protected browser URL and confirm it redirects to the configured login route.
Confirm a safe local GET or HEAD target is restored after login and removed from the session after use.
Confirm cross-origin, scheme-relative, malformed, POST, and login-route targets are not stored.
Confirm login and logout rotate or destroy session state as expected.

Helpful docs

Console 0.10.2 Release Notes Console 0.10.1 Release Notes Events 0.10.0 Release Notes Authentication Authentication and OAuth In Depth Guards, Filters, Interceptors, Pipes, and Middleware Core 0.10.0 Release Notes Core 0.10.0 Upgrade Notes

Looking ahead

Upcoming milestones

Only useful if you are planning more than one upgrade jump.

0.8.0

OpenSwoole Runtime Foundations

Long-lived runtime foundations, safer request scope, and an experimental OpenSwoole path.

0.9.0

ORM Stability Rewrite

Dialect-aware ORM stability across MySQL, MariaDB, SQLite, PostgreSQL, and MSSQL.

0.10.0

Configurable Authentication Failures

Complete exception-filter lifecycle, configurable browser-login redirects, and normal API 401 behavior without an auth interceptor.

1.0.0

Confidence Release

Ship the minimum viable identity of AssegaiPHP in a polished form, with additional 0.x milestones if needed before then and larger expansion work landing in 1.0+.