Rewrite action to Docker container + JS Testcontainers tests

.dockerignore

@@ -0,0 +1,10 @@
+.git
+.github
+.idea
+.zencoder
+node_modules
+tests
+package.json
+package-lock.json
+README.md
+LICENSE

.github/workflows/on-pull-request.yml

@@ -10,34 +10,54 @@ jobs:
   test:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: true
+      max-parallel: 3
       matrix:
-        php:
-          - 5.6
-          - 7.0
-          - 7.1
-          - 7.2
-          - 7.3
-          - 7.4
+        php_version:
+          - '5.4'
+          - '7.0'
+          - '7.1'
+          - '7.2'
+          - '7.3'
+          - '7.4'
 
     steps:
       - name: Checkouting code...
         uses: actions/checkout@v5
 
-      - name: Installing PHP...
-        uses: shivammathur/setup-php@2.35.5
-        with:
-          php-version: ${{ matrix.php }}
-          extensions: curl, gd, json, mbstring, pcre, session
-          coverage: none
-          tools: composer:v2
+      - name: Read Node.js version from package.json
+        id: node-version
+        run: |
+          NODE_VERSION=$(jq -r '.engines.node // empty' package.json)
+          if [[ -z "$NODE_VERSION" || "$NODE_VERSION" == "null" ]]; then
+            echo "package.json engines.node is required" >&2
+            exit 1
+          fi
+          echo "version=$NODE_VERSION" >> "$GITHUB_OUTPUT"
 
-      - name: Setup BATS
-        uses: mig4/setup-bats@v1
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
         with:
-          bats-version: 1.9.0
+          node-version: ${{ steps.node-version.outputs.version }}
+
+      - name: Enable legacy Docker schema v1 pulls for old PHP tags
+        run: |
+          sudo mkdir -p /etc/systemd/system/docker.service.d
+          cat <<'EOF' | sudo tee /etc/systemd/system/docker.service.d/10-enable-schema1.conf
+          [Service]
+          Environment=CONTAINERD_ENABLE_DEPRECATED_PULL_SCHEMA_1_IMAGE=1
+          EOF
+          sudo systemctl daemon-reload
+          sudo systemctl restart docker
+          docker version
 
-      - name: Test
-        run: bats tests
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run integration tests
+        run: npm test
+        env:
+          PHP_VERSION: ${{ matrix.php_version }}
 
   dependabot:
     needs:

.gitignore

@@ -1,3 +1,6 @@
 /.idea/
 /vendor/
 /composer.lock
+/node_modules/
+/.phpdoc/
+/phpDocumentor.phar

Dockerfile

@@ -0,0 +1,21 @@
+ARG PHP_VERSION=7.4
+ARG PHPDOC_VERSION=v2.8.5
+
+FROM php:8.3-cli-bookworm AS phpdocmd-builder
+ARG PHPDOC_VERSION
+
+COPY --from=composer:2.2 /usr/bin/composer /usr/local/bin/composer
+
+COPY --chmod=0755 bin/install-builder-deps.sh bin/setup-phpdoc-md.sh bin/setup-phpdocumentor-cache.sh /usr/local/bin/
+RUN /usr/local/bin/install-builder-deps.sh
+
+RUN /usr/local/bin/setup-phpdoc-md.sh
+RUN /usr/local/bin/setup-phpdocumentor-cache.sh /opt/phpdocumentor-cache "$PHPDOC_VERSION"
+
+FROM php:${PHP_VERSION}-cli
+
+COPY --from=phpdocmd-builder /opt/phpdoc-md /opt/phpdoc-md
+COPY --from=phpdocmd-builder /opt/phpdocumentor-cache /opt/phpdocumentor-cache
+COPY --chmod=0755 bin/entrypoint.sh /usr/local/bin/entrypoint.sh
+
+ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]

README.md

