PHP Installation Troubleshooting Guide: Fix php.ini, PHP-FPM, and 502 Errors on Ubuntu, macOS, and CentOS
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:
On CentOS:
On macOS (with Homebrew):
Verify Installation#
Run:
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:
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:
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:
To make it stick, add it to your shell config (e.g. ~/.bashrc or ~/.zshrc):
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:
On CentOS/RHEL:
Bitnami stack:
Check if it's running:
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:
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:
PHP-FPM error 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.