@voxgig/sdkgen 0.35.2 → 0.37.0

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

@@ -0,0 +1,62 @@
+
+import * as Path from 'node:path'
+
+import {
+  cmp, each, camelify, names,
+  File, Content, Folder, Fragment, Line, FeatureHook, Slot
+} from '@voxgig/sdkgen'
+
+import { EntityOperation } from './EntityOperation_php'
+
+
+const Entity = cmp(function Entity(props: any) {
+  const { model, stdrep } = props.ctx$
+  const { target, entity } = props
+
+  const entrep = {
+    ...stdrep,
+  }
+
+  names(entrep, entity.Name, 'EntityName')
+
+  const ff = Path.normalize(__dirname + '/../../../src/cmp/php/fragment/')
+
+  // Entity files go to entity/ folder
+  Folder({ name: 'entity' }, () => {
+
+    File({ name: entity.name + '_entity.' + target.ext }, () => {
+
+      const opnames = Object.keys(entity.op)
+
+      const opfrags =
+        (['load', 'list', 'create', 'update', 'remove']
+          .reduce((a: any, opname: string) =>
+          (a['// #' + camelify(opname) + 'Op'] =
+            !opnames.includes(opname) ? '' : ({ indent }: any) => {
+              EntityOperation({ ff, opname, indent, entity, entrep })
+            }, a), {}))
+
+      Fragment({
+        from: ff + 'Entity.fragment.php',
+        replace: {
+          ...entrep,
+          ProjectName: model.const.Name,
+          EntityName: entity.Name,
+          entityname: entity.name,
+
+          '#Entity-Hook': ({ name, indent }: any) =>
+            Content({ indent }, `($utility->feature_hook)($ctx, "${name}");`),
+
+          ...opfrags,
+        }
+      })
+
+    })
+  })
+})
+
+
+
+export {
+  Entity
+}

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

@@ -0,0 +1,24 @@
+
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const MainEntity = cmp(async function MainEntity(props: any) {
+  const { entity } = props
+  const { model } = props.ctx$
+
+  Content(`
+    public function ${entity.Name}($data = null)
+    {
+        require_once __DIR__ . '/entity/${entity.name}_entity.php';
+        return new ${entity.Name}Entity($this, $data);
+    }
+
+`)
+
+})
+
+
+export {
+  MainEntity
+}

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

