Upgrading from 2.x to 3.0

Last updated Jul 22nd, 2022 | Page history | Improve this page | Report an issue

Support the team building MODX with a monthly donation.

The budget raised through OpenCollective is transparent, including payouts, and any contributor can apply to be paid for their work on MODX.

Backers

Budget

$305 per month—let's make that $500!

Learn more

This document details the changes made between 2.x and 3.0 that may affect upgrades. It's not a full list of all changes (see the changelog for that), but rather a reference of (breaking) changes that may affect extras and sites.

You may find a list of compatible extras on SiteDash.

Upgrade to 3.0¶

In general, you can follow the standard upgrading process when upgrading to 3.0. It's recommended to first upgrade to the latest 2.8 release for some time, which will log deprecated functionality your site may depend on to the MODX log.

After upgrading the core and upgrading your extras, you may encounter some breaking changes that need to be addressed in extras or custom code.

⚠️ Important: the core folder must now always be located in the project root, and can no longer be renamed
⚠️ Important: MODX 3.0 requires at least PHP 7.2
⚠️ Important: sqlsrv support has been removed
A list of breaking changes can be found here, most notably many core classes have been moved and renamed
The manager language is now dynamic
Various system settings have been removed or changed

Other notable changes and improvements¶

Manager/Interface¶

New template picker allows for easier resource creation #15535
Redesigned installer #14507 and login #13773.
Manager has been redesigned. Improved manager on mobile devices #14700, #14735. Changed resource styles in the tree #14832
Language can now be switched on the fly #14046
All manager permissions are automatically made available in MODx.perm #13924, #14425
Google translations are now disabled in the manager #14414
More consistent resource/element duplication #14411

Packages¶

Markdown is now parsed in package attributes (changelog/readme/license) #13853

Files & Media¶

Media sources now use Flysystem #13709
Core directories are now protected from being renamed/removed from the manager #14374

Resources & Templates¶

Resources can now get an icon based on their content type #14383
New output modifiers related to files: dirname, basename, filename, extensions #14198