Update PHP on CloudLinux with yum groupupdate alt-php — NOC

Introduction

Last week I got an email from a client: “My website broke after upgrading PHP from cPanel. All I get is a blank white screen — no errors, no nothing. Just a white page.” After checking, the problem wasnt in their website code at all. It was the PHP version that wasnt compatible with some libraries the site was using. The client upgraded PHP from 7.4 to 8.2 using cPanel, but they didnt update the Alt-PHP packages on CloudLinux first. As a result, PHP 8.2 as activated in cPanel didnt match the libraries available on the server.

From that experience I learned one important thing: updating PHP on CloudLinux has to be done server-wide, not just from cPanel. You need to update the entire Alt-PHP group on the server first, and only then allow users to upgrade their PHP version from cPanel. If you only update from cPanel without updating Alt-PHP on the server, youll run into the exact problems I just described — white screens, unexpected errors, or even PHP crashes.

In this article Ill show you how to update PHP on CloudLinux the right way using yum groupupdate alt-php*, from preparation all the way through verification. Every command below has been used multiple times on production servers and proven safe.

What Is CloudLinux & Alt-PHP?

Before we jump into the update commands, its important to understand what CloudLinux and Alt-PHP actually are.

CloudLinux

CloudLinux is a CentOS/RHEL-based operating system specifically designed for shared hosting. Its key feature is LVE (Lightweight Virtual Environment), which limits resources (CPU, RAM, I/O) per hosting account. This prevents one high-load website from affecting other sites on the same server.

Alt-PHP

Alt-PHP (Alternative PHP) is a PHP system developed by CloudLinux to give more flexibility in managing PHP versions on shared hosting servers. With Alt-PHP you can:

• Provide multiple PHP versions simultaneously (PHP 5.6, 7.0, 7.1, 7.2, 7.3, 7.4, 8.0, 8.1, 8.2, 8.3)
• Let users choose their PHP version from cPanel
• Isolate PHP per account — each account can use a different PHP version without conflicts
• Configure PHP options (memory_limit, upload_max_filesize, etc.) per version

Why Does Alt-PHP Need Updating?

Alt-PHP needs regular updates because:

• Security patches — each Alt-PHP update typically includes security patches for that PHP version
• Bug fixes — bug fixes that can affect PHP stability
• New PHP versions — CloudLinux frequently adds new PHP versions (like PHP 8.3) through Alt-PHP updates
• Compatibility — updates keep libraries and PHP extensions compatible with the latest releases

Preparation Before Updating

⚠️ SECURITY WARNING: Backup First!

Before running the Alt-PHP update, you MUST backup first. Although Alt-PHP updates rarely cause issues, its better to be safe than sorry.

# Backup existing PHP configurations
cp -r /opt/alt/php* /tmp/backup-php-$(date +%Y%m%d-%H%M)/ 2>/dev/null

# Backup php.ini for all versions
for ver in $(ls /opt/alt/ | grep php); do
  cp /opt/alt/$ver/etc/php.ini /tmp/backup-php-ini-$ver-$(date +%Y%m%d-%H%M).bak 2>/dev/null
done

# Backup list of installed packages
rpm -qa | grep alt-php > /tmp/alt-php-packages-$(date +%Y%m%d-%H%M).txt

Verify the backup succeeded:

ls -lh /tmp/backup-php-*
ls -lh /tmp/backup-php-ini-*
wc -l /tmp/alt-php-packages-*.txt

Check Current PHP Versions

Before updating, note which PHP versions are currently installed on the server:

# Check default server PHP version
php -v

# Check installed Alt-PHP versions
rpm -qa | grep alt-php | sort

# Check available PHP versions in CloudLinux repo
yum list available alt-php* | head -20

Check CloudLinux Repository

Make sure the CloudLinux repository is active and accessible:

# Check repository status
yum repolist | grep cloudlinux

# Check repository connectivity
yum clean all
yum makecache

If the repository is unreachable, the update wont work. Make sure your CloudLinux license is still active and the server can reach the CloudLinux repository.

The Alt-PHP Update Command

Update All PHP Versions at Once

The main command for updating Alt-PHP on CloudLinux is:

yum groupupdate alt-php*

This command will update every Alt-PHP group installed on the server — including PHP 5.6, 7.0, 7.1, 7.2, 7.3, 7.4, 8.0, 8.1, 8.2, and any other versions active in the repository.

Command Breakdown

1. yum — The package manager for Red Hat/CentOS/CloudLinux. Used to install, update, and remove packages on the system.

2. groupupdate — Updates an entire package group at once. Unlike yum update which updates per-package, groupupdate ensures all packages in a group are updated consistently.

