--- title: PHP language-specific guide linkTitle: PHP description: Containerize and develop PHP apps using Docker keywords: getting started, php, composer summary: | This guide explains how to containerize PHP applications using Docker. aliases: - /language/php/ - /guides/language/php/ - /language/php/containerize/ - /language/php/develop/ - /language/php/run-tests/ - /language/php/configure-ci-cd/ - /language/php/deploy/ - /guides/php/configure-ci-cd/ - /guides/php/containerize/ - /guides/php/deploy/ - /guides/php/develop/ - /guides/php/run-tests/ params: tags: [languages] time: 20 minutes --- The PHP language-specific guide teaches you how to create a containerized PHP application using Docker. In this guide, you'll learn how to: - Containerize and run a PHP application - Set up a local environment to develop a PHP application using containers - Run tests for a PHP application within containers After completing the PHP language-specific guide, you should be able to containerize your own PHP application based on the examples and instructions provided in this guide. Start by containerizing an existing PHP application. ## Containerize a PHP application ### Prerequisites - You have installed the latest version of [Docker Desktop](/get-started/get-docker.md). - You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client. ### Overview This section walks you through containerizing and running a PHP application. ### Get the sample applications In this guide, you will use a pre-built PHP application. The application uses Composer for library dependency management. You'll serve the application via an Apache web server. Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the repository. ```console $ git clone https://github.com/docker/docker-php-sample ``` The sample application is a basic hello world application and an application that increments a counter in a database. In addition, the application uses PHPUnit for testing. ### Create Docker assets Now that you have an application, you can create the necessary Docker assets to containerize it. > [!TIP] > > [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application. Create the following files in your `docker-php-sample` directory. ```dockerfile {collapse=true,title=Dockerfile} # syntax=docker/dockerfile:1 # Comments are provided throughout this file to help you get started. # If you need more help, visit the Dockerfile reference guide at # https://docs.docker.com/go/dockerfile-reference/ ################################################################################ # Create a stage for installing app dependencies defined in Composer. FROM composer:lts as deps WORKDIR /app # If your composer.json file defines scripts that run during dependency installation and # reference your application source files, uncomment the line below to copy all the files # into this layer. # COPY . . # Download dependencies as a separate step to take advantage of Docker's caching. # Leverage a bind mounts to composer.json and composer.lock to avoid having to copy them # into this layer. # Leverage a cache mount to /tmp/cache so that subsequent builds don't have to re-download packages. RUN --mount=type=bind,source=composer.json,target=composer.json \ --mount=type=bind,source=composer.lock,target=composer.lock \ --mount=type=cache,target=/tmp/cache \ composer install --no-dev --no-interaction ################################################################################ # Create a new stage for running the application that contains the minimal # runtime dependencies for the application. This often uses a different base # image from the install or build stage where the necessary files are copied # from the install stage. # # The example below uses the PHP Apache image as the foundation for running the app. # By specifying the "8.2-apache" tag, it will also use whatever happens to be the # most recent version of that tag when you build your Dockerfile. # If reproducibility is important, consider using a specific digest SHA, like # php@sha256:99cede493dfd88720b610eb8077c8688d3cca50003d76d1d539b0efc8cca72b4. FROM php:8.2-apache as final # Your PHP application may require additional PHP extensions to be installed # manually. For detailed instructions for installing extensions can be found, see # https://github.com/docker-library/docs/tree/master/php#how-to-install-more-php-extensions # The following code blocks provide examples that you can edit and use. # # Add core PHP extensions, see # https://github.com/docker-library/docs/tree/master/php#php-core-extensions # This example adds the apt packages for the 'gd' extension's dependencies and then # installs the 'gd' extension. For additional tips on running apt-get, see # https://docs.docker.com/go/dockerfile-aptget-best-practices/ # RUN apt-get update && apt-get install -y \ # libfreetype-dev \ # libjpeg62-turbo-dev \ # libpng-dev \ # && rm -rf /var/lib/apt/lists/* \ # && docker-php-ext-configure gd --with-freetype --with-jpeg \ # && docker-php-ext-install -j$(nproc) gd # # Add PECL extensions, see # https://github.com/docker-library/docs/tree/master/php#pecl-extensions # This example adds the 'redis' and 'xdebug' extensions. # RUN pecl install redis-5.3.7 \ # && pecl install xdebug-3.2.1 \ # && docker-php-ext-enable redis xdebug # Use the default production configuration for PHP runtime arguments, see # https://github.com/docker-library/docs/tree/master/php#configuration RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" # Copy the app dependencies from the previous install stage. COPY --from=deps app/vendor/ /var/www/html/vendor # Copy the app files from the app directory. COPY ./src /var/www/html # Switch to a non-privileged user (defined in the base image) that the app will run under. # See https://docs.docker.com/go/dockerfile-user-best-practices/ USER www-data ``` ```yaml {collapse=true,title=compose.yaml} # Comments are provided throughout this file to help you get started. # If you need more help, visit the Docker Compose reference guide at # https://docs.docker.com/go/compose-spec-reference/ # Here the instructions define your application as a service called "server". # This service is built from the Dockerfile in the current directory. # You can add other services your application may depend on here, such as a # database or a cache. For examples, see the Awesome Compose repository: # https://github.com/docker/awesome-compose services: server: build: context: . ports: - 9000:80 # The commented out section below is an example of how to define a PostgreSQL # database that your application can use. `depends_on` tells Docker Compose to # start the database before your application. The `db-data` volume persists the # database data between container restarts. The `db-password` secret is used # to set the database password. You must create `db/password.txt` and add # a password of your choosing to it before running `docker compose up`. # depends_on: # db: # condition: service_healthy # db: # image: postgres # restart: always # user: postgres # secrets: # - db-password # volumes: # - db-data:/var/lib/postgresql/data # environment: # - POSTGRES_DB=example # - POSTGRES_PASSWORD_FILE=/run/secrets/db-password # expose: # - 5432 # healthcheck: # test: [ "CMD", "pg_isready" ] # interval: 10s # timeout: 5s # retries: 5 # volumes: # db-data: # secrets: # db-password: # file: db/password.txt ``` ```text {collapse=true,title=".dockerignore"} # Include any files or directories that you don't want to be copied to your # container here (e.g., local build artifacts, temporary files, etc.). # # For more help, visit the .dockerignore file reference guide at # https://docs.docker.com/go/build-context-dockerignore/ **/.classpath **/.dockerignore **/.env **/.git **/.gitignore **/.project **/.settings **/.toolstarget **/.vs **/.vscode **/.next **/.cache **/*.*proj.user **/*.dbmdl **/*.jfm **/charts **/docker-compose* **/compose.y*ml !**/composer.json !**/composer.lock **/Dockerfile* **/node_modules **/npm-debug.log **/obj **/secrets.dev.yaml **/values.dev.yaml **/vendor LICENSE README.md ``` You should now have the following contents in your `docker-php-sample` directory. ```text ├── docker-php-sample/ │ ├── .git/ │ ├── src/ │ ├── tests/ │ ├── .dockerignore │ ├── .gitignore │ ├── compose.yaml │ ├── composer.json │ ├── composer.lock │ ├── Dockerfile │ └── README.md ``` To learn more about these files, see the following: - [Dockerfile](/reference/dockerfile.md) - [.dockerignore](/reference/dockerfile.md#dockerignore-file) - [compose.yaml](/reference/compose-file/_index.md) ### Run the application Inside the `docker-php-sample` directory, run the following command in a terminal. ```console $ docker compose up --build ``` Open a browser and view the application at [http://localhost:9000/hello.php](http://localhost:9000/hello.php). You should see a simple hello world application. In the terminal, press `ctrl`+`c` to stop the application. #### Run the application in the background You can run the application detached from the terminal by adding the `-d` option. Inside the `docker-php-sample` directory, run the following command in a terminal. ```console $ docker compose up --build -d ``` Open a browser and view the application at [http://localhost:9000/hello.php](http://localhost:9000/hello.php). You should see a simple hello world application. In the terminal, run the following command to stop the application. ```console $ docker compose down ``` For more information about Compose commands, see the [Compose CLI reference](/reference/cli/docker/compose/). ## Use containers for PHP development ### Prerequisites Complete [Containerize a PHP application](#containerize-a-php-application). ### Overview In this section, you'll learn how to set up a development environment for your containerized application. This includes: - Adding a local database and persisting data - Adding phpMyAdmin to interact with the database - Configuring Compose to automatically update your running Compose services as you edit and save your code - Creating a development container that contains the dev dependencies ### Add a local database and persist data You can use containers to set up local services, like a database. To do this for the sample application, you'll need to do the following: - Update the `Dockerfile` to install extensions to connect to the database - Update the `compose.yaml` file to add a database service and volume to persist data #### Update the Dockerfile to install extensions To install PHP extensions, you need to update the `Dockerfile`. Open your Dockerfile in an IDE or text editor and then update the contents. The following `Dockerfile` includes one new line that installs the `pdo` and `pdo_mysql` extensions. All comments have been removed. ```dockerfile {hl_lines=11} # syntax=docker/dockerfile:1 FROM composer:lts as deps WORKDIR /app RUN --mount=type=bind,source=composer.json,target=composer.json \ --mount=type=bind,source=composer.lock,target=composer.lock \ --mount=type=cache,target=/tmp/cache \ composer install --no-dev --no-interaction FROM php:8.2-apache as final RUN docker-php-ext-install pdo pdo_mysql RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" COPY --from=deps app/vendor/ /var/www/html/vendor COPY ./src /var/www/html USER www-data ``` For more details about installing PHP extensions, see the [Official Docker Image for PHP](https://hub.docker.com/_/php). #### Update the compose.yaml file to add a db and persist data Open the `compose.yaml` file in an IDE or text editor. You'll notice it already contains commented-out instructions for a PostgreSQL database and volume. For this application, you'll use MariaDB. For more details about MariaDB, see the [MariaDB Official Docker image](https://hub.docker.com/_/mariadb). Open the `src/database.php` file in an IDE or text editor. You'll notice that it reads environment variables in order to connect to the database. In the `compose.yaml` file, you'll need to update the following: 1. Uncomment and update the database instructions for MariaDB. 2. Add a secret to the server service to pass in the database password. 3. Add the database connection environment variables to the server service. 4. Uncomment the volume instructions to persist data. The following is the updated `compose.yaml` file. All comments have been removed. ```yaml services: server: build: context: . ports: - 9000:80 depends_on: db: condition: service_healthy secrets: - db-password environment: - PASSWORD_FILE_PATH=/run/secrets/db-password - DB_HOST=db - DB_NAME=example - DB_USER=root db: image: mariadb restart: always user: root secrets: - db-password volumes: - db-data:/var/lib/mysql environment: - MARIADB_ROOT_PASSWORD_FILE=/run/secrets/db-password - MARIADB_DATABASE=example expose: - 3306 healthcheck: test: [ "CMD", "/usr/local/bin/healthcheck.sh", "--su-mysql", "--connect", "--innodb_initialized", ] interval: 10s timeout: 5s retries: 5 volumes: db-data: secrets: db-password: file: db/password.txt ``` > [!NOTE] > > To learn more about the instructions in the Compose file, see [Compose file > reference](/reference/compose-file/). Before you run the application using Compose, notice that this Compose file uses `secrets` and specifies a `password.txt` file to hold the database's password. You must create this file as it's not included in the source repository. In the `docker-php-sample` directory, create a new directory named `db` and inside that directory create a file named `password.txt`. Open `password.txt` in an IDE or text editor and add the following password. The password must be on a single line, with no additional lines in the file. ```text example ``` Save and close the `password.txt` file. You should now have the following in your `docker-php-sample` directory. ```text ├── docker-php-sample/ │ ├── .git/ │ ├── db/ │ │ └── password.txt │ ├── src/ │ ├── tests/ │ ├── .dockerignore │ ├── .gitignore │ ├── compose.yaml │ ├── composer.json │ ├── composer.lock │ ├── Dockerfile │ └── README.md ``` Run the following command to start your application. ```console $ docker compose up --build ``` Open a browser and view the application at [http://localhost:9000/database.php](http://localhost:9000/database.php). You should see a simple web application with text and a counter that increments every time you refresh. Press `ctrl+c` in the terminal to stop your application. ### Verify that data persists in the database In the terminal, run `docker compose rm` to remove your containers and then run `docker compose up` to run your application again. ```console $ docker compose rm $ docker compose up --build ``` Refresh [http://localhost:9000/database.php](http://localhost:9000/database.php) in your browser and verify that the previous count still exists. Without a volume, the database data wouldn't persist after you remove the container. Press `ctrl+c` in the terminal to stop your application. ### Add phpMyAdmin to interact with the database You can easily add services to your application stack by updating the `compose.yaml` file. Update your `compose.yaml` to add a new service for phpMyAdmin. For more details, see the [phpMyAdmin Official Docker Image](https://hub.docker.com/_/phpmyadmin). The following is the updated `compose.yaml` file. ```yaml {hl_lines="42-49"} services: server: build: context: . ports: - 9000:80 depends_on: db: condition: service_healthy secrets: - db-password environment: - PASSWORD_FILE_PATH=/run/secrets/db-password - DB_HOST=db - DB_NAME=example - DB_USER=root db: image: mariadb restart: always user: root secrets: - db-password volumes: - db-data:/var/lib/mysql environment: - MARIADB_ROOT_PASSWORD_FILE=/run/secrets/db-password - MARIADB_DATABASE=example expose: - 3306 healthcheck: test: [ "CMD", "/usr/local/bin/healthcheck.sh", "--su-mysql", "--connect", "--innodb_initialized", ] interval: 10s timeout: 5s retries: 5 phpmyadmin: image: phpmyadmin ports: - 8080:80 depends_on: - db environment: - PMA_HOST=db volumes: db-data: secrets: db-password: file: db/password.txt ``` In the terminal, run `docker compose up` to run your application again. ```console $ docker compose up --build ``` Open [http://localhost:8080](http://localhost:8080) in your browser to access phpMyAdmin. Log in using `root` as the username and `example` as the password. You can now interact with the database through phpMyAdmin. Press `ctrl+c` in the terminal to stop your application. ### Automatically update services Use Compose Watch to automatically update your running Compose services as you edit and save your code. For more details about Compose Watch, see [Use Compose Watch](/manuals/compose/how-tos/file-watch.md). Open your `compose.yaml` file in an IDE or text editor and then add the Compose Watch instructions. The following is the updated `compose.yaml` file. ```yaml {hl_lines="17-21"} services: server: build: context: . ports: - 9000:80 depends_on: db: condition: service_healthy secrets: - db-password environment: - PASSWORD_FILE_PATH=/run/secrets/db-password - DB_HOST=db - DB_NAME=example - DB_USER=root develop: watch: - action: sync path: ./src target: /var/www/html db: image: mariadb restart: always user: root secrets: - db-password volumes: - db-data:/var/lib/mysql environment: - MARIADB_ROOT_PASSWORD_FILE=/run/secrets/db-password - MARIADB_DATABASE=example expose: - 3306 healthcheck: test: [ "CMD", "/usr/local/bin/healthcheck.sh", "--su-mysql", "--connect", "--innodb_initialized", ] interval: 10s timeout: 5s retries: 5 phpmyadmin: image: phpmyadmin ports: - 8080:80 depends_on: - db environment: - PMA_HOST=db volumes: db-data: secrets: db-password: file: db/password.txt ``` Run the following command to run your application with Compose Watch. ```console $ docker compose watch ``` Open a browser and verify that the application is running at [http://localhost:9000/hello.php](http://localhost:9000/hello.php). Any changes to the application's source files on your local machine will now be immediately reflected in the running container. Open `hello.php` in an IDE or text editor and update the string `Hello, world!` to `Hello, Docker!`. Save the changes to `hello.php` and then wait a few seconds for the application to sync. Refresh [http://localhost:9000/hello.php](http://localhost:9000/hello.php) in your browser and verify that the updated text appears. Press `ctrl+c` in the terminal to stop Compose Watch. Run `docker compose down` in the terminal to stop the application. ### Create a development container At this point, when you run your containerized application, Composer isn't installing the dev dependencies. While this small image is good for production, it lacks the tools and dependencies you may need when developing and it doesn't include the `tests` directory. You can use multi-stage builds to build stages for both development and production in the same Dockerfile. For more details, see [Multi-stage builds](/manuals/build/building/multi-stage.md). In the `Dockerfile`, you'll need to update the following: 1. Split the `deps` staged into two stages. One stage for production (`prod-deps`) and one stage (`dev-deps`) to install development dependencies. 2. Create a common `base` stage. 3. Create a new `development` stage for development. 4. Update the `final` stage to copy dependencies from the new `prod-deps` stage. The following is the `Dockerfile` before and after the changes. {{< tabs >}} {{< tab name="Before" >}} ```dockerfile # syntax=docker/dockerfile:1 FROM composer:lts as deps WORKDIR /app RUN --mount=type=bind,source=composer.json,target=composer.json \ --mount=type=bind,source=composer.lock,target=composer.lock \ --mount=type=cache,target=/tmp/cache \ composer install --no-dev --no-interaction FROM php:8.2-apache as final RUN docker-php-ext-install pdo pdo_mysql RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" COPY --from=deps app/vendor/ /var/www/html/vendor COPY ./src /var/www/html USER www-data ``` {{< /tab >}} {{< tab name="After" >}} ```dockerfile # syntax=docker/dockerfile:1 FROM composer:lts as prod-deps WORKDIR /app RUN --mount=type=bind,source=./composer.json,target=composer.json \ --mount=type=bind,source=./composer.lock,target=composer.lock \ --mount=type=cache,target=/tmp/cache \ composer install --no-dev --no-interaction FROM composer:lts as dev-deps WORKDIR /app RUN --mount=type=bind,source=./composer.json,target=composer.json \ --mount=type=bind,source=./composer.lock,target=composer.lock \ --mount=type=cache,target=/tmp/cache \ composer install --no-interaction FROM php:8.2-apache as base RUN docker-php-ext-install pdo pdo_mysql COPY ./src /var/www/html FROM base as development COPY ./tests /var/www/html/tests RUN mv "$PHP_INI_DIR/php.ini-development" "$PHP_INI_DIR/php.ini" COPY --from=dev-deps app/vendor/ /var/www/html/vendor FROM base as final RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" COPY --from=prod-deps app/vendor/ /var/www/html/vendor USER www-data ``` {{< /tab >}} {{< /tabs >}} Update your `compose.yaml` file by adding an instruction to target the development stage. The following is the updated section of the `compose.yaml` file. ```yaml {hl_lines=5} services: server: build: context: . target: development # ... ``` Your containerized application will now install the dev dependencies. Run the following command to start your application. ```console $ docker compose up --build ``` Open a browser and view the application at [http://localhost:9000/hello.php](http://localhost:9000/hello.php). You should still see the simple "Hello, Docker!" application. Press `ctrl+c` in the terminal to stop your application. While the application appears the same, you can now make use of the dev dependencies. Continue to the next section to learn how you can run tests using Docker. ## Run PHP tests in a container ### Prerequisites Complete all the previous sections of this guide, starting with [Containerize a PHP application](#containerize-a-php-application). ### Overview Testing is an essential part of modern software development. Testing can mean a lot of things to different development teams. There are unit tests, integration tests and end-to-end testing. In this guide you take a look at running your unit tests in Docker when developing and when building. ### Run tests when developing locally The sample application already has a PHPUnit test inside the `tests` directory. When developing locally, you can use Compose to run your tests. Run the following command in the `docker-php-sample` directory to run the tests inside a container. ```console $ docker compose run --build --rm server ./vendor/bin/phpunit tests/HelloWorldTest.php ``` You should see output that contains the following. ```console Hello, Docker!PHPUnit 9.6.13 by Sebastian Bergmann and contributors. . 1 / 1 (100%) Time: 00:00.003, Memory: 4.00 MB OK (1 test, 1 assertion) ``` To learn more about the command, see [docker compose run](/reference/cli/docker/compose/run/). ### Run tests when building To run your tests when building, you need to update your Dockerfile. Create a new test stage that runs the tests. The following is the updated Dockerfile. ```dockerfile {hl_lines="26-28"} # syntax=docker/dockerfile:1 FROM composer:lts as prod-deps WORKDIR /app RUN --mount=type=bind,source=./composer.json,target=composer.json \ --mount=type=bind,source=./composer.lock,target=composer.lock \ --mount=type=cache,target=/tmp/cache \ composer install --no-dev --no-interaction FROM composer:lts as dev-deps WORKDIR /app RUN --mount=type=bind,source=./composer.json,target=composer.json \ --mount=type=bind,source=./composer.lock,target=composer.lock \ --mount=type=cache,target=/tmp/cache \ composer install --no-interaction FROM php:8.2-apache as base RUN docker-php-ext-install pdo pdo_mysql COPY ./src /var/www/html FROM base as development COPY ./tests /var/www/html/tests RUN mv "$PHP_INI_DIR/php.ini-development" "$PHP_INI_DIR/php.ini" COPY --from=dev-deps app/vendor/ /var/www/html/vendor FROM development as test WORKDIR /var/www/html RUN ./vendor/bin/phpunit tests/HelloWorldTest.php FROM base as final RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" COPY --from=prod-deps app/vendor/ /var/www/html/vendor USER www-data ``` Run the following command to build an image using the test stage as the target and view the test results. Include `--progress plain` to view the build output, `--no-cache` to ensure the tests always run, and `--target test` to target the test stage. ```console $ docker build -t php-docker-image-test --progress plain --no-cache --target test . ``` You should see output containing the following. ```console #18 [test 2/2] RUN ./vendor/bin/phpunit tests/HelloWorldTest.php #18 0.385 Hello, Docker!PHPUnit 9.6.13 by Sebastian Bergmann and contributors. #18 0.392 #18 0.394 . 1 / 1 (100%) #18 0.395 #18 0.395 Time: 00:00.003, Memory: 4.00 MB #18 0.395 #18 0.395 OK (1 test, 1 assertion) ``` ### Summary In this section, you learned how to run tests when developing locally using Compose and how to run tests when building your image. Related information: - [docker compose run](/reference/cli/docker/compose/run/)