@@ -0,0 +1,135 @@
+
+import * as Path from 'node:path'
+
+import {
+  cmp, each, names, cmap,
+  List, File, Content, Copy, Folder, Fragment, Line, FeatureHook,
+} from '@voxgig/sdkgen'
+
+
+import type {
+  ModelEntity
+} from '@voxgig/apidef'
+
+
+import {
+  KIT,
+  getModelPath
+} from '@voxgig/apidef'
+
+
+import { Package } from './Package_php'
+import { Config } from './Config_php'
+import { MainEntity } from './MainEntity_php'
+
+
+const Main = cmp(async function Main(props: any) {
+
+  const { target } = props
+  const { model } = props.ctx$
+
+  const entity: ModelEntity = getModelPath(model, `main.${KIT}.entity`)
+  const feature = getModelPath(model, `main.${KIT}.feature`)
+
+  Package({ target })
+
+  // Copy tm/php files with replacements
+  Copy({
+    from: 'tm/' + target.name,
+    exclude: [/src\//],
+    replace: {
+      ...props.ctx$.stdrep,
+    }
+  })
+
+  // Generate main SDK file
+  File({ name: model.name + '_sdk.' + target.ext }, () => {
+
+    Fragment(
+      {
+        from: Path.normalize(__dirname + '/../../../src/cmp/php/fragment/Main.fragment.php'),
+        replace: {
+          ...props.ctx$.stdrep,
+
+          '#BuildFeatures': ({ indent }: any) => {
+            each(feature, (feat: any) => {
+              const fname = feat.name.charAt(0).toUpperCase() + feat.name.slice(1)
+              Content({ indent }, `  // feature: ${feat.name}
+`)
+            })
+          },
+
+          '#Feature-Hook': ({ name, indent }: any) => Content({ indent }, `
+($utility->feature_hook)($this->_rootctx, "${name}");
+`),
+
+        }
+      },
+
+      // Entities - injected at SLOT
+      () => {
+        each(entity, (entity: ModelEntity) => {
+          const entitySDK = getModelPath(model, `main.${KIT}.entity.${entity.name}`)
+          const entprops = { target, entity, entitySDK }
+          MainEntity(entprops)
+        })
+      })
+  })
+
+  // Generate config module
+  Folder({ name: '.' }, () => {
+    Config({ target })
+  })
+
+  // Generate feature factory module
+  File({ name: 'features.' + target.ext }, () => {
+    Content(`<?php
+declare(strict_types=1);
+
+// ${model.const.Name} SDK feature factory
+
+require_once __DIR__ . '/feature/BaseFeature.php';
+`)
+
+    each(feature, (feat: any) => {
+      if (feat.name !== 'base') {
+        const fname = feat.name.charAt(0).toUpperCase() + feat.name.slice(1)
+        Content(`require_once __DIR__ . '/feature/${fname}Feature.php';
+`)
+      }
+    })
+
+    Content(`
+
+class ${model.const.Name}Features
+{
+    public static function make_feature(string $name)
+    {
+        switch ($name) {
+            case "base":
+                return new ${model.const.Name}BaseFeature();
+`)
+
+    each(feature, (feat: any) => {
+      if (feat.name !== 'base') {
+        const fname = feat.name.charAt(0).toUpperCase() + feat.name.slice(1)
+        Content(`            case "${feat.name}":
+                return new ${model.const.Name}${fname}Feature();
+`)
+      }
+    })
+
+    Content(`            default:
+                return new ${model.const.Name}BaseFeature();
+        }
+    }
+}
+`)
+  })
+
+})
+
+
+export {
+  Main
+}

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

@@ -0,0 +1,87 @@
+
+import {
+  Content,
+  File,
+  cmp,
+  each,
+} from '@voxgig/sdkgen'
+
+
+import {
+  KIT,
+  Model,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+const Package = cmp(async function Package(props: any) {
+  const ctx$ = props.ctx$
+  const target = props.target
+
+  const model: Model = ctx$.model
+
+  const feature = getModelPath(model, `main.${KIT}.feature`)
+
+  // Generate composer.json
+  File({ name: 'composer.json' }, () => {
+    Content(`{
+  "name": "voxgig/${model.name}-sdk",
+  "description": "${model.const.Name} SDK for PHP",
+  "type": "library",
+  "license": "MIT",
+  "minimum-stability": "stable",
+  "require": {
+    "php": ">=8.1"`)
+
+    // Collect dependencies from features
+    const deps: { name: string, version: string }[] = []
+    each(feature, (f: any) => {
+      const phpDeps = f.deps?.php
+      if (phpDeps) {
+        each(phpDeps, (dep: any) => {
+          if (dep.active) {
+            deps.push({ name: dep.key$, version: dep.version })
+          }
+        })
+      }
+    })
+
+    // Add target-level deps
+    const targetDeps = target.deps
+    if (targetDeps) {
+      each(targetDeps, (dep: any) => {
+        if (dep.active !== false) {
+          deps.push({ name: dep.key$, version: dep.version || '0.0' })
+        }
+      })
+    }
+
+    for (const dep of deps) {
+      Content(`,
+    "${dep.name}": "^${dep.version}"`)
+    }
+
+    Content(`
+  },
+  "require-dev": {
+    "phpunit/phpunit": "^10.0"
+  },
+  "autoload": {
+    "psr-4": {
+      "${model.const.Name}\\\\": "src/"
+    }
+  },
+  "autoload-dev": {
+    "psr-4": {
+      "${model.const.Name}\\\\Tests\\\\": "test/"
+    }
+  }
+}
+`)
+  })
+})
+
+
+export {
+  Package
+}

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

@@ -0,0 +1,42 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
+  const { target, ctx$: { model } } = props
+
+  Content(`### Data as arrays
+
+The PHP SDK uses plain PHP associative arrays throughout rather than typed
+objects. This mirrors the dynamic nature of the API and keeps the
+SDK flexible — no code generation is needed when the API schema
+changes.
+
+Use \`Helpers::to_map()\` to safely validate that a value is an array.
+
+### Directory structure
+
+\`\`\`
+php/
+├── ${model.name}_sdk.php          -- Main SDK class
+├── config.php                     -- Configuration
+├── features.php                   -- Feature factory
+├── core/                          -- Core types and context
+├── entity/                        -- Entity implementations
+├── feature/                       -- Built-in features (Base, Test, Log)
+├── utility/                       -- Utility functions and struct library
+└── test/                          -- Test suites
+\`\`\`
+
+The main class (\`${model.name}_sdk.php\`) exports the SDK class
+and test helper. Import entity or utility modules directly only
+when needed.
+
+`)
+
+})
+
+
+export {
+  ReadmeExplanation
+}

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

