iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Antihost offers Linux VPS plans with full root access, unlimited traffic on a 1 Gbps port and a 14-day free trial.
Upgrade PHP on an Ubuntu VPS as a staged runtime migration, not as a single package command. Identify the Ubuntu release, PHP interfaces and extensions your application uses, take a restorable snapshot or backup, install the target PHP and matching extensions, point Apache or Nginx at the new runtime, test both command-line and web requests, then switch production traffic while retaining a rollback path. Ubuntu 24.04 LTS provides PHP 8.3 packages, including PHP-FPM; its standard security maintenance is scheduled through 31 May 2029.
What a PHP upgrade changes on a VPS
A PHP installation has more than one execution path. The CLI binary runs Composer, deployment scripts, cron jobs and queue workers. Apache may load PHP as an in-process module, while Nginx normally sends requests to a separate PHP-FPM service through a Unix socket. Each path can have its own php.ini, enabled modules and service configuration. Checking only php -v can therefore report a successful upgrade while your website still executes the previous FPM pool or Apache module.
Free tools Windows power users keep installed
One-click scans. No signup required.
PHP 8 also removes or changes deprecated behavior. Ubuntu 22.04 release notes specifically warn PHP 7.4 users to prepare for PHP 8 changes. The PHP migration guidance likewise cautions that a new minor release includes incompatibilities that should be tested before production cutover. Treat application code, Composer constraints, extensions, database drivers and background jobs as part of the migration.
Choose the upgrade route before changing packages
| Decision | Option 1 | Option 2 | What to evaluate |
|---|---|---|---|
| Package source | Ubuntu’s native repositories | A separately maintained repository | Security-update ownership, support for your Ubuntu release, extension availability and rollback complexity. Use the native source when its PHP version satisfies the application. |
| Web interface | Apache PHP module | PHP-FPM behind Apache or Nginx | Existing virtual-host design, isolation between sites, pool settings and the socket or proxy target that receives requests. |
| Installation shape | Replace the active version in place | Install the new version alongside the old one and cut over | Parallel installation usually gives an easier rollback, provided disk space and package dependencies allow both versions. |
| Project scope | PHP-only change | Full Ubuntu LTS release upgrade | Do not combine an operating-system release migration with a PHP-only change unless that combined migration is the explicit, tested plan. |
On Ubuntu 24.04 (Noble), the native package index lists php8.3, php8.3-fpm and a php-fpm default metapackage that resolves to the 8.3 FPM line at the time covered here. The Noble release notes identify PHP 8.3.6 as the release package version. Package versions can receive subsequent security updates, so check the host’s current candidate with APT rather than assuming that exact patch number remains installed.
Inventory the current server and application
Run the following as the account that administers the VPS. Save the output in the change record so you can compare the old and new states.
lsb_release -a
cat /etc/os-release
php -v
php -m
php --ini
apt policy php php-fpm
systemctl list-units --type=service 'php*-fpm.service'
If lsb_release is not installed, /etc/os-release still identifies the distribution and release. Record whether the web server is Apache or Nginx, which virtual hosts are enabled, and whether the site uses FPM pools rather than the default pool.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Record application requirements
- Read
composer.jsonand the lock file for the project’s PHP constraint and extension requirements. - List modules reported by
php -m, then compare them with the modules used by the application, such as database, XML, multibyte-string, cURL and ZIP support. - Find cron entries, systemd timers, queue workers, supervisor processes and deployment hooks that invoke PHP by an absolute path.
- Document database versions, writable upload directories, cache backends, scheduled tasks and any command that performs migrations.
- Check the application’s published support range for the target PHP version. A package that installs successfully is not proof that the application is compatible.
Create a restorable backup and rehearse the change
Create a provider-level VPS snapshot or another restore point before package changes. Also back up the data that a snapshot might not capture consistently, especially databases and user uploads. Save the configuration directories and package state:
sudo tar -czf /root/php-upgrade-config.tgz /etc/php /etc/apache2 /etc/nginx
apt-mark showmanual | sudo tee /root/apt-manual-packages.txt
sudo dpkg --get-selections > /root/dpkg-selections.txt
Back up each database using its engine’s supported dump procedure and preserve application secrets separately. A backup is useful only if it can be restored: verify that you can provision a test VPS or staging copy, restore a database and files, and start the application from the saved configuration. Note the snapshot identifier, creation time and the exact person or process authorized to restore it.
Keep the old PHP packages installed during testing when APT permits it. Parallel runtimes let you direct one virtual host or staging copy to the new socket while production remains on the old service.
Refresh APT metadata and simulate package changes
Ubuntu’s package-management guidance requires refreshing the local package index before package operations:
sudo apt update
apt policy php8.3 php8.3-cli php8.3-fpm
sudo apt -s install php8.3-cli php8.3-fpm
The -s simulation shows packages that would be installed, upgraded, removed or held without changing the system. Review removals carefully. An unexpected removal of a web server, database driver or required extension is a reason to stop and resolve dependencies before proceeding. If the target package is not listed for your Ubuntu release, do not guess a package name; identify a supported package source and evaluate its maintenance and rollback implications first.
Install PHP and a matched extension set
Install versioned packages so the CLI, FPM service and extensions belong to the same PHP line. This example targets PHP 8.3 on Ubuntu 24.04:
sudo apt install php8.3-cli php8.3-fpm php8.3-mysql php8.3-xml php8.3-mbstring php8.3-curl php8.3-zipThe list is an example, not a universal requirement. Select only extensions the application needs and adjust names for the target PHP version and Ubuntu release. Common omissions include the database driver used by the framework, XML support required by Composer packages, multibyte-string handling, cURL integrations and ZIP extraction. Installing an extension for the CLI does not automatically prove that the FPM SAPI loaded it; verify both interfaces later.
Inspect the resulting package and service state:
php8.3 -v
php8.3 -m
php8.3 --ini
systemctl status php8.3-fpm --no-pager
ls -l /run/php/
The socket is commonly named /run/php/php8.3-fpm.sock, but use the filename actually created on the host. Pool configuration can change the path, ownership or permissions.
Switch Apache to the intended PHP runtime
Apache module configuration
If the site uses Apache’s distribution module, inspect enabled modules and the installed module package. Ubuntu’s module path is represented by the libapache2-mod-php package. Disable the old PHP module and enable the target module only when that is the design you have chosen; do not enable both versions simultaneously for the same virtual host.
sudo a2dismod php7.4
sudo a2enmod php8.3
sudo apachectl configtest
sudo systemctl reload apache2
Replace php7.4 with the module actually enabled on the host. If the target module package is not installed, install the versioned package supplied for your Ubuntu release before enabling it. Ubuntu 24.04 release notes note that PHP updates restart apache2; schedule the operation for a maintenance window if a restart rather than a reload is triggered by the package transaction.
Apache proxying to FPM
If Apache is configured to proxy requests to FPM, retain that architecture and change the proxy target to the new pool or socket. Confirm that the relevant proxy, FCGI and set-handler directives are enabled, then run sudo apachectl configtest. A successful syntax test does not prove the socket is reachable, so check the FPM service and make a real request through the virtual host.
Switch Nginx to the new PHP-FPM service
Nginx does not execute PHP itself. In the site’s server block, locate the fastcgi_pass directive and change it to the target FPM socket, for example:
fastcgi_pass unix:/run/php/php8.3-fpm.sock;Use the socket listed in /run/php and the pool configuration, not a copied filename. Check the service and validate the complete Nginx configuration before reloading:
sudo systemctl enable --now php8.3-fpm
sudo systemctl status php8.3-fpm --no-pager
sudo nginx -t
sudo systemctl reload nginx
Keep the old FPM service available during testing if the two pools can coexist. If Nginx reports “502 Bad Gateway,” check that the target service is running, the socket exists, and its owner and group permit the Nginx worker to connect. Review both Nginx’s error log and the FPM journal for the same request time.
Test compatibility before production cutover
Run tests against a staging copy or a maintenance host that uses the target runtime. Include more than a homepage request:
- Run the application’s automated test suite with the target CLI binary.
- Run Composer’s dependency checks and installation in a clean working tree. Resolve an explicit PHP-version conflict in the dependency constraints rather than bypassing it.
- Apply database migrations to a restored staging database, never to production as an untested first run.
- Execute representative CLI commands, queue jobs, report generators and scheduled tasks under the target PHP binary.
- Exercise login, sessions, uploads, image or document processing, email delivery, payments and any external API integrations used by the application.
- Check file permissions, opcode-cache settings, worker timeouts and memory limits under realistic traffic.
Look specifically for removed or changed PHP behavior, notices promoted to exceptions, stricter type handling, extension API differences and libraries that have not declared support for the target version. Capture errors with timestamps so a failure can be correlated with the web-server and FPM logs.
Verify the runtime users actually reach
CLI verification
php -v
php -m
php --ini
command -v php
readlink -f "$(command -v php)"
These commands show the default shell binary, not necessarily the binary used by a cron entry or worker. Inspect service unit files and deployment scripts for hard-coded paths such as /usr/bin/php7.4.
Web-SAPI verification
Create a temporary diagnostic endpoint in a protected or otherwise inaccessible location containing:
<?php phpinfo();Request it through the real HTTPS virtual host and confirm the PHP version, SAPI, loaded configuration file, additional scanned files and required modules. Remove the file immediately after verification; a public phpinfo() page discloses paths, environment details and configuration values. If policy forbids a diagnostic page, expose the same information through an authenticated health-check endpoint that your application already controls.
During verification, monitor:
- the web server’s access and error logs;
- the PHP-FPM service journal and pool logs;
- application logs, failed jobs and queue latency;
- database connection errors, upload failures and authentication problems;
- CPU, memory, process counts and response latency.
Cut over gradually and observe normal traffic
After CLI, staging and web-SAPI checks pass, reload the selected web-server configuration and direct traffic to the new runtime. Keep the old runtime, configuration archive and snapshot until the application has completed a normal traffic period that includes scheduled jobs and background work. Watch error rates and logs rather than relying on a single successful request.
Record the cutover time, new socket or module, package versions, configuration changes and test results. This record makes a later rollback or a second server migration reproducible.
Rollback when the site fails
Use the least disruptive reversal that restores service, then investigate the incompatibility in staging.
- For Nginx, point
fastcgi_passback to the previous FPM socket, runsudo nginx -t, and reload Nginx. - For Apache modules, re-enable the previous module, disable the new one, run
sudo apachectl configtest, and reload or restart Apache as required. - For an FPM proxy design, stop routing production requests to the new pool while leaving it installed for diagnosis.
- If package or configuration state is inconsistent, restore the verified VPS snapshot and database backup according to the rehearsed procedure.
- Preserve logs and the failing request or job before retrying; removing evidence makes the cause harder to identify.
Do not delete the old runtime first and assume that reinstalling it will recreate custom pool files, module settings or permissions. A rollback is dependable only when the previous socket, package set and configuration have been preserved.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesClean up only after the migration is proven
Once the site has operated normally and scheduled work has completed, review obsolete packages without automatically purging them. Check reverse dependencies and configuration files:
apt policy php7.4 php7.4-fpm
sudo apt autoremove --simulate
Remove an old runtime in a separate maintenance change, after confirming that no virtual host, cron job, worker or deployment script still invokes it. Keep the configuration archive and a documented restoration path even after package cleanup. Re-run the CLI and web-SAPI checks after removal so an unattended job has not silently switched to an unintended default.
Version and lifecycle considerations
Ubuntu 24.04 LTS and PHP 8.3
Ubuntu 24.04 Noble’s native repositories provide the PHP 8.3 package line, including php8.3 and php8.3-fpm. The release documentation lists PHP 8.3.6 at publication; later updates can change the installed patch level. The php-fpm metapackage follows Ubuntu’s default FPM version, so versioned package names are clearer when you are running more than one line.
Ubuntu maintenance window
Ubuntu 24.04 LTS receives standard security maintenance until 31 May 2029. Longer coverage is available through Ubuntu Pro and its Legacy add-on. This date describes Ubuntu’s maintenance policy, not the support lifetime of your application or every PHP extension; continue to track the PHP and framework support policies that apply to your code.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Older Ubuntu releases
Package availability differs by release. Verify the target with apt policy after sudo apt update. If the native repositories do not provide the required PHP line, compare a separately maintained repository with the native route for update ownership, extension coverage, compatibility and rollback. Introducing an external source is an operational decision, not a harmless way to obtain a newer binary.
Quick Recap
Common failure symptoms and fixes
| Symptom | Likely cause | Checks and corrective action |
|---|---|---|
| CLI shows the new version but the website shows the old one | Apache still has the old module enabled, or Nginx still targets the old FPM socket. | Inspect enabled Apache modules, the virtual-host configuration and fastcgi_pass; verify through the web SAPI, not only the shell. |
| “502 Bad Gateway” after an Nginx change | FPM is stopped, the socket path is wrong, or permissions block Nginx. | Check systemctl status php8.3-fpm, list /run/php, inspect pool permissions and read both logs. |
| “Class not found” or missing-function errors | A required extension was not installed or was loaded only for CLI. | Compare php -m with the web-SAPI module list and install the version-matched extension package. |
| Composer refuses to install | The project’s PHP constraint or a dependency does not support the target version. | Read the exact constraint, update compatible dependencies in staging and run the test suite before changing production. |
| Requests fail only under load | FPM pool limits, memory limits, timeouts or opcode-cache settings differ from the old runtime. | Compare pool configuration, process counts, memory usage and slow/error logs under representative traffic. |
| Cron jobs still run old code | A crontab or service unit invokes an absolute path to the previous PHP binary. | Search scheduled-task definitions and worker units, then change them deliberately and test one job manually. |
| Apache unexpectedly restarts during package installation | The PHP package transaction updated or restarted Apache. | Schedule the change, check service status afterward and confirm the virtual host serves the intended runtime. |
A repeatable runbook
- Identify Ubuntu, PHP, SAPI, web server, extensions, pools, workers and application support limits.
- Create and restore-test a VPS snapshot, database backup, uploads backup and configuration archive.
- Refresh APT metadata, inspect candidates and simulate package changes.
- Install the target PHP CLI, FPM or Apache interface and only the required version-matched extensions.
- Point Apache or Nginx to the target module or FPM socket and validate configuration syntax.
- Run application, Composer, migration, CLI-worker and user-flow tests on the target runtime.
- Verify both
php -vand the served web runtime, then remove any diagnostic endpoint. - Cut over, observe normal traffic and scheduled work, and retain rollback assets.
- Remove obsolete packages only in a later, separately reversible maintenance change.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
