Upgrading

Requirements

Area	Requirement	Notes
Runtime	PHP 8.1+	Test the PHP version used by production.
Dependencies	Composer	Load vendor/autoload.php in scripts and front controllers.
Production	OPcache (optional)	Helpful when loading generated *.pure.php and *.plain.php files.

Upgrade checklist

For a tagged release, update the Composer constraint in your application and run:

composer update yonld/purephp

When following the default branch, pin the tested commit in your application instead of inventing a release number. Before deploying that commit:

1. Read the CHANGELOG for what changed and what a reader has to do about it.

2. Run vendor/bin/pure check <paths> for component and shape units.

3. Rebuild strict and plain artifacts:

   vendor/bin/pure compile <paths>
   vendor/bin/pure compile --plain <paths>
   vendor/bin/pure compile --check --plain <paths>

4. If the application uses Compile::cachePath(), remove only the cache files owned by PurePHP when the release requires regeneration. Compile::clearCache() is the explicit API for that operation.

5. Verify the rendered output and document headers, then deploy the source and generated artifacts together.

Do not hand-edit *.pure.php or *.plain.php. They contain a cache-version or fingerprint contract and must be regenerated by the matching compiler.

Rollback

If a deployment fails, roll back the application source and its generated artifacts as one unit. Then clear the PurePHP renderer cache, rerun vendor/bin/pure compile --check, and check the first failing route. Keeping a known-good artifact beside its source is safer than restoring only one of the two.

For symptom-specific fixes, continue with Troubleshooting.