@bazo/openapi-client-generator 3.0.13 → 3.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@bazo/openapi-client-generator",
-	"version": "3.0.13",
+	"version": "3.0.15",
 	"bin": {
 		"openapi-client-generator": "bin.js"
 	},

package/skills/generate-client/SKILL.md

@@ -2,11 +2,11 @@
 name: generate-client
 description: >
   Run the @bazo/openapi-client-generator CLI to produce a typed API client
-  from an OpenAPI JSON spec. Covers CLI flags (-n/--name, -m/--mode),
-  positional arguments (spec path, output directory), generation modes
-  (full, playwright, swift, kotlin), output file naming, and npm script
-  integration. Load when generating, regenerating, or configuring the
-  openapi-client-generator CLI.
+  from an OpenAPI JSON spec. Covers CLI flags (-n/--name, -m/--mode,
+  --namespace, --php-version), positional arguments (spec path, output
+  directory), generation modes (full, playwright, swift, kotlin, php),
+  output file naming, and npm script integration. Load when generating,
+  regenerating, or configuring the openapi-client-generator CLI.
 type: core
 library: openapi-client-generator
 library_version: "3.0.0"
@@ -36,7 +36,9 @@ Arguments and flags:
 | `<spec.json>` | yes | Path to a local OpenAPI JSON file |
 | `<output-dir>` | yes | Directory for the generated file |
 | `-n, --name` | yes | Client class name (must be a valid TypeScript identifier) |
-| `-m, --mode` | no | `full` (default), `playwright`, `swift`, or `kotlin` |
+| `-m, --mode` | no | `full` (default), `playwright`, `swift`, `kotlin`, or `php` |
+| `--namespace` | no | Root PHP namespace (php mode only, default: `--name`) |
+| `--php-version` | no | Target PHP version for php mode: `8.0`–`8.5` (default: `8.1`) |
 
 Save as an npm script:
 
@@ -82,6 +84,14 @@ npx openapi-client openapi.json src/main/kotlin/api/ -n ApiClient -m kotlin
 
 Produces `src/main/kotlin/api/ApiClient.kt` with `@Serializable` data classes and Ktor suspend functions.
 
+### Generate a PHP client
+
+```bash
+npx openapi-client openapi.json src/Api/ -n ApiClient -m php --namespace "App\\Api" --php-version 8.2
+```
+
+Unlike the other modes, php outputs a directory: `src/Api/ApiClient/` with `ApiClient.php`, `Model/*.php`, `ApiResponse.php`, `ApiException.php`, and `SerializerFactory.php` (Symfony HttpClient + Serializer). `--php-version` gates emitted language features (enums/readonly 8.1+, readonly classes 8.2+, `#[\NoDiscard]` 8.5).
+
 ## Common Mistakes
 
 ### CRITICAL Hallucinating non-existent CLI flags
@@ -98,7 +108,7 @@ Correct:
 npx openapi-client api.json out/ -n MyClient -m full
 ```
 
-The CLI uses `parseArgs` with `strict: true`. Only `-n/--name`, `-m/--mode`, `-v/--version`, and `-h/--help` exist. Any other flag causes a hard error.
+The CLI uses `parseArgs` with `strict: true`. Only `-n/--name`, `-m/--mode`, `--namespace`, `--php-version`, `-v/--version`, and `-h/--help` exist. Any other flag causes a hard error.
 
 Source: src/bin.ts
 
@@ -170,7 +180,7 @@ Correct:
 npx openapi-client api.json out/ -n MyClient -m full
 ```
 
-Mode must be exactly `full`, `playwright`, `swift`, or `kotlin`. Aliases like `react-query`, `ts`, `ios`, or `android` are not recognized.
+Mode must be exactly `full`, `playwright`, `swift`, `kotlin`, or `php`. Aliases like `react-query`, `ts`, `ios`, `android`, or `symfony` are not recognized.
 
 Source: src/bin.ts
 
@@ -178,3 +188,4 @@ See also: integrate-full-client/SKILL.md — peer deps and client instantiation
 See also: integrate-playwright-client/SKILL.md — Playwright fixture setup for playwright mode
 See also: integrate-swift-client/SKILL.md — Xcode integration for swift mode
 See also: integrate-kotlin-client/SKILL.md — Ktor setup for kotlin mode
+See also: integrate-php-client/SKILL.md — Composer setup and Symfony HttpClient integration for php mode

