Verify system requirements and dependencies by confirming OS compatibility and installing essential libraries and build tools, using package managers like apt or yum to simplify dependency management. 2. Check PHP configuration and compilation errors by running a minimal ./configure command, reviewing config.log for specific issues, avoiding complex flags initially, and ensuring proper permissions for installation directories. 3. Resolve web server integration issues by confirming mod_php is loaded in Apache with correct MIME handlers or ensuring PHP-FPM is running and properly configured with Nginx, including correct socket paths and file permissions. 4. Address missing extensions by verifying they are enabled in php.ini or conf.d files, recompiling with appropriate ./configure flags if needed, using php -m to check loaded modules, and confirming the correct php.ini is being used via php --ini. 5. Debug CLI vs. Web SAPI mismatches by comparing php --ini and phpinfo() outputs to identify different configuration files or PHP versions, ensuring consistency between command-line and web environments. 6. Handle permission and ownership problems by setting proper read/write permissions for web server users on document roots and storage directories, and adjusting SELinux policies if necessary to allow PHP execution. Always test installations with a simple phpinfo() script, consult error logs from both the web server and PHP, prefer package managers to avoid dependency complications, and systematically verify each layer of the setup to resolve common PHP installation issues effectively.

Installing PHP can seem straightforward—download, configure, compile (or install via package manager), and go. But in practice, even experienced developers hit snags. Whether you're setting up a local development environment or deploying to production, PHP installation pitfalls can stall progress. Below is a diagnostic checklist to help you identify and resolve the most common issues.

1. Verify System Requirements and Dependencies

Before diving into configuration, confirm your system meets PHP's basic requirements.

• Operating System Compatibility: Ensure your OS is supported. Linux, macOS, and Windows are all supported, but versions and configurations vary.
• Required Libraries: On Linux, missing development libraries are a frequent cause of failure. Common dependencies include:
  • libxml2-dev (or libxml2-devel)
  • openssl-dev (for HTTPS and cURL)
  • zlib-dev
  • bzip2-dev
  • oniguruma-dev (for PCRE/regex support)
  • sqlite3-dev (if enabling SQLite)
• Build Tools: If compiling from source:
  • gcc, make, autoconf
  • bison, re2c

? On Ubuntu/Debian: Run sudo apt-get install build-essential libxml2-dev libssl-dev libonig-dev libcurl4-openssl-dev libsqlite3-dev to cover most bases.

? On CentOS/RHEL: Use sudo yum groupinstall "Development Tools" and install equivalent -devel packages.

2. Check PHP Configuration and Compilation Errors

If compiling from source, the ./configure step is where many issues arise.

• Run ./configure with minimal flags first:

  ./configure --disable-all

  If this fails, the problem is environmental (missing tools or libs), not configuration.

• Review config.log on failure: After a failed configure, check config.log for specific error messages. Search for “error” or “cannot find” to locate missing dependencies.

• Avoid overly complex ./configure lines early on: Start simple, then add extensions incrementally. For example:

  ./configure --with-openssl --enable-mbstring

• Permission issues: Ensure you have write access to the target installation directory (default: /usr/local), or use sudo make install carefully.

3. Resolve Web Server Integration Issues

Even if PHP installs, it may not work with your web server.

For Apache:

• mod_php not loading:

  • Check if libphp.so was built and copied to Apache’s modules directory.
  • Confirm LoadModule php_module modules/libphp.so is in your Apache config.
  • Verify the correct AddHandler or AddType directive:

    AddType application/x-httpd-php .php

• PHP file downloads instead of executing: This usually means the handler isn’t registered. Double-check the MIME type and module loading.

For Nginx PHP-FPM:

• Ensure PHP-FPM is running:

  sudo systemctl status php-fpm

• Check Nginx fastcgi configuration: Make sure the fastcgi_pass directive points to the correct socket or port (e.g., 127.0.0.1:9000 or /run/php/php-fpm.sock).

• File permissions on socket: The web server (e.g., www-data, nginx) must have read/write access to the FPM socket.

4. Address Missing Extensions and Functionality

Even after a successful install, you might find key functions missing (mysqli_connect, json_encode, etc.).

• Confirm extensions are enabled: Check php.ini and look for lines like:

  extension=mysqli
  extension=json

  Note: On some systems, extensions are loaded via .ini files in conf.d/.

• Re-run make with correct flags: If compiling, extensions like mysqli require --with-mysqli in ./configure.

• Use php -m to list loaded modules: This helps verify whether extensions are actually active.

• Don’t forget php.ini location: Run php --ini to see which config file is being used. A common mistake is editing the wrong php.ini.

5. Debug CLI vs. Web SAPI Mismatches

Sometimes PHP works in the command line but not in the browser (or vice versa).

• Different php.ini files: CLI and web SAPIs (like Apache or FPM) may use different configuration files. Confirm with:

  php --ini          # CLI
  <?php phpinfo(); ?> # Web (shows loaded config file)

• Different PHP versions: You might have multiple PHP versions installed. Check:

  php -v             # CLI version
  <?php phpinfo(); ?> # Web version

  If they differ, your system PATH or web server config may be pointing to an old or alternate install.

6. Handle Permission and Ownership Problems

File access issues can prevent scripts from running or writing logs.

• Web server user must read PHP files: Ensure the document root and PHP scripts are readable by the web server user (e.g., www-data, apache, nginx).

• Writable directories: If your app uses sessions, cache, or uploads, the relevant directories must be writable:

  sudo chown -R www-data:www-data /var/www/html/storage
  sudo chmod -R 755 /var/www/html/storage

• SELinux (on RHEL/CentOS): Can silently block PHP execution. Temporarily disable to test:

  sudo setenforce 0

  If that fixes it, adjust SELinux policies instead of leaving it off.

Final Tips

• Always test with a simple <?php phpinfo(); ?> script after installation.
• Keep logs accessible: check Apache/Nginx error logs and php_error_log (configured in php.ini).
• Use package managers when possible (apt, yum, brew, winget) to avoid dependency hell.

Basically, most PHP installation issues come down to missing dependencies, misconfigured SAPI integration, or environmental mismatches. Go step by step, verify each layer, and use logs to guide your diagnosis.

The above is the detailed content of Troubleshooting Common PHP Installation Pitfalls: A Diagnostic Checklist. For more information, please follow other related articles on the PHP Chinese website!