3. alt-php* — A wildcard matching all available Alt-PHP groups. This includes alt-php56, alt-php70, alt-php71, alt-php72, alt-php73, alt-php74, alt-php80, alt-php81, alt-php82, and any others available in the CloudLinux repository.

Example Output

Loaded plugins: fastestmirror, rhnplugin, versionlock
Loading mirror speeds from cached hostfile
cloudlinux-x86_64-server-7          | 2.8 kB  00:00:00
cloudlinux-x86_64-updates           | 2.9 kB  00:00:00
Resolving Dependencies
--> Running transaction check
---> Package alt-php74-php-common.x86_64 0:7.4.33-3.el7 will be updated
---> Package alt-php74-php-common.x86_64 0:7.4.33-4.el7 will be an update
---> Package alt-php80-php-common.x86_64 0:8.0.27-3.el7 will be updated
---> Package alt-php80-php-common.x86_64 0:8.0.28-1.el7 will be an update
---> Package alt-php81-php-common.x86_64 0:8.1.16-3.el7 will be updated
---> Package alt-php81-php-common.x86_64 0:8.1.17-1.el7 will be an update
---> Package alt-php82-php-common.x86_64 0:8.2.3-3.el7 will be updated
---> Package alt-php82-php-common.x86_64 0:8.2.4-1.el7 will be an update
...
Complete!

From the output above we can see several PHP versions were updated: PHP 7.4 from 7.4.33-3 to 7.4.33-4, PHP 8.0 from 8.0.27-3 to 8.0.28-1, PHP 8.1 from 8.1.16-3 to 8.1.17-1, and PHP 8.2 from 8.2.3-3 to 8.2.4-1.

Update Specific PHP Versions Only

If you only want to update a specific PHP version (for example only PHP 8.2), use this command:

# Update only PHP 8.2
yum groupupdate alt-php82

# Update only PHP 8.1 and 8.2
yum groupupdate alt-php81 alt-php82

Verification After Updating

Command #1: Check PHP Versions After Update

After the update finishes, verify it succeeded by checking the installed PHP versions:

# Check default server PHP version
php -v

# Check all installed Alt-PHP versions
for ver in $(ls /opt/alt/ | grep php); do
  echo -n "$ver: "
  /opt/alt/$ver/bin/php -v | head -1
done

Example Output

PHP 7.4.33 (cli) (built: Jan 13 2024 08:23:11) ( NTS )
alt-php56: PHP 5.6.40 (cli) (built: Jan 10 2019 08:23:11) ( NTS )
alt-php70: PHP 7.0.33 (cli) (built: Jan 10 2019 08:23:11) ( NTS )
alt-php71: PHP 7.1.33 (cli) (built: Jan 13 2024 08:23:11) ( NTS )
alt-php72: PHP 7.2.34 (cli) (built: Jan 13 2024 08:23:11) ( NTS )
alt-php73: PHP 7.3.33 (cli) (built: Jan 13 2024 08:23:11) ( NTS )
alt-php74: PHP 7.4.33 (cli) (built: Jan 13 2024 08:23:11) ( NTS )
alt-php80: PHP 8.0.28 (cli) (built: Feb 14 2024 08:23:11) ( NTS )
alt-php81: PHP 8.1.17 (cli) (built: Feb 14 2024 08:23:11) ( NTS )
alt-php82: PHP 8.2.4 (cli) (built: Feb 14 2024 08:23:11) ( NTS )

Note that PHP 8.0, 8.1, and 8.2 have been updated to their latest versions (8.0.28, 8.1.17, 8.2.4). The other versions (5.6, 7.0, 7.1, 7.2, 7.3, 7.4) remain unchanged because there were no new updates for those versions.

Command #2: Check PHP Extensions

Verify that PHP extensions are still working after the update:

# Check loaded extensions
php -m | sort

# Check extensions for a specific PHP version
/opt/alt/php82/bin/php -m | sort

Command #3: Test PHP Execution

Run a simple test to make sure PHP can execute scripts:

# Test PHP execution
php -r "echo 'PHP is working! Version: ' . PHP_VERSION . PHP_EOL;"

# Test for each Alt-PHP version
for ver in php74 php80 php81 php82; do
  echo -n "$ver: "
  /opt/alt/$ver/bin/php -r "echo PHP_VERSION;" 2>&1
  echo
done

Command #4: Restart Services

After updating Alt-PHP, you need to restart services that use PHP so the changes take effect:

# Restart LiteSpeed/LSAPI (if using LiteSpeed)
systemctl restart lsws

# Or restart PHP-FPM for each version
for ver in php74 php80 php81 php82; do
  systemctl restart lsphp$ver
done

# Restart Apache (if using mod_php)
systemctl restart httpd

⚠️ IMPORTANT: Restarting production services must be done carefully. Make sure:

• No deployment or code changes are currently running
• Clients have been notified in case of brief downtime
• Configuration backups exist before restarting

