Recent posts

Troubleshooting PHP Installation: A Developer's Guide to Solving PHP Setup Issues

Nida Sahar

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

First, What Makes Up a PHP Setup?#

Illustration showing components of a PHP setup including PHP binary, php.ini file, extensions, PHP-FPM, and web server

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 Not Found? Let’s Install It#

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#

Visual representation of PHP installation on different operating systems including Ubuntu, CentOS, and macOS

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. No php.ini File? Here’s the Fix#

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.

Understanding php.ini

3. Set Your PHPRC Variable#

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 Not Running? Restart It#

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. Development vs. Production Settings#

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? Check the Logs#

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.

Common PHP Errors & Fixes

Conclusion#

Conceptual image representing successful PHP setup and troubleshooting completion

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.
Build, Deploy & Scale Apps Faster with Nife.