Comprehensive Guide: Setting Up a PHP Development Environment on Linux (2025 Edition)

Setting up a PHP development environment on Linux can feel overwhelming if you are new to the ecosystem. This in-depth, SEO-optimised guide walks you through every step, whether you are running Ubuntu, Debian, Fedora, or Arch. By the end you will have a secure, fast and reproducible workspace including PHP 8.x, Apache / Nginx, MariaDB / MySQL, Composer, Xdebug and VS Code integration.

Table of Contents

• Table of Contents
• 1. Prerequisites & Terminology
• 2. Choose Your Stack (Apache vs Nginx)
• 3. Update Your System
• 4. Install Apache (Skip for Nginx)
• 5. Add the PHP Repository
• 6. Install PHP 8.x & Extensions
• 7. Configure PHP for Development
• 8. Install MariaDB (or MySQL)
• 9. Enable Apache ↔︎ PHP via FPM
• 10. Composer – PHP Dependency Manager
• 11. Xdebug for Step-Through Debugging
• 12. Setting Up HTTPS Locally (mkcert)
• 13. Docker Alternative with Laradock
• 14. Recommended VS Code Extensions
• 15. Common Troubleshooting
• 16. Automating with Ansible
• 17. Next Steps
• Conclusion

1. Prerequisites & Terminology

• A Linux machine (bare-metal or VM) with sudo privileges.
• Familiarity with the terminal.
• Internet connection for package retrieval.

2. Choose Your Stack (Apache vs Nginx)

Apache is battle-tested and easier to configure for beginners, while Nginx offers lower memory usage and excels at static asset delivery. In most local development scenarios Apache is sufficient, especially if you need .htaccess based routing (e.g. Laravel Valet-like setups). You can always switch later because PHP-FPM works with both.

3. Update Your System

sudo apt update && sudo apt upgrade -y  # Debian/Ubuntu
# sudo dnf update -y                    # Fedora
# sudo pacman -Syu                      # Arch

Keeping the base OS updated prevents dependency conflicts during PHP installation.

4. Install Apache (Skip for Nginx)

sudo apt install apache2 apache2-utils -y
sudo systemctl enable --now apache2

Visit http://localhost – you should see the default “It works!” page. For firewall-enabled distributions:

sudo ufw allow in "Apache Full"

5. Add the PHP Repository

Ubuntu LTS often lags behind official PHP releases. Use Ondřej Surý’s PPA to get the latest binaries:

sudo add-apt-repository ppa:ondrej/php
sudo apt update

6. Install PHP 8.x & Extensions

sudo apt install php8.3 php8.3-cli php8.3-fpm php8.3-common \
  php8.3-mysql php8.3-xml php8.3-curl php8.3-mbstring php8.3-gd \
  php8.3-bcmath php8.3-zip php8.3-intl -y

Extensions above cover most frameworks (Laravel, Symfony, WordPress). Verify:

php -v
php -m | grep -E 'mysqli|pdo_mysql'

7. Configure PHP for Development

Edit php.ini (CLI & FPM) to improve debugging:

sudo nano /etc/php/8.3/fpm/php.ini

Change / add:

error_reporting = E_ALL
display_errors = On
memory_limit = 1G
post_max_size = 64M
upload_max_filesize = 64M

Restart FPM:

sudo systemctl restart php8.3-fpm

8. Install MariaDB (or MySQL)

sudo apt install mariadb-server mariadb-client -y
sudo systemctl enable --now mariadb

Secure the server:

sudo mysql_secure_installation

Create a database user for your projects:

CREATE USER 'dev'@'localhost' IDENTIFIED BY 'strongpassword';
GRANT ALL PRIVILEGES ON *.* TO 'dev'@'localhost';
FLUSH PRIVILEGES;

9. Enable Apache ↔︎ PHP via FPM

sudo a2enmod proxy_fcgi setenvif
sudo a2enconf php8.3-fpm
sudo systemctl restart apache2

Test with an info.php file inside /var/www/html:

<?php phpinfo();

10. Composer – PHP Dependency Manager

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php --install-dir=/usr/local/bin --filename=composer
composer --version

11. Xdebug for Step-Through Debugging

sudo apt install php8.3-xdebug -y

Update /etc/php/8.3/mods-available/xdebug.ini:

zend_extension="xdebug.so"
xdebug.mode = debug,develop
xdebug.client_host = 127.0.0.1
xdebug.client_port = 9003
xdebug.start_with_request = yes

Restart FPM. Configure VS Code: install the PHP Debug extension and add to .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
    },
  ],
}

12. Setting Up HTTPS Locally (mkcert)

sudo apt install libnss3-tools
brew install mkcert  # or use package manager
mkcert -install
mkcert localhost 127.0.0.1 ::1

Point Apache to the generated .pem and .key in your virtual host configuration to test secure cookies and OAuth callbacks.

13. Docker Alternative with Laradock

Prefer containerised workflows? Spin up a ready-made LEMP stack in minutes:

git clone https://github.com/laradock/laradock.git
cd laradock
cp env-example .env
docker compose up -d nginx mysql workspace

Stop containers:

docker compose down

14. Recommended VS Code Extensions

• PHP Intelephense – advanced autocompletion & linting
• PHP CS Fixer – code style formatting
• Laravel Blade Snippets (if applicable)
• dotenv – syntax highlight .env files

15. Common Troubleshooting

16. Automating with Ansible

Turn these manual steps into an idempotent playbook:

- hosts: localhost
  become: true
  tasks:
    - apt:
        update_cache: yes
        name:
          - apache2
          - php8.3-fpm
          - mariadb-server
    # … further tasks shortened for brevity …

17. Next Steps

1. Install a PHP framework like Laravel or Symfony via Composer.
2. Set up automated tests with PHPUnit.
3. Integrate CI/CD (GitHub Actions) to run tests and build Docker images.

Conclusion

You now have a full-featured PHP development environment on Linux, optimised for performance, security and productivity. Whether you build REST APIs, CMS platforms or microservices, this setup forms a solid foundation. Happy coding!