Upgrading your PHP version without breaking the site

Why PHP Upgrade is Essential and What Are the Risks?

Upgrading PHP is one of the most important steps to maintain your site's security and performance. Older PHP versions like 5.6 or 7.0 no longer receive security support, and hackers can easily exploit their vulnerabilities. Additionally, newer PHP versions like 8.1 and 8.2 are up to 30% faster than previous versions and offer modern features such as JIT (Just-In-Time Compilation) and typed properties.

However, upgrading PHP without planning can take your site offline. Many legacy codes, especially in content management systems (CMS) like WordPress, Joomla, or Drupal, use deprecated functions that have been removed in newer versions. For example, the mysql_connect() function was removed in PHP 7.0 and replaced with mysqli_connect() or PDO. If your site still uses this function, it will encounter a fatal error.

In this article, we provide a step-by-step process for upgrading PHP, including compatibility checks, setting up a testing environment, backups, and quick rollbacks in case of issues. By following these steps, you can perform a PHP upgrade with minimal risk.

Step 1: Check Code and Plugin Compatibility

Before any action, you need to know whether your code is compatible with the new PHP version. You can do this using automated tools or manually.

Using Online and Command-Line Tools

The PHP Compatibility Checker plugin for WordPress is a free tool that scans all theme and plugin files and reports compatibility issues. For custom projects, you can use the command-line tool PHP_CodeSniffer with the PHPCompatibility standard:

# Install PHP_CodeSniffer and PHPCompatibility standard
composer global require "squizlabs/php_codesniffer=*"
composer global require "phpcompatibility/php-compatibility"

# Run scan on the project folder
phpcs --standard=PHPCompatibility --runtime-set testVersion 8.1 /path/to/your/project

This command checks all PHP files and reports errors such as use of removed functions, incompatible data types, and changes in function behavior. For example, if code uses the each() function (removed in PHP 8.0), you will receive a warning.

Check Plugins and Third-Party Libraries

If you use a CMS, make sure to update your plugins and themes. Many developers have released new versions for compatibility with PHP 8.x. For instance, WordPress 6.0 and later are fully compatible with PHP 8.0 and 8.1. However, older plugins may still have issues. Check the list of incompatible plugins in the WordPress admin panel (Tools > Site Health).

Common mistake: Many administrators assume that updating the CMS solves all problems. But third-party plugins may not have been updated. Always test plugins separately.

Step 2: Create an Isolated Testing Environment

Never upgrade PHP directly on the production site. Create a staging environment that exactly mirrors the main site. This allows you to test changes without worrying about downtime.

Setting Up a Testing Environment with Docker

The simplest way to create a testing environment is using Docker. Create a docker-compose.yml file with the new PHP version:

version: '3.8'
services:
  web:
    image: php:8.1-apache
    ports:
      - "8080:80"
    volumes:
      - ./your-site:/var/www/html
    environment:
      - MYSQL_HOST=db
      - MYSQL_USER=testuser
      - MYSQL_PASSWORD=testpass
  db:
    image: mysql:8.0
    environment:
      - MYSQL_ROOT_PASSWORD=rootpass
      - MYSQL_DATABASE=testdb
      - MYSQL_USER=testuser
      - MYSQL_PASSWORD=testpass

Then, launch the environment with the command docker-compose up -d. Place your site files in the your-site folder and access it via http://localhost:8080.

Using a Subdomain or Subdirectory

If you don't have access to Docker, you can create a subdomain like test.yourdomain.com and enable the new PHP version only for it. In shared hosting, you can usually set the PHP version for each domain separately via cPanel or DirectAdmin. For example, in cPanel, go to the "Select PHP Version" section and choose version 8.1 for the test subdomain.

Important note: Be sure to import a copy of the main database into the testing environment. Use the mysqldump command for backup and then mysql for restoration:

# Backup the main database
mysqldump -u username -p main_database > backup.sql

# Restore to the test database
mysql -u testuser -p test_database < backup.sql

Step 3: Full Functionality Testing and Error Fixing

After setting up the testing environment, check all parts of the site. Do this both manually and automatically.

Manual Testing of Key Pages

Browse the following pages and ensure they display without errors:

