The upgrade checklist
Part 4, chapter 2. This is the whole upgrade on one page. Print it, copy it into an issue of your repository, or tick it off in your notes. Each line links the chapter that explains it. The order is the one that wastes the least time: things that stop the extension from loading first, things that only look wrong last.
0. Before you change anything
- To do: Read the license. You may upgrade and share the extension only as it allows (Reading licenses before you reuse anything).
- To do: Put the extension under Git, if it is not already, and commit it unchanged. That first commit is your "before" (Develop with Git).
- To do: If it came from someone else's repository, fork it on GitHub rather than copying it, so the history and the credit stay (Forking on GitHub, step by step).
- To do: Work on a development installation, never on a live site.
- To do: Take the inventory (Taking inventory of an old extension).
1. Make it load
- To do:
php -lon every PHP file, with PHP 8.0 if you want to support the oldest PHP Exponential 6 runs on, and with the newest PHP you use (PHP 8 errors that stop old code). - To do: Fix
ezinfo.phpif its keys are bare words (Modernizing ezinfo.php and extension.xml). - To do: Activate the extension and regenerate the autoloads (
php bin/php/ezpgenerateautoloads.php -e). - To do: Clear the caches (
php bin/php/ezcache.php --clear-all). - To do: Open the front page and the admin. Both must still load.
2. Make it run without errors
- To do: Turn on the debug output on your development copy (Debug output and logs for developers).
- To do: Open every page, run every view, every cronjob part and every CLI script of the extension.
- To do: Fix every fatal error and every warning that names a file of the extension:
- To do: constructors named after the class (Old-style constructors and static calls)
- To do: instance methods called statically (same chapter)
- To do: removed functions (Removed PHP functions and their replacements)
- To do:
count()on things that are not countable, string functions givennull(PHP 8 errors that stop old code) - To do: database code (Database code for PHP 8 and every engine)
3. Make it quiet
- To do: Fix every "Deprecated" line from the extension's files
(PHP 8.1 to 8.5 deprecations):
- To do: implicitly nullable parameters (Nullable parameters and type declarations)
- To do: dynamic properties (Dynamic properties)
- To do: SPL methods without return types
- To do: functions deprecated in 8.2 to 8.5 (
utf8_decode(),curl_close(),imagedestroy()and others)
4. Make it describe itself
- To do:
ezinfo.php: quoted keys,Name,Version,Copyright,License,Info_url(Modernizing ezinfo.php and extension.xml). - To do:
extension.xml: the same version, license and website. - To do:
composer.json: type, PHP constraint, license, the installer name (Modernizing composer.json).
5. Make it work in the browser
- To do: Open every page with the browser's developer tools; read the console and the network tab.
- To do: Move inline
<script>blocks into files (CSP: moving inline scripts into files). - To do: Replace
onclick=and the other event attributes (CSP: event handler attributes to data attributes). - To do: Replace
href="javascript:...",eval()and string timers (CSP: javascript: links, eval and string timers). - To do: Move
<style>blocks andstyle=""attributes into stylesheets (Inline CSS to stylesheets). - To do: Replace YUI (From YUI to expui).
- To do: Use the jQuery ezjscore loads, and replace calls jQuery 4 removed (From old jQuery to jQuery 4).
6. Make it belong in the administration
- To do: Style admin pages with the shared components and tokens, in light and dark mode (admin4 styling for extension pages).
- To do: Context menu entries, left menu entries and tabs without inline code (Context menus and admin integration).
- To do: Translations for every interface text (
i18nwith your own context).
7. Names and credit
- To do: Product names in texts and documentation ("Exponential"), never rename kernel identifiers (Naming and branding during an upgrade).
- To do: Keep the original authors' copyright notices; add your own beside them (Attribution and copyright notices).
8. Keep it working
- To do: A test that runs without a database: every PHP file lints, no inline scripts or styles in templates (Tests and CI for an upgraded extension).
- To do: A GitHub Actions workflow that runs it on every push.
9. Release it
- To do: Choose the next version from the tags that exist (Choosing the next version number).
- To do: Bump the version in
ezinfo.php,extension.xml(andcomposer.jsonif it has one) in one commit before the tag. - To do: Write the changelog: what changed, and what was wrong with the previous version, if anything.
- To do: Tag, push, create the GitHub release; check that Packagist picked it up.
- To do: Tell the original author: open a pull request or an issue with your fixes (Contributing back with pull requests).
The whole release procedure is in Part 7: Releasing your extension.
How long does it take?
The sources do not give averages, and every extension is different. From the upgrades told in the case studies of this part:
| Kind of extension | What the case studies show |
|---|---|
| Settings and templates only | often nothing beyond step 4 |
| A few PHP classes | an afternoon for steps 1 to 4 |
| Admin pages with JavaScript | steps 5 and 6 are most of the work |
| Its own copy of a JavaScript application | a project of its own (Case study: the layouts editor on jQuery 4) |
Related pages
- Previous: Why most of the changes are small
- Next: Taking inventory of an old extension
- Behavior changes for extensions
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.