How to upgrade PHP for EspoCRM without stopping the upgrade path
An EspoCRM upgrade stops when the server's PHP version falls outside what the new release supports. If your instance runs on an older PHP, the next EspoCRM version may refuse to proceed, or it may install and then fail in ways that are harder to diagnose. The EspoCRM server configuration docs list PHP 8.3 to 8.5 as supported, so the first check is simple: confirm the PHP version your web server actually executes, not only the version installed at the command line. Treat the PHP change as a separate project from the EspoCRM change. It touches the web server handler (PHP-FPM or the Apache module), the cron job that runs EspoCRM's background work, and every PHP extension your instance depends on, including any installed by an extension or by your hosting provider.
For planning, the releases page lists EspoCRM 9.0.0 as released on January 20, 2025 and 10.0.0 as released on July 2, 2026. If your instance is still on 9.x, the 10.0.0 requirements apply to your PHP plan now, and the upgrade window should be set around the PHP work rather than the reverse. Ask your team to inventory three things before scheduling anything: the PHP version and SAPI used by the web server, the same version used by the cron user (these often differ), and the list of loaded modules reported by php -m under each. Record which modules are present on the current server and which were added manually, because those are the ones that will not come back after a new PHP installation unless someone reinstalls them.
Keep the PHP upgrade on a staging copy first, with the EspoCRM version you intend to reach, and run the upgrade there before production. Confirm the web server handler points to the new PHP-FPM socket, that cron runs under the new binary, and that a background job completes end to end. Also confirm with your hosting or platform team whether your OS packages supply the target PHP version or whether a third-party repository is needed, since that decision drives the timeline more than the EspoCRM steps do. Check the extension vendor's stated PHP range for each installed extension before you move, because a PHP upgrade can silently break a module that still loads.
Which PHP path fits your server
This table compares four common ways to get a PHP version that EspoCRM supports onto your server. Read each row against your own change control: who decides the PHP version, how extensions arrive, and how fast you can go back if the upgrade fails.
| Path | Who controls the PHP version | Extension modules and rollback |
|---|---|---|
| Operating system packages | Your OS vendor and repository. Confirm which PHP versions your release offers before planning. | Installed through the package manager. Rollback depends on keeping the old PHP packages available and on a tested backup. |
| Third-party PHP repository | The repository maintainer, alongside your team's choice of version package. | Extensions come from the same repository. Pin versions and keep a record of the packages installed for each PHP version. |
| Docker-based stack | Your image tag. Changing the PHP version means building or pulling a new image. | Extensions are baked into the image. Rollback means redeploying the previous image tag with the same volumes. |
| Managed hosting provider | The provider, usually on a schedule they publish. Ask which PHP versions they support. | Extensions are typically handled by the provider. Ask how they test PHP changes and whether they can roll back for you. |
| Version support check | Confirm the supported range in the EspoCRM server configuration documentation for your target release. | Test every extension your instance loads on the new PHP version before changing production. |
Order of work for a PHP upgrade in staging
This sequence moves the PHP runtime from an inventory of today's setup to a tested staging system, so production changes only happen after the new PHP version has been proven against EspoCRM, its extensions and its scheduled jobs.
Record the current PHP and extension baseline
Start by documenting the PHP version, the php.ini and pool files, every loaded extension module, and the web server and cron configuration on the production host. Your administrator runs
php -vandphp -mfrom the same environment that serves EspoCRM, then saves the output with the EspoCRM version from the administration panel. Capture the same details for the staging copy so you can compare the two. The step is done when you have a written baseline that lists each extension module by name and version, and both environments match the record.Confirm the target PHP range for your EspoCRM version
Check the release notes for the EspoCRM version you plan to run, then compare them with the server configuration documentation, which lists the supported PHP versions. Your platform owner confirms the exact PHP range for the target release and notes any extension that the release requires. Do not assume that a newer EspoCRM release supports the same PHP range as the one you run today. The step is done when the target PHP version is written down with its source, and any gap between the baseline and that range is listed as a blocker.
Install the new PHP version beside the current one
On the staging server, install the target PHP version alongside the existing one where your operating system or package source allows it, using a separate PHP-FPM pool or service so the old runtime keeps working. Your systems engineer keeps the current production version untouched. Confirm the new binary responds with
php8.x -v(using the target version) and that its configuration file loads from the expected path. The step is done when both PHP versions run on staging and neither one has replaced the other.Reinstall and verify each extension module
Install every extension module from the baseline into the new PHP version, using the same package names or build options as before, and adjust the php.ini settings that EspoCRM depends on, such as memory limits and upload sizes. Your engineer runs
php -mon the new binary and compares the result line by line with the baseline. Any module that is missing, or that is only available as a source build, is recorded as an open item. The step is done when every baseline module is present on the new version or has a documented replacement or removal decision.Point the web server and cron at the new version separately
Switch the web server's PHP handler on staging to the new PHP-FPM socket, then update the cron entry or scheduled task that runs EspoCRM background jobs so it calls the new binary explicitly. Treat these as two separate changes, because the web request path and the scheduled job path can run different PHP versions if one is missed. Your engineer checks the web server by loading an EspoCRM page and reading the version in the administration information, then confirms cron with a job that logs
php -voutput. The step is done when both paths report the target version.Run functional and background job tests in staging
Log in on staging with a test user and exercise the workflows your teams depend on: record creation, list views, formula-driven fields, email sending, imports and any extension features. Then confirm that scheduled jobs run under the new version by checking the job log for errors after a full cron cycle. Record every error with its PHP version, module and log line. The step is done when the core workflows pass and the background job log shows no new PHP-related errors compared with the baseline.
Approve the production change with a rollback path
Before any production change, confirm a tested backup of the EspoCRM files and database exists and that the previous PHP-FPM pool and cron entry are saved so they can be restored. Schedule the switch with the people who own the business processes that rely on EspoCRM, and agree on the checks you will repeat after the change. Your platform owner signs off on the staging results and the rollback steps in writing. The step is done when the signed record is attached to the change ticket and the production switch is ready to run.
What changes for a script install, Docker stack or custom server
The EspoCRM installation script for Ubuntu, Debian and Linux Mint deploys a Docker-based stack with Nginx and MariaDB, with optional Let's Encrypt certificates. A command.sh utility handles backups, restores and upgrades, so the upgrade path runs through that tool rather than through hand-edited server packages. Confirm before you upgrade how PHP is supplied inside the stack, because the PHP version is set by the stack's container image, not by the host operating system.
- PHP source: Find out which PHP version the stack's application container runs and whether the script pins it or pulls a newer image on upgrade.
- Upgrade route: Confirm that
command.shupgrade is the supported route for the target version and that you have read the release notes for it. - Backups: Run the utility's backup and confirm you can restore it on a separate host before changing PHP.
- Extensions: Check which PHP modules the container image includes, since extra modules you rely on may not be present.
- Host packages: Do not install PHP on the host to fix a version mismatch inside the container.
Check the installation script documentation for the current PHP and container details before you plan the change.
A Docker deployment ties PHP to the application image. Upgrading PHP means changing the image tag or rebuilding a custom image, then recreating the containers while keeping the same volumes and configuration. Your team owns the image choice, so the PHP version is whatever the image provides, and mismatches show up as a failed start or a blank page after the container is recreated.
- Image tag: Identify the current image and the tag that carries the target PHP version, and confirm the tag exists before you pull it.
- Custom images: If you built an image with extra modules, rebuild it on the new base and reinstall each module.
- Volumes: Keep data, file storage and configuration volumes unchanged so the recreated containers read the same state.
- Cron: Confirm the scheduled job runs in the container or host that the new image expects.
- Rollback: Keep the previous image tag so you can recreate the old container if the new PHP version fails.
Test the new image on a copy of the volumes before you replace production containers.
On a custom server, your team controls PHP entirely. The web server must hand requests to the PHP version you install, usually through a handler on Apache, a FastCGI process manager on Nginx or a FastCGI handler on IIS. Upgrading PHP means installing the new version beside the old one, pointing the web server at its socket or handler, and reinstalling extensions for that version. The server configuration documentation lists the supported PHP range, so check it before you install anything.
- Handler configuration: Update the PHP handler or FastCGI socket path in the virtual host or site configuration, then test with a configuration check before reloading.
- Process manager: Confirm the PHP-FPM pool or FastCGI process for the new version runs under the correct user with access to the EspoCRM files.
- Extensions: Install each required module for the new PHP version and verify it with a PHP info check.
- Cron: Confirm the scheduled job calls the new PHP binary, since the system crontab may still point at the old version.
- Old version: Keep the previous PHP install until the new one passes testing.
Check the server configuration documentation for the current PHP range and the cron requirement before you schedule the change.
With managed hosting, the provider controls the server, the PHP runtime and often the scheduling of upgrades. Your team controls the application and the data. That split means the PHP version may change on a schedule you did not choose, or it may be locked at a version that is too old for the EspoCRM release you want. Ask for both facts in writing before you commit to an upgrade date.
- Version control: Ask which PHP versions are offered, which one your plan runs and who decides when it changes.
- Module list: Request the full list of PHP extensions the host enables and whether it will add the modules EspoCRM and your extensions need.
- Cron access: Confirm the host runs the scheduled job for EspoCRM and tell you how to check it.
- Change notice: Ask how much notice you get before a PHP change and whether you can test on a staging copy first.
- Restore: Confirm the backup and restore process, including how long the host keeps copies.
If the host cannot commit to these points in writing, plan the PHP upgrade with that limit in mind.
Which extension modules to inventory and reinstall
PHP modules fall into four groups that each need their own inventory: database drivers, web server integration, modules used by installed EspoCRM extensions, and modules used by custom code. The same three steps apply to each group: list what is loaded now, compare against the target release's requirements, then test after reinstall. Confirm the exact module list with the release documentation and each extension's manifest before you change anything.
Database drivers for your database
EspoCRM needs a PDO driver that matches your chosen database: MySQL 8.0 or newer, MariaDB 10.6 or newer, or PostgreSQL 15. Run php -m on the target PHP version and confirm the matching driver, such as pdo_mysql or pdo_pgsql, is loaded. Check the database version separately, because a PHP driver on the new runtime does not prove the server meets the minimum. After reinstalling, log in, open the admin health pages and run a record save and a list query to confirm the connection works.
Web server integration modules
The PHP module that connects your web server to PHP, such as libapache2-mod-php for Apache or the PHP-FPM pool for Nginx, must be rebuilt for the new PHP version. Confirm which SAPI your server uses, and point the web server at the new socket or module before disabling the old one. Verify the request path by loading the login page and an API endpoint, and check that the PHP version reported to the web server matches the target. Confirm the exact module set in the server configuration docs.
Modules required by installed extensions
Each installed extension may depend on PHP modules beyond the core set, and its manifest records the PHP range it supports. Read the manifest of every extension, list the extension modules it requires, and check each against the target PHP version. Where a module is missing or an extension has no release for the target PHP, the upgrade is blocked until the extension is updated or replaced. Test each extension's core actions on a staging copy after reinstall.
Modules used by custom code
Custom code in the custom directory, including hooks, formula-driven logic and any scripts that call PHP functions from extra modules, can depend on modules that no EspoCRM release lists. Search the custom code for function calls and class references, such as curl_, mb_, intl or imap, and record each module it needs. Reinstall those modules on the target PHP version, then trigger each custom hook, PDF template and integration path in staging to confirm it still runs.
Testing order after reinstall
Test in order of dependency: runtime and modules first, then the database connection, the web server, extensions, and finally custom code. Start with php -v and php -m on the target runtime, then confirm the database and web server, then run the installed extensions and your custom workflows. Keep a list of which module each failure traces to, because a missing module often shows up as an error in an unrelated feature. Confirm the final list with the release notes and extension manifests.
What to confirm with EspoCRM and your environment before you start
Before you schedule a PHP upgrade, confirm four facts instead of assuming them. First, the PHP range the specific EspoCRM target release requires. The server configuration docs list PHP 8.3 to 8.5 for current releases, but requirements change between versions, so check the EspoCRM releases page and the server configuration docs for the exact target you plan to run. Record the version in writing with the date you checked it, because the answer you need is the one for the release you will actually install.
Second, whether every installed extension has a release that supports the PHP version you plan to run. Make a list of each extension, its installed version and the PHP range its release declares. An extension that works on your current PHP may have no compatible release for the next one, and that gap decides whether the PHP step can happen alone or must wait for the extension vendor. Third, whether your operating system or hosting provider offers the PHP version you need through its supported packages or a maintained repository. Ask your provider in writing which PHP builds they ship, how long they support them, and whether PHP-FPM and the required extension packages are included.
Fourth, whether your custom code, hooks, templates and scripts rely on functions or behavior removed or changed in newer PHP releases. Search the custom directory and any extension source for deprecated calls and run static analysis against the target PHP version. Also confirm which team owns each custom component, since the person who can fix a removed function is often not the person who wrote the original code. Your answers to these four questions determine whether the PHP upgrade is a standalone change or part of a larger project.
Questions buyers ask before upgrading PHP for EspoCRM
What drives the cost of a PHP upgrade for EspoCRM?
The cost follows the amount of work the upgrade touches, not the PHP version number itself. The main drivers are the number of installed extensions and whether each one has a release that supports the target PHP version, the volume of custom code in the custom directory and any hooks or formula scripts that depend on server behavior, the number of environments that must be upgraded in step (production, staging, test), and the chosen PHP path, such as an in-place upgrade of the existing server or a move to new hosts. A fixed-scope quote lists each of these items separately. Ask for the quote to name the extensions, the environments and the testing evidence you will receive.
How long does it take to plan and test a PHP upgrade?
Duration depends on the same drivers as cost: how many extensions need checking, how much custom code runs on the new PHP version, and how many environments must be tested before production. Planning covers an inventory of the running PHP version, modules and extensions, plus a compatibility check against the EspoCRM release you intend to run. Testing then repeats the core user paths, scheduled jobs and integrations on a staging copy. Ask any provider to state the planning and testing phases as separate line items in the written scope, so you can see where time goes.
What does the internal team need to provide for the upgrade?
The internal team usually provides access and decisions rather than hands-on engineering time. Typical needs include administrator access to the server or container host, a current database backup and a staging copy that matches production, a list of business owners who can sign off test results, and someone who knows which custom fields, workflows and integrations matter most. Confirm with your provider who holds the change window, who approves rollback, and how long your users can be without the CRM during cutover.
Can our own team upgrade PHP for EspoCRM without a partner?
Yes, a capable internal team can perform the upgrade if it has Linux and web server administration skills, can read PHP and extension release notes, and can run a staging test before production. The work becomes harder when many extensions are installed, when custom code relies on deprecated functions, or when the team has no spare staging environment. Compare your team's capacity and the risk of a failed cutover against a partner's fixed-scope quote, and decide before the change window is booked.
What happens if the PHP upgrade fails during cutover?
A well-run upgrade keeps a tested rollback path before the change starts. That path normally includes a verified database and file backup taken immediately before the switch, a documented way to restore the previous PHP version and web server configuration, and a checklist for confirming that scheduled jobs and integrations work again. Ask the provider to show how rollback is tested on staging, who makes the rollback decision, and how long the restore step is expected to take based on your data volume.
Which EspoCRM and PHP details should we confirm before requesting a quote?
Before requesting a quote, confirm the EspoCRM version you run today and the target version, the PHP version and extensions on each server, the web server (Apache, Nginx or IIS) and the database engine. The server configuration documentation lists the supported PHP range, so check the target release against that page and the release notes on GitHub. Also list every installed extension and whether it is an official package or custom code. These facts let a provider scope the work accurately.
How do we request a fixed-scope quote for a PHP upgrade?
Send the inventory described above, the target EspoCRM and PHP versions, the number of environments and the business constraints such as change windows and acceptance criteria. DeployOpen does not publish a price list. Most engagements are fixed-scope, so a quote follows from a written scope that sets out deliverables, timelines and what is excluded before work starts. Ask for the scope to state what is tested, what evidence you receive, how rollback is handled and what support, if any, follows the cutover.
How DeployOpen scopes and delivers a PHP upgrade for EspoCRM
DeployOpen plans, builds, tests, documents and supports self-hosted open-source platforms inside your own infrastructure, including the PHP runtime that EspoCRM depends on. We start from your installed version, extensions and custom code, then agree the PHP move in writing before any work begins.
How we scope
- Inventory the current EspoCRM version, PHP version, web server and database versions, and the target release.
- List installed extensions, custom directory code and PHP modules, then confirm which ones need a compatible release or reinstall.
- Agree the scope, deliverables and timeline in writing, with the quote following from that written scope.
How we build
- Build a staging copy of the production instance with the same PHP runtime, extensions and data snapshot.
- Install the target PHP version, reinstall extension modules, and run the EspoCRM CLI upgrade steps against staging.
- Test logins, cron and background jobs, email, integrations and custom formulas before any production change.
How we hand over
- Deliver a written runbook with the PHP switch order, rollback steps, backup checkpoints and verification checks.
- Document the final PHP version, extension list, module versions and any custom code changes made during the upgrade.
- Walk your administrators and engineers through the cutover and confirm who owns each step after handover.
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer if you want DeployOpen to handle future PHP and EspoCRM releases.
- Review extension compatibility and PHP support status again before each later EspoCRM major version upgrade.
- Confirm with your team which support scope, response expectations and maintenance windows apply before the engagement starts.
