Upgrading FreeScout to PHP 8.5 (Ubuntu 26.04 checklist)

Before you move FreeScout to PHP 8.5, confirm that FreeScout and every module you run support it, then check PHP extensions, restart the queue worker, and watch the log for deprecated since 8.5 messages. Ubuntu 26.04 installs PHP 8.5 by default, so an operating system upgrade is often what triggers the change.

This matters more for FreeScout than for most PHP apps, because of how FreeScout handles deprecation notices.

Why PHP 8.5 can break FreeScout modules

Each PHP release deprecates some older functions. PHP 8.5 deprecates several functions that have done nothing since PHP 8.0, including curl_close(), imagedestroy(), and xml_parser_free(). It also deprecates some edge cases, such as using null as an array key or passing chr() a value outside 0 to 255.

Most PHP apps log a deprecation and carry on. FreeScout turns every deprecation notice into an error, so a single leftover call stops the request or background job that hit it. A module can look installed and healthy while every connection it makes fails.

If you see these errors after upgrading, Fix "deprecated since 8.5" errors in FreeScout walks through finding and fixing the module responsible.

Before you upgrade

• Check support: read FreeScout's release notes and system requirements for PHP 8.5, and confirm each installed module has a PHP 8.5 compatible release.
• Update modules first: install those updates while you're still on your current PHP version, so every module is ready before the move.
• Back up: take a copy of the FreeScout directory, the database, and your PHP configuration files.
• Test on a copy: if you can, run the upgrade on a staging copy of the help desk first.

After you upgrade

1. Check the PHP version FreeScout runs

   Open Manage > System. It shows the PHP version your web server uses and lists the PHP extensions FreeScout needs, flagging any that are missing.

2. Match the command-line PHP

   Run php -v on the server. The queue worker and the schedule:run cron use command-line PHP, which can differ from the web server's version. Both must run the same version with the same extensions.

3. Reinstall extensions and settings

   A new PHP version comes with its own extension packages and php.ini files. Install the extensions Manage > System marks as missing, then reapply custom settings such as upload_max_filesize and post_max_size.

4. Point the web server at the new PHP

   If you use PHP-FPM, confirm your web server uses the PHP 8.5 FPM socket or service, then restart PHP-FPM and the web server.

5. Clear caches and restart the queue worker

   Run these from your FreeScout directory so no process keeps running old code:

   terminal

   Copy

   php artisan freescout:clear-cache
   php artisan queue:restart

What to check in the logs

Open Manage > Logs > App Logs after using the help desk for a while. Search for:

• is deprecated since 8.5, which points to a module or file that isn't PHP 8.5 ready yet.
• Providing a value not in-between 0 and 255 is deprecated, from chr() calls.
• Using null as an array offset is deprecated.

Each entry names the file. A path under Modules/<Name> tells you which module needs an update.

Test the features that make outbound connections, because these fail first: fetching mail, AI providers, knowledge sources, and integrations such as Linear, Jira, Slack, or store connectors. Where a module offers a Test connection button, use it.

If something breaks

Move FreeScout back to PHP 8.4 while you wait for updates. PHP 8.4 doesn't treat these functions as deprecated, so the same code runs normally there. Switch both the web server and command-line PHP, then restart PHP-FPM, the web server, and the queue worker.