[FEATURE] Install file in the PHP images

AGENTS.md

@@ -31,6 +31,15 @@ Only these commands are known to work:
 
 Besides `provision`, the Makefile has `structure-test` and `setup`, which the `webdevops/dockerfile-build-env` image runs while it is built. `make structure-test` runs container-structure-test against your local images of `bootstrap`, `base`, `base-app`, `php`, `php-dev` and `php-nginx`, the images that have a suite in `tests/structure-test`. It tests only the tags in `.github/workflows/build.yaml` and fails if a test fails, if `docker` fails or if no such image exists locally; run it inside `webdevops/dockerfile-build-env` with the Docker socket mounted. The CI runs serverspec for every image except `toolbox` and `dockerfile-build-env`, and container-structure-test for the six images above; to check a change by hand, start the image and try it as described below.
 
+### Packages come with tests
+
+A pull request that adds a package or a tool to an image also adds a test for it, in the same pull request:
+
+- Add a shared example to `tests/serverspec/spec/shared/` that runs the tool and checks its output, not only that the file exists, for example `misc::file` in `tests/serverspec/spec/shared/misc/tools.rb`.
+- Include it in the collection of every image that gets the package; for all PHP images that is `collection::php` in `tests/serverspec/spec/collection/php.rb`.
+- Check that the test fails on an image without the package and passes on one with it.
+- In the pull request description, say how much bigger the images get: absolute and in percent, on average over the images that get the package.
+
 ## Keep the documentation up to date
 
 The documentation is part of every change. A pull request that changes what users of the images see also updates the documentation **in the same pull request**. Never leave it for a follow-up.

docker/php-official/8.2-alpine/Dockerfile

@@ -84,6 +84,7 @@ RUN --mount=type=bind,from=ghcr.io/php/pie:bin,source=/pie,target=/usr/local/bin
     set -x \
     # Install php environment
     && apk-install \
+        file \
         imagemagick \
         graphicsmagick \
         ghostscript \

docker/php-official/8.2/Dockerfile

@@ -85,6 +85,7 @@ RUN --mount=type=bind,from=ghcr.io/php/pie:bin,source=/pie,target=/usr/local/bin
     # Install php environment
     && apt-install \
         # Install tools
+        file \
         imagemagick \
         graphicsmagick \
         ghostscript \

docker/php-official/8.3-alpine/Dockerfile

@@ -84,6 +84,7 @@ RUN --mount=type=bind,from=ghcr.io/php/pie:bin,source=/pie,target=/usr/local/bin
     set -x \
     # Install php environment
     && apk-install \
+        file \
         imagemagick \
         graphicsmagick \
         ghostscript \

docker/php-official/8.3/Dockerfile

@@ -85,6 +85,7 @@ RUN --mount=type=bind,from=ghcr.io/php/pie:bin,source=/pie,target=/usr/local/bin
     # Install php environment
     && apt-install \
         # Install tools
+        file \
         imagemagick \
         graphicsmagick \
         ghostscript \

docker/php-official/8.4-alpine/Dockerfile

@@ -84,6 +84,7 @@ RUN --mount=type=bind,from=ghcr.io/php/pie:bin,source=/pie,target=/usr/local/bin
     set -x \
     # Install php environment
     && apk-install \
+        file \
         imagemagick \
         graphicsmagick \
         ghostscript \

docker/php-official/8.4/Dockerfile

@@ -85,6 +85,7 @@ RUN --mount=type=bind,from=ghcr.io/php/pie:bin,source=/pie,target=/usr/local/bin
     # Install php environment
     && apt-install \
         # Install tools
+        file \
         imagemagick \
         graphicsmagick \
         ghostscript \

docker/php-official/8.5-alpine/Dockerfile

@@ -84,6 +84,7 @@ RUN --mount=type=bind,from=ghcr.io/php/pie:bin,source=/pie,target=/usr/local/bin
     set -x \
     # Install php environment
     && apk-install \
+        file \
         imagemagick \
         graphicsmagick \
         ghostscript \

docker/php-official/8.5/Dockerfile

@@ -85,6 +85,7 @@ RUN --mount=type=bind,from=ghcr.io/php/pie:bin,source=/pie,target=/usr/local/bin
     # Install php environment
     && apt-install \
         # Install tools
+        file \
         imagemagick \
         graphicsmagick \
         ghostscript \

docs/customization.md

@@ -70,6 +70,7 @@ These commands are installed in the images. Use them in `RUN` lines of your own
 | `apt-install <packages>` | Runs `apt-get update`, installs the packages without recommended packages and removes the package lists again | Debian- and Ubuntu-based images, including `bootstrap:ubuntu-22.04` |
 | `apk-install <packages>` | Installs packages with `apk add --no-cache` | Alpine-based images, including `bootstrap:alpine` |
 | `docker-image-cleanup` | Removes package lists and caches; use it at the end of a `RUN` that installed packages | all except `toolbox`; fails in the Alpine `php-*` images, see [Known issues](known-issues.md#docker-image-cleanup-in-the-alpine-php-images) |
+| `file <path>` | Shows the type of a file, for example `file --mime-type upload.bin`; tools such as GrumPHP's BOM check call it | `php`, `php-apache`, `php-nginx` and their `-dev` images |
 | `go-replace -s <search> -r <replace> -- <file>` | Replaces text in files; the same tool fills the [placeholders](#placeholders) | all |
 | `gosu <user> <command>` | Runs a command as another user, for example `application` | all except `toolbox` |
 | `docker-service enable <service>`, `docker-service disable <service>`, also `docker-service-enable` and `docker-service-disable` | Enables or disables a [service](#services); enabling installs it if needed | all except `bootstrap` and `toolbox` |

template/Dockerfile/images/php.jinja2

@@ -42,6 +42,7 @@
     # Install php environment
     && apt-install \
         # Install tools
+        file \
         imagemagick \
         graphicsmagick \
         ghostscript \
@@ -196,6 +197,7 @@
 {% macro officialAlpine(role='', version='') -%}
     # Install php environment
     && apk-install \
+        file \
         imagemagick \
         graphicsmagick \
         ghostscript \

tests/serverspec/spec/collection/php.rb

@@ -16,6 +16,7 @@
     include_examples 'misc::graphicsmagick'
     include_examples 'misc::imagemagick'
     include_examples 'misc::ghostscript'
+    include_examples 'misc::file'
 
     include_examples 'base::syslog-ng'
 end

tests/serverspec/spec/shared/misc/tools.rb

@@ -30,3 +30,20 @@
         its(:exit_status) { should eq 0 }
     end
 end
+
+shared_examples 'misc::file' do
+    it "should include file" do
+        expect(file("/usr/bin/file")).to be_executable
+    end
+
+    describe command('file --version') do
+        its(:stdout) { should match %r!^file-5\.[0-9]+! }
+        its(:exit_status) { should eq 0 }
+    end
+
+    # The magic database works: it tells a PHP script from a binary
+    describe command("printf '<?php echo 1;\\n' > /tmp/file-test.php && file --brief --mime-type /tmp/file-test.php /usr/local/bin/php") do
+        its(:stdout) { should eq "text/x-php\napplication/x-pie-executable\n" }
+        its(:exit_status) { should eq 0 }
+    end
+end