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. [Install PHP on Ubuntu Server](https://documentation.ubuntu.com/server/how-to/web-services/install-php/index.html) --- ## 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:** ```bash sudo apt update sudo apt install php ``` **On CentOS:** ```bash sudo yum install php ``` **On macOS (with Homebrew):** ```bash brew install php ``` ### Verify Installation Run: ```bash 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](https://phoenixnap.com/kb/install-php-on-ubuntu) --- ## 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: ```bash cp /path/to/php-*/php.ini-development /usr/local/lib/php.ini ``` Then restart PHP or PHP-FPM to apply the changes. [Understanding php.ini](https://www.php.net/manual/en/configuration.file.php) --- ## 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: ```bash export PHPRC=/usr/local/lib ``` To make it stick, add it to your shell config (e.g. `~/.bashrc` or `~/.zshrc`): ```bash echo "export PHPRC=/usr/local/lib" >> ~/.bashrc source ~/.bashrc ``` Learn more: [PHP Environment Variables Explained](https://www.w3schools.in/php/environment-variables) --- ## 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:** ```bash sudo systemctl restart php7.0-fpm ``` **On CentOS/RHEL:** ```bash sudo systemctl restart php-fpm ``` **Bitnami stack:** ```bash sudo /opt/bitnami/ctlscript.sh restart php-fpm ``` Check if it's running: ```bash 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: ```bash cp php.ini-production /usr/local/lib/php.ini ``` More details: [PHP Runtime Configuration](https://www.php.net/manual/en/ini.core.php) --- ## 6. Still Stuck? Use PHP and PHP-FPM Logs to Debug Errors Logs are your best friends when troubleshooting. **PHP error log:** ```bash tail -f /var/log/php_errors.log ``` **PHP-FPM error log:** ```bash tail -f /var/log/php-fpm.log ``` These will give you insight into config issues, missing extensions, and more. [Common PHP Errors & Fixes](https://phoenixnap.com/kb/php-error-types) --- ## 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.ini` is where PHP expects - Set `PHPRC` if 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](https://nife.io/solutions/Deploy%20Java%20Server%20Page%20App). Build, Deploy & Scale Apps Faster with [Nife](https://nife.io/).

Deploy your next app in minutes, not days.