add php language-specific guide (docker#18794)

* add php language guide
---------

Signed-off-by: Craig Osterhout <[email protected]>
Co-authored-by: David Karlsson <[email protected]>

compose.yaml

@@ -12,4 +12,4 @@ services:
           path: .
           target: /src
           ignore:
-            - node_modules/
+            - node_modules/

content/guides/walkthroughs/publish-your-image.md

@@ -66,5 +66,6 @@ Continue to the language-specific guides to learn how you can use Docker to cont
 - [Go](../../language/golang/_index.md)
 - [Java](../../language/java/_index.md)
 - [Node.js](../../language/nodejs/_index.md)
+- [PHP](../../language/php/_index.md)
 - [Python](../../language/python/_index.md)
 - [Rust](../../language/rust/_index.md)

content/language/_index.md

@@ -42,4 +42,7 @@ Learn how to containerize your applications and start developing using Docker. C
     <div class="flex items-center flex-1 shadow p-4">
         <a href="/language/rust/"><img class="m-auto rounded" src="/language/images/rust-logo.webp" alt="Develop with Rust"></a>
     </div>
+    <div class="flex items-center flex-1 shadow p-4">
+        <a href="/language/php/"><img class="m-auto rounded" src="/language/images/php-logo.webp" alt="Develop with PHP"></a>
+    </div>
 </div>

content/language/php/_index.md

@@ -0,0 +1,21 @@
+---
+description: Containerize and develop PHP apps using Docker
+keywords: getting started, php, composer
+title: PHP language-specific guide
+toc_min: 1
+toc_max: 2
+---
+
+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
+* Configure a CI/CD pipeline for a containerized PHP application using GitHub Actions
+* Deploy your containerized application locally to Kubernetes to test and debug your deployment
+
+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.
+
+{{< button text="Containerize a PHP app" url="containerize.md" >}}

content/language/php/configure-ci-cd.md

@@ -0,0 +1,147 @@
+---
+title: Configure CI/CD for your PHP application
+keywords: php, CI/CD
+description: Learn how to Configure CI/CD for your PHP application
+---
+
+## Prerequisites
+
+Complete all the previous sections of this guide, starting with [Containerize a PHP application](containerize.md). You must have a [GitHub](https://github.com/signup) account and a [Docker](https://hub.docker.com/signup) account to complete this section.
+
+## Overview
+
+In this section, you'll learn how to set up and use GitHub Actions to build and test your Docker image as well as push it to Docker Hub. You will complete the following steps:
+
+1. Create a new repository on GitHub.
+2. Define the GitHub Actions workflow.
+3. Run the workflow.
+
+## Step one: Create the repository
+
+Create a GitHub repository, configure the Docker Hub secrets, and push your source code.
+
+1. [Create a new repository](https://github.com/new) on GitHub.
+
+2. Open the repository **Settings**, and go to **Secrets and variables** >
+   **Actions**.
+
+3. Create a new secret named `DOCKER_USERNAME` and your Docker ID as value.
+
+4. Create a new [Personal Access Token (PAT)](../../security/for-developers/access-tokens.md/#create-an-access-token) for Docker Hub. You can name this token `tutorial-docker`.
+
+5. Add the PAT as a second secret in your GitHub repository, with the name
+   `DOCKERHUB_TOKEN`.
+
+6. In your local repository on your machine, run the following command to change
+   the origin to the repository you just created. Make sure you change
+   `your-username` to your GitHub username and `your-repository` to the name of
+   the repository you created.
+
+   ```console
+   $ git remote set-url origin https://github.com/your-username/your-repository.git
+   ```
+
+7. In your local repository on your machine, run the following command to rename
+   the branch to main.
+
+   ```console
+   $ git branch -M main
+   ```
+
+8. Run the following commands to stage, commit, and then push your local
+   repository to GitHub.
+
+   ```console
+   $ git add -A
+   $ git commit -m "my first commit"
+   $ git push -u origin main
+   ```
+
+## Step two: Set up the workflow
+
+Set up your GitHub Actions workflow for building, testing, and pushing the image
+to Docker Hub.
+
+1. Go to your repository on GitHub and then select the **Actions** tab.
+
+2. Select **set up a workflow yourself**.
+
+   This takes you to a page for creating a new GitHub actions workflow file in
+   your repository, under `.github/workflows/main.yml` by default.
+
+3. In the editor window, copy and paste the following YAML configuration.
+
+   ```yaml
+   name: ci
+
+   on:
+     push:
+       branches:
+         - main
+
+   jobs:
+     build:
+       runs-on: ubuntu-latest
+       steps:
+         -
+           name: Checkout
+           uses: actions/checkout@v4
+         -
+           name: Login to Docker Hub
+           uses: docker/login-action@v3
+           with:
+             username: ${{ secrets.DOCKER_USERNAME }}
+             password: ${{ secrets.DOCKERHUB_TOKEN }}
+         -
+           name: Set up Docker Buildx
+           uses: docker/setup-buildx-action@v3
+         -
+           name: Build and test
+           uses: docker/build-push-action@v5
+           with:
+             context: .
+             target: test
+             load: true
+         -
+           name: Build and push
+           uses: docker/build-push-action@v5
+           with:
+             context: .
+             push: true
+             target: final
+             tags: ${{ secrets.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest
+   ```
+
+   For more information about the YAML syntax used here, see [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions).
+
+## Step three: Run the workflow
+
+Save the workflow file and run the job.
+
+1. Select **Commit changes...** and push the changes to the `main` branch.
+
+   After pushing the commit, the workflow starts automatically.
+
+2. Go to the **Actions** tab. It displays the workflow.
+
+   Selecting the workflow shows you the breakdown of all the steps.
+
+3. When the workflow is complete, go to your
+   [repositories on Docker Hub](https://hub.docker.com/repositories).
+
+   If you see the new repository in that list, it means the GitHub Actions
+   successfully pushed the image to Docker Hub.
+
+## Summary
+
+In this section, you learned how to set up a GitHub Actions workflow for your application.
+
+Related information:
+ - [Introduction to GitHub Actions](../../build/ci/github-actions/index.md)
+ - [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)
+
+## Next steps
+
+Next, learn how you can locally test and debug your workloads on Kubernetes before deploying.
+
+{{< button text="Test your deployment" url="./deploy.md" >}}

content/language/php/containerize.md

@@ -0,0 +1,130 @@
+---
+title: Containerize a PHP application
+keywords: php, containerize, initialize, apache, composer
+description: Learn how to containerize a PHP application.
+---
+
+## Prerequisites
+
+* You have installed the latest version of [Docker
+  Desktop](../../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.
+
+## Initialize Docker assets
+
+Now that you have an application, you can use `docker init` to create the
+necessary Docker assets to containerize your application. Inside the
+`docker-php-sample` directory, run the `docker init` command in a terminal.
+`docker init` provides some default configuration, but you'll need to answer a
+few questions about your application. For example, this application uses PHP
+version 8.2. Refer to the following `docker init` example and use the same
+answers for your prompts.
+
+```console
+$ docker init
+Welcome to the Docker Init CLI!
+
+This utility will walk you through creating the following files with sensible defaults for your project:
+  - .dockerignore
+  - Dockerfile
+  - compose.yaml
+  - README.Docker.md
+
+Let's get started!
+
+? What application platform does your project use? PHP with Apache
+? What version of PHP do you want to use? 8.2
+? What's the relative directory (with a leading .) for your app? ./src
+? What local port do you want to use to access your server? 9000
+```
+
+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.Docker.md
+│ └── README.md
+```
+
+To learn more about the files that `docker init` added, see the following:
+ - [Dockerfile](../../engine/reference/builder.md)
+ - [.dockerignore](../../engine/reference/builder.md#dockerignore-file)
+ - [compose.yaml](../../compose/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](../../compose/reference/_index.md).
+
+## Summary
+
+In this section, you learned how you can containerize and run a simple PHP
+application using Docker.
+
+Related information:
+ - [docker init reference](../../engine/reference/commandline/init.md)
+
+## Next steps
+
+In the next section, you'll learn how you can develop your application using
+Docker containers.
+
+{{< button text="Develop your application" url="develop.md" >}}