Setting up a modern PHP development environment explained

Why your development environment matters

Getting PHP running on your machine is straightforward, but setting up a modern PHP development environment explained takes intention. Without the right foundation—proper PHP version, dependency management, and a local stack that mirrors production—you'll spend more time debugging environment issues than building features. We've seen teams waste weeks chasing bugs that vanished once they aligned their local setup with what runs in staging and production.

Install PHP 8.3+ and Composer

PHP 8.3 brings real benefits over older versions: match expressions for cleaner logic, typed properties throughout, and better performance. You need both PHP itself and Composer, which manages your project dependencies the way npm handles JavaScript packages.

On macOS with Homebrew:

brew install php@8.3
brew install composer

Homebrew handles the installation and keeps PHP updated painlessly. Verify the install:

php -v
# PHP 8.3.0 (cli) (built: Nov 23 2023 15:27:12) (NTS)

composer --version
# Composer 2.6.5 2023-10-06

On Linux (Ubuntu/Debian):

sudo apt update
sudo apt install php8.3 php8.3-cli php8.3-common php8.3-fpm php8.3-mysql php8.3-zip php8.3-gd php8.3-curl
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

On Linux, you'll likely install more extensions upfront because you're often using Nginx or Apache. The php8.3-fpm package is essential for production-like setups; php8.3-mysql, php8.3-zip, and php8.3-gd cover the majority of Laravel applications.

On Windows:

Use the official PHP installer from php.net or download a pre-built bundle like Laravel Herd (covered next). If you go the manual route, add PHP to your PATH so php -v works from any command prompt. Composer installs via its Windows installer and handles PATH setup automatically.

Once installed, run composer diagnose to ensure Composer can reach package repositories and that memory limits are sufficient (minimum 2GB for dependency resolution).

Choose between Laravel Herd and Laravel Sail

Both Herd and Sail give you a complete local stack, but they take different approaches. Picking the right one affects your workflow significantly.

Laravel Herd: native, lightweight, fast

Use Herd if: You're on macOS or Windows and want the simplest path to development. Herd runs PHP natively on your machine without virtualization overhead.

Download from herd.laravel.com and follow the installer. Herd handles PHP 8.3, Nginx, MySQL, Redis, and Mailpit (for viewing test emails) in one go. You don't touch Docker or virtual machines.

After installation, verify:

herd --version
# Herd 1.5.2

Herd automatically registers a .test domain for each project, so a project called shop is instantly accessible at https://shop.test. That means no fiddling with /etc/hosts or port forwarding.

Laravel Sail: containerized, consistent, portable

Use Sail if: Your team runs mixed operating systems, you're using Linux, or you need your local environment to exactly match a Docker-based production setup.

Sail runs everything in Docker containers defined by a docker-compose.yml file. When you create a Laravel project, Sail is included. Start by installing Docker Desktop, then:

composer create-project laravel/laravel shop
cd shop
./vendor/bin/sail up -d

The first time you run Sail, it builds images (a few minutes). After that, containers start in seconds. You access your app via http://localhost.

For Sail, create a shell alias to avoid typing ./vendor/bin/sail constantly:

alias sail='bash vendor/bin/sail'

# Then use it like:
sail artisan migrate
sail tinker

Real-world scenario: We use Sail on projects where the backend also runs Kafka or needs PostgreSQL with specific extensions. Docker guarantees that what runs locally behaves identically in staging. We also use Sail when junior developers join—they clone the repo, run sail up -d, and everything works without installing a dozen system packages.

Create your first Laravel project

With PHP, Composer, and either Herd or Sail ready, scaffolding a project is one command. We'll use Herd for this example.

composer create-project laravel/laravel shop
cd shop

Composer fetches Laravel and ~50 dependencies into vendor/. This takes 30–60 seconds depending on internet speed. The command generates:

• app/ — Your application code: models, controllers, middleware
• routes/ — HTTP and API route definitions
• resources/ — Blade templates, CSS, and JavaScript
• .env — Environment variables (database, API keys)
• artisan — Laravel's command-line tool

Start the development server:

php artisan serve
# Starting Laravel development server: http://127.0.0.1:8000

Open http://127.0.0.1:8000 (or if using Herd, http://shop.test) and you'll see the Laravel welcome screen. If you used Sail, it's already running and accessible at http://localhost.

Database setup: By default, Laravel uses SQLite. For development with MySQL or PostgreSQL, update .env:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=shop
DB_USERNAME=root
DB_PASSWORD=password

If you're using Herd, MySQL is running and ready. With Sail, it's a service in the compose file. Run migrations:

php artisan migrate

This creates database tables from your migration files.

Configure your editor

A good editor catches errors before you run code. PHP development has two main paths:

VS Code with Intelephense

If you use VS Code (free, lightweight, popular in most teams), install the Intelephense extension (search for it in the Extensions marketplace). Intelephense provides:

• Real-time type checking — Catches typos in class names and method calls
• Jump to definition — Click a function name to see its code
• Intelligent autocomplete — Suggestions based on method signatures
• Refactoring — Rename a class everywhere it appears

Configure Intelephense in .vscode/settings.json in your project root:

{
  "intelephense.environment.phpVersion": "8.3",
  "[php]": {
    "editor.defaultFormatter": "bmewburn.vscode-intelephense-client",
    "editor.formatOnSave": true
  }
}

Also install the PHP Namespace Resolver extension to auto-import classes—it saves dozens of keystrokes per day.

PhpStorm

PhpStorm is a paid IDE (JetBrains) that includes everything out of the box: debugging, testing, Docker support, and database tools. The learning curve is steeper, but experienced teams often prefer it because refactoring, running tests, and exploring code are baked in.

Configure the PHP interpreter under Settings → Languages & Frameworks → PHP. Point it to your php executable or to Sail's PHP container if using Sail.

Either way, your editor should highlight Laravel facades and helper functions.** We recommend installing Blade, Laravel Goto Controller, and Laravel Extra Intellisense extensions if using VS Code.

Common mistakes

• Mismatched PHP versions locally and in production. If production runs PHP 8.2 and you develop on 8.3, you might use newer syntax that breaks production. Align versions in your .env file or Docker setup. Use php --version to verify before committing code.
• Skipping .env setup. Beginners often push .env to git or forget to copy it before running migrations, leading to "database does not exist" errors. Copy .env.example to .env and customize database credentials. Add .env to .gitignore (Laravel does this by default).
• Not extending Herd or Sail when needed. If your app uses Redis or needs Elasticsearch, Herd requires manual setup whereas Sail requires editing docker-compose.yml. Know which tool fits your project before diving in.
• Ignoring memory limits. Composer needs at least 2GB of memory. If you see "Allowed memory size exhausted," increase it with composer config --global memory-limit -1.
• Leaving test emails unsorted. Herd includes Mailpit; Sail includes the same. Visit http://localhost:8025 (Sail) or the Herd interface to see test emails. Don't assume mail is working in production just because it worked locally.

Key takeaways

• Install PHP 8.3+ and Composer via your system package manager or official installers; verify with php -v and composer --version.
• Choose Herd for native, fast development on macOS/Windows or Sail for Docker-based consistency across teams and operating systems.
• Scaffold a new Laravel project with composer create-project laravel/laravel [name] and start the dev server immediately.
• Configure VS Code with Intelephense or use PhpStorm for professional-grade type checking and refactoring.
• Align your local environment with staging and production: same PHP version, same extensions, same database software.
• Keep .env out of git and document any custom setup in a SETUP.md file for new team members.