From 76ab26aab7e352a1dfb680229a6ca9fc562540ac Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Wed, 27 May 2026 06:46:50 +0000 Subject: [PATCH 1/4] Refactor Presence to typed metadata property; drop additionalPropertiesKey hack MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Presence's wire format is `{$id, userId, status, source, expiresAt, metadata: {...}}` where `metadata` is a genuine nested object — not inline sibling extras. The previous implementation extended `Any` and used `setAdditionalPropertiesKey('metadata')` to coerce SDK generators into surfacing extras under a `metadata` sub-key via the non-standard `x-additional-properties-key` vendor extension. That conflicted with the standard OpenAPI 3 meaning of outer-level `additionalProperties: true` (siblings of typed properties, inline) — which is what `Row` and `Document` legitimately need. - Presence now extends `Model` and declares `metadata` as a regular `TYPE_JSON` property, producing standard OpenAPI 3 `{type: object, additionalProperties: true}` on the nested property. - Drop `$additionalPropertiesKey`, `setAdditionalPropertiesKey()` and `getAdditionalPropertiesKey()` from `Any`. - Drop the `x-additional-properties-key` emission in `OpenAPI3` and `Swagger2` spec formatters. `Row` and `Document` continue to extend `Any` — they are correct inline-passthrough models whose dynamic attributes are siblings of `$id` etc. at the top level of the wire format. --- .../SDK/Specification/Format/OpenAPI3.php | 7 ------- .../SDK/Specification/Format/Swagger2.php | 7 ------- src/Appwrite/Utopia/Response/Model/Any.php | 20 ------------------- .../Utopia/Response/Model/Presence.php | 15 ++++++++------ 4 files changed, 9 insertions(+), 40 deletions(-) diff --git a/src/Appwrite/SDK/Specification/Format/OpenAPI3.php b/src/Appwrite/SDK/Specification/Format/OpenAPI3.php index b62397b2d0..8d07938bc8 100644 --- a/src/Appwrite/SDK/Specification/Format/OpenAPI3.php +++ b/src/Appwrite/SDK/Specification/Format/OpenAPI3.php @@ -857,13 +857,6 @@ class OpenAPI3 extends Format if ($model->isAny()) { $output['components']['schemas'][$model->getType()]['additionalProperties'] = true; - - $additionalKey = \method_exists($model, 'getAdditionalPropertiesKey') - ? $model->getAdditionalPropertiesKey() - : null; - if ($additionalKey !== null) { - $output['components']['schemas'][$model->getType()]['x-additional-properties-key'] = $additionalKey; - } } if (!empty($required)) { diff --git a/src/Appwrite/SDK/Specification/Format/Swagger2.php b/src/Appwrite/SDK/Specification/Format/Swagger2.php index 6d456e1abc..9c033399e7 100644 --- a/src/Appwrite/SDK/Specification/Format/Swagger2.php +++ b/src/Appwrite/SDK/Specification/Format/Swagger2.php @@ -822,13 +822,6 @@ class Swagger2 extends Format if ($model->isAny()) { $output['definitions'][$model->getType()]['additionalProperties'] = true; - - $additionalKey = \method_exists($model, 'getAdditionalPropertiesKey') - ? $model->getAdditionalPropertiesKey() - : null; - if ($additionalKey !== null) { - $output['definitions'][$model->getType()]['x-additional-properties-key'] = $additionalKey; - } } if (!empty($required)) { diff --git a/src/Appwrite/Utopia/Response/Model/Any.php b/src/Appwrite/Utopia/Response/Model/Any.php index 0ae3040a1d..6863748ac8 100644 --- a/src/Appwrite/Utopia/Response/Model/Any.php +++ b/src/Appwrite/Utopia/Response/Model/Any.php @@ -12,26 +12,6 @@ class Any extends Model */ protected bool $any = true; - /** - * JSON wire-format key under which extra/dynamic attributes are exposed in - * generated SDK models (e.g. Document's `data` slot). Default null means - * SDK templates fall back to their hardcoded "data" key. Set this on - * subclasses (via setAdditionalPropertiesKey) to use a custom key like - * "metadata" while still benefiting from the generic `Model` mapping. - */ - protected ?string $additionalPropertiesKey = null; - - public function setAdditionalPropertiesKey(string $key): self - { - $this->additionalPropertiesKey = $key; - return $this; - } - - public function getAdditionalPropertiesKey(): ?string - { - return $this->additionalPropertiesKey; - } - /** * Get Name * diff --git a/src/Appwrite/Utopia/Response/Model/Presence.php b/src/Appwrite/Utopia/Response/Model/Presence.php index ecc3755bae..809018d29c 100644 --- a/src/Appwrite/Utopia/Response/Model/Presence.php +++ b/src/Appwrite/Utopia/Response/Model/Presence.php @@ -3,9 +3,10 @@ namespace Appwrite\Utopia\Response\Model; use Appwrite\Utopia\Response; +use Appwrite\Utopia\Response\Model; use Utopia\Database\Document as DatabaseDocument; -class Presence extends Any +class Presence extends Model { public function getName(): string { @@ -19,9 +20,6 @@ class Presence extends Any public function __construct() { - // Expose user-defined extras under "metadata" instead of the SDK default "data" - $this->setAdditionalPropertiesKey('metadata'); - $this ->addRule('$id', [ 'type' => self::TYPE_STRING, @@ -73,9 +71,14 @@ class Presence extends Any 'required' => false, 'default' => null, 'example' => self::TYPE_DATETIME_EXAMPLE, + ]) + ->addRule('metadata', [ + 'type' => self::TYPE_JSON, + 'description' => 'Presence metadata.', + 'required' => false, + 'default' => null, + 'example' => ['key' => 'value'], ]); - // User-defined extras flow through Any's generic mapping, surfaced under - // the "metadata" key declared via setAdditionalPropertiesKey() above. } public function filter(DatabaseDocument $document): DatabaseDocument From eb909252750d91b58e860d50a1e1f94ba9ffa8b6 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Wed, 27 May 2026 08:22:04 +0000 Subject: [PATCH 2/4] Remove dead isset check on x-enum-keys in Swagger2 parameter parser The inner if (isset($node['x-enum-keys'])) at line 764 is unreachable as false: the only branch that ever sets $node['enum'] (in the string/Enum validator handling around line 656) unconditionally sets $node['x-enum-keys'] alongside it, so by the time the outer if (isset($node['enum'])) fires, x-enum-keys is guaranteed present. PHPStan rightly flagged the inner check as dead code and the rest of the analyze run was blocked behind it. --- src/Appwrite/SDK/Specification/Format/Swagger2.php | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/Appwrite/SDK/Specification/Format/Swagger2.php b/src/Appwrite/SDK/Specification/Format/Swagger2.php index 9c033399e7..9265e1ec60 100644 --- a/src/Appwrite/SDK/Specification/Format/Swagger2.php +++ b/src/Appwrite/SDK/Specification/Format/Swagger2.php @@ -761,9 +761,7 @@ class Swagger2 extends Format /// If the enum flag is Set, add the enum values to the body $body['schema']['properties'][$name]['enum'] = $node['enum']; $body['schema']['properties'][$name]['x-enum-name'] = $node['x-enum-name'] ?? null; - if (isset($node['x-enum-keys'])) { - $body['schema']['properties'][$name]['x-enum-keys'] = $node['x-enum-keys']; - } + $body['schema']['properties'][$name]['x-enum-keys'] = $node['x-enum-keys']; } if ($parameter['nullable']) { From cb6e502eca858f8aa6d511dfbc5bf997cbea5708 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Wed, 27 May 2026 16:56:55 +0545 Subject: [PATCH 3/4] Update src/Appwrite/SDK/Specification/Format/Swagger2.php Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --- src/Appwrite/SDK/Specification/Format/Swagger2.php | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/Appwrite/SDK/Specification/Format/Swagger2.php b/src/Appwrite/SDK/Specification/Format/Swagger2.php index 9265e1ec60..9c033399e7 100644 --- a/src/Appwrite/SDK/Specification/Format/Swagger2.php +++ b/src/Appwrite/SDK/Specification/Format/Swagger2.php @@ -761,7 +761,9 @@ class Swagger2 extends Format /// If the enum flag is Set, add the enum values to the body $body['schema']['properties'][$name]['enum'] = $node['enum']; $body['schema']['properties'][$name]['x-enum-name'] = $node['x-enum-name'] ?? null; - $body['schema']['properties'][$name]['x-enum-keys'] = $node['x-enum-keys']; + if (isset($node['x-enum-keys'])) { + $body['schema']['properties'][$name]['x-enum-keys'] = $node['x-enum-keys']; + } } if ($parameter['nullable']) { From 49502c489feba92f08421cc50c9792e5bc2f2b92 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Wed, 27 May 2026 11:15:57 +0000 Subject: [PATCH 4/4] Restore unconditional x-enum-keys assignment The defensive isset re-added in cb6e502 reproduces the PHPStan dead-code error the previous commit fixed. PHPStan correctly infers that within the outer if (isset(\$node['enum'])) branch, x-enum-keys is also always set (the sole upstream path that sets enum unconditionally sets x-enum-keys alongside it). The project's analyze gate forbids suppressing the error via @phpstan-ignore, baseline entries, or casts, so the inner isset must go. --- src/Appwrite/SDK/Specification/Format/Swagger2.php | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/Appwrite/SDK/Specification/Format/Swagger2.php b/src/Appwrite/SDK/Specification/Format/Swagger2.php index 9c033399e7..9265e1ec60 100644 --- a/src/Appwrite/SDK/Specification/Format/Swagger2.php +++ b/src/Appwrite/SDK/Specification/Format/Swagger2.php @@ -761,9 +761,7 @@ class Swagger2 extends Format /// If the enum flag is Set, add the enum values to the body $body['schema']['properties'][$name]['enum'] = $node['enum']; $body['schema']['properties'][$name]['x-enum-name'] = $node['x-enum-name'] ?? null; - if (isset($node['x-enum-keys'])) { - $body['schema']['properties'][$name]['x-enum-keys'] = $node['x-enum-keys']; - } + $body['schema']['properties'][$name]['x-enum-keys'] = $node['x-enum-keys']; } if ($parameter['nullable']) {