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 6.0 from 5.7 SupportPal 6.0 is a major release with some breaking changes. This upgrade guide is aimed at those upgrading from the last stable version (5.7.x) to 6.0.0. **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 [6.x Release Notes](6.x+Release+Notes) for the new features and improvements in this series. --- ## New System Requirements Please ensure your server meets the server requirements before trying to upgrade. - The minimum supported PHP version is now **8.3.1**. - The minimum supported ionCube Loader is now **14.4.1**. - The minimum supported MySQL version is now **8.0** and minimum supported MariaDB version is now **10.5**. Additionally, the new version adds support for PHP **8.5**. --- ## Important Changes ### Web Sockets The implementation of the built-in web socket server has changed in this release. If you have manually deployed the web socket server on [Linux](Third+Party+Integrations+Pusher#UsingLinux), you will need to restart the daemon in order to use the new implementation: ``` sudo supervisorctl restart websockets ``` If you're using nginx in front of the web socket server, you may also need to [update your configuration](https://github.com/supportpal/helpdesk-install/commit/b6294ba85cd2da548a22d40ce847a68c4d6a6fb9). ### Throttling Web and email throttling now uses a weighted token system. New tickets consume three tokens, while replies consume one token toward the configured limit. To prevent throttling from becoming more restrictive after upgrading, existing throttling limits will be automatically multiplied by three. We recommend reviewing your throttling settings (**Settings -> Tickets -> Channels-> Web/Email -> Settings**) after upgrading to ensure they are still appropriate for your requirements. ### SimpleAuth The `firebase/jwt` library has been updated and now requires JWT signing keys to be at least 32 characters long. SimpleAuth uses JWTs for authentication, so the configured key (**Settings -> SimpleAuth tab**) must meet this requirement. By default, a 32-character key is generated, so most installations will not be affected. However, if you have manually configured a shorter key (previous validation allowed keys as short as 16 characters), you must update it to a minimum of 32 characters. --- ## Config File Changes **config/app.php** The ticket message loading functionally has changed and the related [configuration options](App+Configuration#TicketMessages) have been updated: - `MESSAGE_LOAD_NO` has been removed, with a new option `MESSAGE_LOAD_INITIAL` introduced. - `MESSAGE_LOAD_LIMIT` no longer accepts `null`, with a maximum value of `50`. --- ## Addons Addons will be upgraded automatically as part of the upgrade to version 6. Pay careful attention to the below upgrade notes. ### AI Assistant #### Regenerating Embeddings Data Embedding data needs to be recreated to use the new version, which will be performed automatically as part of the upgrade process. It will only regenerate embeddings for the last year of ticket data. - If you want to index less than a year of data, then you will need to browse to the AI Assistant settings, disable the ticket source and then re-enable it with a new start date. - If you want to index more than a year of data, then please wait for the existing synchronisation process to complete before starting a new synchronisation with an earlier start date. --- ## Docker Deployment Changes ### Monolithic Deployments The below information is only relevant to those who have deployed SupportPal using [Docker (Monolithic)](Deploy+on+Docker). #### Environment Variables Deprecations The following environment variables have been deprecated: - The `DOMAIN_NAME` variable has been deprecated, use `MAIL_DOMAIN_NAME` instead. - The `DOMAIN_NAMES` variable has been deprecated, use `CADDY_DOMAIN_NAMES` instead. - The `EMAIL_ADDRESS` variable has been deprecated, use `CADDY_EMAIL_ADDRESS` instead. Update the variable name in your `docker-compose.override.yml` and `.env` files. #### Qdrant Qdrant was added to facilitate self-hosted use of the AIAssistant beta plugin. We have since added support for Meilisearch as a vector database, and therefore have decided to remove Qdrant to reduce resource usage and maintenance overhead. If you are using the AIAssistant plugin, it will automatically reindex your data. If you are not using the AIAssistant plugin, then this change will not affect you. #### Caddy Caddy has been bumped to **2.11.3**. This change should not affect you unless you're using a custom `Caddyfile`, in which case, we would encourage you to review Caddy release notes. #### Meilisearch Meilisearch has been bumped to version **1.45.1**. To facilitate this change, the upgrade script will drop your existing Meilisearch data and re-index after the upgrade is complete. Reindexing can be monitored by viewing Utilities, System, Background Jobs in the operator panel. Depending on the size of your installation, this process may take some time, during which search functionality will revert to database search. #### MySQL MySQL has been bumped to version **8.4.9**. Container setup may be slow while MySQL upgrades its data files, so please bear that in mind before upgrading. --- ## Development Changes 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. ### Third-Party Library Updates - We've upgraded the core framework (`laravel/framework`) from version 10 to 13. Please review the upgrade guides for breaking changes: 1. [10.x to 11.x](https://laravel.com/docs/11.x/upgrade) 2. [11.x to 12.x](https://laravel.com/docs/12.x/upgrade) 3. [12.x to 13.x](https://laravel.com/docs/13.x/upgrade) - `blueimp-file-upload` has been replaced by [Uppy](https://uppy.io/). This change is highly unlikely to affect you unless you have custom code that interacts with the file upload functionality, in which case, we would encourage you to review the `uppy.js` documentation. - `selectize.js` has been replaced by [Tom Select](https://tom-select.js.org/). This change is largely backwards compatible. We are still using the `$.selectize` initialiser, and the API function names remain the same. If you have custom code that interacts with Selectize we encourage you to review those changes before upgrading. The most notable change is that the `tom-select` API does not return jQuery objects. - `jQuery` has been upgraded to version 4. This is unlikely to affect you unless you have custom code that interacts with jQuery, in which case, we would encourage you to review the [breaking changes](https://jquery.com/upgrade-guide/4.0/). ### Route Changes The way that permissions are defined on routes has changed. Update your routes to use the new syntax: ``` $router->get('settings', [ - 'can' => 'view.addon', + 'middleware' => 'can:view.addon', 'as' => 'plugin.helloworld.settings', 'uses' => 'Addons\Plugins\HelloWorld\Controllers\HelloWorld@getSettingsPage' ]); ``` **Important** The legacy `can` route option is no longer supported. Add-ons that have not been updated to use the new `middleware` syntax will not load until the route definitions have been updated. ### CSS Class Changes `TailwindCSS` has been upgraded to version 4. If you are using our TailwindCSS utility classes in your custom template or add-on, the class prefix must be updated from `sp-` to `sp:`. However, our own custom classes names have not changed. ``` -
+
``` ### Removal of Ticket Constants The `\App\Modules\Ticket\Models\Ticket::OPERATOR` and `\App\Modules\Ticket\Models\Ticket::USER` constants have been removed. Use the `\App\Modules\Ticket\Models\Message::OPERATOR` and `\App\Modules\Ticket\Models\Message::USER` constants instead. ### Sending Emails Changes The `sendTicketMail`, `sendOperatorMail` and `sendUserMail` mailer methods (see [Plugin Development: Sending Email](Plugin+Development+Sending+Email)) have been updated. The first parameter must now be an email template model instead of a template ID. Please update your code to use the new syntax: ``` \App\Modules\Core\Controllers\Mailer\Mailer::sendTicketMail( - $templateId, + \App\Modules\Core\Models\EmailTemplate::findOrFail($templateId), $ticket, [ 'email_type' => \App\Modules\Core\Models\EmailTemplate::OPERATOR, 'activity_log' => [ 'type' => \App\Modules\Core\Models\ActivityLog\Type::System, 'rel_name' => $ticket->number, 'rel_id' => $ticket->id, 'rel_route' => 'ticket.operator.ticket.show', 'section' => 'ticket.ticket', 'event_name' => 'sent_email_to_operators' ] ] ); ``` ### Context Panels Version 6 introduces [context panels](Plugin+Development+Context+Panels) - a dedicated sidebar area in the operator panel designed to surface contextual information without cluttering the main interface. Context panels appear as collapsible tabs on the right-hand side, keeping supplementary data organised and out of the way until needed. If your add-on currently injects data directly into the ticket view (or other pages), we strongly encourage you to migrate this to a context panel. Context panels offer several advantages over direct view injection: - **Cleaner ticket view** - supplementary data is tucked away in the sidebar rather than competing for space in the main content area. - **Tabbed navigation** - multiple panels from different plugins coexist without conflict, each accessible via its own tab icon. - **Consistent UX** - panels follow a standardised layout, ensuring your add-on feels native to the SupportPal interface. - **On-demand loading** - panel content can be loaded lazily, reducing unnecessary data fetching on every ticket open. See the [context panels documentation](Plugin+Development+Context+Panels) for a full guide on registering and building a panel for your plugin.