Why You Need a Multi-Step Upgrade: The Moodle Time Machine, how to Reach Moodle 5.1

Upgrading an obsolete Moodle to the latest version requires multiple steps due to PHP incompatibility and breaking database changes.

When facing with the task of upgarding an Moodle site to a recent version, a major challenge is posed by how the Moodle upgrading system work. The main factors tp consider when planning to upgrade an old Moodle website are: PHP incompatibility and breaking database changes. Due to this factor Moodle impose some limit on the minium version yuo can upgrade from, for each version; This mean that if your site version is old you have to perfrom a multiple step upgrade, going trough all major Moodle and PHP version. This article describe all steps you have to perform to upgrade yout Moodle site.

Why You Need a Multi-Step Upgrade: The Moodle Time Machine, how to Reach Moodle 5.1

Upgrading an obsolete Moodle to the latest version requires multiple steps due to PHP incompatibility and breaking database changes.

How the Moodle Upgrade Process Works

In simple terms, a Moodle upgrade consists of two main actions: replacing the source code files with the new ones (ensuring all installed plugins are maintained and carried over) and the database migration that immediately follows to adapt the database structure to work with the new code.

To make this possible, all Moodle components from the core system to third-party plugins must implement an "upgrade strategy" to convert and adapt the component's data structure to the new update. Due to the complexity of the system, this logic is designed to work only from a specific, immediate prior version to the next. You can't usually skip several major versions.

In addition to this, newer Moodle versions require newer PHP versions, so the hosting server environment must be upgraded at multiple stages as well.

Which Version Am I Running?

To understand the Moodle version you are currently running, you have a few options.

The quickest method is to use our Moodle Version Identifier tool simply insert your Moodle website's URL.

Alternatively, if you have access to your site's file structure via FTP or command line (CLI), you can inspect the file located at /version.php and look for the release or version variable.

The Complete Roadmap: Moodle 2.x to 5.1

At the time of writing, the most recent stable Moodle version is Moodle 5.1. To upgrade directly to this version, your site needs to be on at least version 4.2.3.

Every Moodle version has a minimum supported version of both PHP and the version you're upgrading from. The following list shows the necessary major steps to take, acting as your "Time Machine" roadmap from Moodle 2.x to the latest version.

Moodle Target Version	Minimum PHP Requirement	Minimum Moodle Source Version
Moodle 5.1	PHP 8.2+	Moodle 4.2
Moodle 4.2	PHP 8.0 to 8.2	Moodle 3.11
Moodle 3.11	PHP 7.3 to 8.0	Moodle 3.6
Moodle 3.6	PHP 7.0+	Moodle 3.1
Moodle 3.1	PHP 7.0+	Moodle 2.7

The Step-by-Step Upgrade Process

The upgrade process for each step in the roadmap is consistent, and it must be performed meticulously in sequence.

Always Take a Backup

This is the most critical step. Before every version upgrade, take a complete backup of:

The database (structure and data).
The codebase (all Moodle files).
The file directory (your user content/uploaded files).

List All Installed Plugins and Check Compatibility

Make a list of all third-party plugins you have installed. For your destination Moodle version, you must then check the Moodle Plugins Directory for compatible versions of each plugin. This allows you to decide what to upgrade, what to replace, or what to discontinue before you begin the code migration.

Gather Your Files

Download the updated files for all your plugins and a fresh installation package for the target Moodle version (e.g., Moodle 3.1, then 3.6, and so on). You will use these to create the new installation package suited for your platform.

Note on Plugin Jumps: While most modern plugins are theoretically capable of jumping multiple versions, it's highly advisable to upgrade all your plugins (when available) alongside Moodle at each major step. This avoids potential problems and side effects later in the multi-step journey.

Ensure No Core Modifications Exist

Knowing your site's history is crucial here. Modifying the Moodle core is highly discouraged because it creates significant trouble during the upgrade process.

If you know your platform is clean, proceed to the next step.
If you are unsure (as many older installations may have been customized over time), you should meticulously check your codebase for modifications and decide how to deal with them (e.g., re-implement them as a proper plugin or eliminate them).

Replace the Code

Replace your existing Moodle codebase with your new installation package. Crucially, ensure you keep your old configuration file (config.php) as it contains your database settings and unique security keys.

Run the Installation

Execute the upgrade process by either visiting the Moodle web page in your browser or via the command line (CLI) if you have the possibility.

The CLI installation is superior for a faster and more reliable process, especially for larger sites with a substantial amount of data to migrate.

Upgrade Details and Pitfalls

Upgrading from Moodle 2.7 or Older

Upgrading from a version this old is significantly challenging. Many tools and technologies have changed or are no longer available. You may be starting on an ancient PHP version like PHP 5.4. In this scenario, you must update gradually through every mentioned version until you reach Moodle 3.1 and PHP 7.0.

A Strong Consideration: If you have a site this old, you should strongly consider a fresh start with a new Moodle installation, importing or recreating only the necessary content and leveraging newer features and technology.

Upgrading from Moodle 3.1

Since Moodle 3.1 requires at least PHP 7.0, you are good to go to upgrade to Moodle 3.6.

Backup.
Gather/update your plugins.
Upgrade Moodle to 3.6.

Upgrading from Moodle 3.6

This is the last major version that supports PHP 7.0.

Backup.
Upgrade your PHP environment to at least PHP 7.4.
Upgrade Moodle to 3.11.

Note on Downtime: Remember that from the moment you upgrade your PHP environment, your existing Moodle 3.6 site may stop working until you complete the Moodle upgrade. It is highly advisable to use Moodle's Maintenance Mode during this window.

Upgrading from Moodle 3.11

This is the last version to fully support the PHP 7 series.

Backup.
Upgrade your PHP environment to at least PHP 8.0.
Upgrade Moodle to 4.2.

Upgrading from Moodle 4.2 (or newer)

You are now in the final stretch!

Backup.
Upgrade your PHP environment to at least PHP 8.2.
Upgrade Moodle to the latest stable version, Moodle 5.1.

Need Help Upgrading?

Migrating a Moodle site across multiple major versions is a highly complex, technical undertaking that requires meticulous planning, multiple staging environments, and deep expertise in database and PHP version compatibility. Ignoring the multi-step nature of the upgrade carries significant risks of data corruption and prolonged downtime.

If the thought of managing these sequential upgrades and ensuring all your plugins and custom data make the journey safely seems overwhelming, don't worry. This is precisely where our expertise comes in.

We specialize in safely navigating these multi-step migrations, minimizing downtime, and ensuring your transition to Moodle 5.1 is seamless, secure, and successful.

Don't risk your data on a single, massive jump. Let our experts handle the Moodle Time Machine for you.