More comprehensive types

Author: tobyzerner

CHANGELOG.md

@@ -31,6 +31,11 @@ and this project adheres to
 
 ### Added
 
+- More comprehensive type schema support
+    - Add `nullable()` method to `Type` classes, allowing sub-types (e.g. array
+      items or object properties) to be nullable
+    - Add `Obj`, `Any`, `AnyOf`, `AllOf`, `OneOf`, and `Not` types
+    - Convert type validation errors to overridable exception classes
 - Add `Context::createResponse()` method for building JSON:API responses with
   automatic `jsonapi` object inclusion
 - Add `JsonApi::meta()` method for including meta information in the `jsonapi`

src/Exception/Type/AdditionalPropertyException.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Tobyz\JsonApiServer\Exception\Type;
+
+use Tobyz\JsonApiServer\Exception\UnprocessableEntityException;
+
+class AdditionalPropertyException extends UnprocessableEntityException
+{
+    public function __construct(string $property)
+    {
+        parent::__construct("Value must not have additional property '$property'");
+
+        $this->error['meta'] = ['property' => $property];
+    }
+}

src/Exception/Type/EnumViolationException.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Tobyz\JsonApiServer\Exception\Type;
+
+use Tobyz\JsonApiServer\Exception\UnprocessableEntityException;
+
+class EnumViolationException extends UnprocessableEntityException
+{
+    public function __construct(array $allowedValues, mixed $actual = null)
+    {
+        $formatted = array_map(fn($value) => '"' . $value . '"', $allowedValues);
+        $message = sprintf('Value must be one of %s', implode(', ', $formatted));
+
+        parent::__construct($message);
+
+        $this->error['meta'] = ['allowed' => $allowedValues];
+
+        if ($actual !== null) {
+            $this->error['meta']['actual'] = $actual;
+        }
+    }
+}

src/Exception/Type/InvalidSchemaException.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace Tobyz\JsonApiServer\Exception\Type;
+
+use Tobyz\JsonApiServer\Exception\UnprocessableEntityException;
+
+class InvalidSchemaException extends UnprocessableEntityException
+{
+    public function __construct(string $constraint, ?int $matched = null)
+    {
+        parent::__construct('Value does not match schema constraint');
+
+        $this->error['meta'] = ['constraint' => $constraint];
+
+        if ($matched !== null) {
+            $this->error['meta']['matched'] = $matched;
+        }
+    }
+}

src/Exception/Type/MultipleViolationException.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace Tobyz\JsonApiServer\Exception\Type;
+
+use Tobyz\JsonApiServer\Exception\UnprocessableEntityException;
+
+class MultipleViolationException extends UnprocessableEntityException
+{
+    public function __construct(int|float $multipleOf, int|float|null $actual = null)
+    {
+        parent::__construct(sprintf('Value must be a multiple of %s', $multipleOf));
+
+        $this->error['meta'] = ['multipleOf' => $multipleOf];
+
+        if ($actual !== null) {
+            $this->error['meta']['actual'] = $actual;
+        }
+    }
+}

src/Exception/Type/NullViolationException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace Tobyz\JsonApiServer\Exception\Type;
+
+use Tobyz\JsonApiServer\Exception\UnprocessableEntityException;
+
+class NullViolationException extends UnprocessableEntityException
+{
+    public function __construct()
+    {
+        parent::__construct('Value must not be null');
+    }
+}

src/Exception/Type/PatternViolationException.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Tobyz\JsonApiServer\Exception\Type;
+
+use Tobyz\JsonApiServer\Exception\UnprocessableEntityException;
+
+class PatternViolationException extends UnprocessableEntityException
+{
+    public function __construct(string $pattern)
+    {
+        parent::__construct(sprintf('Value must match the pattern %s', $pattern));
+
+        $this->error['meta'] = ['pattern' => $pattern];
+    }
+}

src/Exception/Type/RangeViolationException.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Tobyz\JsonApiServer\Exception\Type;
+
+use Tobyz\JsonApiServer\Exception\UnprocessableEntityException;
+
+class RangeViolationException extends UnprocessableEntityException
+{
+    public function __construct(
+        string $constraint,
+        int|float $limit,
+        int|float|null $actual = null,
+        bool $exclusive = false,
+    ) {
+        parent::__construct('Value is out of range');
+
+        $this->error['meta'] = [
+            'constraint' => $constraint,
+            'limit' => $limit,
+        ];
+
+        if ($actual !== null) {
+            $this->error['meta']['actual'] = $actual;
+        }
+
+        if ($exclusive) {
+            $this->error['meta']['exclusive'] = true;
+        }
+    }
+}

src/Exception/Type/RequiredPropertyException.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Tobyz\JsonApiServer\Exception\Type;
+
+use Tobyz\JsonApiServer\Exception\UnprocessableEntityException;
+
+class RequiredPropertyException extends UnprocessableEntityException
+{
+    public function __construct(string $property)
+    {
+        parent::__construct("Value must have required property ':property'");
+
+        $this->error['meta'] = ['property' => $property];
+    }
+}

src/Exception/Type/TypeMismatchException.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Tobyz\JsonApiServer\Exception\Type;
+
+use Tobyz\JsonApiServer\Exception\UnprocessableEntityException;
+
+class TypeMismatchException extends UnprocessableEntityException
+{
+    public function __construct(string $expected, ?string $actual = null)
+    {
+        parent::__construct("Value must be $expected");
+
+        if ($actual !== null) {
+            $this->error['meta'] = [
+                'expected' => $expected,
+                'actual' => $actual,
+            ];
+        }
+    }
+}