You're browsing the documentation for an old version of SupportPal. Consider upgrading to the [latest version](https://docs.supportpal.com/current/Documentation+Home). # Upgrading to 4.0 from 3.7 SupportPal 4.0 is a major release with some breaking changes. The focus of this release is around improving the add-on (a general term we use to cover plugins, widgets, channels, integrations, reports, and languages) functionality and introduces the add-on marketplace. This upgrade guide is aimed at those upgrading from the last stable version (3.7.x) to 4.0.0. **Estimated Upgrade Time: 1 - 2 Hours.** **Backup!** Before attempting an upgrade, please take a [backup](Backup+and+Restore#Backup) of both your SupportPal database and all associated SupportPal files, then verify the backup is valid (not corrupt). If you use either of our operator panel [system update](System+Update) or [app update command](App+Update+Command) options, a backup will automatically be taken before performing the update. ## What's New? View the [4.0 Release Notes](4.x+Release+Notes) for the new features and improvements in this series. ## New System Requirements - The new minimum PHP version is now **7.4.0**. PHP 7.2 and 7.3 have reached [end of life](https://www.php.net/supported-versions.php) and support for them have been dropped in this release. - The new minimum version for ionCube loaders is now **11.0.1**. - The **[Hash](https://www.php.net/manual/en/hash.installation.php)** PHP extension is now required. - Internet Explorer 11 is no longer supported. - The `/addons` directory and subdirectories must be writeable. ## Docker Changes Breaking changes have been introduced to all of our docker deployment methods in order to facilitate easier customisation and upgrades. Jump ahead to the relevant section depending on which docker deployment method you're using: - Monolithic container ([installation guide](Deploy+on+Docker)) - [jump ahead](#MonolithicDeployments). - High availability containers ([installation guide](Deploy+on+Docker+HA) & AWS Elastic Beanstalk) - [jump ahead](#HighAvailabilityDeployments). ### Monolithic Deployments Follow the usual upgrade steps described at [Upgrade Guide](Upgrade+Guide#UpgradeDockerMonolithic). ### High Availability Deployments #### New Image Tag Naming Convention The format used for tags on our high availability images has changed. Previously the format `version-type-os` was used, where: 1. `version` represented the SupportPal version number 2. `type` represented the purpose of the image, for example `web`, `cron` 3. `os` represented the os version string, for example Debian `buster` (version 10) The new, simplified, format is now `version-type`. #### Upgrade steps Due to the introduction of breaking changes, we recommend migrating to a new directory. Follow the steps below to begin: 1. Open a bash compatible terminal. If you're on Windows, use Git Bash. 2. Take a [full backup](Backup+and+Restore). 3. Browse to a directory where you would like to create a new SupportPal deployment, and run the below commands: ``` curl -LsS https://raw.githubusercontent.com/supportpal/helpdesk-install/master/templates/docker-compose/setup.sh bash setup.sh --target ``` 4. Follow the [new customisation guidance](Deploy+on+Docker+HA#Customisation) to adapt any previous customisations to the new structure. This should typically be the difference between the `*.dist.yml` and `.yml` files. 5. Destroy the old containers: 1. Browse to your **old** `helpdesk-install` deployment directory. 2. Copy the value of the `COMPOSE_FILES` variable from `Makefile`. For example given: ``` COMPOSE_FILES=-f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.override.yml ``` The copied value would be: ``` -f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.override.yml ``` 3. In the copied value, replace `docker-compose.override.yml` with `docker-compose.https.yml` 4. Replace `COMPOSE_FILES` with the copied value in the command below and run: ``` docker compose COMPOSE_FILES down -v ``` 6. Initialise the new containers: 1. Browse to your **old** `helpdesk-install` deployment directory. 2. Copy the entire `COMPOSE_FILES` line from `Makefile`. For example: ``` COMPOSE_FILES=-f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.override.yml ``` 3. In the copied value, replace `docker-compose.override.yml` with `docker-compose.https.yml` 4. Paste the copied value at the top of the `Makefile` within your **new** deployment directory (created earlier by `setup.sh`). For example, ``` COMPOSE_FILES=-f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.https.yml include Makefile.dist include .env ``` 5. From your old deployment directory, copy over your database secrets and SSL certificates from `ssl/` and `secrets/` directories. 6. Remaining within the **new** deployment directory, run: ``` make start ``` ## Development Changes ### Template Engine [Twig](https://twig.symfony.com/docs), our template engine, has been upgraded from v2 to v3 which offers better performance and robustness. The template engine is used throughout the help desk to render [merge fields](Merge+Fields). For most users, the upgrade should not make a difference. However, if you have written any custom Twig code we encourage to read over the [list of deprecations in Twig 2.x](https://twig.symfony.com/doc/2.x/deprecated.html). ### Framework We've upgraded the core framework (`laravel/framework`) from version 6 to 8. Please review the upgrade guides for breaking changes: 1. [6.x to 7.x](https://laravel.com/docs/7.x/upgrade) 2. [7.x to 8.x](https://laravel.com/docs/8.x/upgrade) We recommend testing any customisations on a development installation before upgrading your help desk. Please contact us for a development license key if you don't already have one. ### Add-ons An important part of this release is the improvements to the add-on framework that exists in the software. An add-on is a general term that covers any component which is not core to the software and adds additional functionality. **Add-on Categories** - [Channels](Reports) - the methods through which tickets can be opened in the system. - [Integrations](Third+Party+Integrations) - for configuring connection (API or app) details for third-party providers that are utilised in various places in the system. - [Languages](Languages) - translate the system to other languages. *New in 4.0.0.* - [Plugins](Plugins) - general area to build extra functionality to the system. - [Widgets](Widgets) - the panels that show on the operator dashboard. All add-ons are now placed in the `/addons` directory in the SupportPal installation directory, within which there are subdirectories for each category of add-on. During the upgrade, the system will try to move non-default add-ons to the new directories, such as plugins from `/app/Plugins/` to `/addons/Plugins`. The old directories will no longer be used. ##### **PHP Namespace** As the files have moved to a new directory, we recommend updating the PHP namespace in your add-ons. It is just a case of replacing any instances of `App\Plugins\` to `Addons\Plugins\` (and similar applies to the other add-on categories). For example: ``` namespace App\Plugins\BlestaInformation\Controllers; ``` This should be changed to: ``` namespace Addons\Plugins\BlestaInformation\Controllers; ``` ##### **Language/View Namespace** To avoid conflicts between different types of add-ons, the language and view namespaces have been prefixed with the add-on category. It is just a case of replacing any instances of `MyPlugin::` to `Plugins#MyPlugin::` (and similar applies to the other add-on categories) throughout your PHP and Twig files. **Views** ``` View::composer('BlestaInformation::settings', function ($view) { ``` This should be changed to: ``` View::composer('Plugins#BlestaInformation::settings', function ($view) { ``` **Languages** ``` {{ Lang.get('BlestaInformation::lang.invoice_no') }} ``` This should be changed to: ``` {{ Lang.get('Plugins#BlestaInformation::lang.invoice_no') }} ``` #### Plugins All non-default plugins will be automatically disabled on upgrade and must be manually reactivated. We recommend reading over this section and ensure each plugin works on 4.0.0 before reactivating. #### Widgets The signature of the `getEmbeddableView` function has changed, you must update your widgets to return a `View` object or null. ``` public function getEmbeddableView(): ?View; ``` #### Languages Language files have moved from `/resources/lang` to `/addons/Languages` and now have a new structure. If you have one or more custom languages installed currently, the upgrade script will automatically attempt migrating them to the new format during the upgrade to 4.0. ## Other Important Changes - **New editor: TinyMCE** The text editor included in SupportPal has been replaced with TinyMCE. We have tried to replicate the look and feel of the old editor as much as possible, but there will be some differences in usage. - **Assigning a ticket to an SLA plan must match its conditions** If you wish to change the SLA plan on a ticket, the conditions for each plan are now checked before a list of matching plans are provided to choose from. Previously it was possible to assign to any SLA plan. - **Default order for articles search API endpoint** The default order for articles that are fetched by the articles search API endpoint now uses the `weight` option with descending direction (the strongest weight first).