From ba335819e662ac1650126883c990eb134261f7b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Tue, 5 May 2026 12:17:55 +0200 Subject: [PATCH 1/5] Allowed building dev version of the API references from Github Actions --- .github/workflows/api_refs.yaml | 43 ++++++++++++++++++++++++++++----- tools/api_refs/api_refs.sh | 6 ++--- 2 files changed, 40 insertions(+), 9 deletions(-) diff --git a/.github/workflows/api_refs.yaml b/.github/workflows/api_refs.yaml index a647a15c49..4521477ac0 100644 --- a/.github/workflows/api_refs.yaml +++ b/.github/workflows/api_refs.yaml @@ -4,9 +4,19 @@ on: workflow_dispatch: inputs: version: - description: 'Released version tag (for example: v4.6.21 or v5.0.0)' + # 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 dev version (install from x-dev branch, e.g. v5.0.x-dev)' + required: false + type: boolean + default: false jobs: open_php_api_ref_pr: @@ -17,12 +27,30 @@ jobs: - 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 }}" - base_branch="$(echo $version | sed 's/v\(.*\..*\)\..*/\1/')" - work_branch="api_refs_$version" - echo "version=$version" >> "$GITHUB_OUTPUT" - echo "base_branch=$base_branch" >> "$GITHUB_OUTPUT" - echo "work_branch=$work_branch" >> "$GITHUB_OUTPUT" + 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 @@ -44,6 +72,9 @@ jobs: SATIS_NETWORK_KEY: ${{ secrets.SATIS_NETWORK_KEY }} SATIS_NETWORK_TOKEN: ${{ secrets.SATIS_NETWORK_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: | composer config --global http-basic.updates.ibexa.co $SATIS_NETWORK_KEY $SATIS_NETWORK_TOKEN if [[ '4.6' != $BASE_BRANCH ]]; then diff --git a/tools/api_refs/api_refs.sh b/tools/api_refs/api_refs.sh index 2cb7d5788e..50a93703e7 100755 --- a/tools/api_refs/api_refs.sh +++ b/tools/api_refs/api_refs.sh @@ -9,7 +9,7 @@ REST_API_OPENAPI_FILE_YAML=${4:-./docs/api/rest_api/rest_api_reference/openapi.y REST_API_OPENAPI_FILE_JSON=${5:-./docs/api/rest_api/rest_api_reference/openapi.json}; # Path to the REST API OpenAPI spec file DXP_EDITION='commerce'; # Edition from and for which the Reference is built -DXP_VERSION='5.0.*'; # Version from and for which the Reference is built +DXP_VERSION="${DXP_VERSION:-5.0.*}"; # Version from and for which the Reference is built; can be overridden by the DXP_VERSION env var (e.g. v5.0.x-dev for a dev build) DXP_ADD_ONS=(automated-translation rector integrated-help fieldtype-richtext-rte connector-anthropic connector-gemini shopping-list cdp connector-raptor connector-quable mcp); # Packages not included in $DXP_EDITION but added to the Reference, listed without their vendor "ibexa" DXP_EDITIONS=(oss headless experience commerce); # Available editions ordered by ascending capabilities SF_VERSION='7.4'; # Symfony version used by Ibexa DXP @@ -26,8 +26,8 @@ OPENAPI_FIX="$(pwd)/tools/api_refs/openapi.php"; # A script editing and fixing f PHP_BINARY="php -d error_reporting=`php -r 'echo E_ALL & ~E_DEPRECATED;'`"; # Avoid depreciation messages from phpDocumentor/Reflection/issues/529 when using PHP 8.2 or higher TMP_DXP_DIR=/tmp/ibexa-dxp-phpdoc; # Absolute path of the temporary directory in which Ibexa DXP will be installed and the PHP API Reference built FORCE_DXP_INSTALL=1; # If 1, empty the temporary directory, install DXP from scratch, build, remove temporary directory; if 0, potentially reuse the DXP already installed in temporary directory, keep temporary directory for future uses. -BASE_DXP_BRANCH=''; # Branch from and for which the Reference is built when using a dev branch as version -VIRTUAL_DXP_VERSION=''; # Version for which the reference is supposedly built when using dev branch as version +BASE_DXP_BRANCH="${BASE_DXP_BRANCH:-}"; # Branch from and for which the Reference is built when using a dev branch as version; can be overridden by the BASE_DXP_BRANCH env var +VIRTUAL_DXP_VERSION="${VIRTUAL_DXP_VERSION:-}"; # Version for which the reference is supposedly built when using dev branch as version; can be overridden by the VIRTUAL_DXP_VERSION env var if [ ! -d $PHP_API_OUTPUT_DIR ]; then echo -n "Creating ${PHP_API_OUTPUT_DIR}… "; From 61d234b62340acabbc3a1f597df54103efe0f765 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Tue, 5 May 2026 17:36:40 +0200 Subject: [PATCH 2/5] TMP commit to test the changes --- .github/workflows/api_refs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/api_refs.yaml b/.github/workflows/api_refs.yaml index 4521477ac0..126cd9edd1 100644 --- a/.github/workflows/api_refs.yaml +++ b/.github/workflows/api_refs.yaml @@ -55,7 +55,7 @@ jobs: - name: Checkout documentation uses: actions/checkout@v4 with: - ref: ${{ steps.version_and_branches.outputs.base_branch }} + ref: php-api-ref-dev-version # TMP: hardcoded to test dev version workflow; revert to ${{ steps.version_and_branches.outputs.base_branch }} - name: Disable PHP coverage uses: shivammathur/setup-php@v2 From f4dd1daa86c2b8db85df221b98638455b10127b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Fri, 15 May 2026 15:42:57 +0200 Subject: [PATCH 3/5] Added GitHub token to the workflow --- .github/workflows/api_refs.yaml | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/.github/workflows/api_refs.yaml b/.github/workflows/api_refs.yaml index 126cd9edd1..dee2c7eb24 100644 --- a/.github/workflows/api_refs.yaml +++ b/.github/workflows/api_refs.yaml @@ -67,16 +67,30 @@ jobs: - 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: From 932939275a78da76e81d00e643658f3a6aaae0b4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Tue, 19 May 2026 21:13:19 +0200 Subject: [PATCH 4/5] Added Readme --- tools/api_refs/README.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/tools/api_refs/README.md b/tools/api_refs/README.md index 968c0bd919..200eaa418b 100644 --- a/tools/api_refs/README.md +++ b/tools/api_refs/README.md @@ -64,6 +64,21 @@ nano phpdoc.dev.xml # Edit and make your changes. For example, target only your tools/api_refs/api_refs.sh ~/.composer/auth.json ./docs/api/php_api/php_api_reference-TMP ``` +### Creating a build of dev version + +To build the reference for an unreleased version, set the following variables: + +- `DXP_VERSION` +- `BASE_DXP_BRANCH` +- `VIRTUAL_DXP_VERSION` + +For example, to build the API Reference based on the development version of the DXP before the 5.0.10 release, run: + +``` bash +DXP_VERSION=v5.0.x-dev BASE_DXP_BRANCH=5.0 VIRTUAL_DXP_VERSION=5.0.10 tools/api_refs/api_refs.sh ~/my/path/to/auth.json +``` + + ### Test a branch To load a package on a development branch instead of a released version, From 8913a628579da8035362d78c1658c03dcaecc2e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Tue, 19 May 2026 21:13:38 +0200 Subject: [PATCH 5/5] Update .github/workflows/api_refs.yaml Co-authored-by: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> --- .github/workflows/api_refs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/api_refs.yaml b/.github/workflows/api_refs.yaml index dee2c7eb24..fd0829b757 100644 --- a/.github/workflows/api_refs.yaml +++ b/.github/workflows/api_refs.yaml @@ -13,7 +13,7 @@ on: # 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 dev version (install from x-dev branch, e.g. v5.0.x-dev)' + description: 'Use x-dev branch (default: false)' required: false type: boolean default: false