Dev Containers

A dev container describes the development environment an editor or cloud workspace should open. For PHP projects, it can standardise the PHP version, Composer, extensions, shell tools, editor extensions, forwarded ports, and setup commands.

Dev containers are often used with Docker Compose. Compose runs the services; the dev container tells the editor which container is the development workspace.

A simple devcontainer file

{
  "name": "PHP App",
  "dockerComposeFile": "../docker-compose.yml",
  "service": "php",
  "workspaceFolder": "/var/www/app",
  "postCreateCommand": "composer install",
  "customizations": {
    "vscode": {
      "extensions": [
        "bmewburn.vscode-intelephense-client",
        "xdebug.php-debug"
      ]
    }
  }
}

This says: open the php service from the Compose file, use /var/www/app as the workspace, install Composer dependencies after creation, and recommend PHP editor extensions.

What belongs in a dev container

Good dev container configuration captures repeatable developer setup:

• PHP and Composer versions
• required system packages
• editor extensions that help the project
• forwarded ports for the app, mail tool, or debugging
• post-create setup such as composer install
• a non-root remote user when the project needs it

It should not contain production secrets or personal machine assumptions.

Dev container versus production image

A dev container may include debugging tools, shell utilities, Composer, Xdebug, and editor support. A production image should usually be smaller and stricter.

Do not assume the dev container is the production deployment. Instead, treat it as a reproducible local workspace that should be close enough to catch real PHP/runtime issues early.

Opening And Rebuilding The Workspace

When the editor opens a dev container, it starts or reuses the configured service and attaches the workspace to it. Commands opened in the editor terminal now run inside that container.

The first setup may take longer because images must be built and dependencies installed. After a Dockerfile, extension list, or dev-container setting changes, rebuild the workspace rather than assuming the running container updated itself.

For a Compose-based project, confirm the same thing from a terminal:

docker compose exec php php -v
docker compose exec php composer install
docker compose exec php vendor/bin/phpunit

These commands prove the PHP runtime, dependencies, and tests work inside the workspace service.

Ports And Debugging

Applications and debugging tools may need ports forwarded from the container to the host. A dev-container file can declare them:

{
  "forwardPorts": [8080, 9003]
}

Port 8080 might expose the local web application. Port 9003 is the usual Xdebug 3 debugging port. Forwarding a port only makes the connection possible; the relevant service must still be running and configured correctly.

Workspace Ownership

The editor and terminal should normally use a non-root user that can edit mounted files and write the directories needed by the application. Otherwise, Composer, test runs, or framework commands can leave root-owned files on the host.

Check ownership early when a new developer can run the container but cannot edit generated files, clear a cache, or create a log file.

Common PHP concerns

For PHP projects, check:

• Xdebug is available only when needed
• Composer runs inside the container
• generated files are not owned by the wrong user
• the container has the same core extensions as the application expects
• forwarded ports match the local app URL
• database and cache hosts use Compose service names

What you should be able to do

After this lesson, you should be able to explain the role of .devcontainer/devcontainer.json, identify the workspace service, understand post-create commands, rebuild the workspace after runtime changes, check forwarded ports and file ownership, and review whether a dev container helps new developers start work without hiding important runtime details.