How Users Upgrade PHP from cPanel

After Alt-PHP on the server has been updated, users can upgrade their PHP version from cPanel. Here are the steps:

Step 1: Open cPanel → Select PHP Version

Log into cPanel and find the “Select PHP Version” or “PHP Version Selector” menu. This is usually under the “Software” or “Programming” section.

Step 2: Choose the Desired PHP Version

On the Select PHP Version page, youll see a list of available PHP versions. Select the PHP version you want (e.g., PHP 8.2) and click “Set as current” or “Apply”.

Step 3: Enable Required Extensions

After selecting the PHP version, make sure the extensions your website needs are enabled. Click the “Extensions” tab and ensure extensions like mysqli, pdo_mysql, gd, mbstring, curl, and others are active.

Step 4: Test the Website

After changing the PHP version, test the website to make sure there are no errors. Open the site in a browser and verify everything is working properly.

Troubleshooting: Update Failed

Problem 1: Repository Unreachable

If the update fails because the repository is unreachable:

# Check repository connectivity
yum clean all
yum makecache

# Check CloudLinux license status
cat /etc/cloudlinux-release

# If still failing, check DNS server
cat /etc/resolv.conf

Problem 2: Package Conflicts

If the update fails due to package conflicts:

# Check conflicting packages
yum groupupdate alt-php* 2>&1 | grep -i conflict

# Update the conflicting package first
yum update [conflicting-package-name]

# Run the update again
yum groupupdate alt-php*

Problem 3: PHP Not Working After Update

If PHP doesnt work after the update (white screen, errors, etc.):

# Check error log
tail -50 /var/log/lsphp82/error.log

# Check if PHP-FPM is running
systemctl status lsphp82

# Restart PHP-FPM
systemctl restart lsphp82

# If still having issues, restore config backup
cp /tmp/backup-php-ini-php82-*.bak /opt/alt/php82/etc/php.ini

Pro Tips: Preventing PHP Update Issues

1. Update on staging first — if possible, test the update on a staging server before production. This prevents unexpected issues in production.
2. Read the changelog before updating — check what changed in the latest version. Sometimes there are changes that can affect compatibility.
3. Update during low traffic — run the update when server traffic is low (e.g., late at night) to minimize impact on users.
4. Monitor error logs after updating — after the update, monitor error logs for several hours to make sure no new errors appear.
5. Schedule regular updates — create a schedule for Alt-PHP updates (e.g., once a month) to ensure the server always uses the latest, secure PHP versions.
6. Use yum versionlock — if you dont want to update all PHP versions at once, use yum versionlock to lock specific versions and only update the ones you want.
7. Always backup before updating — always backup PHP configuration before updating. This is the most important step that gets forgotten.

FAQ

Will updating Alt-PHP remove existing PHP versions?

No. yum groupupdate alt-php* only updates already-installed packages to newer versions. Existing PHP versions remain available and wont be removed. Users can still use their old PHP version from cPanel.

Is it safe to run yum groupupdate alt-php* on production?

Yes, its generally safe. Alt-PHP updates are designed to be backward-compatible — there are no changes that will break compatibility with older versions. But its still recommended to backup first and test on staging if possible.

How do I update only a specific PHP version?

Use yum groupupdate alt-php82 to update only PHP 8.2. Or yum groupupdate alt-php81 alt-php82 to update PHP 8.1 and 8.2. The wildcard alt-php* updates all versions at once.

Do users need to do anything after the server updates Alt-PHP?

Generally no. Users dont need to do anything after the server updates Alt-PHP. But if users want to upgrade their websites PHP version, they can do so from cPanel → Select PHP Version. The PHP versions available in cPanel will automatically update after the server updates Alt-PHP.

Related Issues

• Troubleshoot High Database Load in MariaDB — PHP updates can affect database performance due to changes in mysqli/PDO extensions
• Detect Deleted Files on Linux with lsof +L1 — PHP updates can generate temporary or backup files holding disk space
• Fix Apache Slot Full 503 Service Unavailable — PHP not working after an update can cause Apache slots to fill up

Conclusion

Updating PHP on CloudLinux using yum groupupdate alt-php* is an important step to keep your server secure and performant. By updating regularly, you ensure that all PHP versions on the server have the latest security patches and are compatible with the latest libraries.

What I keep coming back to from my own experience: never upgrade a PHP version from cPanel without updating Alt-PHP on the server first. Because if you dont, youll end up with problems like white screens, unexpected errors, or even PHP crashes. Always backup first, update Alt-PHP with yum groupupdate alt-php*, verify the update succeeded, and only then allow users to upgrade from cPanel. Better to be cautious than to have to explain to a client why their website is broken after a PHP upgrade — trust me, Ive been there and I dont want to go through that again.