How to upgrade Modx CMS from MODX Revolution 2.7.3-pl to version 3.1.2 (rel. 2-Apr-2025)

The upgrade from MODX Revolution 2.7.3-pl to version 3.1.2 requires careful planning and a multi-step approach due to the significant changes between major versions. This comprehensive guide outlines the recommended upgrade path, prerequisites, and step-by-step procedures to ensure a smooth transition to the latest MODX version released on April 2, 2025.

Understanding the Upgrade Path

Moving from MODX 2.7.3 to version 3.1.2 cannot be done in a single step. The recommended upgrade path follows this sequence:

1. Upgrade from 2.7.3 to the latest 2.8.x version (currently 2.8.8-pl)

2. Upgrade from 2.8.x to MODX 3.0.0-pl

3. Finally, upgrade from 3.0.0-pl to 3.1.2

This phased approach helps identify compatibility issues and minimizes the risk of data loss or site breakage.

Prerequisites and Server Requirements

Technical Requirements for MODX 3.1.2

Important Notes:

• MODX 3.x does not support the SQL Server database driver

• The core folder must always be located in the project root and can no longer be renamed in MODX 3

Compatibility Verification

Before proceeding with the upgrade:

1. Update all extras (plugins, modules, etc.) to their latest versions compatible with your current MODX version

2. Check SiteDash or the MODX forums for compatibility information about your installed extras

3. Test the upgrade on a development/staging environment before making changes to your production site

Detailed Upgrade Process

Phase 1: Preparation and Backup

1. Prepare your site:

   • Log into the Manager and clear the cache (Manage → Clear Cache)

   • Log out all users (Manage → Logout All Users)

2. Clear residual cache files via SSH:

    rm -rf core*/cache/*
   

3. Create a comprehensive backup:

   • Dump your database:

       mysqldump -u database_user -p database_name > database_name.sql
     

   • Back up all files:

       tar -cvzf backup.tar.gz .
     

Phase 2: Upgrade to Latest 2.8.x Version

The easiest method is to use the UpgradeMODX extra, but manual installation is also possible.

Using UpgradeMODX (Recommended)

1. Install the UpgradeMODX package from the MODX Package Manager

2. Once installed, you'll see a dashboard widget showing available upgrades

3. Select version 2.8.8-pl from the list and follow the instructions to download and install it

Manual Upgrade to 2.8.8

1. Download MODX 2.8.8-pl from the MODX website

2. Extract the files to your server

3. Replace the core, manager, and connector files:

    rsync -avP modx-2.8.8-pl/connectors/ connectors/
    rsync -avP modx-2.8.8-pl/core/ core/
    rsync -avP modx-2.8.8-pl/manager/ manager/
    rsync -avP modx-2.8.8-pl/setup/ setup/
   

4. Run the setup by navigating to yourdomain.com/setup in your browser

5. Choose "Upgrade Existing Install" when prompted

Phase 3: Upgrade to MODX 3.0.0-pl

1. After successfully upgrading to 2.8.8, run your site for some time to ensure everything works properly

2. Use UpgradeMODX to upgrade to MODX 3.0.0-pl or follow these manual steps:

   • Download MODX 3.0.0-pl

   • Extract the files and replace core, manager, and connector directories as in the previous step

   • Run setup and select "Upgrade Existing Install"

Important Notes for 3.0 Upgrade:

• The core folder must now be located in the project root

• Certain system settings and classes have been renamed or moved

• The manager language is now dynamic

Phase 4: Upgrade to MODX 3.1.2

1. After confirming your site works properly on 3.0.0-pl, proceed to upgrade to 3.1.2

2. Using UpgradeMODX or manual download, upgrade to version 3.1.2

3. Run setup and complete the upgrade process

Post-Upgrade Checks

After completing the upgrade to 3.1.2, perform these essential checks:

1. Check for any PHP warnings or errors in your error log

2. Verify that all extras are functioning properly

3. Test core functionality across your website

4. Check template rendering and custom snippets

5. Verify that user permissions are working correctly

6. Clean up by removing the setup directory:

    rm -rf setup
   

Troubleshooting Common Issues

Missing Items in Manager

If elements are missing or unresponsive in the Manager interface, check file permissions:

chmod 755 manager
chmod 755 manager/index.php
chmod 755 connectors
chmod 755 connectors/index.php
chmod 755 connectors/modx.config.js.php
chmod 755 connectors/lang.js.php

Template Access Issues

MODX 3.1.2 fixed an issue where the Template Access grid was empty when creating a new TV. If you encounter this problem, ensure you've completed the upgrade to 3.1.2.

User Creation Issues

Earlier versions of MODX 3.x had a bug that blocked creating new users. This has been fixed in 3.1.2.

Conclusion

Upgrading from MODX 2.7.3 to 3.1.2 requires careful planning and a multi-stage approach. By following this guide and testing thoroughly at each step, you can successfully migrate to the latest version while minimizing disruption to your site.

Remember that MODX 3.x represents a significant evolution of the platform with improved performance, security, and features. Though the upgrade process requires attention to detail, the benefits of running the latest version include enhanced stability, better security, and access to the latest features and improvements.