package/skills/integrate-php-client/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: integrate-php-client
+description: >
+  Use the generated PHP client in a PHP 8 application. Covers Symfony
+  HttpClient and Serializer dependencies via Composer, PSR-4 autoloading of
+  the generated directory, instantiation with HttpClientInterface and
+  baseUrl, typed model classes and backed enums, ApiResponse, ApiException
+  handling, the generated SerializerFactory, and the --php-version /
+  --namespace generation flags. Load when importing or using a generated
+  php-mode client directory.
+type: framework
+library: openapi-client-generator
+library_version: "3.0.0"
+requires:
+  - generate-client
+sources:
+  - "bazo/openapi-client-generator:src/modes/php/index.ts"
+  - "bazo/openapi-client-generator:src/modes/php/helpers.ts"
+  - "bazo/openapi-client-generator:src/modes/php/runtime.ts"
+---
+
+This skill builds on generate-client. Read it first for CLI usage.
+
+# Integrate PHP Client
+
+## Setup
+
+Generate the client (unlike other modes, php outputs a directory of PSR-4 files):
+
+```bash
+openapi-client-generator api.json src/Api -n PetstoreClient -m php \
+  --namespace "App\\Api\\Petstore" --php-version 8.2
+```
+
+This writes `src/Api/PetstoreClient/` containing `PetstoreClient.php`, `ApiResponse.php`, `ApiException.php`, `SerializerFactory.php`, and `Model/*.php`. `--namespace` defaults to the client name; `--php-version` (8.0–8.5) defaults to 8.1 and gates emitted features (backed enums and readonly need 8.1+, `readonly class` 8.2+, `#[\Deprecated]` 8.4+, `#[\NoDiscard]` and `Uri\Rfc3986` URL building 8.5+).
+
+Add Composer dependencies:
+
+```bash
+composer require symfony/http-client symfony/serializer \
+  symfony/property-info symfony/property-access phpdocumentor/reflection-docblock
+```
+
+`phpdocumentor/reflection-docblock` is required — without it, `Pet[]` collection properties silently degrade to arrays of plain arrays instead of hydrated model objects.
+
+Map the namespace in `composer.json` (adjust to where you generated):
+
+```json
+{
+    "autoload": {
+        "psr-4": { "App\\Api\\Petstore\\": "src/Api/PetstoreClient/" }
+    }
+}
+```
+
+Instantiate the client:
+
+```php
+use App\Api\Petstore\PetstoreClient;
+use Symfony\Component\HttpClient\HttpClient;
+
+$api = new PetstoreClient(HttpClient::create(), 'https://api.example.com');
+```
+
+The constructor signature is:
+
+```php
+public function __construct(
+    private readonly HttpClientInterface $client,
+    private readonly string $baseUrl = self::DEFAULT_BASE_URL, // default only when the spec declares servers
+    ?SerializerInterface $serializer = null,                   // defaults to SerializerFactory::create()
+)
+```
+
+In a Symfony app, inject `HttpClientInterface` and register the client as a service instead of calling `HttpClient::create()`.
+
+## Core Patterns
+
+### Call a query operation
+
+```php
+$result = $api->listTasks(page: 1, limit: 10);
+$result->data;    // TaskList — typed, hydrated model
+$result->status;  // 200
+$result->headers; // response headers (keys lower-cased by Symfony HttpClient)
+```
+
+Optional parameters default to `null`; use named arguments to skip earlier ones.
+
+### Call a mutation operation
+
+```php
+use App\Api\Petstore\Model\CreateTaskRequest;
+use App\Api\Petstore\Model\TaskStatus;
+
+$result = $api->createTask(new CreateTaskRequest(
+    title: 'Build feature',
+    status: TaskStatus::Todo,
+));
+$result->data->id; // created task ID
+```
+
+Bodies are typed model classes; enum-typed fields take backed enum cases (PHP 8.1+ targets). Unset optional properties are omitted from the request JSON.
+
+### Handle API errors
+
+```php
+use App\Api\Petstore\ApiException;
+
+try {
+    $result = $api->getTask('nonexistent');
+} catch (ApiException $e) {
+    $e->statusCode;       // 404
+    $e->body;             // raw response body
+    $e->responseHeaders;
+    $e->url;
+}
+```
+
+Every non-success status throws `ApiException`; Symfony's own `HttpExceptionInterface` auto-throw is disabled by the generated code (`getContent(false)`).
+
+### Immutable model updates (PHP 8.5 target)
+
+Models are readonly; on a PHP 8.5 target use clone-with instead of mutation:
+
+```php
+$renamed = clone($task, ['title' => 'New title']);
+```
+
+## Common Mistakes
+
+### CRITICAL Missing serializer support packages
+
+Wrong:
+
+```bash
+composer require symfony/http-client symfony/serializer
+```
+
+Correct:
+
+```bash
+composer require symfony/http-client symfony/serializer \
+  symfony/property-info symfony/property-access phpdocumentor/reflection-docblock
+```
+
+The generated `SerializerFactory` wires `PhpDocExtractor` so constructor `@param Pet[]` docblocks drive collection hydration. Without `phpdocumentor/reflection-docblock`, nested arrays of models arrive as raw arrays and property reads fatal on type mismatch.
+
+Source: src/modes/php/runtime.ts SerializerFactory
+
+### HIGH Wrong serializer version for a PHP 8.0 target
+
+Wrong:
+
+```bash
+# --php-version 8.0 output with serializer 7.x
+composer require symfony/serializer:^7.0
+```
+
+Correct:
+
+```bash
+# 8.0-target output uses AnnotationLoader, removed in serializer 7
+composer require symfony/serializer:"^5.4|^6.0"
+```
+
+Code generated with `--php-version 8.0` imports `AnnotationLoader` and `Serializer\Annotation\SerializedName`, which serializer 7 removed. Targets 8.1+ use `AttributeLoader` and require serializer >= 6.4. Prefer `--php-version 8.1` or newer unless you are stuck on PHP 8.0.
+
+Source: src/modes/php/runtime.ts serializerFactoryUses
+
+### HIGH Editing the generated files directly
+
+Wrong:
+
+```php
+// Adding a custom method inside the generated PetstoreClient.php
+final class PetstoreClient
+{
+    // ...generated code...
+    public function customMethod(): void { /* hand-written */ }
+}
+```
+
+Correct:
+
+```php
+// Wrap or compose in your own class
+final class PetstoreGateway
+{
+    public function __construct(private readonly PetstoreClient $api) {}
+
+    public function customMethod(): void { /* hand-written */ }
+}
+```
+
+The generated directory is regenerated from the spec; manual edits are overwritten. The generated client is `final` — compose, don't extend.
+
+Source: maintainer interview
+
+See also: generate-client/SKILL.md — CLI usage for regenerating the client