Using PhpStorm Docker Integration to Run Laravel Apps Consistently

Problem: Environment drift causes hard‑to‑reproduce bugs

When developers run PHP locally, differences in PHP version, installed extensions, or configuration files can make a feature work on one machine but fail on another. This "works on my machine" syndrome wastes time during debugging and testing.

Thesis: PhpStorm’s Docker integration gives every team member an identical runtime

By defining the application stack in Docker Compose and telling PhpStorm to use the container as a remote PHP interpreter, the IDE can edit, run, and debug code inside the same environment that will be used in production.

Worked example: Laravel project with app, database, and cache services

1. Create a Docker Compose file in the project root (e.g., docker-compose.yml):

   version: '3.8'
   services:
     app:
       image: php:8.2-apache
       container_name: laravel_app
       working_dir: /var/www/html
       volumes:
         - ./:/var/www/html
       ports:
         - "8000:80"
       depends_on:
         - db
         - redis
     db:
       image: mysql:8.0
       container_name: laravel_db
       environment:
         MYSQL_ROOT_PASSWORD: example
         MYSQL_DATABASE: laravel
         MYSQL_USER: laravel
         MYSQL_PASSWORD: secret
       ports:
         - "3306:3306"
     redis:
       image: redis:7-alpine
       container_name: laravel_redis
       ports:
         - "6379:6379"
   

2. Start the stack from a terminal (you need Docker Desktop or Engine running and user must be in the docker group or run with sudo):

   cd /path/to/laravel-project
   docker compose up -d
   

3. Register the Compose file in PhpStorm
   1. Open Tools → Docker → Configuration and ensure the Docker daemon URL points to your Docker Desktop/Engine.
   2. In the Docker tool window, click the + button, choose Docker Compose, and select the docker-compose.yml file.
   3. PhpStorm will list the services; verify they show a green status.
4. Add a remote PHP interpreter pointing to the app container
   1. Go to Settings → PHP → CLI Interpreter.
   2. Click the + button, choose From Docker, Vagrant, VM, WSL... → Docker.
   3. Select the laravel_app service image (php:8.2-apache) and set the Interpreter path to /usr/local/bin/php (default for the image).
   4. Click Test connection; a success dialog confirms PhpStorm can execute PHP inside the container.
   5. Apply and set this interpreter as the project default.
5. Configure Xdebug for step‑through debugging
   1. Inside the app container, ensure Xdebug is installed (you can extend the Dockerfile or exec into the container and run pecl install xdebug).
   2. Add a custom php.ini snippet via a bind‑mount or Dockerfile:

      zend_extension=xdebug.so
      xdebug.mode=debug
      xdebug.start_with_request=yes
      xdebug.client_host=host.docker.internal
      xdebug.client_port=9003
      

   3. In PhpStorm, open Settings → PHP → Debug, set the debug port to 9003, and enable Can accept external connections.
   4. Set a breakpoint in a controller method (e.g., app/Http/Controllers/WelcomeController.php).
   5. Choose Run → Debug and select the Docker‑based PHP interpreter; PhpStorm will launch a zero‑configuration debug session.
   6. Make an HTTP request to http://localhost:8000 (via browser or curl). The debugger should stop at the breakpoint, letting you inspect variables and step through code.

Trade‑off / Limitation: Startup overhead and learning curve

• Running PHP inside a container adds a few seconds of startup time compared to a native CLI interpreter.
• Team members must understand Docker Compose syntax and how to manage containers (e.g., docker compose logs, docker compose down).
• Performance‑sensitive workloads (e.g., heavy CPU‑bound scripts) may feel slower due to the abstraction layer; consider using bind‑mounts for code and keeping only runtime dependencies inside the container.

Actionable closing: Commit configuration and onboard teammates

1. Add docker-compose.yml and any custom Dockerfiles to version control.
2. Commit the PhpStorm Docker configuration (the .idea folder contains Docker settings; they are safe to share).
3. When a new developer clones the repository, they only need to run docker compose up -d and open the project in PhpStorm; the IDE will auto‑detect the Compose file and suggest the remote interpreter.
4. Verify the setup by creating a simple script (php -r "echo 'Hello Docker\n';"), setting a breakpoint, and debugging as described above.
5. To tear down the environment, run docker compose down -v from the project root; this stops containers and removes anonymous volumes, returning the system to a clean state.