api_refs.yaml

name: 'Build API Refs'

on:
    workflow_dispatch:
        inputs:
            version:
                # The version to build the API Reference for.
                # Use a released tag (e.g. v5.0.9) or a plain number (e.g. 5.0.9).
                description: 'Version (e.g. v5.0.9 or 5.0.9)'
                required: true
                type: string
            use_dev_version:
                # When checked, Composer installs from the x-dev branch instead of a released tag.
                # Useful for building a reference before the final release is tagged.
                # Example: version=5.0.9 + use_dev_version=true → DXP_VERSION=v5.0.x-dev, BASE_DXP_BRANCH=5.0, VIRTUAL_DXP_VERSION=5.0.9
                description: 'Use x-dev branch (default: false)'
                required: false
                type: boolean
                default: false

jobs:
    open_php_api_ref_pr:
        name: "PHP & REST API References' PR"
        runs-on: ubuntu-latest

        steps:
            - name: Set version and branches
              id: version_and_branches
              run: |
                  # Strip leading 'v' to get a plain version number (e.g. 5.0.9)
                  version="${{ inputs.version }}"
                  version="${version#v}"
                  base_branch="$(echo $version | sed 's/\(.*\..*\)\..*/\1/')"
                  work_branch="api_refs_v${version}"

                  if [[ "${{ inputs.use_dev_version }}" == "true" ]]; then
                    # Dev build: install from the x-dev branch and label output with the target version
                    dxp_version="v${base_branch}.x-dev"
                    base_dxp_branch="${base_branch}"
                    virtual_dxp_version="${version}"
                  else
                    # Stable build: install from the released tag
                    dxp_version="v${version}"
                    base_dxp_branch=""
                    virtual_dxp_version=""
                  fi

                  echo "version=v${version}" >> "$GITHUB_OUTPUT"
                  echo "base_branch=${base_branch}" >> "$GITHUB_OUTPUT"
                  echo "work_branch=${work_branch}" >> "$GITHUB_OUTPUT"
                  echo "dxp_version=${dxp_version}" >> "$GITHUB_OUTPUT"
                  echo "base_dxp_branch=${base_dxp_branch}" >> "$GITHUB_OUTPUT"
                  echo "virtual_dxp_version=${virtual_dxp_version}" >> "$GITHUB_OUTPUT"

            - name: Checkout documentation
              uses: actions/checkout@v4
              with:
                  ref: ${{ steps.version_and_branches.outputs.base_branch }}

            - name: Disable PHP coverage
              uses: shivammathur/setup-php@v2
              with:
                  coverage: none

            - name: Set up node
              uses: actions/setup-node@v4
            - name: Install Redocly CLI
              run: npm install -g @redocly/cli@latest

            - name: Generate token
              id: generate_token
              if: inputs.use_dev_version == true
              uses: actions/create-github-app-token@v2
              with:
                  app-id: ${{ secrets.AUTOMATION_CLIENT_ID }}
                  private-key: ${{ secrets.AUTOMATION_CLIENT_SECRET }}
                  owner: ibexa

            - name: Build API Refs
              env:
                  SATIS_NETWORK_KEY: ${{ secrets.SATIS_NETWORK_KEY }}
                  SATIS_NETWORK_TOKEN: ${{ secrets.SATIS_NETWORK_TOKEN }}
                  GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}
                  BASE_BRANCH: ${{ steps.version_and_branches.outputs.base_branch }}
                  DXP_VERSION: ${{ steps.version_and_branches.outputs.dxp_version }}
                  BASE_DXP_BRANCH: ${{ steps.version_and_branches.outputs.base_dxp_branch }}
                  VIRTUAL_DXP_VERSION: ${{ steps.version_and_branches.outputs.virtual_dxp_version }}
              run: |
                  if [ -n "$GITHUB_TOKEN" ]; then
                    composer config --global github-oauth.github.com "$GITHUB_TOKEN"
                  fi
                  composer config --global http-basic.updates.ibexa.co $SATIS_NETWORK_KEY $SATIS_NETWORK_TOKEN

                  if [[ '4.6' != $BASE_BRANCH ]]; then
                    tools/api_refs/api_refs.sh
                    # Fix escape character:
                    perl -pi -e 's/\e/\\E/g' tools/api_refs/.phpdoc/template/package-edition-map.twig
                  else
                    tools/php_api_ref/phpdoc.sh
                    # Fix escape character:
                    perl -pi -e 's/\e/\\E/g' tools/php_api_ref/.phpdoc/template/package-edition-map.twig
                    cd tools/raml2html/; composer install; cd -;
                    php tools/raml2html/raml2html.php build --non-standard-http-methods=COPY,MOVE,PUBLISH,SWAP -t default -o docs/api/rest_api/rest_api_reference/ docs/api/rest_api/rest_api_reference/input/ibexa.raml
                  fi

            - name: Commit
              env:
                  BASE_BRANCH: ${{ steps.version_and_branches.outputs.base_branch }}
              run: |
                  git config --global user.name "${GITHUB_ACTOR}"
                  git config --global user.email "${GITHUB_ACTOR}@users.noreply.github.com"
                  git add docs/api/php_api/php_api_reference/
                  if [[ '4.6' != $BASE_BRANCH ]]; then
                    git add tools/api_refs/.phpdoc/template/package-edition-map.twig
                  else
                    git add tools/php_api_ref/.phpdoc/template/package-edition-map.twig
                  fi
                  git diff-index --quiet --cached HEAD || git commit -m "PHP API Ref HTML"
                  git add docs/api/rest_api/rest_api_reference/rest_api_reference.html
                  git diff-index --quiet --cached HEAD || git commit -m "REST API Ref HTML"
                  if [[ '4.6' != $BASE_BRANCH ]]; then
                    git add docs/api/rest_api/rest_api_reference/openapi.yaml
                    git add docs/api/rest_api/rest_api_reference/openapi.json
                    git diff-index --quiet --cached HEAD || git commit -m "REST API OpenAPI spec"
                  fi

            - name: Create Pull Request
              uses: peter-evans/create-pull-request@v7
              with:
                  token: ${{ secrets.EZROBOT_PAT }}
                  title: "API Refs ${{ steps.version_and_branches.outputs.version }}"
                  body: "PHP API & REST API References update for ${{ steps.version_and_branches.outputs.version }}"
                  branch: "${{ steps.version_and_branches.outputs.work_branch }}"
                  base: "${{ steps.version_and_branches.outputs.base_branch }}"
                  draft: false
                  labels: 'Needs DOC review'