@@ -0,0 +1,101 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
+  const { target, ctx$: { model } } = props
+
+  Content(`### Make a direct HTTP request
+
+For endpoints not covered by entity methods:
+
+\`\`\`php
+[$result, $err] = $client->direct([
+    "path" => "/api/resource/{id}",
+    "method" => "GET",
+    "params" => ["id" => "example"],
+]);
+if ($err) { throw new \\Exception($err); }
+
+if ($result["ok"]) {
+    echo $result["status"];  // 200
+    print_r($result["data"]);  // response body
+}
+\`\`\`
+
+### Prepare a request without sending it
+
+\`\`\`php
+[$fetchdef, $err] = $client->prepare([
+    "path" => "/api/resource/{id}",
+    "method" => "DELETE",
+    "params" => ["id" => "example"],
+]);
+if ($err) { throw new \\Exception($err); }
+
+echo $fetchdef["url"];
+echo $fetchdef["method"];
+print_r($fetchdef["headers"]);
+\`\`\`
+
+### Use test mode
+
+Create a mock client for unit testing — no server required:
+
+\`\`\`php
+$client = ${model.const.Name}SDK::test(null, null);
+
+[$result, $err] = $client->${model.const.Name}(null)->load(
+    ["id" => "test01"], null
+);
+// $result contains mock response data
+\`\`\`
+
+### Use a custom fetch function
+
+Replace the HTTP transport with your own function:
+
+\`\`\`php
+$mock_fetch = function ($url, $init) {
+    return [
+        [
+            "status" => 200,
+            "statusText" => "OK",
+            "headers" => [],
+            "json" => function () { return ["id" => "mock01"]; },
+        ],
+        null,
+    ];
+};
+
+$client = new ${model.const.Name}SDK([
+    "base" => "http://localhost:8080",
+    "system" => [
+        "fetch" => $mock_fetch,
+    ],
+]);
+\`\`\`
+
+### Run live tests
+
+Create a \`.env.local\` file at the project root:
+
+\`\`\`
+${model.NAME}_TEST_LIVE=TRUE
+${model.NAME}_APIKEY=<your-key>
+\`\`\`
+
+Then run:
+
+\`\`\`bash
+cd php && ./vendor/bin/phpunit test/
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeHowto
+}

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

@@ -0,0 +1,19 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeInstall = cmp(function ReadmeInstall(props: any) {
+  const { target, ctx$ } = props
+  const { model } = ctx$
+
+  Content(`\`\`\`bash
+composer require voxgig/${model.name}-sdk
+\`\`\`
+
+`)
+})
+
+
+export {
+  ReadmeInstall
+}

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

