← Blog
Perfex CRMPHPSelf-Hosting

Perfex CRM PHP 8 Upgrade: What Breaks and What Does Not

Perfex CRM PHP 8 compatibility is decided by your weakest module, not the core. Build the matrix, read the three error signatures, and switch without downtime.

The host sends a notice: PHP 7.4 is retired on this server, accounts move to 8.3 on the 14th, no action required. Or there is no notice at all, and you find out on a Monday when the admin loads perfectly, invoices are fine, the portal is fine - and one module’s settings screen returns a blank white page.

The useful question is not “does Perfex support PHP 8”. It does, and has for years. Perfex CRM PHP 8 compatibility is decided by the weakest third-party module you have installed, because the core is one codebase maintained by one team while your modules/ directory is a dozen codebases on a dozen different schedules. The upgrade does not break Perfex. It breaks whichever add-on has not been touched since 2021.

We build and sell several of the Perfex modules named below. They appear here because we publish exact version floors and ceilings for them, which is the thing this article argues you should demand from every vendor - weigh the mentions accordingly.

Perfex CRM PHP 8 compatibility is two numbers per module, not one

Every module has a floor and a ceiling, and vendors overwhelmingly publish only the floor.

“Requires PHP 7.4 or later” is a claim about the past: the code uses no syntax older than 7.4. It says nothing about whether the code survives 8.2, because “or later” is an aspiration, not a test result. The number you need is the ceiling - the highest version the vendor has actually run the module against.

Across our own Perfex catalogue the spread looks like this, and the shape of it is the point:

ModuleStated minimumStated ceiling
Advanced Email SystemPHP 7.4no PHP version named
Staff Outsourcing & Resources BookingPHP 7.4PHP 8.x, Perfex core v3.x
SaaS / multi-tenancy modulePHP 7.4PHP 8.x, Perfex 3.0.0+, MySQL 5.6+
REST API modulePHP 7.4full PHP 8.x
Webhooks modulePHP 7.4PHP 8.2 and 8.3, Perfex 3.2.1+
GoCardless gatewayPHP 8.1 recommendedPHP 8.2+
Mercado Pago gatewaynot publishedPHP 8.x

Read the sixth row again. The GoCardless gateway has no low floor at all - it is built for modern hosting, recommends 8.1 or newer, and states 8.2+ compatibility. A module can push you forward as easily as hold you back. On 7.4, that gateway makes the upgrade a prerequisite rather than a deferrable task.

So the arithmetic is:

  • Your floor = the highest minimum across all installed modules.
  • Your ceiling = the lowest tested maximum across all installed modules.
  • Your safe window = everything in between.

If the window is empty you do not have an upgrade to plan, you have a module to replace - and you found that out before the downtime rather than during it.

How to find the Perfex module PHP version requirement a vendor never published

