@voxgig/sdkgen 1.2.1 → 1.3.2

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

@@ -10,6 +10,7 @@ import {
   cmp,
   each,
   isAuthActive,
+  resolveAuthPrefix,
 } from '@voxgig/sdkgen'
 
 
@@ -39,8 +40,8 @@ const Config = cmp(async function Config(props: any) {
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
 
   const authActive = isAuthActive(model)
-  let authPrefix = ''
-  try { authPrefix = getModelPath(model, `main.${KIT}.config.auth.prefix`) } catch (_e) { }
+  // config.auth.prefix override -> spec-derived info.security.prefix -> 'Bearer'
+  const authPrefix = resolveAuthPrefix(model)
 
   let baseUrl = ''
   try { baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`) } catch (_e) { }

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

@@ -0,0 +1,142 @@
+
+
+// Typed-model generator (PHP target).
+//
+// Ported from the TypeScript reference EntityTypes_ts.ts. Reads
+// main.<KIT>.entity.<e>.fields[] and per-op params (op.<name>.points[].args.params[])
+// and emits one file, types/<Sdk>Types.php, containing a PHP 8 class with typed
+// properties per active entity plus a request/match class per active op. Field/param
+// sentinels ($STRING, $INTEGER, ...) are turned into real PHP types by the shared
+// sdkgen helper `canonToType` (source of truth: @voxgig/apidef VALID_CANON):
+//   $STRING -> string, $INTEGER -> int, $NUMBER -> float, $BOOLEAN -> bool,
+//   $OBJECT/$ARRAY -> array, unknown -> mixed.
+//
+// Type-name scheme (IDENTICAL to TS): data type = <Name>; per-op request
+// <Name>LoadMatch / <Name>ListMatch / <Name>RemoveMatch (query/id ops),
+// <Name>CreateData / <Name>UpdateData (body ops). An op WITH params -> a typed
+// class of those params (reqd:false -> nullable, defaulted null). An op WITHOUT
+// params -> a match class over the entity fields, all nullable/optional (the
+// PHP stand-in for TS `Partial<Name>`; callers may also pass a plain assoc-array).
+//
+// PHP has no generics and no structural typing, so these classes are documentation-
+// grade value objects: op signatures keep a permissive native type (assoc-array in,
+// mixed out at the item-5 boundary) and surface the class names via PHPDoc. The file
+// lands under types/ and is registered on composer's classmap autoload (see
+// Package_php.ts) so `new <Name>()` / type references resolve globally.
+
+import {
+  cmp, each,
+  File, Content, Folder,
+} from '@voxgig/sdkgen'
+
+import { canonToType, opTypeName, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+const LANG = 'php'
+
+
+// A valid PHP property/label name (identifiers only; the corpus never carries
+// exotic field names, but guard so a bad name can never emit invalid PHP).
+function validName(name: string): boolean {
+  return /^[A-Za-z_\x80-\xff][A-Za-z0-9_\x80-\xff]*$/.test(name)
+}
+
+
+// Emit one typed PHP property line. `mixed` is already nullable in PHP and
+// rejects the `?` prefix, so it is special-cased; every other optional field
+// becomes `?type` with a `= null` default so the property is safely optional.
+function propLine(name: string, sentinel: unknown, optional: boolean): string {
+  const type = canonToType(sentinel, LANG)
+  if ('mixed' === type) {
+    return optional
+      ? `    public mixed $${name} = null;\n`
+      : `    public mixed $${name};\n`
+  }
+  return optional
+    ? `    public ?${type} $${name} = null;\n`
+    : `    public ${type} $${name};\n`
+}
+
+
+const EntityTypes = cmp(function EntityTypes(props: any) {
+  const { model } = props.ctx$
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const entityList = each(entity).filter((e: any) => e.active !== false)
+
+  Folder({ name: 'types' }, () => {
+
+    File({ name: model.const.Name + 'Types.' + LANG }, () => {
+
+      Content(`<?php
+declare(strict_types=1);
+
+// Typed models for the ${model.const.Name} SDK.
+//
+// GENERATED from the API model: main.${KIT}.entity.<e>.fields[] and per-op
+// params (op.<name>.points[].args.params[]). Field/param types come from the
+// canonical type sentinels via @voxgig/sdkgen canonToType (source of truth:
+// @voxgig/apidef VALID_CANON). Do not edit by hand.
+//
+// These are documentation-grade value objects (PHP 8 typed properties),
+// registered on the composer classmap autoload. The SDK boundary exchanges
+// assoc-arrays; these classes name the shapes for tooling and typed callers.
+
+`)
+
+      entityList.forEach((ent: any) => {
+        const Name = ent.Name
+        const fields = (ent.fields ? each(ent.fields) : [])
+          .filter((f: any) => f.active !== false && validName(f.name))
+
+        // Entity data model: one typed property per field (`req:false` -> nullable).
+        Content(`/** ${Name} entity data model. */
+class ${Name}
+{
+`)
+        fields.forEach((f: any) => {
+          Content(propLine(f.name, f.type, false === f.req))
+        })
+        Content(`}
+
+`)
+
+        // Per active op: a request/match class. Members and their optionality
+        // come from the shared partiality policy (opRequestShape); this file
+        // only renders them as a PHP value-object class.
+        const ops = ent.op || {}
+        ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
+          if (null == ops[opname]) {
+            return
+          }
+
+          const typeName = opTypeName(Name, opname)
+          const { items } = opRequestShape(ent, opname)
+
+          Content(`/** Request payload for ${Name}#${opname}. */
+class ${typeName}
+{
+`)
+          items.forEach((it: any) => {
+            if (validName(it.name)) {
+              Content(propLine(it.name, it.type, it.optional))
+            }
+          })
+          Content(`}
+
+`)
+        })
+      })
+    })
+  })
+})
+
+
+export {
+  EntityTypes,
+}

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

@@ -13,14 +13,31 @@ const MainEntity = cmp(async function MainEntity(props: any) {
   const { entity } = props
   const { model } = props.ctx$
 
-  const accessor = PHP_RESERVED_LOWER.has(entity.Name.toLowerCase())
+  // Canonical facade method name is the PascalCase entity Name
+  // (`$client->${entity.Name}()`). PHP method names are case-insensitive, so
+  // the lowercase spelling `$client->${entity.name}()` still resolves here as
+  // a convenience — we declare it ONCE under the PascalCase name. An entity
+  // literally named 'test' would collide (case-insensitively) with the static
+  // `test()` test-mode constructor, so mangle to `<Name>_` in that case.
+  const accessor = PHP_RESERVED_LOWER.has(entity.name.toLowerCase())
     ? entity.Name + '_'
     : entity.Name
 
   Content(`
+    private $_${entity.name} = null;
+
+    // Canonical facade: $client->${accessor}()->list() / ->load(["id" => ...]).
+    // PHP method names are case-insensitive, so lowercase $client->${entity.name}()
+    // resolves here too.
     public function ${accessor}($data = null)
     {
         require_once __DIR__ . '/entity/${entity.name}_entity.php';
+        if ($data === null) {
+            if ($this->_${entity.name} === null) {
+                $this->_${entity.name} = new ${entity.Name}Entity($this, null);
+            }
+            return $this->_${entity.name};
+        }
         return new ${entity.Name}Entity($this, $data);
     }
 

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

@@ -22,6 +22,7 @@ import { Package } from './Package_php'
 import { Config } from './Config_php'
 import { Gitignore } from './Gitignore_php'
 import { MainEntity } from './MainEntity_php'
+import { EntityTypes } from './EntityTypes_php'
 
 
 const Main = cmp(async function Main(props: any) {
@@ -84,6 +85,9 @@ const Main = cmp(async function Main(props: any) {
     Config({ target })
   })
 
+  // Generate typed models (types/<Sdk>Types.php) — classmap-autoloaded.
+  EntityTypes({ target })
+
   // Generate feature factory module
   File({ name: 'features.' + target.ext }, () => {
     Content(`<?php

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

@@ -4,6 +4,9 @@ import {
   File,
   cmp,
   collectDeps,
+  pkgDescription,
+  keywords,
+  repoInfo,
 } from '@voxgig/sdkgen'
 
 
@@ -23,14 +26,25 @@ const Package = cmp(async function Package(props: any) {
   // "-sdk" (matches the TS Package generator).
   const ns = model.origin || 'voxgig-sdk'
   const pkgBase = ns.endsWith('-sdk') ? model.name : `${model.name}-sdk`
+  const { repoUrl, issuesUrl } = repoInfo(model)
+  const kw = keywords(model).map((k) => `"${k}"`).join(', ')
 
   // Generate composer.json
   File({ name: 'composer.json' }, () => {
     Content(`{
   "name": "${ns}/${pkgBase}",
-  "description": "${model.const.Name} SDK for PHP",
+  "description": "${pkgDescription(model, 'php')}",
   "type": "library",
+  "keywords": [${kw}],
+  "homepage": "${repoUrl}",
   "license": "MIT",
+  "authors": [
+    { "name": "Voxgig", "homepage": "https://voxgig.com" }
+  ],
+  "support": {
+    "issues": "${issuesUrl}",
+    "source": "${repoUrl}"
+  },
   "minimum-stability": "stable",
   "require": {
     "php": ">=8.2"`)
@@ -47,14 +61,11 @@ const Package = cmp(async function Package(props: any) {
     "phpunit/phpunit": "^11.0"
   },
   "autoload": {
-    "psr-4": {
-      "${model.const.Name}\\\\": "src/"
-    }
+    "files": ["${model.const.Name.toLowerCase()}_sdk.php"],
+    "classmap": ["core/", "entity/", "feature/", "types/", "utility/", "config.php", "features.php"]
   },
   "autoload-dev": {
-    "psr-4": {
-      "${model.const.Name}\\\\Tests\\\\": "test/"
-    }
+    "classmap": ["test/"]
   }
 }
 `)

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,6 +7,19 @@ import {
 } from '@voxgig/apidef'
 
 
+// A type-correct, executable PHP literal for a param: numeric/boolean/array
+// params render a typed literal; strings render the quoted placeholder (the
+// doc test EXECUTES runnable blocks, so a comment placeholder would not
+// parse).
+function phpLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '1'
+  if ('BOOLEAN' === k) return 'true'
+  if ('ARRAY' === k || 'OBJECT' === k) return '[]'
+  return `"${placeholder}"`
+}
+
+
 // Operation method spelling differs between Go and other languages — Go
 // uses PascalCase methods with explicit ctrl arg, others use lowercase
 // methods with optional ctrl. The op descriptions are language-agnostic.
@@ -41,6 +54,8 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
   publishedEntities.map((entity: any) => {
     const opnames = Object.keys(entity.op || {})
     const fields = entity.fields || []
+    // Model-driven id key: null when this entity has no id-like field.
+    const idF = entityIdField(entity)
 
     Content(`
 ### ${entity.Name}
@@ -53,7 +68,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    Content(`Create an instance: \`const ${entity.name} = client.${entity.Name}()\`
+    Content(`Create an instance: \`$${entity.name} = $client->${entity.Name}();\`
 
 `)
 
@@ -84,7 +99,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
       each(fields, (field: any) => {
         const desc = field.short || ''
-        Content(`| \`${field.name}\` | \`${field.type || 'any'}\` | ${desc} |
+        Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${desc} |
 `)
       })
 
@@ -93,10 +108,23 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
     }
 
     if (opnames.includes('load')) {
+      // The id key plus every REQUIRED match key (parent path params like
+      // page_id) — the same shape the runtime resolves path params from, so
+      // the example always works.
+      const loadItems = opRequestShape(entity, 'load').items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const loadArg = 0 < loadItems.length
+        ? `[${loadItems.map((it: any) =>
+          `"${it.name}" => ${phpLit(it.type,
+            it.name === idF ? entity.name + '_id' : it.name)}`).join(', ')}]`
+        : ''
       Content(`#### Example: Load
 
-\`\`\`ts
-const ${entity.name} = await client.${entity.Name}().load({ id: '${entity.name}_id' })
+\`\`\`php
+// load() returns the bare ${entity.Name} record (throws on error).
+$${entity.name} = $client->${entity.Name}()->load(${loadArg});
 \`\`\`
 
 `)
@@ -105,26 +133,30 @@ const ${entity.name} = await client.${entity.Name}().load({ id: '${entity.name}_
     if (opnames.includes('list')) {
       Content(`#### Example: List
 
-\`\`\`ts
-const ${entity.name}s = await client.${entity.Name}().list()
+\`\`\`php
+// list() returns an array of ${entity.Name} records (throws on error).
+$${entity.name}s = $client->${entity.Name}()->list();
 \`\`\`
 
 `)
     }
 
     if (opnames.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.
+      const createItems = opRequestShape(entity, 'create').items
+        .filter((it: any) => !it.optional)
       Content(`#### Example: Create
 
-\`\`\`ts
-const ${entity.name} = await client.${entity.Name}().create({
+\`\`\`php
+$${entity.name} = $client->${entity.Name}()->create([
 `)
-      each(fields, (field: any) => {
-        if ('id' !== field.name && field.req) {
-          Content(`  ${field.name}: /* ${field.type || 'value'} */,
+      createItems.map((it: any) => {
+        Content(`    "${it.name}" => null, // ${canonToType(it.type, target.name)}
 `)
-        }
       })
-      Content(`})
+      Content(`]);
 \`\`\`
 
 `)