• Home page and internal pages
• Contact, registration, and login forms
• Admin panel pages
• Payment process and shopping cart (for e-commerce sites)

Also, check PHP errors in the logs. In the testing environment, enable error display:

// In php.ini file or at the beginning of the script
ini_set('display_errors', 1);
ini_set('display_startup_errors', 1);
error_reporting(E_ALL);

Automated Testing with PHPUnit

If your project has unit tests, run them with the new PHP version. For example:

cd /path/to/your/project
phpunit --configuration phpunit.xml

This ensures that core functions work without issues. If a test fails, fix the error and run the test again.

Fixing Common Issues

Some of the most common PHP upgrade issues include:

• Use of removed functions: Such as create_function() (removed in PHP 7.2) or each() (removed in PHP 8.0). Replace these with modern equivalents.
• Changes in data types: In PHP 8.0, default data types have become stricter. For example, if a function expects an int and you pass a string, you will get a TypeError.
• Problems with PHP extensions: Some extensions like mcrypt were removed in PHP 7.2. Use openssl or sodium instead.

Common mistake: Some administrators only test the home page and neglect other sections. Be sure to check all user flows.

Step 4: Full Backup and Rollback Planning

Before applying changes to the main site, create a complete backup. This includes files and the database.

Backing Up Files and Database

Use the following commands for backup:

# Backup files (using tar)
tar -czf site-backup-$(date +%Y%m%d).tar.gz /path/to/your/site

# Backup database
mysqldump -u username -p --all-databases > db-backup-$(date +%Y%m%d).sql

Store these files in a secure location (e.g., cloud storage or a separate hard drive).

Quick Rollback Plan

If your site breaks after the PHP upgrade, you should be able to revert to the previous version in less than 5 minutes. Prepare the following steps in advance:

1. Keep the previous PHP version on the server (e.g., have both PHP 7.4 and PHP 8.1 installed).
2. Write a simple script to switch PHP versions. For example, on Nginx servers with PHP-FPM:

# Switch from PHP 8.1 to PHP 7.4
sudo update-alternatives --set php /usr/bin/php7.4
sudo systemctl restart php7.4-fpm
sudo systemctl restart nginx

Also, if you use shared hosting, there is usually an option to change the PHP version in the control panel. Identify this option in advance.

Important note: If your site uses Redis or Memcached, clear the cache after rollback to avoid interference from old data.

Step 5: Perform the PHP Upgrade on the Main Site

After ensuring compatibility in the testing environment, it's time to perform the PHP upgrade on the main site. Do this during low-traffic times (e.g., midnight).

Apply Changes Step by Step

First, put the site in maintenance mode so users don't encounter errors. In WordPress, you can use plugins like "WP Maintenance Mode". Then, change the PHP version:

• On VPS servers: Use the update-alternatives command or modify the .htaccess file (for Apache).
• On shared hosting: Change the PHP version for the main domain via the control panel (cPanel or DirectAdmin).

After the change, take the site out of maintenance mode and quickly check its functionality. If everything is fine, you're done.

Check Logs and Fix Post-Upgrade Issues

Even after thorough testing, minor errors may appear. Check the PHP error logs:

tail -f /var/log/php_errors.log

If you see an error, fix it. For example, if a plugin uses the strftime() function (deprecated in PHP 8.1), you can replace it with date().

Common mistake: Some administrators abandon the site after the upgrade. Monitor the logs for at least 24 hours.

Conclusion: Upgrade PHP with Confidence

Upgrading PHP is a sensitive process, but by following the steps above, you can do it without breaking your site. Summary of steps:

1. Check code and plugin compatibility using tools like PHP_CodeSniffer.
2. Create an isolated testing environment (with Docker or a subdomain).
3. Test all parts of the site and fix errors.
4. Take a full backup and have a quick rollback plan.
5. Perform the upgrade during low-traffic times and monitor the logs.

If you're looking for a professional solution for server management, ServerNet offers web hosting services with support for various PHP versions, which can simplify the PHP upgrade process for you. However, the most important point is to always back up and have a testing environment before any changes. With this approach, upgrading PHP is not only risk-free but also improves your site's security and performance.