feat(codegen): generate validated PHP code samples

.github/workflows/codegen.yaml

@@ -6,12 +6,18 @@ on:
       - main
     paths:
       - "codegen/**"
+      - "openapi.json"
+      - "composer.json"
+      - "justfile"
       - ".github/workflows/codegen.yaml"
   pull_request:
     branches:
       - main
     paths:
       - "codegen/**"
+      - "openapi.json"
+      - "composer.json"
+      - "justfile"
       - ".github/workflows/codegen.yaml"
 
 permissions:
@@ -51,5 +57,11 @@ jobs:
         with:
           go-version-file: './codegen/go.mod'
 
+      - name: Set up PHP
+        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2.37.2
+        with:
+          php-version: '8.2'
+          coverage: none
+
       - name: Run tests
         run: go test ./...

.github/workflows/release-code-samples.yaml

@@ -0,0 +1,124 @@
+name: Release Code Samples
+
+on:
+  release:
+    types:
+      - published
+
+concurrency:
+  group: release-code-samples-${{ github.event.release.tag_name }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  sync-php-code-samples:
+    name: Sync PHP code samples
+    runs-on: ubuntu-latest
+    env:
+      TARGET_REPOSITORY: sumup/sumup-developer
+      TARGET_BRANCH: automation/php-code-samples
+      TARGET_FILE: src/codesamples/php.json
+    steps:
+      - name: Checkout source code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          ref: refs/tags/${{ github.event.release.tag_name }}
+          persist-credentials: false
+
+      - name: Install Go
+        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+        with:
+          go-version-file: codegen/go.mod
+
+      - name: Create GitHub App token
+        id: app-token
+        uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
+        with:
+          app-id: ${{ secrets.SUMUP_BOT_APP_ID }}
+          private-key: ${{ secrets.SUMUP_BOT_PRIVATE_KEY }}
+          owner: sumup
+          repositories: sumup-developer
+
+      - name: Checkout target repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          repository: ${{ env.TARGET_REPOSITORY }}
+          ref: main
+          token: ${{ steps.app-token.outputs.token }}
+          path: sumup-developer
+          persist-credentials: true
+
+      - name: Get GitHub App User ID
+        id: get-user-id
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: echo "user-id=$(gh api "/users/${{ steps.app-token.outputs.app-slug }}[bot]" --jq .id)" >> "$GITHUB_OUTPUT"
+
+      - name: Configure git
+        run: |
+          git config --global user.name '${{ steps.app-token.outputs.app-slug }}[bot]'
+          git config --global user.email '${{ steps.get-user-id.outputs.user-id }}+${{ steps.app-token.outputs.app-slug }}[bot]@users.noreply.github.com'
+
+      - name: Prepare target branch
+        working-directory: sumup-developer
+        run: |
+          git fetch origin "${{ env.TARGET_BRANCH }}:refs/remotes/origin/${{ env.TARGET_BRANCH }}" || true
+          git checkout -B "${{ env.TARGET_BRANCH }}" origin/main
+
+      - name: Generate PHP code samples
+        working-directory: codegen
+        run: |
+          mkdir -p "../sumup-developer/$(dirname "${{ env.TARGET_FILE }}")"
+          go run . samples \
+            --sdk-version-file ../composer.json \
+            --out "../sumup-developer/${{ env.TARGET_FILE }}" \
+            ../openapi.json
+
+      - name: Commit generated samples
+        id: commit
+        working-directory: sumup-developer
+        run: |
+          git add "${{ env.TARGET_FILE }}"
+          if git diff --cached --quiet; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          git commit -m "chore: update PHP code samples for ${{ github.event.release.tag_name }}"
+          echo "changed=true" >> "$GITHUB_OUTPUT"
+
+      - name: Push branch
+        if: steps.commit.outputs.changed == 'true'
+        working-directory: sumup-developer
+        run: git push --force-with-lease origin "${{ env.TARGET_BRANCH }}"
+
+      - name: Create or update pull request
+        if: steps.commit.outputs.changed == 'true'
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          head_ref="sumup:${{ env.TARGET_BRANCH }}"
+          pr_url="$(gh pr list \
+            --repo "${{ env.TARGET_REPOSITORY }}" \
+            --head "$head_ref" \
+            --base main \
+            --state open \
+            --json url \
+            --jq '.[0].url')"
+
+          if [ -n "$pr_url" ]; then
+            gh pr edit "$pr_url" \
+              --repo "${{ env.TARGET_REPOSITORY }}" \
+              --title "chore: update PHP code samples" \
+              --body "Updates \`${{ env.TARGET_FILE }}\` from \`${{ github.repository }}\` release \`${{ github.event.release.tag_name }}\`."
+            exit 0
+          fi
+
+          gh pr create \
+            --repo "${{ env.TARGET_REPOSITORY }}" \
+            --base main \
+            --head "${{ env.TARGET_BRANCH }}" \
+            --title "chore: update PHP code samples" \
+            --body "Updates \`${{ env.TARGET_FILE }}\` from \`${{ github.repository }}\` release \`${{ github.event.release.tag_name }}\`."

.gitignore

@@ -8,4 +8,5 @@ composer.lock
 .phpunit.result.cache
 .envrc
 build/
+code-samples.json
 .phpdoc/

codegen/README.md

@@ -16,6 +16,18 @@ go run . generate ../openapi.json ./build
 
 > Note: The PHP SDK now ships only with `openapi.json`; the YAML version is no longer maintained.
 
+## PHP Code Samples
+
+The `samples` command generates a deterministic, versioned JSON catalog from the same OpenAPI model used to generate the SDK. Each entry contains a complete PHP program that calls the generated service method. Named OpenAPI request examples produce separate entries.
+
+Generate the catalog from the repository root with:
+
+```sh
+just generate-codesamples
+```
+
+The recipe writes `code-samples.json` in the repository root by default. Pass another path as its argument to write it elsewhere. The generated file is ignored in this repository, and the codegen tests lint every program with PHP. Published releases regenerate the catalog from the release tag and open or update a pull request in `sumup/sumup-developer`.
+
 ## Features
 
 ### Enum Support

codegen/main.go

@@ -28,6 +28,7 @@ func App() *cli.App {
 		},
 		Commands: []*cli.Command{
 			Generate(),
+			Samples(),
 		},
 	}
 }