UpgradeMODX Package
If you use this extra and like it, please consider donating. The suggested donation for this extra is $15.00, but any amount you want to give is fine (really). For a one-time donation of $50.00 you can use all of my non-premium extras with a clear conscience.
UpgradeMODX provides a dashboard widget that checks for available upgrades to MODX and (optionally) installs them. The upgrade process is automatic and very simple. It shows you a form with available versions to install (you can set how many it shows). Once you've selected one, UpgradeMODX downloads all the files, puts them in place, and launches Setup. It should upgrade *any* version of MODX except the SDK development version. It should correctly upgrade versions with a moved and/or renamed manager, core, connectors, assets, or processors directory. I think it will upgrade the SDK version to the non-SDK version, but I haven't tested that.
Upgrade MODX is only for upgrades. It will not install a fresh MODX site.
(Jump to System Settings Table)
No matter what upgrade method you use, you are strongly advised to make a full backup of the database and all files and be prepared to restore the site if things go wrong.
New System Setting
MODX 3 versions will not be shown in the list on sites running MODX 2.x unless you change the ugm_show_modx3 System Setting. There are still extras that will not work in MODX 3, so please don't upgrade a production website to MODX 3 unless you've made sure that any extras you need will work on that platform and understand the risks and requirements involved in the upgrade. For more information, see the MODX 3 Notes section below.
If the UpgradeMODX widget doesn't show up on the dashboard, make sure you are a member of the Administrator group. (You're not by default if you're logged in as an admin user created on the MODX Cloud dashboard.) Add yourself to the Administrator group, clear the cache, go to Manage -> Flush Your Permissions, then log out and back in again.
If you want Manager users to see the dashboard without belonging to the Administrator group, change the ugm_groups System Setting.
For testing purposes (and to fix possible corrupted or missing MODX files), you can "upgrade" MODX to the
version you currently have by changing the settings_version System Setting to an earlier version.
UpgradeMODX will go through all of its steps, download and replace all the MODX files, and launch setup. In theory,
UpgradeMODX can also be used to "downgrade" MODX to a previous version, though this has not been
extensively tested.
If you have moved or renamed any directories. UpgradeMODX should work fine. It calculates the correct location
for the files by reading the config.inc.php file. Setup should no longer ask you where your core
directory is.
Installing UpgradeMODX
Go to Extras -> Installer (or System -> Package Management in older versions of MODX) on the main menu in the MODX Manager and click on the "Download Extras" button. That will take you to the Revolution Repository. Put UpgradeMODX in the search box and press Enter. Click on the "Download" button, and once the package is downloaded, click on the "Back to Package Manager" button. That should bring you back to your Package Management grid. Click on the "Install" button next to UpgradeMODX in the grid. The UpgradeMODX package should now be installed.
Upgrade Notes
Version 2.3.x of UpgradeMODX is fully tested in MODX 3. It can be used to upgrade from MODX 2.8.x to MODX 3.x.x. It stores configuration data in System Settings, so all settings will survive upgrades. The Settings can be found by going to System (gear icon) -> System Settings and selecting the upgrademodx namespace.
Here's a quick summary showing some of the changes:
- Extensive mods for MODX 3.
- Fixes a critical security vulnerability in the guzzlehttp/psr7 library
- More reliable connection of widget to default dashboard
- Improved docs
- Other bug fixes and improvements
Because Guzzle is used for the HTTP requests, PHP 5.4 is now the minimum required version of PHP, though some users have reported that they needed to upgrade to PHP 7 to get UpgradeMODX to work for them.
Credits
This package was inspired by the work of a number of people and I have borrowed some of their code. Dmytro Lukianenko (dmi3yy) is the original author of the MODX install script. Susan Sottwell, Sharapov, Bumkaka, Inreti, Zaigham Rana, frischnetz, AgelxNash, and halftrainedharry, also contributed and I'd like to thank all of them for laying the groundwork and helping improve the code.
Usage
To upgrade your site, just select a version to upgrade to and click on the "Upgrade MODX" button in the widget. UpgradeMODX will select the recommended version automatically. Downloading and extracting the files may take some time, so be patient.
Once you've installed UpgradeMODX, the widget should appear. It's attached to the default dashboard, so if you have another dashboard showing, you'll have to attach it to that dashboard by going to System (gear icon) -> Dashboards.
MODX 3 Notes
MODX Revolution 3 is a significantly different from MODX Revolution 2. While UpgradeMODX will upgrade you from one to the next, you need to keep a couple of things in mind.
First, you should always upgrade to MODX 3.0.0-pl before upgrading to higher versions. If you are coming from an older version of MODX 2, install all the versions ending in .0 and then the highest version before 3.0.0 before installing 3.0.0.
Second, after you upgrade, you need to clear the MODX cache (I recommend doing it with the CacheClear extra, which works fine in MODX 3), and also your browser cache and cookies. Left over stuff in the cache and cookies can make a mess of the MODX Manager. I use the Cache Killer Chrome extension, but Incognito or Private mode will work as well. Once Cache Killer is installed, one click on the toolbar turns off the cache for both web pages and cookies. Another click turns it back on.
Before upgrading to MODX 3, you'll also want to make sure the extras you need work in MODX 3. There's a MODX 3 compatibility list here. There may be extras not listed as compatible there that will work in MODX 3 but haven't been tested yet. If you try one be sure to report whether it works or not on that page.
In very old versions of MODX, creation of the dashboard widget will fail and you'll see a bunch of error messages
during the install. The UpgradeMODX installer will attempt to create a resource called UpgradeMODX
that will show the install check. If no widget appears, view the resource to check for MODX upgrades. When an
upgrade is available, it should let you launch the installer.
If the snippet and chunks fail to install (this is fairly rare), your version of PHP is too new for your MODX install and you'll have trouble saving chunks and snippets in the Manager as well. You can either downgrade the version of PHP , or manually make the changes to the three files shown in this commit.
Once you've upgraded MODX to a recent-enough version, you can uninstall and re-install UpgradeMODX to get the widget. You can also upgrade to the current version of PHP.
As installed, the widget will only appear for members of the Administrator group. To show it to other groups, change
the ugm_groups System Setting to a comma-separated list of groups who can see the widget. You can also change the ugm_interval System Setting if
you'd like it to check for upgrades more, or less often, though the default value is now 1 day.
Hint: To get to the Manager's dashboard, you can click on the MODX logo at the upper left.
Note that if you set the interval to 60 seconds (as it is in the beta and rc versions), it won't execute every 60
seconds. It will only execute when you visit the dashboard at least 60 seconds after the last check. The minimum
recommendation for the ugm_interval System Setting on a production site is 1 hour.
By default, UpgradeMODX considers only pl (stable) versions for upgrade (except in the beta and rc versions). You can
change the ugm_pl_only System Setting to see all versions. You can change the ugm_versions_to_show
System Setting to show more versions (the default is 5). UpgradeMODX will automatically extend the versions shown to
include your current version. Initially, the interval for checking is set to 1 day (except in the beta
and rc versions where it's 60 seconds). You can change that by setting the ugm_interval System Setting.
That setting should always be an integer followed by the name of the unit (e.g., 6 hours, 3 days, 1 week, 1 month.
If you would like to hide the widget when no upgrade is available, change the ugm_hide_when_no_upgrade
System Setting. The widget will still check for upgrades at the selected interval, but won't appear in the
dashboard(s) unless an upgrade exists.
If you would like to fool the widget into thinking there is an upgrade, you can change the
settings_version System Setting. Make it any earlier version (it doesn't have to be a real version) and
the widget will show an update. If you install the update (even though it's not an update) and finish Setup, it will
restore the System Setting to its correct value. If you don't run an upgrade, be sure to change the System Setting
back to its original value.
You can set the language used by the widget with the ugm_language System Setting
You are *strongly* advised not to change anything in the package except the System Settings.
Security
The upgrade processors can only be run from the Manager, and only by users who belong to allowed user groups (Administrator by default). Even if the processors were available to the public, all they would do is upgrade your site.
The upgrade script downloads everything to the /ugmtemp directory in the MODX root directory (or another
directory if you have set the ugm_temp_dir System Setting). At the default location, UpgradeMODX
deletes that directory when it finishes successfully so nothing should be left behind after the upgrade.
If you have changed the directory, UpgradeMODX will leave the downloaded .zip files in place. This is
handy if you have multiple MODX installs on the same server and avoid downloading the .zip file for
each one.
After upgrading the site, It's a good idea to make sure that the /ugmtemp directory has been removed,
especially if the script times out or fails. The files are relatively harmless, but their existence could identify
your site as a MODX site, and there's no point in giving potential hackers that information.
GitHub API Rate Limit Exceeded
The default install of UpgradeMODX makes anonymous requests to the MODX repository at GitHub for information.
Requests of this type are limited to 60 per hour. If a lot of people are making requests, or your
ugm_interval setting is very short, or if you are doing a lot of testing, this limit could be hit and
you will either get the error message: GitHub API Rate Limit Exceeded or the script will report that it
couldn't get the version list from GitHub. You can try again later, but to solve this problem permanently, you can
get your own GitHub token so your requests will not be anonymous. That will bump your limit up to 5,000 requests per
hour.
You can create a free account at GitHub, or use an existing one. To get a token, follow the directions here.
Copy your token to the clipboard, then paste it into the ugm_github_token System Setting. Enter your
GitHub username in the ugm_github_username System Setting. Don't forget to clear the cache after
changing any settings. Some browsers will cache the request headers, which contain the credentials, so you may also
need to clear your browser cache and cookies.
Multiple Installs
If you have multiple MODX sites on the same server, you can set the ugm_temp_dir System Setting to a
path that's available to all sites, like your server's tmp directory. Once you do that, UpgradeMODX will leave the
downloaded .zip file in place and skip the download for all sites but the first one. Remember to change that setting
on all the sites before performing any upgrades.
Troubleshooting
If UpgradeMODX reports trouble getting the versions from GitHub, you should get a helpful error message. If you'd
like to see the full message returned from GitHub, set the ugm_verbose System Setting to
Yes.
If you get persistent errors about the versionlist, you can bypass them by following the
steps below. Before you do that, though, try turning off the MODX News and Security Feeds. Go to System
(gear->icon) -> System Settings and put feed in the search box at the upper right.
It might also be wise to move the UpgradeMODX widget above the Feed widgets in your dashboard by giving it a lower rank in System -> Dashboards. Right-click on your dashboard and select "Update Dashboard." Change the ranks and click on the "Save" button.
If none of that works, create the file: core/cache/upgrademodx/versionlist then follow these steps:
- Go to this url: //api.github.com/repos/modxcms/revolution/tags.
- Copy the entire contents of your browser window (Ctrl-a, Ctrl-c)
- Paste it into the file (Ctrl-v).
- Note the name of the latest version at the top of the file (e.g., 2.7.0-pl)
- Set the
ugm_last_checkandugm_file_versionsettings to the latest version - Clear the Site Cache in the Manager
You should be able to do as many upgrades as needed in the next 24 hours
If you get frequent timeouts, you can increase the ugm_github_timeout or ugm_modx_timeout
System Settings. They set how long the program will wait for a response. The default is 6 seconds.
UpgradeMODX now uses Guzzle (which uses cURL by default) to check for and download files. If cURL isn't installed on your server, Guzzle uses streams to get remote files and requires PHP 5.4 to work.
UpgradeMODX uses ZipArchive to unzip the files. You can set the ugm_force_pcl_zip SystemSetting to
Yes to avoid using ZipArchive to unzip the downloaded MODX file.
As of Version 2.0.0 of UpgradeMODX the cURL SSL_VERIFY_PEER option to is set to true by default in Guzzle. Guzzle uses the server's certificate file, so there should be no need to turn it off. Having this
setting off leaves you vulnerable to man-in-the-middle attacks where the attacker could pretend to be the MODX
repo and lead you to download malicious code instead of MODX. If you can't get UpgradeMODX to work because of
SSL issues, the best solution is to check with your host. There is a information here on the verification process.
Turning the ugm_ssl_verify_peer System Setting off might make it work for you, but in a less secure
way.
UGM has a ugm_cert_path System Setting (empty by default). If you are having SSL trouble,
you could try asking the host or checking their forum for the path to the SSL cert file. Paste that path into
the value field of this setting.
If UpgradeMODX shows an available upgrade but the submit button doesn't work, check the spelling of the assets/components/upgrademodx/js/progressButton.js
file. Make sure the "B" matches the case of the filename in the UpgradeMODXTpl chunk.
Note that some browsers cache the credentials used in HTTP requests. If you change the
ugm_github_username and ugm_github_token settings. They may not take effect until you
clear the browser cache (and maybe the cookies) or use a different browser that doesn't have the cached credentials.
If the widget doesn't appear. Go to System (gear icon) -> Dashboards and check to make sure the widget is on the default dashboard (or whatever dashboard you're using).
Catch 22
There is a bug in very old versions of MODX that prevents some elements of UpgradeMODX and other extras from being installed if you are using PHP 7 (see the note above about fixing this bug manually). At the same time, UpgradeMODX now requires PHP 5.4 or above because that's what Guzzle requires. There may be other incompatibilities in older versions of MODX and some of your plugins might interfere with the setup process.
If UpgradeMODX fails for you and the troubleshooting steps above don't work, the best approach is to use PHP 5.4, and upgrade MODX manually using the method described here. Make sure you install all major versions of MODX (the ones ending in .0).
Once you hit MODX 2.4, you should be able to upgrade to PHP 7 (assuming that you've fixed the bug), then uninstall and remove Upgrade MODX, re-install it, and use UpgradeMODX from that point on. For security, and to prevent future hassles, keep your MODX install up to date.
UpgradeMODX System Settings
| Setting | Description | Default |
|---|---|---|
| GitHub | ||
| ugm_verbose | Display full GitHub Error Messages | No |
| ugm_cert_path | Path to SSL cert file in .pem format; rarely necessary | |
| ugm_github_username | Your username at GitHub | |
| ugm_github_token | Github token - available from your GitHub profile | |
| ugm_github_timeout | Timeout in seconds for checking Github | 6 |
| Widget | ||
| ugm_versionlist_api_url | URL of API to get version list from | //api.github.com/repos/modxcms/revolution/tags |
| ugm_temp_dir | Path to the directory used for temporary storage for downloading and unzipping files; Must be writable | {base_path}ugmtemp/ |
| ugm_file_version | Version when versionlist file was last updated. Set automatically -- do not edit! | |
| ugm_interval | Interval between checks -- Examples: 1 week, 3 days, 6 hours | 1 day |
| ugm_last_check | Date and time of last check -- set automatically | |
| ugm_latest_version | Latest version (at last check) -- set automatically | |
| ugm_hide_when_no_upgrade | Hide widget when no upgrade is available | No |
| ugm_version_list_path | Path to versionlist file (minus the filename -- should end in a slash) | {core_path}cache/upgrademodx/ |
| Download | ||
| ugm_force_pcl_zip | Force the use of PclZip instead of ZipArchive | No |
| ugm_modx_timeout | Timeout in seconds for checking download status from MODX | 6 |
| ugm_ssl_verify_peer | For security, have cURL verify the identity of the server | Yes |
| Form | ||
| ugm_language | Two-letter language code for language to use | en |
| ugm_pl_only | Show only pl (stable) versions | Yes |
| ugm_show_modx3 | Show MODX 3 versions on MODX 2 sites | No |
| ugm_versions_to_show | Number of versions to show in upgrade form | 5 |
| Security | ||
| ugm_groups | group, or comma-separated list of groups, who will see the widget | Administrator |
My book, MODX: The Official Guide - Digital Edition is now available here. The paper version of the book may still be available from Amazon.
If you have the book and would like to download the code, you can find it here.
If you have the book and would like to see the updates and corrections page, you can find it here.
MODX: The Official Guide is 772 pages long and goes far beyond this web site in explaining beginning and advanced MODX techniques. It includes detailed information on:
- Installing MODX
- How MODX Works
- Working with MODX resources and Elements
- Using Git with MODX
- Using common MODX add-on components like SPForm, Login, getResources, and FormIt
- MODX security Permissions
- Customizing the MODX Manager
- Using Form Customization
- Creating Transport Packages
- MODX and xPDO object methods
- MODX System Events
- Using PHP with MODX
Go here for more information about the book.
Thank you for visiting BobsGuides.com
— Bob Ray
