Merge pull request #23 from krystal/feat/various

feat: Public API, new namespace, disk actions, sort order, 503s, automated builds

.editorconfig

@@ -13,3 +13,6 @@ trim_trailing_whitespace = true
 
 [*.md]
 trim_trailing_whitespace = false
+
+[*.yml]
+indent_size = 2

.gitattributes

@@ -9,3 +9,5 @@
 /.scrutinizer.yml   export-ignore
 /tests              export-ignore
 /.editorconfig      export-ignore
+/.github            export-ignore
+/generator          export-ignore

.github/workflows/build.yml

@@ -0,0 +1,111 @@
+name: Build PHP client
+
+on:
+  pull_request:
+concurrency:
+  # On the main branch we want all builds to complete, even if new commits are merged.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ !contains(github.ref, 'main')}}
+
+jobs:
+  build-php:
+    if: "!contains(github.head_ref, 'release-please')"
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Cache generator dependencies
+        uses: actions/cache@v4
+        with:
+          path: generator/vendor
+          key: ${{ runner.os }}-generator-vendor-${{ hashFiles('**/composer.lock') }}
+          restore-keys: ${{ runner.os }}-generator-vendor-
+
+      - name: Generate our client
+        run: make build
+
+      # Commit all changed files back to the repository
+      - uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: "feat(generator): new client automatically generated in GitHub Actions"
+
+  openapi:
+    if: "!contains(github.head_ref, 'release-please')"
+    runs-on: ubuntu-latest
+    steps:
+
+      - name: Check out the base branch
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.base.ref }}
+
+      - name: Copy the spec files to /tmp for comparison
+        run: |
+          cp katapult-core-openapi.json /tmp/katapult-core-openapi.json
+          cp katapult-public-openapi.json /tmp/katapult-public-openapi.json
+
+      - name: Check out the current branch
+        uses: actions/checkout@v4
+
+      - name: Cache node modules
+        uses: actions/cache@v4
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-node_modules-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: ${{ runner.os }}-node_modules-
+
+      - name: Install openapi-changes
+        run: npm install
+
+      - name: Katapult Core API Spec Changes
+        id: core-changes
+        run: |
+          set +e
+          echo "core_changes<<EOF" >> $GITHUB_OUTPUT
+          npx openapi-changes summary --no-logo --no-color --markdown /tmp/katapult-core-openapi.json katapult-core-openapi.json >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+          npx openapi-changes html-report /tmp/katapult-core-openapi.json katapult-core-openapi.json
+          if [ -f report.html ]; then mv report.html openapi-core-report.html; fi
+
+      - name: Katapult Public API Spec Changes
+        id: public-changes
+        run: |
+          set +e
+          echo "public_changes<<EOF" >> $GITHUB_OUTPUT
+          npx openapi-changes summary --no-logo --no-color --markdown /tmp/katapult-public-openapi.json katapult-public-openapi.json >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+          npx openapi-changes html-report /tmp/katapult-public-openapi.json katapult-public-openapi.json
+          if [ -f report.html ]; then mv report.html openapi-public-report.html; fi
+
+      - name: Emit changes in GHA runs
+        run: echo ${{ steps.core-changes.outputs.core_changes }}
+        continue-on-error: true
+
+      - name: Emit changes in GHA runs
+        run: echo ${{ steps.public-changes.outputs.public_changes }}
+        continue-on-error: true
+
+      - name: Upload HTML reports as artefacts
+        id: upload-report
+        uses: actions/upload-artifact@v4
+        with:
+          name: openapi-changes
+          path: openapi-*-report.html
+          if-no-files-found: ignore
+
+      - name: Add/update a comment on the PR with the changes for the two APIs
+        uses: mshick/add-pr-comment@v2
+        with:
+          message: |
+            ## Download Reports
+            [Download the OpenAPI Changes Report](${{ steps.upload-report.outputs.artifact-url }})
+
+            ## Core API Changes
+            ${{ steps.core-changes.outputs.core_changes || 'No changes.' }}
+
+            ## Public API Changes
+            ${{ steps.public-changes.outputs.public_changes || 'No changes.'  }}

.gitignore

@@ -4,3 +4,5 @@ vendor
 coverage
 .idea
 .phpunit.result.cache
+generator/.php-cs-fixer.cache
+node_modules

Makefile

@@ -0,0 +1,15 @@
+.PHONY: help
+
+help: ## Print this help message
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
+
+.DEFAULT_GOAL := help
+
+.PHONY: build
+build:
+	./generator/generate
+
+.PHONY: download-spec
+download-spec:
+	wget -O katapult-core-openapi.json https://api.katapult.io/core/v1/schema/openapi.json
+	wget -O katapult-public-openapi.json https://api.katapult.io/public/v1/schema/openapi.json

README.md

@@ -5,7 +5,9 @@
 [![Latest Version on Packagist](https://img.shields.io/packagist/v/krystal/katapult.svg?style=flat-square)](https://packagist.org/packages/krystal/katapult)
 [![Total Downloads](https://img.shields.io/packagist/dt/krystal/katapult.svg?style=flat-square)](https://packagist.org/packages/krystal/katapult)
 
-A PHP library for integrating with [Katapult](https://katapult.io/)
+A PHP library for integrating with [Katapult](https://katapult.io/).
+
+You can find all the Katapult Developer Docs [here](https://developers.katapult.io/).
 
 ## Version constraints
 * [v1.x](https://github.com/krystal/katapult-php/tree/1.x) supports PHP 5.6
@@ -34,7 +36,7 @@ If you need control over this, you can call `setHttpClient` in `ClientFactory`.
 The usage sample below emits the IPv4 and IPv6 addresses for each VM in your Organization.
 
 ```php
-use Krystal\Katapult\KatapultAPI\ClientFactory;
+use KatapultAPI\Core\ClientFactory;
 
 $katapult = (new ClientFactory('your-katapult-api-token'))->create();
 

composer.json

@@ -17,7 +17,7 @@
   },
   "autoload": {
     "psr-4": {
-      "Krystal\\Katapult\\KatapultAPI\\": "src/"
+      "KatapultAPI\\": "src/"
     }
   },
   "prefer-stable": true

generator/README.md

@@ -0,0 +1,19 @@
+# PHP
+
+## `manual`
+
+This directory contains non-generated files.
+
+## Class name generation
+
+The class name is derived from the method, URI and expected status code.
+
+A URI of `/organizations/:organization` will result in `Model\OrganizationsOrganizationGetResponse200`
+
+A URI of `/organizations/_` will result in `Model\OrganizationsGetResponse200`
+
+A POST with an expected HTTP response of 201 and a URI of `/world/europe/britain/manchester` will result in `Model\WorldEuropeBritainManchesterPostResponse201`
+
+A change to the URI therefore changes the class name.
+
+Characters that aren't valid within a class name are silently stripped out.

generator/composer.json

@@ -0,0 +1,17 @@
+{
+  "require-dev": {
+    "jane-php/open-api-3": "^7",
+    "nyholm/psr7": "^1.8",
+    "friendsofphp/php-cs-fixer": "^3.46"
+  },
+  "config": {
+    "allow-plugins": {
+      "php-http/discovery": true
+    }
+  },
+  "minimum-stability": "stable",
+  "prefer-stable": true,
+  "require": {
+    "symfony/serializer": "v5.4"
+  }
+}