@@ -0,0 +1,129 @@
+
+import { cmp, each, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+const ReadmeModel = cmp(function ReadmeModel(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const entityList = each(entity).filter((e: any) => e.active !== false)
+
+  Content(`### ${model.const.Name}SDK
+
+\`\`\`php
+require_once '${model.name}_sdk.php';
+$client = new ${model.const.Name}SDK($options);
+\`\`\`
+
+Creates a new SDK client.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| \`apikey\` | \`string\` | API key for authentication. |
+| \`base\` | \`string\` | Base URL of the API server. |
+| \`prefix\` | \`string\` | URL path prefix prepended to all requests. |
+| \`suffix\` | \`string\` | URL path suffix appended to all requests. |
+| \`feature\` | \`array\` | Feature activation flags. |
+| \`extend\` | \`array\` | Additional Feature instances to load. |
+| \`system\` | \`array\` | System overrides (e.g. custom \`fetch\` callable). |
+
+### test
+
+\`\`\`php
+$client = ${model.const.Name}SDK::test($testopts, $sdkopts);
+\`\`\`
+
+Creates a test-mode client with mock transport. Both arguments may be \`null\`.
+
+### ${model.const.Name}SDK methods
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| \`options_map\` | \`(): array\` | Deep copy of current SDK options. |
+| \`get_utility\` | \`(): Utility\` | Copy of the SDK utility object. |
+| \`prepare\` | \`(array $fetchargs): array\` | Build an HTTP request definition without sending. |
+| \`direct\` | \`(array $fetchargs): array\` | Build and send an HTTP request. |
+`)
+
+  each(entityList, (ent: any) => {
+    Content(`| \`${ent.Name}\` | \`($data): ${ent.Name}Entity\` | Create a ${ent.Name} entity instance. |
+`)
+  })
+
+  Content(`
+### Entity interface
+
+All entities share the same interface.
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| \`load\` | \`($reqmatch, $ctrl): array\` | Load a single entity by match criteria. |
+| \`list\` | \`($reqmatch, $ctrl): array\` | List entities matching the criteria. |
+| \`create\` | \`($reqdata, $ctrl): array\` | Create a new entity. |
+| \`update\` | \`($reqdata, $ctrl): array\` | Update an existing entity. |
+| \`remove\` | \`($reqmatch, $ctrl): array\` | Remove an entity. |
+| \`data_get\` | \`(): array\` | Get entity data. |
+| \`data_set\` | \`($data): void\` | Set entity data. |
+| \`match_get\` | \`(): array\` | Get entity match criteria. |
+| \`match_set\` | \`($match): void\` | Set entity match criteria. |
+| \`make\` | \`(): Entity\` | Create a new instance with the same options. |
+| \`get_name\` | \`(): string\` | Return the entity name. |
+
+### Result shape
+
+Entity operations return \`[$result, $err]\`. The first value is an
+\`array\` with these keys:
+
+| Key | Type | Description |
+| --- | --- | --- |
+| \`ok\` | \`bool\` | \`true\` if the HTTP status is 2xx. |
+| \`status\` | \`int\` | HTTP status code. |
+| \`headers\` | \`array\` | Response headers. |
+| \`data\` | \`mixed\` | Parsed JSON response body. |
+
+On error, \`ok\` is \`false\` and \`$err\` contains the error value.
+
+`)
+
+  // Entities summary
+  Content(`### Entities
+
+`)
+  each(entityList, (ent: any) => {
+    const fields = ent.fields || []
+    const opnames = Object.keys(ent.op || {})
+    const ops = ent.op || {}
+    const points = each(ops).map((op: any) =>
+      op.points ? each(op.points) : []
+    ).flat()
+    const path = points.length > 0 ? (points[0] as any).orig || '' : ''
+
+    Content(`#### ${ent.Name}
+
+| Field | Description |
+| --- | --- |
+`)
+    each(fields, (field: any) => {
+      Content(`| \`${field.name}\` | ${field.short || ''} |
+`)
+    })
+
+    Content(`
+Operations: ${opnames.map((n: string) => n.charAt(0).toUpperCase() + n.slice(1)).join(', ')}.
+
+API path: \`${path}\`
+
+`)
+  })
+
+})
+
+
+export {
+  ReadmeModel
+}

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

@@ -0,0 +1,100 @@
+
+import { cmp, each, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+
+const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+  const nestedEntity = Object.values(entity).find((e: any) =>
+    e.active !== false && e.ancestors && e.ancestors.length > 0
+  ) as any
+
+  Content(`### 1. Create a client
+
+\`\`\`php
+<?php
+require_once '${model.name}_sdk.php';
+
+$client = new ${model.const.Name}SDK([
+    "apikey" => getenv("${model.NAME}_APIKEY"),
+]);
+\`\`\`
+
+`)
+
+  if (exampleEntity) {
+    const eName = nom(exampleEntity, 'Name')
+    const opnames = Object.keys(exampleEntity.op || {})
+
+    if (opnames.includes('list')) {
+      Content(`### 2. List ${eName.toLowerCase()}s
+
+\`\`\`php
+[$result, $err] = $client->${eName}(null)->list(null, null);
+if ($err) { throw new \\Exception($err); }
+
+if (is_array($result)) {
+    foreach ($result as $item) {
+        $d = $item->data_get();
+        echo $d["id"] . " " . $d["name"] . "\\n";
+    }
+}
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('load')) {
+      Content(`### 3. Load a ${eName.toLowerCase()}
+
+\`\`\`php
+[$result, $err] = $client->${eName}(null)->load(["id" => "example_id"], null);
+if ($err) { throw new \\Exception($err); }
+print_r($result);
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {
+      Content(`### 4. Create, update, and remove
+
+\`\`\`php
+`)
+      if (opnames.includes('create')) {
+        Content(`// Create
+[$created, $_] = $client->${eName}(null)->create(["name" => "Example"], null);
+
+`)
+      }
+      if (opnames.includes('update')) {
+        Content(`// Update
+$client->${eName}(null)->update(["id" => $created["id"], "name" => "Example-Renamed"], null);
+
+`)
+      }
+      if (opnames.includes('remove')) {
+        Content(`// Remove
+$client->${eName}(null)->remove(["id" => $created["id"]], null);
+`)
+      }
+      Content(`\`\`\`
+
+`)
+    }
+  }
+})
+
+
+export {
+  ReadmeQuick
+}