PHP Installation Troubleshooting Guide: Fix php.ini, PHP-FPM, and 502 Errors on Ubuntu, macOS, and CentOS
Learn how to fix common PHP installation issues including missing php.ini, PHP-FPM not running, PHPRC misconfiguration, and 502 Bad Gateway errors on Ubuntu, CentOS, and macOS.
So, you're setting up PHP and things aren't going as smoothly as you hoped. Maybe you're staring at a php -v error or wondering why your server is throwing a 502 Bad Gateway at you. Don’t sweat it—we’ve all been there.
In this guide, we’re going to walk through the most common PHP installation issues, explain what’s happening behind the scenes, and show you how to fix them without losing your sanity. Whether you’re setting up PHP for the first time or maintaining an existing server, there’s something here for you.
Components of a PHP Setup: Binary, php.ini, Extensions, and PHP-FPM
Before diving into the fix-it steps, let’s quickly look at the key parts of a typical PHP setup:
- PHP Binary – The main engine that runs your PHP scripts.
- php.ini File – The config file that controls things like error reporting, memory limits, and file uploads.
- PHP Extensions – Add-ons like MySQL drivers or image processing libraries.
- PHP-FPM (FastCGI Process Manager) – Manages PHP processes when working with a web server like Nginx or Apache.
- Web Server – Apache, Nginx, etc. It passes web requests to PHP and serves the results.
Understanding how these parts work together makes troubleshooting way easier. Now, let’s fix things up!
1. PHP Command Not Found? How to Install PHP on Ubuntu, CentOS, or macOS
Tried running php -v and got a "command not found" error? That means PHP isn’t installed—or your system doesn’t know where to find it.
Install PHP
On Ubuntu:
sudo apt update
sudo apt install php
On CentOS:
sudo yum install php
On macOS (with Homebrew):
brew install php
Verify Installation
Run:
php -v
If that doesn’t work, check if PHP is in your system’s $PATH. If not, you’ll need to add it.
Full PHP install guide on phoenixnap
2.Missing php.ini? How to Locate or Create Your PHP Configuration File
You’ve installed PHP, but it’s not picking up your php.ini configuration file? You might see something like:
Loaded Configuration File => (none)
Find or Create php.ini
Common locations:
/etc/php.ini/usr/local/lib/php.ini- Bitnami stacks:
/opt/bitnami/php/etc/php.ini
If missing, copy a sample config:
cp /path/to/php-*/php.ini-development /usr/local/lib/php.ini
Then restart PHP or PHP-FPM to apply the changes.
3. How to Set the PHPRC Variable to Load Your Custom php.ini File
Still no luck loading the config? Set the PHPRC environment variable to explicitly tell PHP where your config file lives:
export PHPRC=/usr/local/lib
To make it stick, add it to your shell config (e.g. ~/.bashrc or ~/.zshrc):
echo "export PHPRC=/usr/local/lib" >> ~/.bashrc
source ~/.bashrc
Learn more: PHP Environment Variables Explained
4. PHP-FPM Crashed? Restart PHP FastCGI Process to Fix 502 Errors
Getting a 502 Bad Gateway? That usually means PHP-FPM is down.
Restart PHP-FPM
On Ubuntu/Debian:
sudo systemctl restart php7.0-fpm
On CentOS/RHEL:
sudo systemctl restart php-fpm
Bitnami stack:
sudo /opt/bitnami/ctlscript.sh restart php-fpm
Check if it's running:
ps aux | grep php-fpm
If not, check the logs (see below).
5. php.ini-development vs php.ini-production: Which Should You Use?
PHP offers two default config templates:
php.ini-development– More error messages, ideal for dev work.php.ini-production– Safer settings, ideal for live sites.
Pick the one that fits your needs, and copy it to the right spot:
cp php.ini-production /usr/local/lib/php.ini
More details: PHP Runtime Configuration
6. Still Stuck? Use PHP and PHP-FPM Logs to Debug Errors
Logs are your best friends when troubleshooting.
PHP error log:
tail -f /var/log/php_errors.log
PHP-FPM error log:
tail -f /var/log/php-fpm.log
These will give you insight into config issues, missing extensions, and more.
Conclusion: How to Get PHP Running Smoothly Across Different Environments
Getting PHP working can be frustrating at first, but once you understand the pieces—PHP binary, php.ini, extensions, PHP-FPM, and the web server—it’s much easier to fix issues when they pop up.
To recap:
- Install PHP
- Make sure
php.iniis where PHP expects - Set
PHPRCif needed - Restart PHP-FPM if you're using Nginx/Apache
- Check your logs
Once everything is running smoothly, your PHP-powered site or app will be good to go.
Simplify JSP Deployment – Powered by Nife.
Build, Deploy & Scale Apps Faster with Nife.
From the team at Nife
Deploy your next app in minutes, not days.
Nife is a multi-cloud edge platform that lets you deploy, scale, and manage applications globally without the infrastructure headache.