Redesign PHP documentation with One Identity

.eleventy.cjs

@@ -3,6 +3,8 @@ const path = require('node:path');
 
 // Deployment tooling can be newer than the selected published SDK source.
 const sourceDirectory = path.resolve(process.env.DOCS_SOURCE_DIRECTORY || __dirname);
+const portalDirectory = process.env.DOCS_PORTAL_DIRECTORY || 'docs/portal';
+const templateDirectory = process.env.DOCS_TEMPLATE_DIRECTORY || path.join(sourceDirectory, '.phpdoc/template');
 const QUICKSTART_CONTRACT = require(path.join(sourceDirectory, 'docs/quickstart-contract.json'));
 const QUICKSTART_BASES = QUICKSTART_CONTRACT.reference_resolution?.bases;
 const QUICKSTART_SOURCES = Object.freeze(Object.fromEntries(
@@ -70,14 +72,21 @@ function headingIds(markdown) {
 module.exports = function configure(eleventyConfig) {
   eleventyConfig.amendLibrary('md', (markdown) => markdown.use(headingIds));
 
+  // Both rendering engines use the same static product chrome.
+  for (const [name, file] of [['identityHeader', 'identity-header'], ['identityFooter', 'identity-footer']]) {
+    eleventyConfig.addShortcode(name, () => fs.readFileSync(
+      path.join(templateDirectory, `components/${file}.html.twig`), 'utf8',
+    ));
+  }
+
   eleventyConfig.addPassthroughCopy({'docs/CNAME': 'CNAME'});
-  eleventyConfig.addPassthroughCopy({'docs/portal/assets': 'assets'});
+  eleventyConfig.addPassthroughCopy({[path.join(portalDirectory, 'assets')]: 'assets'});
   eleventyConfig.addPassthroughCopy({'docs/quickstart-contract.json': 'quickstart-contract.json'});
   eleventyConfig.addPassthroughCopy({'docs/quickstart-contract.schema.v2.json': 'quickstart-contract.schema.v2.json'});
   eleventyConfig.addPassthroughCopy({'docs/laravel-adoption-contract.json': 'laravel-adoption-contract.json'});
   eleventyConfig.addPassthroughCopy({'docs/laravel-adoption-contract.schema.json': 'laravel-adoption-contract.schema.json'});
   eleventyConfig.addPassthroughCopy({'.phpdoc/template/analytics': 'analytics'});
-  eleventyConfig.addPassthroughCopy({'.phpdoc/template/assets': 'assets'});
+  eleventyConfig.addPassthroughCopy({[path.join(templateDirectory, 'assets')]: 'assets'});
   eleventyConfig.addPassthroughCopy({'build/api': 'api'});
 
   eleventyConfig.addShortcode('sourceFile', function sourceFile(sourceName, language = 'text', label = sourceName) {
@@ -98,7 +107,7 @@ module.exports = function configure(eleventyConfig) {
 
   return {
     dir: {
-      input: 'docs/portal',
+      input: portalDirectory,
       includes: '_includes',
       data: '_data',
       output: 'build/site',

.github/workflows/ci.yml

@@ -558,6 +558,8 @@ jobs:
       - name: Test documentation release-channel guards
         if: matrix.source == 'current'
         run: python "$DOCS_TOOLING_DIRECTORY/scripts/test-docs-release-channel.py"
+      - name: Test presentation and published SDK source isolation
+        run: python "$DOCS_TOOLING_DIRECTORY/scripts/prepare-docs-presentation.test.py"
       - name: Select authenticated dependency trust
         uses: durable-workflow/.github/.github/actions/bootstrap-patched-pip@75587fc33ff40c34f32ef777293dad56bb6f48c7  # clean-trust
         with:
@@ -577,6 +579,7 @@ jobs:
       - run: npm --prefix "$DOCS_TOOLING_DIRECTORY" audit --audit-level=moderate
       - run: node "$DOCS_TOOLING_DIRECTORY/scripts/check-docs-examples.mjs"
       - run: npm --prefix "$DOCS_TOOLING_DIRECTORY" run test:docs-portal-links
+      - run: npm --prefix "$DOCS_TOOLING_DIRECTORY" run test:docs-identity-status
       - name: Verify Composer trust before requests
         uses: durable-workflow/.github/.github/actions/verify-composer-trust@75587fc33ff40c34f32ef777293dad56bb6f48c7  # clean-trust
       - run: bash "$DOCS_TOOLING_DIRECTORY/scripts/build-docs.sh"
@@ -595,7 +598,15 @@ jobs:
       - name: Verify missing-resource browser evidence
         run: npm --prefix "$DOCS_TOOLING_DIRECTORY" run test:docs-browser-failures
       - name: Check portal and API layouts in Chromium
+        env:
+          DOCS_SCREENSHOTS_DIRECTORY: build/one-identity-screenshots
         run: node "$DOCS_TOOLING_DIRECTORY/scripts/check-docs-browser.mjs" build/site
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
+        if: always()
+        with:
+          name: php-docs-visual-${{ matrix.source }}
+          path: build/one-identity-screenshots
+          if-no-files-found: ignore
       - name: Check repository-owned documentation links offline
         uses: docker://lycheeverse/lychee@sha256:e2d19e57cf6ab037026f20b8e449a1f30d9d7f81eef4194763aab2eab20bd28d  # 0.24.2
         with:

.github/workflows/docs.yml

@@ -12,6 +12,7 @@ on:
       - 'scripts/finalize-api-reference.php'
       - 'scripts/build-docs.sh'
       - 'scripts/prepare-docs-tooling.py'
+      - 'scripts/prepare-docs-presentation.py'
       - 'scripts/bind-docs-artifact.py'
       - 'README.md'
       - 'composer.json'
@@ -24,6 +25,14 @@ on:
         description: 'Published stable SDK tag to deploy, or empty for current main'
         type: string
         required: false
+      build_only:
+        description: 'Build and qualify the exact stable tuple without deploying Pages'
+        type: boolean
+        default: false
+      presentation_source:
+        description: 'Optional exact accepted-main presentation commit; published SDK source stays unchanged'
+        type: string
+        required: false
       stable_source:
         description: 'Optional exact main commit with docs fixes and identical published SDK code'
         type: string
@@ -49,6 +58,7 @@ jobs:
         env:
           STABLE_TAG: ${{ inputs.stable_tag }}
           STABLE_SOURCE: ${{ inputs.stable_source }}
+          PRESENTATION_SOURCE: ${{ inputs.presentation_source }}
         run: |
           if [[ ! "$STABLE_TAG" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
             echo 'stable_tag must name an exact stable SDK version' >&2
@@ -58,8 +68,12 @@ jobs:
             echo 'stable_source must be an exact lowercase source commit' >&2
             exit 1
           fi
+          if [ -n "$PRESENTATION_SOURCE" ] && [[ ! "$PRESENTATION_SOURCE" =~ ^[0-9a-f]{40}$ ]]; then
+            echo 'presentation_source must be an exact lowercase source commit' >&2
+            exit 1
+          fi
       - name: Require a stable tag for a documentation source override
-        if: inputs.stable_source != '' && inputs.stable_tag == ''
+        if: (inputs.stable_source != '' || inputs.presentation_source != '') && inputs.stable_tag == ''
         run: exit 1
       - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803  # v6
         with:
@@ -96,6 +110,11 @@ jobs:
           STABLE_SOURCE: ${{ inputs.stable_source }}
           GH_TOKEN: ${{ github.token }}
         run: python "$DOCS_TOOLING_DIRECTORY/scripts/check-docs-release-channel.py"
+      - name: Stage presentation over the unchanged published SDK docs
+        if: inputs.presentation_source != ''
+        env:
+          PRESENTATION_SOURCE: ${{ inputs.presentation_source }}
+        run: python "$DOCS_TOOLING_DIRECTORY/scripts/prepare-docs-presentation.py" "$PRESENTATION_SOURCE" "$RUNNER_TEMP/docs-presentation"
       - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38  # v6
         with:
           node-version: '24'
@@ -106,6 +125,7 @@ jobs:
       - run: npm --prefix "$DOCS_TOOLING_DIRECTORY" audit --audit-level=moderate
       - run: node "$DOCS_TOOLING_DIRECTORY/scripts/check-docs-examples.mjs"
       - run: npm --prefix "$DOCS_TOOLING_DIRECTORY" run test:docs-portal-links
+      - run: npm --prefix "$DOCS_TOOLING_DIRECTORY" run test:docs-identity-status
       - name: Check repository-owned documentation links offline
         uses: docker://lycheeverse/lychee@sha256:e2d19e57cf6ab037026f20b8e449a1f30d9d7f81eef4194763aab2eab20bd28d  # 0.24.2
         with:
@@ -140,10 +160,19 @@ jobs:
       - name: Test missing-resource browser evidence
         run: npm --prefix "$DOCS_TOOLING_DIRECTORY" run test:docs-browser-failures
       - name: Check portal and API layouts in Chromium
+        env:
+          DOCS_SCREENSHOTS_DIRECTORY: build/one-identity-screenshots
         run: node "$DOCS_TOOLING_DIRECTORY/scripts/check-docs-browser.mjs" build/site
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
+        if: always()
+        with:
+          name: php-docs-visual-checks
+          path: build/one-identity-screenshots
+          if-no-files-found: ignore
       - name: Bind Pages artifact to the exact source revision
         env:
           EXPECTED_SOURCE_REVISION: ${{ steps.release-channel.outputs.source_revision }}
+          STABLE_TAG: ${{ inputs.stable_tag }}
         run: |
           test "$(git -C "$DOCS_TOOLING_DIRECTORY" rev-parse HEAD)" = "$GITHUB_WORKFLOW_SHA"
           python "$DOCS_TOOLING_DIRECTORY/scripts/bind-docs-artifact.py" "$EXPECTED_SOURCE_REVISION"
@@ -156,6 +185,7 @@ jobs:
     if: >-
       github.server_url == 'https://github.com' &&
       github.ref == 'refs/heads/main' &&
+      inputs.build_only != true &&
       needs.build.outputs.stable == 'true'
     needs: build
     runs-on: ubuntu-latest