This commit adds support for PHP 8.0+ union types (like string|int|bool) in the JSON Schema Generator. Union types are now properly represented in JSON Schema using the oneOf keyword.

Author: butschster

context.yaml

@@ -25,4 +25,32 @@ documents:
     sources:
       - type: file
         sourcePaths:
-          - tests
+          - tests
+
+tools:
+  - id: run-all-tests
+    description: "Run all PHPUnit tests for the json-schema-generator"
+    type: run
+    commands:
+      - cmd: composer
+        args:
+          - install
+        workingDir: "./"
+      - cmd: vendor/bin/phpunit
+        args:
+          - "--color=always"
+        workingDir: "./"
+
+  - id: run-union-tests
+    description: "Run only the union type tests"
+    type: run
+    commands:
+      - cmd: composer
+        args:
+          - install
+        workingDir: "./"
+      - cmd: vendor/bin/phpunit
+        args:
+          - "--color=always"
+          - "--filter=UnionType"
+        workingDir: "./"

examples/UnionTypeExample.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Examples;
+
+use Spiral\JsonSchemaGenerator\Attribute\Field;
+
+/**
+ * Example DTO with union types to demonstrate the oneOf JSON Schema generation.
+ */
+class UnionTypeExample
+{
+    public function __construct(
+        #[Field(title: 'String or Integer Value', description: 'A value that can be either a string or an integer')]
+        public readonly string|int $stringOrInt,
+
+        #[Field(title: 'Multiple Types', description: 'A value that can be one of multiple types')]
+        public readonly string|int|bool|null $multiType = null,
+
+        #[Field(title: 'Object Union', description: 'A value that can be one of multiple object types')]
+        public readonly SimpleObject|ComplexObject|null $objectUnion = null,
+    ) {}
+}
+
+/**
+ * Simple object for union type example.
+ */
+class SimpleObject
+{
+    public function __construct(
+        public readonly string $name,
+    ) {}
+}
+
+/**
+ * Complex object for union type example.
+ */
+class ComplexObject
+{
+    public function __construct(
+        public readonly string $title,
+        public readonly int $count,
+    ) {}
+}

runAllTests.php

@@ -0,0 +1,6 @@
+<?php
+// Simple script to execute all PHPUnit tests
+
+echo "Running all PHPUnit tests...\n";
+passthru('vendor/bin/phpunit', $exitCode);
+exit($exitCode);

src/Generator.php

@@ -12,6 +12,7 @@
 use Spiral\JsonSchemaGenerator\Parser\ParserInterface;
 use Spiral\JsonSchemaGenerator\Parser\PropertyInterface;
 use Spiral\JsonSchemaGenerator\Parser\TypeInterface;
+use Spiral\JsonSchemaGenerator\Parser\UnionType;
 use Spiral\JsonSchemaGenerator\Schema\Definition;
 use Spiral\JsonSchemaGenerator\Schema\Property;
 
@@ -197,6 +198,12 @@ protected function generateProperty(PropertyInterface $property): ?Property
 
         $type = $property->getType();
 
