clients/php: initial PHP SDK for clawdforge

PHP 8.2+ Guzzle-based client mirroring the Python SDK surface:

- Client::healthz / run / uploadFile / createToken / listTokens / revokeToken
- Readonly value objects: RunRequest, RunResult, FileToken, AppToken
- Exception hierarchy: ForgeException (abstract) -> ApiException ->
  AuthException, plus TransportException
- camelCase PHP <-> snake_case wire conversion at the boundary
- Streamed multipart uploads via fopen($path, 'r')
- Injectable GuzzleHttp\ClientInterface (MockHandler-friendly)
- HTTP timeout = subprocess timeout + 30s margin
- 15 PHPUnit tests, 61 assertions, no live network
- README with Laravel + WordPress integration snippets
- MIT license, no Sulkta-specific assumptions

clients/php/examples/basic.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Minimal clawdforge usage from PHP.
+ *
+ * Set CLAWDFORGE_URL and CLAWDFORGE_TOKEN in the environment before running:
+ *
+ *     CLAWDFORGE_URL=http://localhost:8800 \
+ *     CLAWDFORGE_TOKEN=cf_xxxxxxxx \
+ *     php examples/basic.php
+ */
+
+require __DIR__ . '/../vendor/autoload.php';
+
+use Clawdforge\Client;
+use Clawdforge\Exception\ForgeException;
+use Clawdforge\RunRequest;
+
+$baseUrl = getenv('CLAWDFORGE_URL') ?: 'http://localhost:8800';
+$token = getenv('CLAWDFORGE_TOKEN') ?: '';
+if ($token === '') {
+    fwrite(STDERR, "set CLAWDFORGE_TOKEN in env\n");
+    exit(2);
+}
+
+$forge = new Client($baseUrl, $token);
+
+try {
+    $health = $forge->healthz();
+    fwrite(STDOUT, "claude_version: " . ($health['claude_version'] ?? 'unknown') . "\n");
+
+    $result = $forge->run(new RunRequest(
+        prompt: 'Reply with JSON: {"hello": "world"}',
+        model: 'sonnet',
+        timeoutSecs: 30,
+    ));
+
+    fwrite(STDOUT, "duration_ms: {$result->durationMs}, stop_reason: {$result->stopReason}\n");
+    if (is_array($result->result)) {
+        fwrite(STDOUT, "json: " . json_encode($result->result) . "\n");
+    } else {
+        fwrite(STDOUT, "text: " . (string) $result->result . "\n");
+    }
+} catch (ForgeException $e) {
+    fwrite(STDERR, "forge error: {$e->getMessage()}\n");
+    exit(1);
+}