@kirigami/php-prepros 1.9.3 → 3.0.0

package/src/libraries/schema.class.php

@@ -3,39 +3,44 @@
 declare(strict_types=1);
 
 /**
- * SchemaValidator
+ * SCHEMA — JSON Schema validator backed by the native `jsonk` extension
+ * (statically built into @kirigami/php-wasm — see php-kirigami/php-jsonk),
+ * with an Ajv-like API.
  *
- * A pure PHP JSON Schema validator (Draft 7 style, similar to Ajv),
- * with no external dependencies.
+ * jsonk targets draft 2020-12 and takes JSON strings, so this class encodes
+ * the PHP schema and data first. The encoding step keeps the schemas written
+ * for the previous pure-PHP validator working:
+ *   - an empty PHP array in a schema position (`'properties' => []`, a `[]`
+ *     sub-schema) becomes `{}` instead of JSON `[]`;
+ *   - draft-07 tuple `items` (a list of schemas) becomes `prefixItems`, and
+ *     `additionalItems` becomes `items`;
+ *   - `format: url` becomes `format: uri`.
  *
- * Usage example:
+ * Errors keep the previous `"path: message"` string format, with paths such
+ * as `(root)`, `name` or `tags[1]`.
  *
- *   $schema = [
- *       'type' => 'object',
- *       'required' => ['name', 'age'],
- *       'properties' => [
- *           'name' => ['type' => 'string', 'minLength' => 1],
- *           'age'  => ['type' => 'integer', 'minimum' => 0],
- *           'tags' => ['type' => 'array', 'items' => ['type' => 'string']],
- *       ],
- *       'additionalProperties' => false,
- *   ];
+ * Kept the old implementation as SCHEMA_LEGACY (schema-legacy.class.php) —
+ * untouched, still autoloadable — as a rollback path.
  *
- *   $validator = new SchemaValidator($schema);
- *
- *   if (!$validator->isValid(['name' => 'Alice', 'age' => 30])) {
- *       foreach ($validator->getErrors() as $error) {
- *           echo $error, PHP_EOL;
- *       }
- *   }
+ * Usage:
+ *   $validator = new SCHEMA(['type' => 'object', 'required' => ['name']]);
+ *   if (!$validator->isValid($data)) print_r($validator->getErrors());
  */
 final class SCHEMA
 {
-    /** @var array<string,mixed> Schema used as the entry point of isValid(). */
-    private array $rootSchema;
+    /** Keywords whose value is a single sub-schema. */
+    private const SUBSCHEMA = [
+        'additionalItems', 'additionalProperties', 'contains', 'else', 'if', 'items',
+        'not', 'propertyNames', 'then', 'unevaluatedItems', 'unevaluatedProperties',
+    ];
+
+    /** Keywords whose value is a list of sub-schemas. */
+    private const SUBSCHEMA_LIST = ['allOf', 'anyOf', 'oneOf', 'prefixItems'];
+
+    /** Keywords whose value maps names to sub-schemas. */
+    private const SUBSCHEMA_MAP = ['$defs', 'definitions', 'dependentSchemas', 'patternProperties', 'properties'];
 
-    /** @var array<string,mixed> Root document used to resolve local $ref pointers. */
-    private array $refRoot;
+    private string $schemaJson;
 
     /** @var string[] */
     private array $errors = [];
@@ -45,506 +50,128 @@ final class SCHEMA
      */
     public function __construct(array $schema)
     {
-        $this->rootSchema = $schema;
-        $this->refRoot = $schema;
+        if (!function_exists('jsonk_validate')) {
+            throw new RuntimeException('SCHEMA requires the jsonk extension; use SCHEMA_LEGACY without it.');
+        }
+        $this->schemaJson = json_encode(self::normalize($schema), JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
     }
 
     /**
      * Validates data. Returns true/false, like Ajv's `validate()`.
      * Errors are available via getErrors().
-     *
-     * @param mixed $data
      */
     public function isValid(mixed $data): bool
     {
         $this->errors = [];
-        $this->validateAgainst($data, $this->rootSchema, '');
-
-        return count($this->errors) === 0;
-    }
-
-    /**
-     * Alias closer to Ajv's semantics (validate($data)).
-     */
-    public function validate(mixed $data): bool
-    {
-        return $this->isValid($data);
-    }
-
-    /**
-     * @return string[] List of error messages (path: message).
-     */
-    public function getErrors(): array
-    {
-        return $this->errors;
-    }
 
-    private function addError(string $path, string $message): void
-    {
-        $p = $path === '' ? '(root)' : $path;
-        $this->errors[] = "{$p}: {$message}";
-    }
-
-    /**
-     * @param mixed                $data
-     * @param array<string,mixed>  $schema
-     */
-    private function validateAgainst(mixed $data, array $schema, string $path): void
-    {
-        // Local $ref (#/definitions/xxx or #/$defs/xxx)
-        if (isset($schema['$ref'])) {
-            $resolved = $this->resolveRef((string) $schema['$ref']);
-            if ($resolved === null) {
-                $this->addError($path, "reference not found: {$schema['$ref']}");
-                return;
-            }
-            $this->validateAgainst($data, $resolved, $path);
-            return;
-        }
-
-        if (isset($schema['const'])) {
-            if (!$this->looseEquals($data, $schema['const'])) {
-                $this->addError($path, 'does not match the expected const value');
-            }
-        }
-
-        if (isset($schema['enum']) && is_array($schema['enum'])) {
-            $found = false;
-            foreach ($schema['enum'] as $candidate) {
-                if ($this->looseEquals($data, $candidate)) {
-                    $found = true;
-                    break;
-                }
-            }
-            if (!$found) {
-                $this->addError($path, 'is not one of the allowed enum values');
-            }
-        }
-
-        if (isset($schema['type'])) {
-            $this->validateType($data, $schema['type'], $path);
-        }
-
-        $this->validateCombinators($data, $schema, $path);
-
-        $type = $this->detectType($data);
-
-        switch ($type) {
-            case 'string':
-                $this->validateString($data, $schema, $path);
-                break;
-            case 'integer':
-            case 'number':
-                $this->validateNumber($data, $schema, $path);
-                break;
-            case 'array':
-                $this->validateArray($data, $schema, $path);
-                break;
-            case 'object':
-                $this->validateObject($data, $schema, $path);
-                break;
-        }
-    }
-
-    /**
-     * @param array<string,mixed> $schema
-     */
-    private function validateCombinators(mixed $data, array $schema, string $path): void
-    {
-        if (isset($schema['allOf']) && is_array($schema['allOf'])) {
-            foreach ($schema['allOf'] as $sub) {
-                $this->validateAgainst($data, $sub, $path);
-            }
-        }
-
-        if (isset($schema['anyOf']) && is_array($schema['anyOf'])) {
-            $ok = false;
-            foreach ($schema['anyOf'] as $sub) {
-                if ($this->isSubSchemaValid($data, $sub)) {
-                    $ok = true;
-                    break;
-                }
-            }
-            if (!$ok) {
-                $this->addError($path, 'does not satisfy any of the anyOf schemas');
-            }
-        }
-
-        if (isset($schema['oneOf']) && is_array($schema['oneOf'])) {
-            $matches = 0;
-            foreach ($schema['oneOf'] as $sub) {
-                if ($this->isSubSchemaValid($data, $sub)) {
-                    $matches++;
-                }
-            }
-            if ($matches !== 1) {
-                $this->addError($path, "must satisfy exactly one oneOf schema ({$matches} match(es))");
-            }
-        }
-
-        if (isset($schema['not'])) {
-            if ($this->isSubSchemaValid($data, $schema['not'])) {
-                $this->addError($path, 'must not satisfy the "not" schema');
-            }
-        }
-    }
-
-    /**
-     * @param array<string,mixed> $schema
-     */
-    private function isSubSchemaValid(mixed $data, array $schema): bool
-    {
-        $sub = new self($schema);
-        // $ref pointers inside the sub-schema must keep resolving against
-        // the original root document, not against the sub-schema itself.
-        $sub->refRoot = $this->refRoot;
-        return $sub->isValid($data);
-    }
-
-    private function validateType(mixed $data, mixed $expected, string $path): void
-    {
-        $expectedTypes = is_array($expected) ? $expected : [$expected];
-        $actual = $this->detectType($data);
-
-        foreach ($expectedTypes as $t) {
-            if ($t === 'integer' && $actual === 'number' && is_float($data) && floor($data) === $data) {
-                return;
-            }
-            if ($t === $actual) {
-                return;
-            }
-            if ($t === 'number' && $actual === 'integer') {
-                return;
-            }
-        }
-
-        $expectedStr = implode('|', $expectedTypes);
-        $this->addError($path, "invalid type: expected {$expectedStr}, got {$actual}");
-    }
-
-    private function detectType(mixed $data): string
-    {
-        return match (true) {
-            $data === null => 'null',
-            is_bool($data) => 'boolean',
-            is_int($data) => 'integer',
-            is_float($data) => (floor($data) === $data ? 'integer' : 'number'),
-            is_string($data) => 'string',
-            // A JSON array always decodes to a PHP list array, whether or not
-            // json_decode() was called with associative=true.
-            is_array($data) && $this->isList($data) => 'array',
-            // A JSON object decodes to either an associative array
-            // (json_decode(..., true)) or a stdClass (json_decode(..., false)).
-            is_array($data) || is_object($data) => 'object',
-            default => 'unknown',
-        };
-    }
-
-    /**
-     * True for plain PHP list arrays (sequential integer keys from 0).
-     * Objects (stdClass or associative arrays) are never lists.
-     */
-    private function isList(mixed $arr): bool
-    {
-        if (!is_array($arr)) {
+        try {
+            $json = json_encode($data, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
+        } catch (JsonException $e) {
+            $this->errors[] = '(root): value cannot be encoded as JSON: ' . $e->getMessage();
             return false;
         }
-        if ($arr === []) {
+
+        if (jsonk_validate($json, $this->schemaJson)) {
             return true;
         }
-        return array_keys($arr) === range(0, count($arr) - 1);
-    }
-
-    /**
-     * True when $data behaves like a JSON object: either a stdClass
-     * (json_decode(..., false)) or a non-list associative array
-     * (json_decode(..., true)).
-     */
-    private function isObjectLike(mixed $data): bool
-    {
-        return is_object($data) || (is_array($data) && !$this->isList($data));
-    }
 
-    /**
-     * @return string[] Property names of an object-like value, in order.
-     */
-    private function objectKeys(mixed $data): array
-    {
-        if (is_object($data)) {
-            return array_keys(get_object_vars($data));
-        }
-        if (is_array($data)) {
-            return array_map('strval', array_keys($data));
+        $violations = jsonk_get_last_errors();
+        if (!$violations) {
+            // Schema-level failure (unresolvable $ref, invalid keyword value…):
+            // jsonk reports it through its last error message only.
+            $this->errors[] = '(root): ' . jsonk_last_error_msg();
+            return false;
         }
-        return [];
-    }
 
-    private function objectHas(mixed $data, string $key): bool
-    {
-        if (is_object($data)) {
-            return property_exists($data, $key);
-        }
-        if (is_array($data)) {
-            return array_key_exists($key, $data);
+        $decoded = json_decode($json);
+        foreach ($violations as $violation) {
+            $this->errors[] = self::displayPath($violation['path'], $decoded) . ': ' . $violation['message'];
         }
         return false;
     }
 
-    private function objectGet(mixed $data, string $key): mixed
-    {
-        if (is_object($data)) {
-            return $data->{$key};
-        }
-        return $data[$key];
-    }
-
     /**
-     * @param array<string,mixed> $schema
+     * Alias closer to Ajv's semantics (validate($data)).
      */
-    private function validateString(mixed $data, array $schema, string $path): void
-    {
-        if (!is_string($data)) {
-            return;
-        }
-
-        $len = function_exists('mb_strlen') ? mb_strlen($data) : strlen($data);
-
-        if (isset($schema['minLength']) && $len < (int) $schema['minLength']) {
-            $this->addError($path, "minimum length {$schema['minLength']} not met ({$len})");
-        }
-
-        if (isset($schema['maxLength']) && $len > (int) $schema['maxLength']) {
-            $this->addError($path, "maximum length {$schema['maxLength']} exceeded ({$len})");
-        }
-
-        if (isset($schema['pattern'])) {
-            $pattern = '/' . str_replace('/', '\/', (string) $schema['pattern']) . '/u';
-            if (@preg_match($pattern, $data) !== 1) {
-                $this->addError($path, "does not match pattern {$schema['pattern']}");
-            }
-        }
-
-        if (isset($schema['format'])) {
-            $this->validateFormat($data, (string) $schema['format'], $path);
-        }
-    }
-
-    private function validateFormat(string $data, string $format, string $path): void
+    public function validate(mixed $data): bool
     {
-        $ok = match ($format) {
-            'email' => (bool) filter_var($data, FILTER_VALIDATE_EMAIL),
-            'uri', 'url' => (bool) filter_var($data, FILTER_VALIDATE_URL),
-            'date' => (bool) preg_match('/^\d{4}-\d{2}-\d{2}$/', $data)
-                && checkdate((int) substr($data, 5, 2), (int) substr($data, 8, 2), (int) substr($data, 0, 4)),
-            'date-time' => (bool) preg_match(
-                '/^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2}:\d{2})$/',
-                $data
-            ),
-            'ipv4' => (bool) filter_var($data, FILTER_VALIDATE_IP, FILTER_FLAG_IPV4),
-            'ipv6' => (bool) filter_var($data, FILTER_VALIDATE_IP, FILTER_FLAG_IPV6),
-            'uuid' => (bool) preg_match(
-                '/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i',
-                $data
-            ),
-            default => true, // Unknown format: does not block, same as Ajv in non-strict mode.
-        };
-
-        if (!$ok) {
-            $this->addError($path, "invalid format, expected '{$format}'");
-        }
+        return $this->isValid($data);
     }
 
     /**
-     * @param array<string,mixed> $schema
+     * @return string[] List of error messages (path: message).
      */
-    private function validateNumber(mixed $data, array $schema, string $path): void
+    public function getErrors(): array
     {
-        if (!is_int($data) && !is_float($data)) {
-            return;
-        }
-
-        if (isset($schema['minimum']) && $data < $schema['minimum']) {
-            $this->addError($path, "must be >= {$schema['minimum']}");
-        }
-
-        if (isset($schema['maximum']) && $data > $schema['maximum']) {
-            $this->addError($path, "must be <= {$schema['maximum']}");
-        }
-
-        if (isset($schema['exclusiveMinimum']) && $data <= $schema['exclusiveMinimum']) {
-            $this->addError($path, "must be > {$schema['exclusiveMinimum']}");
-        }
-
-        if (isset($schema['exclusiveMaximum']) && $data >= $schema['exclusiveMaximum']) {
-            $this->addError($path, "must be < {$schema['exclusiveMaximum']}");
-        }
-
-        if (isset($schema['multipleOf'])) {
-            $factor = (float) $schema['multipleOf'];
-            if ($factor > 0) {
-                $div = $data / $factor;
-                if (abs($div - round($div)) > 1e-9) {
-                    $this->addError($path, "must be a multiple of {$schema['multipleOf']}");
-                }
-            }
-        }
+        return $this->errors;
     }
 
     /**
-     * @param array<string,mixed> $schema
+     * Prepares a schema node for JSON encoding (see the class comment).
      */
-    private function validateArray(mixed $data, array $schema, string $path): void
+    private static function normalize(mixed $schema): mixed
     {
-        if (!is_array($data) || !$this->isList($data)) {
-            return;
+        if (is_object($schema)) {
+            $schema = get_object_vars($schema);
         }
-
-        $count = count($data);
-
-        if (isset($schema['minItems']) && $count < (int) $schema['minItems']) {
-            $this->addError($path, "must contain at least {$schema['minItems']} item(s)");
-        }
-
-        if (isset($schema['maxItems']) && $count > (int) $schema['maxItems']) {
-            $this->addError($path, "must contain at most {$schema['maxItems']} item(s)");
-        }
-
-        if (($schema['uniqueItems'] ?? false) === true) {
-            $seen = [];
-            foreach ($data as $item) {
-                $key = json_encode($item, JSON_THROW_ON_ERROR);
-                if (isset($seen[$key])) {
-                    $this->addError($path, 'items must be unique');
-                    break;
-                }
-                $seen[$key] = true;
-            }
+        if (!is_array($schema)) {
+            return $schema; // Boolean schema, or an invalid value jsonk reports.
         }
 
-        if (isset($schema['items'])) {
-            $items = $schema['items'];
-
-            if ($this->isList($items) && array_is_list($items)) {
-                // Tuple mode: items is a list of positional schemas.
-                foreach ($data as $i => $item) {
-                    if (isset($items[$i])) {
-                        $this->validateAgainst($item, $items[$i], "{$path}[{$i}]");
-                    } elseif (isset($schema['additionalItems']) && $schema['additionalItems'] === false) {
-                        $this->addError("{$path}[{$i}]", 'additional item not allowed');
-                    }
-                }
-            } else {
-                // Standard mode: a single schema applied to every item.
-                foreach ($data as $i => $item) {
-                    $this->validateAgainst($item, $items, "{$path}[{$i}]");
-                }
+        if (isset($schema['items']) && is_array($schema['items']) && $schema['items'] !== [] && array_is_list($schema['items'])) {
+            $schema['prefixItems'] = $schema['items'];
+            unset($schema['items']);
+            if (array_key_exists('additionalItems', $schema)) {
+                $schema['items'] = $schema['additionalItems'];
+                unset($schema['additionalItems']);
             }
         }
-    }
 
-    /**
-     * @param array<string,mixed> $schema
-     */
-    private function validateObject(mixed $data, array $schema, string $path): void
-    {
-        // Accepts a JSON object regardless of how it was decoded:
-        // associative array (json_decode(..., true)) or stdClass (json_decode(..., false)).
-        if (!$this->isObjectLike($data)) {
-            return;
+        if (($schema['format'] ?? null) === 'url') {
+            $schema['format'] = 'uri';
         }
 
-        $keys = $this->objectKeys($data);
-
-        // required
-        if (isset($schema['required']) && is_array($schema['required'])) {
-            foreach ($schema['required'] as $requiredKey) {
-                if (!$this->objectHas($data, (string) $requiredKey)) {
-                    $this->addError($path, "missing required property: '{$requiredKey}'");
-                }
+        foreach ($schema as $keyword => $value) {
+            if (in_array($keyword, self::SUBSCHEMA, true)) {
+                $schema[$keyword] = self::normalize($value);
+            } elseif (in_array($keyword, self::SUBSCHEMA_LIST, true) && is_array($value)) {
+                $schema[$keyword] = array_map(self::normalize(...), array_values($value));
+            } elseif (in_array($keyword, self::SUBSCHEMA_MAP, true) && (is_array($value) || is_object($value))) {
+                $schema[$keyword] = (object) array_map(self::normalize(...), is_object($value) ? get_object_vars($value) : $value);
+            } elseif ($keyword === 'dependentRequired' && is_array($value)) {
+                $schema[$keyword] = (object) $value;
             }
         }
 
-        $properties = $schema['properties'] ?? [];
-        $patternProperties = $schema['patternProperties'] ?? [];
-        $additional = $schema['additionalProperties'] ?? true;
-
-        foreach ($keys as $key) {
-            $value = $this->objectGet($data, $key);
-            $childPath = $path === '' ? $key : "{$path}.{$key}";
-            $matched = false;
-
-            if (isset($properties[$key])) {
-                $matched = true;
-                $this->validateAgainst($value, $properties[$key], $childPath);
-            }
-
-            foreach ($patternProperties as $pattern => $subSchema) {
-                $regex = '/' . str_replace('/', '\/', (string) $pattern) . '/u';
-                if (@preg_match($regex, $key) === 1) {
-                    $matched = true;
-                    $this->validateAgainst($value, $subSchema, $childPath);
-                }
-            }
-
-            if (!$matched) {
-                if ($additional === false) {
-                    $this->addError($childPath, 'additional property not allowed');
-                } elseif (is_array($additional)) {
-                    $this->validateAgainst($value, $additional, $childPath);
-                }
-            }
-        }
-
-        $count = count($keys);
-
-        if (isset($schema['minProperties']) && $count < (int) $schema['minProperties']) {
-            $this->addError($path, "must have at least {$schema['minProperties']} propert(y/ies)");
-        }
-
-        if (isset($schema['maxProperties']) && $count > (int) $schema['maxProperties']) {
-            $this->addError($path, "must have at most {$schema['maxProperties']} propert(y/ies)");
-        }
+        // An object, even when empty or keyed 0..n.
+        return (object) $schema;
     }
 
     /**
-     * Resolves a local reference such as "#/definitions/foo" or "#/$defs/foo".
-     *
-     * @return array<string,mixed>|null
+     * Converts a jsonk JSON Pointer ("/tags/1") to the previous validator's
+     * path format ("tags[1]"), using the data to tell array indexes from
+     * object keys.
      */
-    private function resolveRef(string $ref): ?array
+    private static function displayPath(string $pointer, mixed $data): string
     {
-        if (!str_starts_with($ref, '#/')) {
-            return null; // External references are not supported.
-        }
+        $path = '';
+        $node = $data;
 
-        $segments = explode('/', substr($ref, 2));
-        $current = $this->refRoot;
-
-        foreach ($segments as $segment) {
-            $segment = str_replace(['~1', '~0'], ['/', '~'], $segment);
-            if (!is_array($current) || !array_key_exists($segment, $current)) {
-                return null;
+        foreach (explode('/', ltrim($pointer, '/')) as $segment) {
+            if ($segment === '') {
+                continue;
             }
-            $current = $current[$segment];
-        }
-
-        return is_array($current) ? $current : null;
-    }
-
-    private function looseEquals(mixed $a, mixed $b): bool
-    {
-        $aStructured = is_array($a) || is_object($a);
-        $bStructured = is_array($b) || is_object($b);
+            $segment = str_replace(['~1', '~0'], ['/', '~'], $segment);
 
-        if ($aStructured && $bStructured) {
-            try {
-                // Compares structural (JSON) equality, so an associative array
-                // and a stdClass with the same content are considered equal.
-                return json_encode($a, JSON_THROW_ON_ERROR) === json_encode($b, JSON_THROW_ON_ERROR);
-            } catch (\JsonException) {
-                return false;
+            if (is_array($node)) {
+                $path .= "[{$segment}]";
+                $node = $node[(int) $segment] ?? null;
+            } else {
+                $path .= $path === '' ? $segment : ".{$segment}";
+                $node = is_object($node) ? ($node->{$segment} ?? null) : null;
             }
         }
-        return $a === $b;
+
+        return $path === '' ? '(root)' : $path;
     }
-}
+}