@voxgig/sdkgen 4.34.0 → 4.34.2

package/project/.sdk/src/cmp/php/PrepareAuth_php.ts

@@ -84,9 +84,9 @@ class ${Name}PrepareAuth
 
   const bag = bagVar(spec.where)
 
-  return head + `class ${Name}PrepareAuth
+  return head + `${'cookie' === spec.where ? "require_once __DIR__ . '/PrepareHeaders.php';\n\n" : ''}class ${Name}PrepareAuth
 {
-${constants(spec)}${cookieHelper(spec)}
+${constants(spec)}${authName(spec)}${cookieHelper(spec)}
     public static function call(${Name}Context $ctx): array
     {
         $spec = $ctx->spec;
@@ -99,9 +99,15 @@ ${constants(spec)}${cookieHelper(spec)}
 
         // Public APIs that need no auth omit the options.auth block entirely.
         if (!isset($options['auth']) || $options['auth'] === null) {
-${suppressed(spec.where)}            return [$spec, null];
+${clear(spec.where, 'self::' + credConst(spec.where))}            return [$spec, null];
         }
 
+        $name = self::authName($options);
+
+        // A credential left under the declared name would travel beside the renamed one.
+        if ($name !== self::${credConst(spec.where)}) {
+${clear(spec.where, 'self::' + credConst(spec.where))}        }
+
         $apikey = \\Voxgig\\Struct\\Struct::getprop($options, self::OPTION_APIKEY, self::NOT_FOUND);
 ${basicBlock(spec)}${placeBlock(spec)}
         return [$spec, null];
@@ -141,11 +147,24 @@ ${secretConst}    private const NOT_FOUND = '__NOTFOUND__';
 
 // A spec reaching prepare_auth may already carry the credential pair, and
 // leaving it sends a withdrawn credential.
-function suppressed(where: string): string {
+function clear(where: string, name: string): string {
   if ('cookie' === where) {
-    return `            self::applyCookie($headers, null);\n`
+    return `            self::applyCookie($headers, ${name}, null);\n`
   }
-  return `            unset($${bagVar(where)}[self::${credConst(where)}]);\n`
+  return `            unset($${bagVar(where)}[${name}]);\n`
+}
+
+
+function authName(spec: AuthSpec): string {
+  const name = 'header' === spec.where ? 'strtolower($name)' : '$name'
+  return `
+    // The client's auth.name option, when set, replaces the name the API declares.
+    private static function authName(array $options): string
+    {
+        $name = \\Voxgig\\Struct\\Struct::getpath($options, 'auth.name');
+        return is_string($name) && '' !== $name ? ${name} : self::${credConst(spec.where)};
+    }
+`
 }
 
 
@@ -156,24 +175,13 @@ function cookieHelper(spec: AuthSpec): string {
   }
 
   return `
-    private static function applyCookie(array &$headers, ?string $value): void
+    private static function applyCookie(array &$headers, string $name, ?string $value): void
     {
-        $kept = [];
         $existing = $headers[self::HEADER_COOKIE] ?? '';
-
-        if (is_string($existing) && '' !== $existing) {
-            foreach (explode(';', $existing) as $part) {
-                $piece = trim($part);
-                if ('' === $piece || $piece === self::COOKIE_AUTH
-                    || str_starts_with($piece, self::COOKIE_AUTH . '=')) {
-                    continue;
-                }
-                $kept[] = $piece;
-            }
-        }
+        $kept = is_string($existing) ? ${spec.Name}PrepareHeaders::cookieKeep($existing, [$name]) : [];
 
         if (null !== $value) {
-            $kept[] = self::COOKIE_AUTH . '=' . $value;
+            $kept[] = $name . '=' . $value;
         }
 
         if ([] === $kept) {
@@ -213,14 +221,14 @@ function basicBlock(spec: AuthSpec): string {
             $secret_val = is_string($secret) && $secret !== self::NOT_FOUND ? $secret : '';
 
             if ($apikey_val === '') {
-                unset($headers[self::HEADER_AUTH]);
+                unset($headers[$name]);
             } else {
                 $auth_prefix = \\Voxgig\\Struct\\Struct::getpath($options, 'auth.prefix') ?? '';
                 $b64 = base64_encode("{$apikey_val}:{$secret_val}");
                 // The joined, encoded pair is a wire form neither credential's
                 // own registration covers.
                 ($ctx->utility->clean_add)($ctx, $b64);
-                $headers[self::HEADER_AUTH] = $auth_prefix === ''
+                $headers[$name] = $auth_prefix === ''
                     ? $b64 : "{$auth_prefix} {$b64}";
             }
 
@@ -239,10 +247,10 @@ function placeBlock(spec: AuthSpec): string {
         $missing = ${missing};
 
         if ($missing) {
-            self::applyCookie($headers, null);
+            self::applyCookie($headers, $name, null);
         } else {
             // One \`Cookie:\` header holds every cookie, separated by '; '.
-            self::applyCookie($headers, is_string($apikey) ? $apikey : '');
+            self::applyCookie($headers, $name, is_string($apikey) ? $apikey : '');
         }
 `
   }
@@ -252,12 +260,12 @@ function placeBlock(spec: AuthSpec): string {
         if (
             ${missing}
         ) {
-            unset($query[self::QUERY_AUTH]);
+            unset($query[$name]);
         } else {
             // NO PREFIX IN A QUERY STRING. \`?token=Bearer%20abc\` is not a
             // thing any API reads; the prefix is a header convention and is
             // dropped here deliberately rather than silently concatenated.
-            $query[self::QUERY_AUTH] = is_string($apikey) ? $apikey : '';
+            $query[$name] = is_string($apikey) ? $apikey : '';
         }
 `
   }
@@ -266,12 +274,12 @@ function placeBlock(spec: AuthSpec): string {
         if (
             ${missing}
         ) {
-            unset($headers[self::HEADER_AUTH]);
+            unset($headers[$name]);
         } else {
             $auth_prefix = \\Voxgig\\Struct\\Struct::getpath($options, 'auth.prefix') ?? '';
             $apikey_val = is_string($apikey) ? $apikey : '';
             // Empty prefix (raw apiKey credential) must not add a leading space.
-            $headers[self::HEADER_AUTH] = $auth_prefix === ''
+            $headers[$name] = $auth_prefix === ''
                 ? $apikey_val : "{$auth_prefix} {$apikey_val}";
         }
 `

package/project/.sdk/src/cmp/php/ReadmeEntity_php.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, entityIdField, opRequestShape, phpEntityAccessor } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, entityIdField, opRequestShape, phpEntityAccessor, opNeedsAction, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -13,6 +13,7 @@ import {
 // parse).
 function phpLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'null'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k || 'OBJECT' === k) return '[]'
@@ -28,6 +29,7 @@ const OP_DESC: Record<string, { method: string, desc: string }> = {
   list:   { method: 'list(match)',   desc: 'List entities matching the criteria.' },
   create: { method: 'create(data)',  desc: 'Create a new entity with the given data.' },
   update: { method: 'update(data)',  desc: 'Update an existing entity.' },
+  patch:  { method: 'patch(data)',   desc: 'Change part of an existing entity.' },
   remove: { method: 'remove(match)', desc: 'Remove the matching entity.' },
 }
 
@@ -53,6 +55,8 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
   publishedEntities.map((entity: any) => {
     const opnames = Object.keys(entity.op || {})
+    // An op that needs an action has no plain call to show.
+    const callable = opnames.filter((o: string) => !opNeedsAction(entity.op[o]))
     const fields = Object.values(entity.fields || {})
     const idF = entityIdField(entity)
 
@@ -106,7 +110,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    if (opnames.includes('load')) {
+    if (callable.includes('load')) {
       const loadItems = opRequestShape(entity, 'load').items
         .filter((it: any) => !it.optional || it.name === idF)
         .sort((a: any, b: any) =>
@@ -126,18 +130,18 @@ $${entity.name} = $client->${phpEntityAccessor(entity.Name)}()->load(${loadArg})
 `)
     }
 
-    if (opnames.includes('list')) {
+    if (callable.includes('list')) {
       Content(`#### Example: List
 
 \`\`\`php
-// list() returns an array of ${entity.Name} records (throws on error).
-$${entity.name}s = $client->${phpEntityAccessor(entity.Name)}()->list();
+// list() returns an array of ${entity.Name} entities, one per record (throws on error).
+$${entity.name}s = $client->${phpEntityAccessor(entity.Name)}()->list(${listMatchArg('php', entity)});
 \`\`\`
 
 `)
     }
 
-    if (opnames.includes('create')) {
+    if (callable.includes('create')) {
       // Members come from the SAME shape the runtime validates
       // (opRequestShape): every required member must appear — including a
       // required id and parent keys like page_id.

package/project/.sdk/src/cmp/php/ReadmeExamplesTest_php.ts

@@ -36,7 +36,7 @@ declare(strict_types=1);
 //   1. SYNTAX — 'php -l' on every block (a leading <?php is prepended when the
 //      snippet omits one). Every documented php example must parse.
 //   2. RUN — every RUNNABLE block (one that constructs the SDK, drives
-//      \\$client->, or performs an entity op load/list/create/update/remove) is
+//      \\$client->, or performs an entity op load/list/create/update/patch/remove) is
 //      EXECUTED offline in seeded test mode (${model.const.Name}SDK::test)
 //      against the real SDK. The captured output is scanned for a real
 //      PHP-level error (undefined method, wrong-arg-count, TypeError, ...)
@@ -129,7 +129,7 @@ ${entityLines}
         return preg_match('/new\\s+' . $cls . '\\b/', $b) === 1
             || preg_match('/' . $cls . '::test\\b/', $b) === 1
             || preg_match('/\\$client\\s*->/', $b) === 1
-            || preg_match('/->\\s*(?:load|list|create|update|remove)\\s*\\(/', $b) === 1;
+            || preg_match('/->\\s*(?:load|list|create|update|patch|remove)\\s*\\(/', $b) === 1;
     }
 
     /**
@@ -146,7 +146,7 @@ ${entityLines}
         if (preg_match('/\\b' . preg_quote(self::SDK_CLASS, '/') . '\\b/', $b) === 1) {
             return true;
         }
-        if (preg_match('/->\\s*(?:load|list|create|update|remove)\\b/', $b) === 1) {
+        if (preg_match('/->\\s*(?:load|list|create|update|patch|remove)\\b/', $b) === 1) {
             return true;
         }
         foreach (array_keys(self::ENTITIES) as $name) {

package/project/.sdk/src/cmp/php/ReadmeHowto_php.ts

@@ -1,11 +1,12 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, phpEntityAccessor } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, phpEntityAccessor, seededList, litPair } from '@voxgig/sdkgen'
 
 import { KIT, getModelPath, nom } from '@voxgig/apidef'
 
 
 function phpLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'null'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k || 'OBJECT' === k) return '[]'
@@ -27,29 +28,34 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const { entity: exampleEntity, primaryOp } = pickExampleEntity(
     Object.keys(seedable).length ? seedable : entity)
   const eName = exampleEntity ? nom(exampleEntity, 'Name') : 'Entity'
-  // Model-driven id key: null when the entity has no id-like field.
+  // Model-driven id key (null when the entity has none); the seed is keyed by model name.
   const idF = exampleEntity ? entityIdField(exampleEntity) : null
   const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+  const listed = exampleEntity && 'list' === primaryOp
+    ? seededList('php', exampleEntity, idF, 'test01') : null
   const seedSentence = idF
     ? '. Seed fixture\ndata via the `entity` option so offline calls resolve without a live server'
     : ''
+  const record = idF ? (listed ? listed.record : [litPair('php', idF, '"test01"')]).join(', ') : ''
   const testCtor = idF
-    ? `${model.const.Name}SDK::test([\n    "entity" => ["${eName.toLowerCase()}" => ["test01" => ["${idF}" => "test01"]]],\n])`
+    ? `${model.const.Name}SDK::test([\n    "entity" => ["${exampleEntity.name}" => ["test01" => [${record}]]],\n])`
     : `${model.const.Name}SDK::test()`
   let testCallArg = ''
-  if (exampleEntity && isMatchOp) {
+  if (listed) {
+    testCallArg = 0 < listed.call.length ? `[${listed.call.join(', ')}]` : ''
+  } else if (exampleEntity && isMatchOp) {
     const items = opRequestShape(exampleEntity, primaryOp).items
       .filter((it: any) => !it.optional || it.name === idF)
       .sort((a: any, b: any) => (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
     testCallArg = 0 < items.length
-      ? `[${items.map((it: any) => `"${it.name}" => ${it.name === idF ? '"test01"' : phpLit(it.type)}`).join(', ')}]`
+      ? `[${items.map((it: any) => litPair('php', it.name, it.name === idF ? '"test01"' : phpLit(it.type))).join(', ')}]`
       : ''
-  } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp)) {
+  } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp)) {
     const items = opRequestShape(exampleEntity, primaryOp).items
       .filter((it: any) => it.name !== idF && it.name !== 'id')
     const required = items.filter((it: any) => !it.optional)
     const chosen = required.length ? required : items.slice(0, 3)
-    testCallArg = `[${chosen.map((it: any) => `"${it.name}" => ${phpLit(it.type)}`).join(', ')}]`
+    testCallArg = `[${chosen.map((it: any) => litPair('php', it.name, phpLit(it.type))).join(', ')}]`
   }
 
   // The op-driven test-mode line, shown only when the SDK has an entity op.

package/project/.sdk/src/cmp/php/ReadmeInstall_php.ts

@@ -17,9 +17,9 @@ ${installCommand(model, target.name)}
 
   // Publish pending: not yet on Packagist. Install from the git release tag,
   // or from a clone as a Composer path repository, since a tag may not exist.
-  const { releasesUrl, repoUrl, repo } = repoInfo(model)
+  const { hostName, tagsUrl, repoUrl, repo } = repoInfo(model)
   Content(`This package is not yet published to Packagist. Install it from the
-GitHub release tag (\`${target.name}/vX.Y.Z\`, see [Releases](${releasesUrl})), or
+${hostName} release tag (\`${target.name}/vX.Y.Z\`, see [Tags](${tagsUrl})), or
 from a clone as a Composer path repository:
 
 \`\`\`bash

package/project/.sdk/src/cmp/php/ReadmeIntro_php.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, phpEntityAccessor } from '@voxgig/sdkgen'
+import { cmp, Content, phpEntityAccessor, modelText } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -10,7 +10,7 @@ import {
 
 const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
   const { target, ctx$: { model } } = props
-  const info = (model.main && model.main.kit && model.main.kit.info) || {}
+  const info = modelText(model)
   const tagline = info.tagline || ''
 
   // Derive a representative entity (and its operations) from the model so the
@@ -21,7 +21,7 @@ const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
   // Model-driven op list — union of the operations the active entities
   // actually expose (a read-only entity has just list+load), in canonical
   // order; never claim create/update/remove exist when no entity has them.
-  const CANON_OPS = ['list', 'load', 'create', 'update', 'remove']
+  const CANON_OPS = ['list', 'load', 'create', 'update', 'patch', 'remove']
   const opSet = new Set<string>()
   Object.values(entity || {}).forEach((e: any) => {
     if (!e || e.active === false) return

package/project/.sdk/src/cmp/php/ReadmeModel_php.ts

@@ -21,13 +21,14 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   entityList.forEach((e: any) => Object.keys(e.op || {})
     .forEach((o: string) => { if (e.op[o] && e.op[o].active !== false) opUnion.add(o) }))
   const opRowDefs: Record<string, string> = {
-    load: '| `load` | `($reqmatch, $ctrl): array` | Load a single entity by match criteria. |',
-    list: '| `list` | `(?array $reqmatch = null, $ctrl): array` | List entities matching the criteria (call with no argument to list all). |',
-    create: '| `create` | `($reqdata, $ctrl): array` | Create a new entity. |',
-    update: '| `update` | `($reqdata, $ctrl): array` | Update an existing entity. |',
-    remove: '| `remove` | `($reqmatch, $ctrl): array` | Remove an entity. |',
+    load: '| `load` | `($reqmatch, $ctrl): mixed` | Load a single entity by match criteria, and return it. |',
+    list: '| `list` | `(?array $reqmatch = null, $ctrl): mixed` | List entities matching the criteria (call with no argument to list all), one per record. |',
+    create: '| `create` | `($reqdata, $ctrl): mixed` | Create a new entity, and return it. |',
+    update: '| `update` | `($reqdata, $ctrl): mixed` | Update an existing entity, and return it. |',
+    patch: '| `patch` | `($reqdata, $ctrl): mixed` | Change part of an existing entity, and return it. |',
+    remove: '| `remove` | `($reqmatch, $ctrl): mixed` | Remove an entity, and return it marked as deleted. |',
   }
-  const opRows = ['load', 'list', 'create', 'update', 'remove']
+  const opRows = ['load', 'list', 'create', 'update', 'patch', 'remove']
     .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
 
   const apikeyOptionRow = isAuthActive(model)
@@ -93,9 +94,9 @@ ${opRows}
 
 ### Result shape
 
-Entity operations return the ENTITY (call data_get() for the record) (an \`array\` for single-entity
-ops, a \`list\` for \`list\`) and throw on error. Wrap calls in
-\`try\`/\`catch\` to handle failures.
+Entity operations return the entity, and \`list\` an \`array\` of entities, one
+per record; an entity's \`data_get()\` reads its record (an \`array\`). They
+throw on error, so wrap calls in \`try\`/\`catch\` to handle failures.
 
 The \`direct()\` escape hatch never throws — it returns a result \`array\`
 you branch on via \`$result["ok"]\`:

package/project/.sdk/src/cmp/php/ReadmeQuick_php.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive, envName, canonKey, canonScalarKey, opRequestShape, entityIdField, entityDataIdField, entityOps, phpEntityAccessor } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, envName, canonKey, canonScalarKey, opRequestShape, entityIdField, entityDataIdField, entityOps, phpEntityAccessor, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -55,6 +55,7 @@ $client = ${ctor};
     // placeholder would not parse).
     const phpLit = (type: any, placeholder: string = 'example'): string => {
       const k = canonScalarKey(type)
+      if ('NULL' === k) return 'null'
       if ('INTEGER' === k || 'NUMBER' === k) return '1'
       if ('BOOLEAN' === k) return 'true'
       if ('ARRAY' === k || 'OBJECT' === k) return '[]'
@@ -79,7 +80,7 @@ $client = ${ctor};
 \`\`\`php
 try {
     // list() returns entity instances; data_get() reads each record.
-    $${eName.toLowerCase()}s = $client->${phpEntityAccessor(eName)}()->list();
+    $${eName.toLowerCase()}s = $client->${phpEntityAccessor(eName)}()->list(${listMatchArg('php', exampleEntity)});
     foreach ($${eName.toLowerCase()}s as $record) {
         $item = $record->data_get();
         echo ${itemPrint} . "\\n";
@@ -174,7 +175,8 @@ try {
       ? `$created->data_get()["${dataIdF}"]`
       : phpLit(idParamType(opname), 'example_id')
 
-    if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {
+    if (opnames.includes('create') || opnames.includes('update') || opnames.includes('patch') ||
+      opnames.includes('remove')) {
       Content(`### 4. Create, update, and remove
 
 \`\`\`php
@@ -191,6 +193,13 @@ $created = $client->${phpEntityAccessor(eName)}()->create([${examplePairs('creat
         Content(`// Update${fromCreated ? ` — index the record via data_get() ($created->data_get()["${dataIdF}"]).` : ''}
 $client->${phpEntityAccessor(eName)}()->update([${updatePairs.join(', ')}]);
 
+`)
+      }
+      if (opnames.includes('patch')) {
+        const patchPairs = (idF ? [`"${idF}" => ${idValueFor('patch')}`] : []).concat(examplePairs('patch'))
+        Content(`// Patch — sends only the fields given
+$client->${phpEntityAccessor(eName)}()->patch([${patchPairs.join(', ')}]);
+
 `)
       }
       if (opnames.includes('remove')) {

package/project/.sdk/src/cmp/php/ReadmeRef_php.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, phpEntityAccessor , targetFeatures } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, phpEntityAccessor, targetFeatures, opNeedsAction, bodyNote, listMatchArg } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -14,6 +14,7 @@ import {
 // parse).
 function phpLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'null'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k || 'OBJECT' === k) return '[]'
@@ -24,28 +25,33 @@ function phpLit(type: any, placeholder: string = 'example'): string {
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
     sig: 'load(array $reqmatch, ?array $ctrl = null): mixed',
-    returns: 'mixed — the result data; throws on error',
-    desc: 'Load a single entity matching the given criteria. Throws on error.',
+    returns: 'mixed — the entity; throws on error',
+    desc: 'Load a single entity matching the given criteria. Returns the entity, whose record `data_get()` reads, and throws on error.',
   },
   list: {
     sig: 'list(?array $reqmatch = null, ?array $ctrl = null): mixed',
-    returns: 'array — the list of results; throws on error',
-    desc: 'List entities matching the given criteria (call with no argument to list all). Returns an array. Throws on error.',
+    returns: 'array — the entities, one per record; throws on error',
+    desc: 'List entities matching the given criteria (call with no argument to list all). Returns an array of entities, one per record, and throws on error.',
   },
   create: {
     sig: 'create(array $reqdata, ?array $ctrl = null): mixed',
-    returns: 'mixed — the result data; throws on error',
-    desc: 'Create a new entity with the given data. Throws on error.',
+    returns: 'mixed — the created entity; throws on error',
+    desc: 'Create a new entity with the given data. Returns the created entity and throws on error.',
   },
   update: {
     sig: 'update(array $reqdata, ?array $ctrl = null): mixed',
-    returns: 'mixed — the result data; throws on error',
-    desc: 'Update an existing entity. The data must include the entity `id`. Throws on error.',
+    returns: 'mixed — the updated entity; throws on error',
+    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity and throws on error.',
+  },
+  patch: {
+    sig: 'patch(array $reqdata, ?array $ctrl = null): mixed',
+    returns: 'mixed — the patched entity; throws on error',
+    desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity `id`. Returns the patched entity and throws on error.',
   },
   remove: {
     sig: 'remove(array $reqmatch, ?array $ctrl = null): mixed',
-    returns: 'mixed — the result data; throws on error',
-    desc: 'Remove the entity matching the given criteria. Throws on error.',
+    returns: 'mixed — the entity, marked as deleted; throws on error',
+    desc: 'Remove the entity matching the given criteria. Returns the entity, marked as deleted, and throws on error.',
   },
 }
 
@@ -214,7 +220,7 @@ $${ent.name} = $client->${phpEntityAccessor(ent.Name)}();
         if (hasFieldOps) {
           // Only emit columns for operations this entity actually exposes —
           // never advertise a create/update/remove column the entity lacks.
-          const opcols = ['load', 'list', 'create', 'update', 'remove']
+          const opcols = ['load', 'list', 'create', 'update', 'patch', 'remove']
             .filter((op: string) => opnames.includes(op) && ent.op[op]?.active !== false)
           Content(`### Field Usage by Operation
 
@@ -255,6 +261,10 @@ ${info.desc}
 
 `)
 
+          if (opNeedsAction(ent.op[opname])) {
+            return
+          }
+
           if ('load' === opname || 'remove' === opname) {
             // The id key plus every REQUIRED match key (parent path params
             // like page_id) — the same shape the runtime resolves path
@@ -276,7 +286,7 @@ $result = $client->${phpEntityAccessor(ent.Name)}()->${opname}(${arg});
           }
           else if ('list' === opname) {
             Content(`\`\`\`php
-$results = $client->${phpEntityAccessor(ent.Name)}()->list();
+$results = $client->${phpEntityAccessor(ent.Name)}()->list(${listMatchArg('php', ent)});
 \`\`\`
 
 `)
@@ -299,10 +309,10 @@ $result = $client->${phpEntityAccessor(ent.Name)}()->create([
 
 `)
           }
-          else if ('update' === opname) {
+          else if ('update' === opname || 'patch' === opname) {
             // The id key plus every REQUIRED data member — the same shape the
             // runtime validates — then the patch-fields note.
-            const updateItems = opRequestShape(ent, 'update').items
+            const updateItems = opRequestShape(ent, opname).items
               .filter((it: any) => !it.optional || it.name === idF)
               .sort((a: any, b: any) =>
                 (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
@@ -310,13 +320,21 @@ $result = $client->${phpEntityAccessor(ent.Name)}()->create([
               `  "${it.name}" => ${phpLit(it.type,
                 it.name === idF ? ent.name + '_id' : it.name)},\n`).join('')
             Content(`\`\`\`php
-$result = $client->${phpEntityAccessor(ent.Name)}()->update([
-${updateLines}  // Fields to update
+$result = $client->${phpEntityAccessor(ent.Name)}()->${opname}([
+${updateLines}  // ${'patch' === opname ? 'Only the fields to change' : 'Fields to update'}
 ]);
 \`\`\`
 
 `)
           }
+
+          if ('create' === opname || 'update' === opname || 'patch' === opname) {
+            const note = bodyNote(ent.op[opname], {
+              values: 'a string or a stream resource',
+              once: 'a stream resource',
+            })
+            if ('' !== note) Content(note)
+          }
         })
       }
 

package/project/.sdk/src/cmp/php/ReadmeTopQuick_php.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, opRequestShape, phpEntityAccessor } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, opRequestShape, phpEntityAccessor, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -13,6 +13,7 @@ import {
 // doc test EXECUTES this block, so a comment placeholder would break it).
 function phpLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'null'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k || 'OBJECT' === k) return '[]'
@@ -50,8 +51,8 @@ $client = ${ctor};
     let hasCall = false
 
     if (opnames.includes('list')) {
-      Content(`// List all ${eName.toLowerCase()}s (returns an array; throws on error)
-$${eName.toLowerCase()}s = $client->${phpEntityAccessor(eName)}()->list();
+      Content(`// List all ${eName.toLowerCase()}s (an array of entities, one per record; throws on error)
+$${eName.toLowerCase()}s = $client->${phpEntityAccessor(eName)}()->list(${listMatchArg('php', exampleEntity)});
 print_r(array_map(fn($item) => $item->data_get(), $${eName.toLowerCase()}s));
 `)
       hasCall = true
@@ -71,7 +72,7 @@ print_r(array_map(fn($item) => $item->data_get(), $${eName.toLowerCase()}s));
             it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(', ')}]`
         : ''
       Content(`
-// Load a specific ${eName.toLowerCase()} (returns the ENTITY; call data_get() for the record; throws on error)
+// Load a specific ${eName.toLowerCase()} (returns the entity; data_get() reads its record; throws on error)
 $${eName.toLowerCase()} = $client->${phpEntityAccessor(eName)}()->load(${loadArg});
 print_r($${eName.toLowerCase()}->data_get());
 `)

package/project/.sdk/src/cmp/php/ReadmeTopTest_php.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, phpEntityAccessor } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, phpEntityAccessor, seededList, litPair } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -11,6 +11,7 @@ import {
 // A type-correct PHP literal for a field's canonical type.
 function phpLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'null'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k || 'OBJECT' === k) return '[]'
@@ -33,9 +34,13 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
     // Model-driven id key: null when the entity has no id-like field.
     const idF = entityIdField(exampleEntity)
     const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
-    const recBody = idF ? `["${idF}" => "test01"]` : '[]'
+    const listed = 'list' === primaryOp ? seededList('php', exampleEntity, idF, 'test01') : null
+    const recPairs = listed ? listed.record : idF ? [litPair('php', idF, '"test01"')] : []
+    const recBody = `[${recPairs.join(', ')}]`
     let callArg = ''
-    if (isMatchOp) {
+    if (listed) {
+      callArg = 0 < listed.call.length ? `[${listed.call.join(', ')}]` : ''
+    } else if (isMatchOp) {
       // Every REQUIRED match key (id first, then parent path params like
       // page_id) — the same shape the runtime resolves path params from.
       const items = opRequestShape(exampleEntity, primaryOp).items
@@ -44,21 +49,22 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
           (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
       callArg = 0 < items.length
         ? `[${items.map((it: any) =>
-          `"${it.name}" => ${it.name === idF ? '"test01"' : phpLit(it.type)}`).join(', ')}]`
+          litPair('php', it.name, it.name === idF ? '"test01"' : phpLit(it.type))).join(', ')}]`
         : ''
-    } else if ('create' === primaryOp || 'update' === primaryOp) {
+    } else if ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp) {
       const items = opRequestShape(exampleEntity, primaryOp).items
         .filter((it: any) => it.name !== idF && it.name !== 'id')
       const required = items.filter((it: any) => !it.optional)
       const chosen = required.length ? required : items.slice(0, 3)
-      callArg = `[${chosen.map((it: any) => `"${it.name}" => ${phpLit(it.type)}`).join(', ')}]`
+      callArg = `[${chosen.map((it: any) => litPair('php', it.name, phpLit(it.type))).join(', ')}]`
     }
-    // A list result is an array — name the variable accordingly.
+    // A list result is an array — name the variable accordingly. The fixture
+    // key is the model name, which the mock looks the entity up by.
     const eVar = ename + ('list' === primaryOp ? 's' : '')
     Content(`\`\`\`php
 // Seed fixture data so offline calls resolve without a live server.
 $client = ${model.const.Name}SDK::test([
-    "entity" => ["${ename}" => ["test01" => ${recBody}]],
+    "entity" => ["${exampleEntity.name}" => ["test01" => ${recBody}]],
 ]);
 $${eVar} = $client->${phpEntityAccessor(eName)}()->${primaryOp}(${callArg});
 \`\`\`