WordPress Environment Requirements and Version Selection: PHP, MySQL, and Essential Extensions

WordPress fails to install, shows a white screen after installation, or throws errors when enabling plugins—quite a large proportion of these issues are not caused by WordPress itself, but by unsatisfied runtime environment requirements. Choosing the wrong version or missing extensions might not cause errors during installation, but can lead to crashes when you enable certain plugins.

This article explains how to verify if your environment is qualified and how to choose versions. For specific minimum version requirements, please refer to the official wordpress.org documentation.

Basic Environment Combination

Essential Extensions (Missing Any Will Cause Issues)

# View installed extensions
php -m | tr 'n' ' '

# Verify critical extensions one by one
for e in mysqli curl mbstring gd imagick xml zip intl openssl; do
  php -m | grep -qi "^$e$" && echo "$e OK" || echo "$e Missing"
done

How to Choose a PHP Version

Principle: Use newer versions as much as possible, provided all plugins are compatible. Newer versions are typically faster, and older versions will gradually lose security support.

However, note a practical constraint: old plugins and themes may not be compatible with PHP 8. Typical symptoms include fatal errors upon activation or various deprecation warnings.

# Check before installing (the backend "Site Health" will also prompt)
wp plugin list --fields=name,version,status

# Enable debugging to see specific compatibility issues
wp config set WP_DEBUG true --raw
tail -f /var/www/html/wp-content/debug.log

Safe approach: Use newer PHP for new sites; before upgrading PHP on existing sites, run tests in a staging environment to confirm major plugins have no errors before upgrading. Upgrading PHP directly in production is a common cause of white screens.

A Common Pitfall with MySQL 8

MySQL 8.0 changed the default authentication method. If the client (PHP’s MySQL extension) is old, it won’t be able to connect to the database, throwing an error similar to:

The server requested authentication method unknown to the client

# Check user authentication methods
mysql -e "SELECT user, host, plugin FROM mysql.user;"

The cause is that the server uses a newer authentication plugin while the client library does not support it. There are two ways to handle this:

• Upgrade the client (PHP and related extensions) — more fundamental
• Revert the user to the old authentication method — as a transitional measure

Pay special attention to this during migration or new installations: Old servers use MySQL 5.7, new servers use 8.0, code remains unchanged but the database connection fails—the issue lies here.

Environment Checklist

# ① Versions
php -v
mysql --version
nginx -v

# ② Extensions
for e in mysqli curl mbstring gd xml zip intl; do
  php -m | grep -qi "^$e$" && echo "$e OK" || echo "$e Missing"; done

# ③ WordPress built-in environment check
wp core version
wp doctor check --all 2>/dev/null || echo "(Requires wp-cli doctor package)"

# ④ Key PHP parameters (too small values cause upload/import failures)
php -i | grep -iE 'upload_max_filesize|post_max_size|memory_limit|max_execution_time'

# ⑤ Directory writability (affects uploads and auto-updates)
test -w /var/www/html/wp-content/uploads && echo "uploads writable" || echo "uploads not writable"

Decision Tree

WordPress Environment Issues
├─ Fails to install / Database connection errors
│  ├─ mysqli missing        → Install extension
│  ├─ Authentication incompatibility → MySQL 8 + old client, see above
│  └─ Insufficient account permissions → Check wp-config.php
├─ Installs but shows white screen
│  ├─ Enable WP_DEBUG       → Check specific errors
│  └─ PHP version conflicts with plugins → Downgrade or change plugins
├─ Image upload/cropping fails
│  ├─ gd/imagick missing    → Install extension
│  ├─ upload_max_filesize too small → Increase value
│  └─ uploads directory not writable → Change owner/permissions
└─ Online plugin installation fails
   ├─ zip missing           → Install extension
   └─ Directory not writable → Change permissions

Scenario Walkthrough: Thumbnails Disappear After Migration with Identical Environment

Symptom: A WordPress site is migrated to a new server with the same version and complete files,
pages load correctly, but article thumbnails do not display, and re-uploading does not generate them.

1. First, confirm if the image files themselves were migrated → Files are present, ruling out file loss.
2. Check if image processing extensions are missing → The extension responsible for image processing is not installed,
   so the program cannot process images. This is the most common single cause of such faults.
3. Check if the process executing has write permissions → The upload directory owner differs from the running process,
   so generation fails even if extensions are present.
4. Confirm if the web server allows execution in the directory → Some environments prohibit writing or execution in specific directories.
5. Add extensions and reload services → Restart the web service and PHP processes after installing image processing extensions.
6. Regenerate thumbnails and verify individually → Batch regenerate existing images to confirm they display.

# Check if image processing extensions exist
php -m | grep -iE 'gd|imagick'

# Install if missing (example using common combinations)
apt install -y php-gd 2>/dev/null || yum install -y php-gd
systemctl reload php-fpm

# Permissions: Confirm the running process user matches the directory owner
ps -eo user,cmd | grep -E 'php-fpm|nginx|httpd' | head
ls -ld wp-content/uploads

# Regenerate thumbnails
wp media regenerate --yes --allow-root

Root Cause: The new environment lacks image processing extensions, so the program cannot crop or scale images.
Version consistency only ensures code runs, not that optional extensions are complete.

Two points worth remembering:

• “Identical environment” includes extensions, not just major versions.
  Comparing the output of php -m before migration is the easiest verification method.
• For image issues, check extensions and permissions first, then the program.
  These cover the vast majority of scenarios; confirming them is preferable to modifying code or changing plugins.

8 Common Pitfalls

1. Not checking extensions after installation: Successful installation does not mean full functionality.
2. Upgrading PHP major versions directly in production: Incompatible old plugins cause white screens; verify in a test environment first.
3. Incompatible MySQL 8 authentication: Old clients cannot connect, and error messages are hard to understand.
4. upload_max_filesize too small: Uploads fail, often mistaken for permission issues.
5. Directory not writable: Cannot upload or update online.
6. Only checking PHP version via control panel: Command line and Web may use different PHP versions (see PHP multi-version notes).
7. Ignoring php.ini parameters: Low memory_limit causes import failures.
8. Not comparing environments during migration: Relying on memory to set up the environment inevitably leads to omissions.

Real Customer Feedback (From Cloud Market Reviews and Consultations for Similar Products)

The following excerpts are taken from real buyer reviews and consultations for similar operations services on Alibaba Cloud / Tencent Cloud / Huawei Cloud marketplaces (service providers include our store and peers, provided for reference only, not fictional tickets from this site):

10***09 2024-03-18 5.0 Convenient and stable | Clean interface | Complete after-sales service (User did not fill in review content)