The following is an instructional guide on how to upgrade your 3.x October CMS installation to the latest version 4.0

October CMS Version 4.0 is a technology upgrade and introduces a new dashboard. The foundation framework has been upgraded to Laravel 12 and the Dashboard has been improved that brings improved reporting features.

Table of Contents

• Public Source Code
• Upgrading to 3.x from 4.x
• Vendor Upgrade Guides
• Tag List Defaults
• Twig Output Escaping

Public Source Code

From the 4.0 release, we have made the source code for October CMS publicly available on GitHub. This is to improve accessibility and encourage collaboration among the community. It comes after a 5-year review period of keeping the source code private.

Installing October CMS the same as usual using the complimentary license key.

composer create-project october/october

This means you can evaluate October CMS for free, however, a license is still required to run October CMS for any other purpose.

Upgrading to 4.x from 3.x

PHP Minimum Version

Make sure you are using the new minimum PHP version 8.2 or above.

Configuration Files

Some configuration files have been updated. The following files should be updated to use the latest content. It is best to compare them with your current configuration files to be sure they are the same.

• config/app.php

The following commands will replace the files with their latest contents:

curl -o ./config/app.php https://raw.githubusercontent.com/octobercms/october/refs/heads/4.x/config/app.php

Bootstrap Files

Some bootstrap files have been created and updated. The following files should be created or updated to use the latest contents:

• bootstrap/app.php
• bootstrap/providers.php
• bootstrap/autoload.php

The following commands will replace the files with their latest contents:

curl -o ./bootstrap/app.php https://raw.githubusercontent.com/octobercms/october/refs/heads/4.x/bootstrap/app.php
curl -o ./bootstrap/providers.php https://raw.githubusercontent.com/octobercms/october/refs/heads/4.x/bootstrap/providers.php
curl -o ./bootstrap/autoload.php https://raw.githubusercontent.com/octobercms/october/refs/heads/4.x/bootstrap/autoload.php

Composer Dependencies

Update the following dependencies in your application's composer.json file:

• october/all to ^4.0
• october/rain to ^4.0
• laravel/framework to ^12.0

If you are including individual modules, these can be updated to be the same as the october/all package.

Once this file has been updated, you may run composer update to perform the upgrade. In most cases everything should update smoothly.

Note: For any errors or support with upgrading packages, you may reach out on the GitHub Issues Area.

Vendor Upgrade Guides

Laravel has been upgraded from version 6 to version 9:

• Upgrading To 9.0 From 10.x
• Upgrading To 10.0 From 11.x
• Upgrading To 11.0 From 12.x

For information on the changes between PHP versions:

• PHP Appendices page

Tag List Defaults

The taglist form widgets has new defaults for the useKey and customTags properties. The new default values in v4.0 onwards are as follows.

# New Defaults
type: taglist
customTags: false
useKey: true

If you have these unset in your form fields, you may set them to their previous default values:

# Previous Defaults
type: taglist
customTags: true
useKey: false

Twig Output Escaping

Twig functions and filters registered with the registerMarkupTags method are now escaped by default. Please review all your custom Twig filters. If they do not contain user input or have escaping handled internally, you can revert this change by setting the last array value to false in the definition. In the following example, all of the Twig extensions will not include output escaping.

public function registerMarkupTags()
{
    return [
        'functions' => [
            'input' => ['input', false],
            'str_*' => [\Str::class, '*', false],
        ],
        'filters' => [
            'avatar_url' => [fn ($user) => $user->getAvatarUrl(), false],
            'url_*' => [\Url::class, '*', false],
        ]
    ];
}

Note: This change is backward compatible with October CMS v2 and later.

This is the end of the document, you may read the announcement blog post or visit the changelog for more information.