Bob's Guides

Why Subscribe?

As a Subscriber, you will receive access to certain parts
of the site that are hidden from others. You'll also get
email updates when new content is available
on the site or existing content is updated.

When logged in, you'll no longer see this request to
subscribe.

As an added incentive to subscribe, I have a bunch
of new and updated MODX extras I plan to release
as soon as I have a significant number of subscribers
to notify.

Privacy Policy

I'm too lazy to collect any information about you other
than the data you submit when you subscribe, which I will
never intentionally share with anyone.

As usual, Google and other entities may also collect
information about you during your visit.

MODX Upgrade FAQ

Upgrade Steps

Here are the steps I use to upgrade Bob's Guides. The site is down for about 10 minutes at the most. The last time I did it, the whole process took about 10 minutes (not counting backing up the site), and the site was down for less than 3 minutes.

Clear the site cache and the two logs (under the Reports menu)

Log out!!! This is very important

Back up your site!:

In PhpMyAdmin, select your MODX database and export it to an SQL file on your local machine

It's not a bad idea to take open the SQL file in a text editor to make sure all the tables are there

In cPanel'sFile Manager, go to your root directory, select all files and directories, and compress them to a .zip archive

Download the .zip archive to your local machine

It's not a bad idea to explore the .zip archive on your local machine and make sure all the directories are there

Let the install delete the setup directory — if you need to reinstall, you can re-upload just that directory

Once Setup is finished, the site should be back up and using the new version

Troubleshooting

If you tried to upgrade from MODX 1.x to MODX 2.x, at present there's no simple upgrade method. Simply installing the files and running upgrade will result in a complete disaster.

If you did an upgrade of MODX Revolution from an earlier version of MODX Revolution, here are some things to try if you run into trouble:

Try running an upgrade install of MODX (again, if necessary) and then clearing your browser cache and cookies (especially the java cache) before logging in.

Try logging in from another browser.

Check the information in the core/config/config.inc.php file in case you overwrote it with one from your local site (pay special attention to the server name, DB name, and password, the character set, and the location of the processors directory).

Try deleting the contents of the core/cache directory manually.

If the Manager works, but not the front end. Try turning off Friendly URLs (use_friendl_urls System Setting), visit the site, then turn them back on again. That will refresh the uri field of all resources.

Check the paths in the four config.core.php files (they should all point to the directory containing the /core directory):

MODX root directory

/manager/

/connectors/

/setup/includes/

In the modx_system_settings table in the database, set the compress_css and compress_js settings to 0. Set the manager_theme setting to default.

In the modx_site_plugins table, set the 'disabled' field of all plugins to 1. Once the site is working normally, re-enable the plugins one by one until something breaks.

Check the path in the modx_workspaces table in the database

If you are getting PHP errors, you may have extras with deprecated functions that were removed in the current version. The error message will usually indicate the problem element by ID number. You can disable plugins on the Create/Edit Plugin panel. You can disable snippets by putting a space between the two opening brackets.

In upgrading from certain versions, it may be necessary to delete and remove the entire TinyMCE package, download it again, and reinstall it.

There are three System Settings that should be missing or empty in the modx_system_settings table in the database:

session_name

session_cookie_path

session_cookie_domain

Once you've altered them in PhpMyAdmin, delete the core/cache/config.cache.php file, clear your browser cache and cookies, and login again.

Here are some more possibilities:

File permissions or your FTP program may have prevented some new files from overwriting the old ones.

The upgrade process may have changed some file or folder permissions so that MODX can't read or write necessary files

One or more files got corrupted during the download from MODX, or the upload to the site. Try the whole process again.

The new version may contain code that violates the mod_security rules at your host (for example, mod_security causes trouble downloading packages after an upgrade to MODX 2.3 on some hosts).

If none of that works, you may have a missing or corrupted file in your install -- it happen. Try uploading the files again using the method described above. Also, see the MODX Installation FAQ for more ideas.

Disaster Recovery

If everything fails and you want to revert to your backup of the earlier version, follow these steps. Important: this assumes that you followed the backup steps above correctly.

If you were able to log into the Manager, log out

In the cPanel File Manager, rename index.php to index.php.bak

In PhpMyAdmin, select your MODX database and drop all tables in the database (don't drop the database itself!)

Still in PhpMyAdmin in the same database, import the SQL file you saved earlier

In cPanel's File Manager, go to the MODX root directory

Delete the core, manager, and connectors directories, and the setup directory if it's still there

Upload the .zip file you saved earlier

Extract all the files to the root directory

Delete the index.php.bak file

The site should now be back up with the old version

It shouldn't be necessary, but if you run into trouble, you can always upload the setup directory from the previous version and run setup again

My book, MODX: The Official Guide - Digital Edition is now available here. The paper version of the book is 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