@@ -5,7 +5,7 @@
 
 GitHub action to generate PHP project documentation in [MarkDown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) format. Based on [evert/phpdoc-md](https://github.com/evert/phpdoc-md) library.
 
-***Warning***: at current moment this action doesn't work with PHP newer than 7.4.
+This action is container-based and runs on official PHP Docker images. It does not require setting up PHP or Composer on the runner.
 
 ## Usage
 
@@ -22,22 +22,11 @@ jobs:
     steps:
       - name: Checkouting project code...
         uses: actions/checkout@v2
-
-      - name: Install PHP
-        uses: shivammathur/setup-php@v2.2
-        with:
-          php-version: 7.4
-          extensions: curl, gd, pdo_mysql, json, mbstring, pcre, session
-          ini-values: post_max_size=256M
-          coverage: none
-          tools: composer:v2
-
-      - name: Install Composer dependencies (with dev)
-        run: composer install --no-progress --no-suggest --prefer-dist --optimize-autoloader       
-
+
       - name: Generating documentation...
         uses: impresscms-dev/generate-phpdocs-with-evert-phpdoc-md-action@v1.0.0
         with:
+          php_version: '7.4'
           output_path: ./docs/
           ignored_files: |
             test/
@@ -54,10 +43,19 @@ jobs:
 This action supports such arguments (used in `with` keyword):
 | Argument    | Required | Default value        | Description                       |
 |-------------|----------|----------------------|-----------------------------------|
+| php_version | No | 7.4 | PHP version to run (accepted range: `5.4` to `7.4`, inclusive) |
 | ignored_files | No      |                      | Defines files that can be ignored (supports glob rules; each line means one rule) |
-| phpdocumentor_version | No | latest | What [PHP Documentator](https://www.phpdoc.org) version to use? (version = docker image tag) |
+| phpdocumentor_version | No | v2.8.5 | What [phpDocumentor](https://www.phpdoc.org) version to use (latest or release tag like `v2.8.5`) |
 | output_path | Yes | | Path where to write generated documentation |
 
+## Notes
+
+- Docker build clones `git@github.com:evert/phpdoc-md.git` directly and falls back to HTTPS clone when SSH credentials are not available.
+- phpDocumentor release artifacts are downloaded during action runtime and are not stored in this repository.
+- Dockerfile supports selecting PHP by version: `docker build --build-arg PHP_VERSION=7.4 .`
+- `php_version` input must match the container runtime version (this image version is controlled by `PHP_VERSION` build arg).
+- Tests are JavaScript integration tests based on [testcontainers-node](https://github.com/testcontainers/testcontainers-node).
+
 ## How to contribute? 
 
 If you want to add some functionality or fix bugs, you can fork, change and create pull request. If you not sure how this works, try [interactive GitHub tutorial](https://skills.github.com).

action.yml

@@ -6,48 +6,27 @@ branding:
   color: red
 
 inputs:
+  php_version:
+    description: "PHP version to run (must be between 5.4 and 7.4 inclusive)"
+    required: false
+    default: '7.4'
   ignored_files:
     description: "Defines files that can be ignored (supports glob rules; each line means one rule)"
     required: false
     default: ''
   phpdocumentor_version:
-    description: "What PHP Documentator version to use? (version = docker image tag)"
-    default: latest
+    description: "What phpDocumentor version to use? (latest or release tag like v2.8.5)"
+    default: v2.8.5
     required: false
   output_path:
     description: "Path where to write generated documentation"
     required: true
 
 runs:
-  using: 'composite'
-  steps:
-    - name: Setting env variables...
-      env:
-        GENERATOR_TMP_FILES_PATH: "${{ runner.temp }}/phpdocs-${{ github.sha }}-${{ github.run_id }}-${{ github.github.run_attempt }}"
-        GENERATOR_DOCS_PATH: ${{ inputs.output_path }}
-      run: $ACTION_BIN_PATH/generate-env.sh "$GENERATOR_TMP_FILES_PATH" "$GENERATOR_DOCS_PATH" >> $GITHUB_ENV
-      shell: bash
-
-    - name: Creating required paths...
-      run: $ACTION_BIN_PATH/create-paths.sh
-      shell: bash
-
-    - name: Running phpDocumentator...
-      run: $ACTION_BIN_PATH/phpdoc.sh "${{ inputs.ignored_files }}" "${{ inputs.phpdocumentor_version }}"
-      shell: bash
-
-    - name: Installing evert/phpdoc-md...
-      run: $ACTION_BIN_PATH/add-composer-packages.sh
-      shell: bash
-
-    - name: Generating documentation...
-      run: $ACTION_BIN_PATH/generate-docs.sh
-      shell: bash
-
-    - name: Uninstalling evert/phpdoc-md...
-      run: $ACTION_BIN_PATH/remove-composer-dependencies.sh
-      shell: bash
-
-    - name: Deleting tmp data...
-      run: $ACTION_BIN_PATH/remove-tmp-data.sh
-      shell: bash
+  using: 'docker'
+  image: 'Dockerfile'
+  args:
+    - ${{ inputs.php_version }}
+    - ${{ inputs.output_path }}
+    - ${{ inputs.ignored_files }}
+    - ${{ inputs.phpdocumentor_version }}

bin/entrypoint.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+REQUESTED_PHP_VERSION=${1:-7.4}
+OUTPUT_PATH=${2:-}
+IGNORED_FILES=${3:-}
+PHPDOC_VERSION=${4:-v2.8.5}
+
+if ! php -r '$version = isset($argv[1]) ? $argv[1] : ""; if (!preg_match("/^(5\\.[4-6]|7\\.[0-4])$/", $version)) { fwrite(STDERR, "Input '\''php_version'\'' must be between 5.4 and 7.4 (inclusive).\n"); exit(1); }' "$REQUESTED_PHP_VERSION"; then
+  exit 1
+fi
+
+RUNTIME_PHP_VERSION=$(php -r 'echo PHP_MAJOR_VERSION . "." . PHP_MINOR_VERSION;')
+if [[ "$REQUESTED_PHP_VERSION" != "$RUNTIME_PHP_VERSION" ]]; then
+  echo "Input 'php_version' is '$REQUESTED_PHP_VERSION' but action container uses PHP '$RUNTIME_PHP_VERSION'. Build the action image with matching PHP_VERSION." >&2
+  exit 1
+fi
+
+if [[ -z "$OUTPUT_PATH" ]]; then
+  echo "Input 'output_path' is required." >&2
+  exit 1
+fi
+
+WORKSPACE_PATH=${GITHUB_WORKSPACE:-/github/workspace}
+
+if [[ ! -d "$WORKSPACE_PATH" ]]; then
+  echo "Workspace path does not exist: $WORKSPACE_PATH" >&2
+  exit 1
+fi
+
+if [[ "$OUTPUT_PATH" = /* ]]; then
+  DOCS_PATH=$OUTPUT_PATH
+else
+  DOCS_PATH="$WORKSPACE_PATH/$OUTPUT_PATH"
+fi
+
+TMP_ROOT=$(mktemp -d)
+PHPDOC_XML_PATH="$TMP_ROOT/phpdoc-xml"
+PHPDOC_PHAR_PATH="$TMP_ROOT/phpDocumentor.phar"
+PHPDOC_TAR_GZ_PATH="$TMP_ROOT/phpDocumentor.tgz"
+PHPDOC_EXTRACT_PATH="$TMP_ROOT/phpDocumentor"
+PHPDOC_MD_PATH=/opt/phpdoc-md
+PHPDOC_CACHE_PATH=/opt/phpdocumentor-cache
+
+cleanup() {
+  rm -rf "$TMP_ROOT"
+}
+trap cleanup EXIT
+
+mkdir -p "$DOCS_PATH"
+mkdir -p "$PHPDOC_XML_PATH"
+mkdir -p "$PHPDOC_EXTRACT_PATH"
+
+download_file() {
+  local url=$1
+  local target=$2
+  php -r '$url = isset($argv[1]) ? $argv[1] : null; $target = isset($argv[2]) ? $argv[2] : null; if (!$url || !$target) { fwrite(STDERR, "Missing download arguments\n"); exit(1); } $data = @file_get_contents($url); if ($data === false) { exit(1); } if (@file_put_contents($target, $data) === false) { fwrite(STDERR, "Unable to write file: $target\n"); exit(1); }' "$url" "$target"
+}
+
+extract_tgz() {
+  local archive=$1
+  local target=$2
+  php -r '$archive = isset($argv[1]) ? $argv[1] : null; $target = isset($argv[2]) ? $argv[2] : null; if (!$archive || !$target) { fwrite(STDERR, "Missing extract arguments\n"); exit(1); } if (!is_dir($target) && !mkdir($target, 0777, true)) { fwrite(STDERR, "Unable to create extract directory\n"); exit(1); } $tarPath = preg_replace("/\\.tgz$/", ".tar", $archive); if ($tarPath === null) { fwrite(STDERR, "Unable to derive tar path\n"); exit(1); } try { $tgz = new PharData($archive); if (!file_exists($tarPath)) { $tgz->decompress(); } $tar = new PharData($tarPath); $tar->extractTo($target, null, true); } catch (Exception $e) { fwrite(STDERR, "Unable to extract phpDocumentor archive: " . $e->getMessage() . "\n"); exit(1); }' "$archive" "$target"
+}
+
+PHPDOC_COMMAND=()
+PHPDOC_COMMAND_SET=0
+if [[ "$PHPDOC_VERSION" == "latest" ]]; then
+  PHPDOC_PHAR_URL="https://phpdoc.org/phpDocumentor.phar"
+  download_file "$PHPDOC_PHAR_URL" "$PHPDOC_PHAR_PATH"
+  PHPDOC_COMMAND=(php "$PHPDOC_PHAR_PATH" run)
+  PHPDOC_COMMAND_SET=1
+else
+  PHPDOC_VERSION_NO_PREFIX=${PHPDOC_VERSION#v}
+  CACHED_PHPDOC_TAR_GZ_PATH="$PHPDOC_CACHE_PATH/phpDocumentor-${PHPDOC_VERSION_NO_PREFIX}.tgz"
+  CACHED_PHPDOC_PHAR_PATH="$PHPDOC_CACHE_PATH/phpDocumentor-${PHPDOC_VERSION_NO_PREFIX}.phar"
+  PHPDOC_TAR_GZ_URL="https://github.com/phpDocumentor/phpDocumentor/releases/download/v${PHPDOC_VERSION_NO_PREFIX}/phpDocumentor-${PHPDOC_VERSION_NO_PREFIX}.tgz"
+  PHPDOC_PHAR_URL="https://github.com/phpDocumentor/phpDocumentor/releases/download/v${PHPDOC_VERSION_NO_PREFIX}/phpDocumentor.phar"
+
+  if [[ "$PHPDOC_COMMAND_SET" -eq 0 ]] && [[ -f "$CACHED_PHPDOC_TAR_GZ_PATH" ]]; then
+    cp "$CACHED_PHPDOC_TAR_GZ_PATH" "$PHPDOC_TAR_GZ_PATH"
+  elif [[ "$PHPDOC_COMMAND_SET" -eq 0 ]] && ! download_file "$PHPDOC_TAR_GZ_URL" "$PHPDOC_TAR_GZ_PATH"; then
+    download_file "$PHPDOC_PHAR_URL" "$PHPDOC_PHAR_PATH"
+    PHPDOC_COMMAND=(php "$PHPDOC_PHAR_PATH" run)
+    PHPDOC_COMMAND_SET=1
+  fi
+
+  if [[ "$PHPDOC_COMMAND_SET" -eq 0 ]]; then
+    extract_tgz "$PHPDOC_TAR_GZ_PATH" "$PHPDOC_EXTRACT_PATH"
+    PHPDOC_BIN_PATH="$PHPDOC_EXTRACT_PATH/phpDocumentor-${PHPDOC_VERSION_NO_PREFIX}/bin/phpdoc"
+    if [[ ! -f "$PHPDOC_BIN_PATH" ]]; then
+      echo "Unable to find phpDocumentor binary after extraction." >&2
+      exit 1
+    fi
+    PHPDOC_COMMAND=(php "$PHPDOC_BIN_PATH")
+    PHPDOC_COMMAND_SET=1
+  fi
+fi
+
+declare -a PHPDOC_IGNORE_ARGS
+PHPDOC_IGNORE_ARGS+=("--ignore=vendor/**")
+while IFS= read -r LINE; do
+  LINE=${LINE%$'\r'}
+  if [[ -n "$LINE" ]]; then
+    PHPDOC_IGNORE_ARGS+=("--ignore=$LINE")
+  fi
+done <<< "$IGNORED_FILES"
+
+"${PHPDOC_COMMAND[@]}" \
+  --target="$PHPDOC_XML_PATH" \
+  --directory="$WORKSPACE_PATH" \
+  --cache-folder="$TMP_ROOT/cache" \
+  --template=xml \
+  --no-interaction \
+  --ansi \
+  "${PHPDOC_IGNORE_ARGS[@]}"
+
+if [[ ! -f "$PHPDOC_MD_PATH/bin/phpdocmd" ]]; then
+  echo "phpdoc-md binary is missing: $PHPDOC_MD_PATH/bin/phpdocmd" >&2
+  exit 1
+fi
+
+php "$PHPDOC_MD_PATH/bin/phpdocmd" "$PHPDOC_XML_PATH/structure.xml" "$DOCS_PATH"