Upgrades without breaking integrations #

This page is for integrators and operators who must upgrade an installation that other systems depend on. Exponential is maintained actively; each release brings fixes, security hardening and new features, and a few of them change behavior an integration relies on. Upgrades are safe when you know where to look and rehearse once. The upgrade itself is described in Upgrading.

Contents #

1. What tends to change under an integration
2. Read before you upgrade
3. Versions and Composer
4. The upgrade, with integrations
5. Writing integrations that age well

What tends to change under an integration #

Read before you upgrade #

• The behavior change notes in doc/eng-us/bc/6.0/ (for example Behavior changes 2026-10 and Behavior changes of the extensions): each says what changed, who is affected, how to check and how to fix.
• The release notes of every extension your integration uses (doc/changelogs/extensions/).
• The upgrade guide's checklist for each period you pass (Upgrading, part C).

Search them for the names your integration uses: the classes it calls, the settings it sets, the routes it calls.

Versions and Composer #

• The root composer.json uses tilde constraints (~1.2.6): the last position floats, so composer update brings fixes of the same line but no new minor line.
• Your integration extension declares what it needs in its own composer.json ("se7enxweb/ezprestapi": "~1.2.6"), so an installation cannot update into a line you have not tested (composer.json for extensions).
• Record the versions in the handover documents; composer show and Setup > Extensions list them.

The upgrade, with integrations #

1. Rehearse on a copy of production with the same integration versions; run the acceptance cases and the import dry runs (Testing integrations).
2. Tell the owners of the other systems the window; calls during it may fail.
3. Pause the integration's cronjob parts at Setup > Cronjobs (and the queue workers), so no import runs half on the old and half on the new code (Cronjobs for integrations).
4. Optionally switch maintenance mode on (php bin/php/maintenance.php on --message="..." --until=1h); API clients get 503 with Retry-After and should back off.
5. Upgrade: code, database update, autoloads, caches, php bin/php/console exp:velocity deploy.
6. Check: the acceptance cases, one dry run per import, one call per API client, exp:audit sinks list.
7. Resume the cronjob parts and watch the first runs.
8. Write down what changed for the integration in its changelog.

Writing integrations that age well #

• Use the supported APIs (eZContentFunctions, operations, expservices, the REST routes) rather than tables and internal methods.
• Keep the code in one extension with tests, not in scattered scripts.
• Guard optional kernel classes with class_exists() (the audit API documents this) so a missing piece degrades instead of failing.
• Prefer settings to code for anything a site may need to change.
• Follow the project: contribute fixes you need upstream, so the next release carries them (Contributing integrations back).

Related pages #

• Upgrading
• Part 4 of the extension book: upgrading
• Keeping customer sites current
• Release and upgrade planning
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.