@apollo-deploy/tesseract 1.8.0 → 2.0.0

package/templates/php/domain.hbs

@@ -1,172 +1,141 @@
 <?php
 
-/**
- * @generated
- * This file was automatically generated by Tesseract.
- * DO NOT MODIFY THIS FILE DIRECTLY.
- */
-
 declare(strict_types=1);
 
 namespace {{namespace}}\Api;
 
+use {{namespace}}\SDKError;
+use {{namespace}}\Transport;
+{{#each imports}}
+use {{this}};
+{{/each}}
 use Psr\Http\Message\ResponseInterface;
 
-/**
- * {{interfaceName}} domain operations.
- *
-{{#if description}}
- * {{description}}
- *
-{{/if}}
- * @generated
- */
+/** {{#if description}}{{description}}{{else}}{{interfaceName}} domain operations.{{/if}} */
 class {{className}}
 {
-    private Transport $transport;
-
-    public function __construct(Transport $transport)
+    public function __construct(private Transport $transport)
     {
-        $this->transport = $transport;
     }
 
 {{#each operations}}
-{{#if (isEventStream this)}}
-    // SSE operations are not yet supported in the PHP adapter — skipping {{name}}
-
-{{else}}
     /**
-     {{#if deprecated}}
+{{#if deprecated}}
      * @deprecated{{#if deprecationMessage}} {{deprecationMessage}}{{/if}}
-     *
-     {{/if}}
-     {{#if (or summary description)}}
-     * {{#if summary}}{{summary}}{{#if description}} — {{description}}{{/if}}{{else}}{{description}}{{/if}}
-     *
-     {{/if}}
-     {{#each pathParams}}
-     * @param {{type}} ${{name}}{{#if description}} {{description}}{{/if}}
-     {{/each}}
-     {{#if requestBody}}
-     * @param array<string, mixed>{{#unless requestBody.required}}|null{{/unless}} $input Request body
-     {{/if}}
-     {{#each queryParams}}
-     * @param {{type}}|null ${{name}}{{#if description}} {{description}}{{/if}}
-     {{/each}}
-     {{#each headerParams}}
-     * @param {{type}}|null ${{name}}{{#if description}} {{description}}{{/if}}
-     {{/each}}
-     * @return {{responseType}}
+{{/if}}
+{{#each parameters}}
+     * @param {{docType}} ${{variableName}}{{#if description}} {{description}}{{/if}}
+{{/each}}
+{{#if isEventStream}}
+     * @return \Generator<int, string>
+{{else}}
+     * @return {{responseDocType}}
+{{/if}}
      * @throws SDKError
      */
-    public function {{name}}(
-        {{#each pathParams}}
-        {{type}} ${{name}},
-        {{/each}}
-        {{#if requestBody}}
-        {{#unless requestBody.required}}?{{/unless}}array $input{{#unless requestBody.required}} = null{{/unless}},
-        {{/if}}
-        {{#each queryParams}}
-        ?{{type}} ${{name}} = null,
-        {{/each}}
-        {{#each headerParams}}
-        ?{{type}} ${{name}} = null,
-        {{/each}}
-    ): {{responseType}}
+    public function {{methodName}}(
+{{#each parameters}}
+        {{targetType}} ${{variableName}}{{#unless required}} = null{{/unless}},
+{{/each}}
+    ): {{#if isEventStream}}\Generator{{else}}{{targetResponseType}}{{/if}}
     {
-        // Build path with parameter substitution
         $path = '{{path}}';
-        {{#if (hasPathParams this)}}
-        $path = str_replace(
-            [{{#each pathParams}}'{{@root.LBRACE}}{{originalName}}{{@root.RBRACE}}'{{#unless @last}}, {{/unless}}{{/each}}],
-            [{{#each pathParams}}${{name}}{{#unless @last}}, {{/unless}}{{/each}}],
-            $path
-        );
-        {{/if}}
+{{#each pathParams}}
+        $path = str_replace('{{placeholder}}', rawurlencode((string) ${{variableName}}), $path);
+{{/each}}
 
-        // Build query parameters
         $query = [];
-        {{#if (hasQueryParams this)}}
-        {{#each queryParams}}
-        if (${{name}} !== null) {
-            $query['{{originalName}}'] = ${{name}};
+{{#each queryParams}}
+        if (${{variableName}} !== null) {
+            $query['{{originalName}}'] = ${{variableName}};
         }
-        {{/each}}
-        {{/if}}
+{{/each}}
 
-        // Build extra headers
         $headers = [];
-        {{#each headerParams}}
-        if (${{name}} !== null) {
-            $headers['{{originalName}}'] = (string) ${{name}};
+{{#each headerParams}}
+        if (${{variableName}} !== null) {
+            $headers['{{originalName}}'] = (string) ${{variableName}};
+        }
+{{/each}}
+{{#if cookieParams.length}}
+        $cookies = [];
+{{#each cookieParams}}
+        if (${{variableName}} !== null) {
+            $cookies[] = '{{originalName}}=' . rawurlencode((string) ${{variableName}});
         }
-        {{/each}}
+{{/each}}
+        if ($cookies !== []) {
+            $headers['Cookie'] = implode('; ', $cookies);
+        }
+{{/if}}
 
-        // Execute request
-        $requestDef = [
+        $request = [
             'method' => '{{httpMethod}}',
             'path' => $path,
             'query' => $query,
             'headers' => $headers,
+{{#if isEventStream}}
+            'stream' => true,
+{{/if}}
         ];
-
-        {{#if (hasRequestBody this)}}
+{{#if requestBody}}
         if ($input !== null) {
-            $requestDef['body'] = $input;
+            $request['body'] = $input;
+            $request['contentType'] = '{{requestBody.contentType}}';
         }
-        {{/if}}
-
-        $response = $this->transport->executeRequest($requestDef);
+{{/if}}
 
-        // Deserialize response
+        $response = $this->transport->executeRequest($request);
+{{#if isEventStream}}
+        $body = $response->getBody();
+        $buffer = '';
+        while (!$body->eof()) {
+            $buffer .= $body->read(8192);
+            while (($lineEnd = strpos($buffer, "\n")) !== false) {
+                $line = substr($buffer, 0, $lineEnd);
+                $buffer = substr($buffer, $lineEnd + 1);
+                yield rtrim($line, "\r");
+            }
+        }
+        if ($buffer !== '') {
+            yield rtrim($buffer, "\r");
+        }
+{{else}}
         $data = $this->decodeResponse($response);
-
-        {{#if (eq responseType "void")}}
+{{#if isVoid}}
         return;
-        {{else if (eq responseType "string")}}
+{{else if (eq targetResponseType "string")}}
         return (string) $data;
-        {{else if (eq responseType "int")}}
+{{else if (eq targetResponseType "int")}}
         return (int) $data;
-        {{else if (eq responseType "float")}}
+{{else if (eq targetResponseType "float")}}
         return (float) $data;
-        {{else if (eq responseType "bool")}}
+{{else if (eq targetResponseType "bool")}}
         return (bool) $data;
-        {{else if (eq responseType "array")}}
+{{else if (eq targetResponseType "array")}}
+        return is_array($data) ? $data : [];
+{{else if (eq targetResponseType "mixed")}}
         return $data;
-        {{else}}
-        // Complex type: deserialize via fromArray
-        if (class_exists({{responseType}}::class) && method_exists({{responseType}}::class, 'fromArray')) {
-            return {{responseType}}::fromArray($data);
+{{else}}
+        if (is_array($data) && method_exists({{targetResponseType}}::class, 'fromArray')) {
+            return {{targetResponseType}}::fromArray($data);
         }
         return $data;
-        {{/if}}
+{{/if}}
+{{/if}}
     }
 
-{{/if}}
 {{/each}}
-
-    /**
-     * Decode a PSR-7 response body to an associative array or raw value.
-     *
-     * @return array<string, mixed>|string
-     */
-    private function decodeResponse(ResponseInterface $response): array|string
+    private function decodeResponse(ResponseInterface $response): mixed
     {
         $contents = $response->getBody()->__toString();
+        if (trim($contents) === '') {
+            return null;
+        }
 
         try {
-            $decoded = json_decode($contents, true, 512, JSON_THROW_ON_ERROR);
-            if (is_array($decoded)) {
-                return $decoded;
-            }
-            if (is_scalar($decoded)) {
-                return (string) $decoded;
-            }
-            return ['raw' => $decoded];
+            return json_decode($contents, true, 512, JSON_THROW_ON_ERROR);
         } catch (\JsonException) {
-            if (trim($contents) === '') {
-                return [];
-            }
             return $contents;
         }
     }

package/templates/php/errors.hbs

@@ -110,7 +110,7 @@ class SDKError extends \Exception
      */
     public function isRetryable(): bool
     {
-        return $this->httpStatus >= 500 || $this->httpStatus === 429;
+        return $this->httpStatus >= 500 || in_array($this->httpStatus, [408, 425, 429], true);
     }
 
     /**

package/templates/php/readme.hbs

@@ -1,10 +1,8 @@
 # {{title}} PHP SDK
 
-{{#if description}}
-{{description}}
+{{#if description}}{{description}}{{else}}PHP client for the {{title}} API.{{/if}}
 
-{{/if}}
-> This SDK was automatically generated by [Tesseract](https://www.npmjs.com/package/@apollo-deploy/tesseract).
+> Generated by [Tesseract](https://www.npmjs.com/package/@apollo-deploy/tesseract). Generated source files should not be edited manually.
 
 ## Installation
 
@@ -12,7 +10,7 @@
 composer require {{composerName}}
 ```
 
-## Quick Start
+## Quick start
 
 ```php
 <?php
@@ -24,66 +22,61 @@ use {{namespace}}\Client;
 $client = new Client([
     'baseUrl' => '{{baseUrl}}',
 {{#each securitySchemes}}
-    '{{configKey}}' => 'your-{{kebabCase name}}-credential',
+    '{{configKey}}' => getenv('{{upperCase (snakeCase configKey)}}'),
 {{/each}}
+    'timeoutMs' => 15000,
 ]);
 
-{{#with groups.[0]}}
-$api = $client->{{name}}();
-{{/with}}
+{{#if groups.length}}
+$api = $client->{{groups.[0].accessorName}}();
+{{/if}}
 ```
 
-## Configuration
-
-The `Client` constructor accepts an associative array with the following keys:
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `baseUrl` | `string` | `'{{baseUrl}}'` | Base URL for the API |
-{{#each securitySchemes}}
-| `{{configKey}}` | `string` | `null` | {{#if description}}{{description}}{{else}}{{type}} credential for {{name}}{{/if}} |
-{{/each}}
-| `timeoutMs` | `int` | `15000` | Request timeout in milliseconds |
-| `retries` | `array` | `['attempts' => 3, 'backoffMs' => 400, 'jitter' => true]` | Retry configuration |
-| `defaultHeaders` | `array` | `[]` | Default headers sent with every request |
-
-## API Reference
-
-{{#each groups}}
-### `{{className}}`
+## Configuration and reliability
 
-{{#if description}}
-{{description}}
+The generated Guzzle transport supports bounded timeouts, exponential-backoff retries, rate-limit handling, default headers, and structured `SDKError` exceptions. Unsafe methods are not retried unless the request is idempotent or unsafe retries are explicitly enabled.
 
-{{/if}}
-| Method | HTTP | Path | Description |
-|--------|------|------|-------------|
-{{#each operations}}
-| `{{name}}()` | `{{upperCase httpMethod}}` | `{{path}}` | {{#if description}}{{description}}{{else}}-{{/if}} |
-{{/each}}
+```php
+$client = new Client([
+    'timeoutMs' => 30000,
+    'retries' => [
+        'attempts' => 3,
+        'backoffMs' => 400,
+        'jitter' => true,
+        'maxBackoffMs' => 30000,
+    ],
+    'defaultHeaders' => ['X-Application' => 'my-service'],
+]);
+```
 
-{{/each}}
+## Documentation
 
-## Types
+- [Documentation index](./docs/README.md)
+- [Generated types](./docs/types.md)
 
-{{#each schemas}}
-{{#if isEnum}}
-- `{{name}}` — enum: {{#each enumValues}}`{{this}}`{{#unless @last}}, {{/unless}}{{/each}}
-{{else}}
-- `{{name}}`{{#if description}} — {{description}}{{/if}}
-{{/if}}
+| Domain | Description |
+|---|---|
+{{#each groups}}
+| [{{className}}](./docs/domains/{{fileName}}.md) | {{#if description}}{{description}}{{else}}{{name}} operations{{/if}} |
 {{/each}}
 
-## Error Handling
+## Error handling
 
 ```php
-<?php
-
 use {{namespace}}\SDKError;
 
 try {
-    $result = $client->{{groups.[0].name}}()->{{groups.[0].operations.[0].name}}(/* params */);
-} catch (SDKError $e) {
-    echo sprintf("Error %d: %s (%s)\n", $e->getHttpStatus(), $e->getMessage(), $e->getErrorCode());
+    // Call a domain operation.
+} catch (SDKError $error) {
+    fprintf(STDERR, "%d %s request=%s\n", $error->getHttpStatus(), $error->getErrorCode(), $error->getRequestId());
+    throw $error;
 }
 ```
+
+## Requirements
+
+- PHP 8.2 or later
+
+## License
+
+MIT