ibexa · mnocon · Sep 9, 2026 · Sep 9, 2026 · Sep 9, 2026 · Sep 9, 2026
diff --git a/.github/workflows/api_refs.yaml b/.github/workflows/api_refs.yaml
@@ -1,18 +1,18 @@
-name: 'Build API Refs'
+name: 'Build REST API Reference'
 
 on:
     workflow_dispatch:
         inputs:
             version:
-                # The version to build the API Reference for.
+                # The version to build the REST 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
+                # Example: version=5.0.9 + use_dev_version=true → DXP_VERSION=v5.0.x-dev, VIRTUAL_DXP_VERSION=5.0.9
                 description: 'Use x-dev branch (default: false)'
                 required: false
                 type: boolean
@@ -32,8 +32,8 @@ on:
                 default: false
 
 jobs:
-    open_php_api_ref_pr:
-        name: "PHP & REST API References' PR"
+    open_rest_api_ref_pr:
+        name: "REST API Reference's PR"
         runs-on: ubuntu-26.04
 
         steps:
@@ -59,21 +59,19 @@ jobs:
 
                   if [[ "$INPUT_USE_DEV_VERSION" == "true" ]]; then
                     # Dev build: install from the x-dev branch and label output with the target version
-                    base_dxp_branch="$(echo "$version" | sed 's/\(.*\..*\)\..*/\1/')"
-                    dxp_version="v${base_dxp_branch}.x-dev"
+                    dxp_branch="$(echo "$version" | sed 's/\(.*\..*\)\..*/\1/')"
+                    dxp_version="v${dxp_branch}.x-dev"
                     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
@@ -109,60 +107,37 @@ jobs:
                   private-key: ${{ secrets.AUTOMATION_CLIENT_SECRET }}
                   owner: ibexa
 
-            - name: Build API Refs
+            - name: Build REST API Reference
               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
+                  tools/api_refs/api_refs.sh
 
             - 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
+                  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"
 
             - name: Create Pull Request
               uses: peter-evans/create-pull-request@v8
               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 }}"
+                  title: "REST API Reference ${{ steps.version_and_branches.outputs.version }}"
+                  body: "REST API Reference 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

diff --git a/.github/workflows/preview_comment.yaml b/.github/workflows/preview_comment.yaml
@@ -32,34 +32,16 @@ jobs:
                     build_url="https://ez-systems-developer-documentation--${{ github.event.pull_request.number }}.com.readthedocs.build/${{inputs.project}}en/${{ github.event.pull_request.number }}/"
 
                     md_change_list=$(git diff --name-only HEAD "origin/$GITHUB_BASE_REF" -- docs/ | grep -E "^docs\/.*\.md$" | sed -E "s|^docs/(.*)\.md$|- [docs/\1.md](${build_url}\1/)|")
-                    par_change_list='';
-                    for par_file in $(git diff --diff-filter=A --name-only "origin/$GITHUB_BASE_REF" HEAD -- docs/api/php_api/php_api_reference/ | grep -E '^docs\/.*\.html$'); do
-                      fqcn=$(grep -o 'data-copy-value=".*">Copy FQCN' $par_file | sed -E 's|data-copy-value="(.*)">.*|\1|' | sed 's|\\|\\\\|g')
-                      link=$(echo $par_file | sed -E "s|^docs/(.*\.html)$|- [\`${fqcn}\`](${build_url}\1)|")
-                      par_change_list=$(echo -e "$par_change_list\n$link")
-                    done
-                    par_change_list=$(echo "$par_change_list" | sed '1d' | sort -t '`' -k 2,2)
-                    change_count=$(( $(echo "$md_change_list" | wc -l) + $(echo "$par_change_list" | wc -l) ))
+                    change_count=$(echo "$md_change_list" | wc -l)
 
-                    echo -e "Markdown files:\n$md_change_list\n\nPHP API Ref.:\n$par_change_list" | perl -p -e 's/\e/\\E/g'
+                    echo -e "Markdown files:\n$md_change_list" | perl -p -e 's/\e/\\E/g'
 
-                    if [[ $change_count -gt $file_limit ]]; then
-                        par_change_list=$(echo "$par_change_list" | grep -v namespaces)
-                        change_count=$(( $(echo "$md_change_list" | wc -l) + $(echo "$par_change_list" | wc -l) ))
-                    fi
-
-                    if [[ -z "$md_change_list$par_change_list" ]]; then
+                    if [[ -z "$md_change_list" ]]; then
                       comment="Preview of modified files: no change to preview."
                     elif [[ $change_count -gt $file_limit ]]; then
                       comment="Preview of modified files: Too many files modified in a single PR, preview link list is skipped. ($change_count files &gt; $file_limit)"
                     else
-                      comment="# Preview of modified files"
-                      if [[ -n "$md_change_list" ]]; then
-                        comment="$comment\n\nPreview of modified Markdown:\n\n$md_change_list"
-                      fi
-                      if [[ -n "$par_change_list" ]]; then
-                        comment="$comment\n\nPreview of addition to PHP API Reference:\n\n$par_change_list"
-                      fi                  
+                      comment="# Preview of modified files\n\nPreview of modified Markdown:\n\n$md_change_list"
                     fi
 
                     echo -e "$comment" | perl -p -e 's/\e/\\E/g' > comment.md

