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

How customized is your app?

A fairly standard app using first-party defaults.

What does your app use?
Coordinated Framework Release
Released assegai update --to=0.11 --dry-run

Upgrade from 0.10.x to 0.11.1

Select application paths at bootstrap and move the framework modules and established queue-adapter streams through one reviewed dependency plan.

Heads up. Use Console 0.11.1 or a later patch; Console 0.11.0 predates the corrective release inventory.

Before you run the update

  1. Confirm PHP 8.4 or newer and commit or back up the application, including composer.json and composer.lock.
  2. Run composer global require assegaiphp/console:~0.11.1 --with-all-dependencies and verify the running binary with assegai --version.
  3. Run assegai update --to=0.11 --dry-run. Check every direct requirement, including require-dev, against the coordinated release inventory before approving the plan.
  4. Review changes to existing dependency ranges. Adding the coordinated target must preserve previously verified support, including compatible later patches and broader supported ranges; review unresolved conflicts before approving changes.

What `assegai update` should handle

  • The corrective Console plan adds support for the coordinated framework targets to direct require and require-dev dependencies, including project-local Console, while preserving verified existing support.
  • The recommended graph uses RabbitMQ and Beanstalkd 1.2 with Common 0.11 and the compatible Attributes stream. Library dependency ranges may also retain verified older combinations.
  • Apply the reviewed Composer transaction and configuration-default migration without rewriting application PHP.

What you still need to do

  • Apply the update only after reviewing the dry run. Cross-release changes require confirmation; non-interactive execution requires an explicit --yes.
  • Release artifacts follow the coordinated plan. Dependency compatibility follows the APIs used and tested combinations; preserve verified older support when extending an existing requirement to include a target release.
  • Review the manifest and lock diff, then run composer validate --strict. Reconcile vendor with composer install if a failed Composer operation restored the original manifests.
  • Existing factory calls retain their defaults. Opt into ApplicationPaths only when the deployment needs independent application, configuration, secrets, state or Composer locations.
  • Provision selected directories before bootstrap. Load an autoloader mapping application classes to the selected release; composerDirectory selects metadata only.
  • Keep secrets and persistent state outside the public document root and replaceable application directory. Explicit paths guard runtime configuration persistence by default.
  • A selected missing environment file fails bootstrap. Use environmentFile: null only when process environment values supply the application configuration.
  • For a new application, use composer create-project assegaiphp/starter:~0.11.1 <project-name>.

Before you call the upgrade done

  • Run composer show "assegaiphp/*" and compare the installed framework and established legacy streams with the reviewed inventory.
  • Run the complete application test suite and verify protected API routes, browser login, static assets, Twig/PHP views and component resources used by the application.
  • For explicit paths, verify application resources come from the selected release and writable state survives replacing the application directory.
  • Verify runtime configuration commits are rejected when readOnly is enabled and that selected environment/configuration files are used without source-directory fallback.

Helpful docs

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.

0.11.1

Application Paths and Coordinated Modules

Independent application, configuration, secrets and state locations, with a coordinated framework and queue-adapter dependency plan.

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