How to upgrade October CMS to Laravel 6?
Tags: octobercms, laravel
Published: 2020-12-16 19:11:44

It’s been over a year since the release of the 6th version of the Laravel framework. And some time ago October CMS that we developed the Shopaholic e-commerce platform for, released the long-awaited 1.1.0 that supports Laravel 6. As you may have noticed, the version numbering principle has also changed, and it now better reflects the current state of affairs.

Anticipating possible comments about the current major version of Laravel, we clarify that so far October CMS has been based exclusively on LTS releases. This seems like a reasonable choice in light of the fact that there have been cases of broken backward compatibility even when upgrading the next minor version of the framework.

##Moving to Laravel 6

###General information###

The October core has undergone many major changes, which led to a rather long wait. At the same time, the release of Laravel 6 is marked as LTS (Long Term Support), which means an increased life cycle and maintaining long-term relevance.

Some of the system requirements have changed:

* minimum PHP 7.2, PHP 7.4 recommended (versions from 7.0 will also work, but cannot be updated);
* minimum SQLite 3.7.11, 3.8.8+ recommended.

Version 1.1.0 was available as a test update on August 16, and the stable version was released on September 7.

###Installing October CMS v1.1.x “from scratch”

To clean install October version 1.1.x use the Composer installation:

1. Run the composer `create-project october/october .` command.
2. Open the `config/cms.php` file and activate the `disableCoreUpdates` setting, which will disable CMS core updates via the October gateway: `'disableCoreUpdates' =>; true,`.
3. Finish the installation using the terminal by running the `php artisan october:install` command.

Correctly installed October version 1.1.x will not display its number in the admin settings.

![Dashboard screenshot with no build version](https://dev-to-uploads.s3.amazonaws.com/i/fg55sc9fs7cs8g2isa44.png)

If you try to update the core from the admin panel after installation without enabling the `disableCoreUpdates` setting, you will get the following picture indefinitely.

![Dashboard screenshot with wrong build version](https://dev-to-uploads.s3.amazonaws.com/i/mvfd24r10z8dme2ywpb5.png)

###Update of October CMS v1.0.x

In order to upgrade an existing October installation to the 1.1.x branch, it must be originally installed with Composer. If not, then the easiest update will look like this (if you’ve installed October with Composer, skip to step 6):

1. Install in a separate directory for October CMS version 1.469 using the command composer `create-project october/october . "1.0.469"`.</li>
2. Open the file `config/cms.php` and activate the setting `disableCoreUpdates`, which will disable CMS core updates via the October gateway: `'disableCoreUpdates' =>; true,`.
3. Copy the plugins and themes folders to this directory.
4. Apply migrations using the `php artisan october:up` command.
5. Resolve the conflicts that have arisen.
6. Raise dependency versions in `composer.json`*:```json
"require": {
    "php": "^7.2",
    "october/rain": "dev-develop as 1.1",
    "october/system": "dev-develop",
    "october/backend": "dev-develop",
    "october/cms": "dev-develop",
    "laravel/framework": "~6.0",
    "wikimedia/composer-merge-plugin": "1.4.1"
},
"config": {
    "preferred-install": "dist",
    "platform": {
        "php": "7.2.9"
    }
},
```
7. If you started with step 6, you should make sure step 2 is complete.
8. Update dependencies using `composer update` command.
9. Apply migrations with `php artisan october:up` command.

_*Note the non-standard <code>wikimedia/composer-merge-plugin</code>, it is forked by Luke Towers (one of the main developers of the October kernel) to ensure compatibility with Composer v2._

Congrats, you now have the latest features of the October CMS platform!

##Affected functionality

As we’ve already noted, the move to Laravel 6 deeply affected the functionality of the October CMS. Therefore, some parts of your code may also require changes:

* [Configuration files (`/config/*.php`)](https://octobercms.com/support/article/RN-11#upgrade-config)
* [Environment variables (`.env` files)](https://octobercms.com/support/article/RN-11#upgrade-env)
* [Server configuration (`.htaccess` files)](https://octobercms.com/support/article/RN-11#upgrade-server-config)
* [Any packages made for Laravel](https://octobercms.com/support/article/RN-11#upgrade-laravel-packages)
* [Laravel package auto-discovery](https://octobercms.com/support/article/RN-11#laravel-package-autodiscovery)
* [Interacting with `Cache` repositories](https://octobercms.com/support/article/RN-11#upgrade-cache)
* [String-based primary keys in models](https://octobercms.com/support/article/RN-11#upgrade-string-keys)
* [Use of `$guarded` in models](https://octobercms.com/support/article/RN-11#guarded-in-models)
* [Wildcard event listeners](https://octobercms.com/support/article/RN-11#upgrade-wildcard-listeners)
* [Catch-all routing](https://octobercms.com/support/article/RN-11#catchall-routing)
* [Using Carbon directly](https://octobercms.com/support/article/RN-11#upgrade-carbon)
* [Jenssegers/Date directly](https://octobercms.com/support/article/RN-11#upgrade-jenssegers-date)
* [Using Symfony directly](https://octobercms.com/support/article/RN-11#upgrade-symfony)
* [Using League/Csv directly](https://octobercms.com/support/article/RN-11#upgrade-league)
* [Unit Testing](https://octobercms.com/support/article/RN-11#upgrade-unit-testing)

Also, don’t forget to update all installed plugins to the latest versions. Thus, if you have RainLab.Translate installed, make sure its version is at least 1.7.3. With earlier versions, you will run into trouble using it.

##New versioning scheme

In addition to supporting Laravel 6, October moved to a new one, more suitable for the current realities of the development of this CMS. The main change is that the version number will now include the minor version number.

October CMS is still in the "evergreen" stage, where versions differ only in build numbers. This is the result of the development team agreement from day one of the project.

The previous LTS version of Laravel had a fairly long lifespan. It is currently used by many sites. Therefore, we need a way to keep providing security updates for these websites, especially if they cannot update to the latest CMS or PHP.

As a result, October CMS switched to a new version control scheme where the major number (v1) will remain at 1 to reflect the commitment to update stability. Minor number (v1.x) will now increase when updates that might affect dependencies are released (for example, Laravel framework updates). The patch number (v1.0.x) will still reflect ongoing updates or builds, but will be reset every time a minor version is changed.

There will now be three main types of releases for this CMS:

* Develop - where active developments take place;
* 1.0 - stable build running Laravel 5.5 (previously master);
*1.1 is a stable build running Laravel 6.

It’s important to note that October CMS is still evergreen, so when a minor version is released all previous versions will no longer be supported. Only security issues in the core will be patched in prior versions. So we recommend that you always stay up to date with the latest version of October CMS.