Upgrading to 6.0 from 5.7

SupportPal 6.0 is a major release with some breaking changes.

What's New?

View the 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, 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.

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.

Config File Changes

config/app.php
The ticket message loading functionally has changed and the related configuration options 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

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
  2. 11.x to 12.x
  3. 12.x to 13.x
• blueimp-file-upload has been replaced by Uppy. 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. 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.

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'
]);

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.

-<div class="sp-form-container sp-pt-0 sp-border-t-0">
+<div class="sp-form-container sp:pt-0 sp:border-t-0">

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) 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 - 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 for a full guide on registering and building a panel for your plugin.