+        // Handle union types (e.g., string|int|bool)
+        if ($type instanceof UnionType) {
+            $required = $default === null && !$type->allowsNull();
+            return new Property($type, [], $title, $description, $required, $default);
+        }
+
         $options = [];
         if ($property->isCollection()) {
             $options = \array_map(

src/Parser/ClassParser.php

@@ -78,17 +78,12 @@ public function getProperties(): array
                 continue;
             }
 
-            /**
-             * @var \ReflectionNamedType|null $type
-             */
-            $type = $property->getType();
-            if (!$type instanceof \ReflectionNamedType) {
-                continue;
-            }
+            // Parse the type using TypeParser
+            $typeInterface = TypeParser::fromReflectionType($property->getType());
 
             $properties[] = new Property(
                 property: $property,
-                type: new Type(name: $type->getName(), builtin: $type->isBuiltin(), nullable: $type->allowsNull()),
+                type: $typeInterface,
                 hasDefaultValue: $this->hasPropertyDefaultValue($property),
                 defaultValue: $this->getPropertyDefaultValue($property),
                 collectionValueTypes: $this->getPropertyCollectionTypes($property->getName()),

src/Parser/TypeParser.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Spiral\JsonSchemaGenerator\Parser;
+
+use Spiral\JsonSchemaGenerator\Exception\InvalidTypeException;
+
+/**
+ * Parses PHP reflection types into TypeInterface instances.
+ *
+ * @internal
+ */
+final class TypeParser
+{
+    /**
+     * Parse a PHP reflection type into a TypeInterface.
+     */
+    public static function fromReflectionType(\ReflectionType $reflectionType): TypeInterface
+    {
+        if ($reflectionType instanceof \ReflectionUnionType) {
+            return self::parseUnionType($reflectionType);
+        }
+
+        if ($reflectionType instanceof \ReflectionNamedType) {
+            return self::parseNamedType($reflectionType);
+        }
+
+        // PHP 8.1+ intersection types are not supported in JSON Schema
+        if ($reflectionType instanceof \ReflectionIntersectionType) {
+            throw new InvalidTypeException('Intersection types are not supported in JSON Schema.');
+        }
+
+        throw new InvalidTypeException('Unsupported reflection type: ' . $reflectionType::class);
+    }
+
+    /**
+     * Parse a union type into a UnionType.
+     */
+    private static function parseUnionType(\ReflectionUnionType $unionType): UnionType
+    {
+        $types = [];
+        foreach ($unionType->getTypes() as $type) {
+            if ($type instanceof \ReflectionNamedType) {
+                $types[] = self::parseNamedType($type);
+            } else {
+                throw new InvalidTypeException('Nested union or intersection types are not supported.');
+            }
+        }
+
+        return new UnionType($types);
+    }
+
+    /**
+     * Parse a named type into a Type.
+     */
+    private static function parseNamedType(\ReflectionNamedType $namedType): Type
+    {
+        return new Type(
+            name: $namedType->getName(),
+            builtin: $namedType->isBuiltin(),
+            nullable: $namedType->allowsNull(),
+        );
+    }
+}

src/Parser/UnionType.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Spiral\JsonSchemaGenerator\Parser;
+
+use Spiral\JsonSchemaGenerator\Schema\Type as SchemaType;
+
+/**
+ * Represents a PHP union type (e.g., string|int|null).
+ *
+ * @internal
+ */
+final readonly class UnionType implements TypeInterface
+{
+    /**
+     * @param array<TypeInterface> $types
+     */
+    public function __construct(private array $types) {}
+
+    /**
+     * Always returns SchemaType::Union for union types.
+     */
+    public function getName(): string|SchemaType
+    {
+        return SchemaType::Union;
+    }
+
+    /**
+     * @return array<TypeInterface>
+     */
+    public function getTypes(): array
+    {
+        return $this->types;
+    }
+
+    /**
+     * Union types are not built-in types.
+     */
+    public function isBuiltin(): bool
+    {
+        return false;
+    }
+
+    /**
+     * Checks if any of the types in the union allows null.
+     */
+    public function allowsNull(): bool
+    {
+        foreach ($this->types as $type) {
+            if ($type->allowsNull()) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+}

src/Schema/Property.php

@@ -5,17 +5,18 @@
 namespace Spiral\JsonSchemaGenerator\Schema;
 
 use Spiral\JsonSchemaGenerator\Exception\InvalidTypeException;
+use Spiral\JsonSchemaGenerator\Parser\UnionType;
 
 final readonly class Property implements \JsonSerializable
 {
     public PropertyOptions $options;
 
     /**
-     * @param Type|class-string $type
+     * @param Type|class-string|UnionType $type
      * @param array<class-string|Type> $options
      */
     public function __construct(
-        public Type|string $type,
+        public Type|string|UnionType $type,
         array $options = [],
         public string $title = '',
         public string $description = '',
@@ -44,8 +45,25 @@ public function jsonSerialize(): array
             $property['default'] = $this->default;
         }
 
+        // Handle UnionType instance
+        if ($this->type instanceof UnionType) {
+            $unionOptions = [];
+            foreach ($this->type->getTypes() as $unionType) {
+                $typeName = $unionType->getName();
+                if (\is_string($typeName) && !$unionType->isBuiltin()) {
+                    // Class reference
+                    $unionOptions[] = ['$ref' => (new Reference($typeName))->jsonSerialize()];
+                } else {
+                    // Primitive type
+                    $unionOptions[] = ['type' => $typeName instanceof Type ? $typeName->value : $typeName];
+                }
+            }
+            $property['oneOf'] = $unionOptions;
+            return $property;
+        }
+
         if ($this->type === Type::Union) {
-            $property['anyOf'] = $this->options->jsonSerialize();
+            $property['oneOf'] = $this->options->jsonSerialize();
             return $property;
         }
 
@@ -67,7 +85,7 @@ public function jsonSerialize(): array
 
                 $property['items']['type'] = $this->options[0]->value->value;
             } else {
-                $property['items']['anyOf'] = $this->options->jsonSerialize();
+                $property['items']['oneOf'] = $this->options->jsonSerialize();
             }
         }
 
@@ -77,6 +95,17 @@ public function jsonSerialize(): array
     public function getDependencies(): array
     {
         $dependencies = [];
+
+        // Extract dependencies from union types
+        if ($this->type instanceof UnionType) {
+            foreach ($this->type->getTypes() as $unionType) {
+                $typeName = $unionType->getName();
+                if (!$unionType->isBuiltin() && \is_string($typeName)) {
+                    $dependencies[] = $typeName;
+                }
+            }
+        }
+
         foreach ($this->options->getOptions() as $option) {
             if (\is_string($option->value)) {
                 $dependencies[] = $option->value;

src/Schema/PropertyOptions.php

@@ -21,7 +21,7 @@ final class PropertyOptions implements \Countable, \ArrayAccess, \JsonSerializab
     public function __construct(array $options = [])
     {
         foreach ($options as $option) {
-            $this->options[] = new PropertyOption($option);
+            $this->options[] = $option instanceof PropertyOption ? $option : new PropertyOption($option);
         }
     }
 

tests/Unit/Fixture/ComplexUnionTypes.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Spiral\JsonSchemaGenerator\Tests\Unit\Fixture;
+
+use Spiral\JsonSchemaGenerator\Attribute\Field;
+use Spiral\JsonSchemaGenerator\Attribute\Definition;
+
+/**
+ * Example of complex nested union types.
+ */
+#[Definition(title: 'Complex Union Types', description: 'Class with complex union type combinations')]
+class ComplexUnionTypes
+{
+    /**
+     * @var array<string|int>
+     */
+    #[Field(title: 'Array of Union Types', description: 'An array that can contain strings or integers')]
+    public array $arrayOfUnionTypes = [];
+
+    /**
+     * @var array<Movie|Actor>
+     */
+    #[Field(title: 'Array of Objects', description: 'An array that can contain different object types')]
+    public array $arrayOfObjects = [];
+
+    public function __construct(
+        #[Field(title: 'Nullable Union', description: 'A nullable union of primitive types')]
+        public readonly string|int|null $nullableUnion = null,
+        #[Field(title: 'Complex Property', description: 'Union of primitive, array, and object types')]
+        public readonly string|array|Movie|null $complexProperty = null,
+        #[Field(title: 'Default Value', description: 'Union type with default value')]
+        public readonly string|int $defaultValue = 42,
+    ) {}
+}