diff --git a/.github/workflows/yaml_samples.yaml b/.github/workflows/yaml_samples.yaml
@@ -0,0 +1,51 @@
+name: "Validate YAML samples"
+
+on:
+    pull_request: ~
+
+jobs:
+    yaml-samples-validation:
+        name: Validate YAML samples
+        runs-on: "ubuntu-26.04"
+        strategy:
+            fail-fast: false
+            matrix:
+                php:
+                    - "8.4" # Upper supported version
+                    - "8.3" # Lower supported version
+        steps:
+            - uses: actions/checkout@v7
+
+            - name: Setup PHP Action
+              uses: shivammathur/setup-php@v2
+              with:
+                  php-version: ${{ matrix.php }}
+                  coverage: none
+                  extensions: "pdo_sqlite, gd"
+                  tools: cs2pr
+
+            - name: Generate token
+              id: generate_token
+              uses: actions/create-github-app-token@v3
+              with:
+                  app-id: ${{ secrets.AUTOMATION_CLIENT_ID }}
+                  private-key: ${{ secrets.AUTOMATION_CLIENT_SECRET }}
+                  owner: ${{ github.repository_owner }}
+
+            - name: Add composer keys for private packagist
+              run: |
+                  composer config --global http-basic.updates.ibexa.co $SATIS_NETWORK_KEY $SATIS_NETWORK_TOKEN
+                  composer config --global github-oauth.github.com $GITHUB_TOKEN
+              env:
+                  SATIS_NETWORK_KEY: ${{ secrets.SATIS_NETWORK_KEY }}
+                  SATIS_NETWORK_TOKEN: ${{ secrets.SATIS_NETWORK_TOKEN }}
+                  GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}
+
+            # The installed ibexa/* bundles are what makes it possible to build the
+            # full Symfony configuration tree the YAML samples are validated against.
+            - uses: ramsey/composer-install@v4
+              with:
+                  dependency-versions: highest
+
+            - name: Validate YAML configuration samples
+              run: composer check-yaml --ansi
diff --git a/.gitignore b/.gitignore
@@ -4,21 +4,17 @@ __pycache__/*
 **/__pycache__
 /site/
 **/.idea/
-.php-cs-fixer.cache
 composer.lock
-tools/php-cs-fixer/vendor
 node_modules/
 auth.json
 .yarn
 yarn.lock
 docs/css/*.map
-.deptrac.cache
 .lycheecache
 lychee.toml
 /repositories/
 lychee-report.md
 .phpunit.result.cache
-code_samples/_inline_php/
 /build/
 *.egg-info/
 /doc/
@@ -27,3 +23,5 @@ code_samples/_inline_php/
 /user/
 /class_paths.json
 /user-docs/
+.scratch/
+AGENTS.md
diff --git a/README.md b/README.md
@@ -42,11 +42,12 @@ mkdocs serve
 After a short while your documentation should be reachable at http://localhost:8000. If it isn't, check the output
 of the command.
 
-## Testing the code samples
+## Testing the documentation
 
 ### YAML configuration
 
-To test the YAML configuration, run the following commands:
+The YAML snippets in `code_samples/` and in the Markdown pages are validated against the
+Symfony configuration trees of the installed Ibexa bundles. To run the validation, use:
 
 ``` bash
 composer update
@@ -78,54 +79,6 @@ Some issues can be fixed automatically:
 yarn markdownlint --fix
 ```
 
-### PHPStan
-
-This repository uses PHPStan to test the code samples. To run the tests locally execute the commands below:
-```bash
-composer update
-composer phpstan
-```
-
-Regenerate the baseline by running:
-
-```bash
-composer phpstan-update-baseline
-```
-
-#### Skipping validation of inline PHP snippets
-
-PHP code blocks embedded directly in Markdown files are extracted and tested with PHPStan.
-To exclude a snippet from validation (for example, for an intentionally incomplete fragment), add the `skip-validation` marker to its opening fence:
-
-````markdown
-``` php {skip-validation}
-```
-````
-
-If the code block uses other options, such as `hl_lines`, they must be placed **inside the same curly-brace group** as the marker:
-
-````markdown
-``` php {skip-validation hl_lines="6 14"}
-```
-````
-
-Both `php {skip-validation} hl_lines="6 14"` and `php hl_lines="6 14" {skip-validation}` are rejected by the Markdown parser, and the whole code block is rendered as plain paragraph text.
-
-### Deptrac
-
-This repository uses Deptrac to test the code samples. To run the tests locally execute the commands below:
-
-```bash
-composer update
-composer deptrac
-```
-
-Regenerate the baseline by running:
-
-```bash
-composer deptrac-update-baseline
-```
-
 ## Checking links
 
 External links in the built documentation are checked using [lychee](https://lychee.cli.rs).