Half your modules will have no stated ceiling. Three places answer it without guessing:

  1. The changelog. A module whose newest entry reads “PHP 8.3 fixes” has been looked at recently. One whose last entry is from 2021 has a real ceiling of 8.0, whatever the product page claims.
  2. composer.json inside the module. Run grep -rn '"php"' modules/*/composer.json from the install root. The require.php constraint is the only machine-readable version statement most modules carry; ^7.2 signals that nobody has thought about 8.x since.
  3. The presence of a vendor directory. find modules -maxdepth 2 -type d -name vendor tells you which modules ship third-party PHP of their own.

Bundled Composer dependencies carry their own PHP floors

This is the failure mode people miss, and it has nothing to do with a module’s own code. Our GoCardless gateway ships up-to-date GoCardless Pro, Guzzle and PSR-7 dependencies - a deliberate statement, because Guzzle and psr/http-message are the two libraries most likely to exist twice in a Perfex install, since nearly every module that talks HTTP bundles them. Guzzle 7 is the line built for PHP 8; Guzzle 6.5 predates it and trips over changes introduced from 8.0 onward. psr/http-message 2.0 added return types that 1.x did not have, so a class written against one interface version is not substitutable for the other.

Now put two such modules in one install, each bundling a different Guzzle major in its own vendor/. PHP resolves one class name per process: whichever autoloader registers first wins, and the second module silently runs against a library it was never tested against. The symptom is a fatal error naming a class you have never heard of, in a file you did not write.

To check, open modules/<name>/vendor/composer/installed.json and search for guzzlehttp/guzzle; the version field beside it is what you actually have. Two modules disagreeing by a major version is your highest-risk item.

Three error signatures and what each one means

After the switch, almost everything you see is one of three things.

A completely blank page

A fatal error with display_errors off. The page is blank because PHP died mid-render, so nothing is wrong with your theme, database or file permissions. A Perfex CRM blank page after a PHP upgrade is always sitting in the error log - the job is finding the log, not diagnosing the screen.

The 8.0 fatals worth recognising on sight: curly-brace string offsets ($s{0}), each() and create_function() were all removed, and many conditions that used to emit a warning now throw TypeError or ValueError. That last category kills old modules - the code always did something invalid, and 7.4 let it carry on.

HTTP 500 with nothing in the log

Nearly always one of two causes, and neither is the application.

The log is somewhere else. CLI, Apache mod_php and PHP-FPM each resolve error_log from a different php.ini, and a multi-version host gives every version its own configuration tree. Confirm with php -i | grep error_log for the CLI binary, then read the FPM pool config for the web one. The file you are tailing is usually the wrong one.

A missing extension. Extensions are enabled per version, so moving from 7.4 to 8.3 hands you a fresh, minimal set. Perfex needs mysqli or pdo_mysql, mbstring, curl, gd, zip, openssl and intl before it renders anything. Check with php -m against the correct binary - ten seconds, and it resolves more upgrade tickets than anything else here.

Restart PHP-FPM fully rather than reloading; a graceful reload can leave OPcache holding files compiled by the previous version.

A flood of deprecation notices

These are not failures. PHP 8.1 deprecated implicit nullable parameters and passing null to non-nullable internal arguments; 8.2 deprecated dynamic properties. Old code hits all three constantly, and none of it halts execution.

The damage is indirect, which is why it generates bug reports that look nothing like a PHP problem. With display_errors on, every deprecation is written into the response body - in the Perfex admin that means notice text prepended to JSON responses, so every AJAX table, autocomplete and save button appears broken while the underlying code works perfectly. The fix is configuration, not code:

display_errors = Off
log_errors = On
error_reporting = E_ALL

Log everything, display nothing, and clear the notices when vendors ship updates.

CLI and FPM are two different PHP installations

Your cron runs the CLI binary; your site runs FPM. On multi-version hosts they are routinely different versions, with different memory_limit, max_execution_time and extension sets.

This is where an upgrade quietly kills background work. If the crontab calls a bare php, a host-level default change repoints it and Perfex background jobs stop - no error, no banner, just recurring invoices that never appear. Anything queue-driven inherits the fragility: delayed trigger execution in our webhooks module requires a custom cron job, and a cron on the wrong binary looks exactly like a broken module.

Point the crontab at an absolute path and verify it after the switch:

crontab -l
/opt/cpanel/ea-php83/root/usr/bin/php -v

A rollback plan that actually rolls back

Switching the handler back is one click. What is not one click is anything that wrote to the database in between.

Module upgrades are the specific trap. Our REST API module is deliberately forgiving here: replace the files without deactivating first and any pending database changes apply themselves on the next admin page load, so a files-only upgrade does not leave you with “Unknown column” errors. That is what you want on an ordinary Tuesday - and exactly what you do not want inside the same window as a PHP switch, because once those changes apply, reverting PHP does not revert them and you can no longer tell which change caused the symptom.

The rule is blunt: change one variable at a time. PHP this week, module updates next week. When a vendor ships an updater with a downgrade guard and an OPcache reset built in, as that module does, run it on its own day.

The order to do it in

  1. List every directory in modules/ with its stated minimum and ceiling. Compute your floor, your ceiling and the window between them.
  2. Where no ceiling is published, check the changelog date and the require.php constraint. Treat “last touched three years ago” as a ceiling of 8.0.
  3. Grep the bundled vendor/composer/installed.json files for duplicate Guzzle or psr/http-message majors. Resolve conflicts before the switch, not after.
  4. Clone to a staging subdomain on the same host and stack. A local Docker copy proves nothing about your host’s extension set, the thing most likely to bite.
  5. Set display_errors = Off, log_errors = On, error_reporting = E_ALL, and confirm the resolved log path for both the CLI binary and the FPM pool.
  6. Switch staging to the target version and fully restart PHP-FPM.
  7. Smoke test in order: log in, open an invoice PDF, send a test email, run one sandbox payment, run the cron with the absolute new binary, call one API endpoint, fire one test webhook. Outbound HTTP calls are where bundled dependencies surface.
  8. On production, take a file snapshot and database dump first, switch in a low-traffic window, and leave the previous version installed for 72 hours.

If step 1 produces an empty window, stop there. You are not planning an upgrade, you are choosing which module to replace - and that is a purchasing decision, not a maintenance one.