Merge pull request #121 from wol-soft/feat/composition-required-promotion

Add composition required promotion and fix allOf untyped-branch type erasure

Author: wol-soft

.claude/settings.local.json

@@ -18,20 +18,20 @@
       "Bash(cat:*)",
       "Bash(where gh:*)",
       "Bash(composer update:*)",
-      "Bash(./vendor/bin/rector process:*)",
+      "Bash(./vendor/bin/rector:*)",
       "Bash(git checkout:*)",
       "Bash(git add:*)",
-      "Bash(./vendor/bin/rector --version 2>&1 | grep Rector)",
-      "Bash(./vendor/bin/phpcs --standard=PSR12 --report=summary src/ 2>&1)",
-      "Bash(./vendor/bin/phpcs --standard=PSR12 --report=source src/)",
-      "Bash(./vendor/bin/phpcs --standard=PSR12 --report=json src/)",
       "Bash(python3 -c \":*)",
-      "Bash(./vendor/bin/phpcbf --standard=phpcs.xml src/)",
-      "Bash(./vendor/bin/phpcs --standard=phpcs.xml --report=full src/)",
-      "Bash(./vendor/bin/phpcs --standard=phpcs.xml src/)",
-      "Bash(./vendor/bin/phpcs --standard=phpcs.xml --report=summary src/)",
+      "Bash(./vendor/bin/phpcbf:*)",
+      "Bash(./vendor/bin/phpcs:*)",
       "Bash(git merge:*)",
-      "Bash(gh api:*)"
+      "Bash(gh api:*)",
+      "Bash(git restore:*)",
+      "Bash(git stash:*)",
+      "Bash(composer show:*)",
+      "Bash(php -r \":*)",
+      "Bash(gh pr:*)",
+      "Bash(xargs wc:*)"
     ]
   }
 }

docs/source/combinedSchemas/allOf.rst

@@ -81,3 +81,10 @@ The thrown exception will be a *PHPModelGenerator\\Exception\\ComposedValue\\All
     the intersection of all declared types across branches. See
     `Cross-typed compositions <crossTypedComposition.html>`__ for the full explanation and a contrast
     with ``anyOf``/``oneOf`` union widening.
+
+.. note::
+
+    For object-level ``allOf`` compositions, when a property appears in the ``required`` array of
+    **any** branch, the generator promotes that property to non-nullable in the generated class. All
+    ``allOf`` branches must hold simultaneously, so any branch's ``required`` constraint is effectively
+    global. See `Cross-typed compositions <crossTypedComposition.html>`__ for the full promotion rules.

docs/source/combinedSchemas/anyOf.rst

@@ -70,3 +70,11 @@ The thrown exception will be a *PHPModelGenerator\\Exception\\ComposedValue\\Any
     widens the property to a union type. See
     `Cross-typed compositions <crossTypedComposition.html>`__ for the full explanation including
     nullability rules and the ``allOf`` contrast.
+
+.. note::
+
+    For object-level ``anyOf`` compositions, when a property appears in the ``required`` array of
+    **every** branch, the generator promotes that property to non-nullable in the generated class.
+    Because at least one branch must apply and all branches guarantee the property's presence, the
+    getter can safely be non-nullable. See `Cross-typed compositions <crossTypedComposition.html>`__
+    for the full promotion rules.

docs/source/combinedSchemas/crossTypedComposition.rst

@@ -49,15 +49,72 @@ The ``age`` property appears in both branches with different types, so the gener
 object might satisfy the ``anyOf`` constraint via a branch that carries a different property
 entirely, leaving ``age`` absent.
 
-Nullability
------------
+Nullability and required promotion
+------------------------------------
 
 A property that is present in some branches but not others is always nullable in the generated
 class. The matching branch at runtime may not define the property at all, so the getter must be
 able to return ``null``.
 
-If a property is marked as ``required`` in **every** branch that defines it, and at least one
-branch is guaranteed to apply, the property may be non-nullable.
+When the composition structure **guarantees** that a property will always be present, the generator
+promotes the property to non-nullable — regardless of whether ``implicitNull`` is enabled. The
+promotion rules depend on the keyword:
+
+* **allOf** — property is promoted when it appears in ``required`` in **any** branch (because all
+  branches must hold simultaneously, so any branch's ``required`` constraint applies globally).
+* **anyOf** / **oneOf** — property is promoted only when it appears in ``required`` in **every**
+  branch (because only one branch applies at runtime; the property is present only if all branches
+  guarantee it).
+* **if / then / else** — property is promoted only when it appears in ``required`` in **both**
+  ``then`` and ``else``. If only a ``then`` block exists (no ``else``), the property is never
+  promoted because the ``else`` path may apply at runtime and the property would be absent.
+
+For example, with a two-branch ``oneOf`` where ``age`` is required in both branches:
+
+.. code-block:: json
+
+    {
+        "$id": "example",
+        "type": "object",
+        "oneOf": [
+            {
+                "type": "object",
+                "required": ["age"],
+                "properties": {
+                    "age": {
+                        "type": "integer"
+                    }
+                }
+            },
+            {
+                "type": "object",
+                "required": ["age"],
+                "properties": {
+                    "age": {
+                        "type": "string"
+                    }
+                }
+            }
+        ]
+    }
+
+Generated interface:
+
+.. code-block:: php
+
+    public function setAge(int | string $age): static;
+    public function getAge(): int | string;
+
+Because ``age`` is required in every branch, the generator removes the ``null`` from the union — a
+valid input always provides ``age``. If ``age`` were optional in even one branch, the getter would
+be ``int | string | null``.
+
+.. note::
+
+    Promotion only affects the PHP type hint (nullability). It does **not** set ``isRequired()``
+    to ``true`` on the property. The schema-level ``required`` constraint is still enforced by the
+    composition validator, not by a separate required-value check. This means omitting a promoted
+    property still raises a composition exception, not a ``RequiredValueException``.
 
 Properties exclusive to a single branch
 ----------------------------------------

docs/source/combinedSchemas/if.rst

@@ -167,3 +167,12 @@ When only a ``then`` block is present (no ``else``), the branch may not apply at
     The union-widening and nullability rules for ``if``/``then``/``else`` follow the same logic as
     ``anyOf``/``oneOf``. See `Cross-typed compositions <crossTypedComposition.html>`__ for the full
     explanation.
+
+.. note::
+
+    For object-level ``if``/``then``/``else`` compositions, when a property appears in the
+    ``required`` array of **both** ``then`` and ``else``, the generator promotes that property to
+    non-nullable. Exactly one of the two branches applies at runtime, and both guarantee the
+    property's presence. If there is no ``else`` block, the property is never promoted — the schema
+    is silent when the condition fails, so the property may be absent. See
+    `Cross-typed compositions <crossTypedComposition.html>`__ for the full promotion rules.

docs/source/combinedSchemas/oneOf.rst

@@ -80,3 +80,11 @@ The thrown exception will be a *PHPModelGenerator\\Exception\\ComposedValue\\One
     widens the property to a union type. See
     `Cross-typed compositions <crossTypedComposition.html>`__ for the full explanation including
     nullability rules and the ``allOf`` contrast.
+
+.. note::
+
+    For object-level ``oneOf`` compositions, when a property appears in the ``required`` array of
+    **every** branch, the generator promotes that property to non-nullable in the generated class.
+    Exactly one branch applies at runtime; because all branches guarantee the property's presence,
+    the getter can safely be non-nullable. See `Cross-typed compositions <crossTypedComposition.html>`__
+    for the full promotion rules.

src/ModelGenerator.php

@@ -11,6 +11,7 @@
 use PHPModelGenerator\Model\GeneratorConfiguration;
 use PHPModelGenerator\SchemaProcessor\PostProcessor\Internal\ {
     AdditionalPropertiesPostProcessor,
+    CompositionRequiredPromotionPostProcessor,
     CompositionValidationPostProcessor,
     ExtendObjectPropertiesMatchingPatternPropertiesPostProcessor,
     PatternPropertiesPostProcessor,
@@ -45,7 +46,8 @@ public function __construct(protected GeneratorConfiguration $generatorConfigura
             ->addPostProcessor(new CompositionValidationPostProcessor())
             ->addPostProcessor(new AdditionalPropertiesPostProcessor())
             ->addPostProcessor(new PatternPropertiesPostProcessor())
-            ->addPostProcessor(new ExtendObjectPropertiesMatchingPatternPropertiesPostProcessor());
+            ->addPostProcessor(new ExtendObjectPropertiesMatchingPatternPropertiesPostProcessor())
+            ->addPostProcessor(new CompositionRequiredPromotionPostProcessor());
     }
 
     public function addPostProcessor(PostProcessor $postProcessor): self

src/SchemaProcessor/PostProcessor/Internal/CompositionRequiredPromotionPostProcessor.php

@@ -0,0 +1,137 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPModelGenerator\SchemaProcessor\PostProcessor\Internal;
+
+use PHPModelGenerator\Model\GeneratorConfiguration;
+use PHPModelGenerator\Model\Property\PropertyInterface;
+use PHPModelGenerator\Model\Property\PropertyType;
+use PHPModelGenerator\Model\Schema;
+use PHPModelGenerator\Model\Validator\AbstractComposedPropertyValidator;
+use PHPModelGenerator\Model\Validator\ComposedPropertyValidator;
+use PHPModelGenerator\Model\Validator\ConditionalPropertyValidator;
+use PHPModelGenerator\PropertyProcessor\ComposedValue\AllOfProcessor;
+use PHPModelGenerator\SchemaProcessor\PostProcessor\PostProcessor;
+
+/**
+ * Promotes properties transferred from composition branches to non-nullable when the composition
+ * structure guarantees the property is always present in a valid object.
+ *
+ * Rules:
+ *   allOf  — property is required in any branch (all branches apply simultaneously)
+ *   anyOf  — property is required in every branch (at least one always matches)
+ *   oneOf  — property is required in every branch (exactly one always matches)
+ *   if/then/else — property is required in both then and else (one always applies)
+ *
+ * The property's isRequired() flag is intentionally left false so the template short-circuit
+ * (which exits early when the key is absent) continues to work correctly during construction.
+ * Only the nullable flag on the PropertyType is changed to false.
+ */
+class CompositionRequiredPromotionPostProcessor extends PostProcessor
+{
+    public function process(Schema $schema, GeneratorConfiguration $generatorConfiguration): void
+    {
+        foreach ($schema->getBaseValidators() as $validator) {
+            if (!($validator instanceof AbstractComposedPropertyValidator)) {
+                continue;
+            }
+
+            foreach ($this->collectPromotablePropertyNames($validator) as $propertyName) {
+                $this->promoteProperty($schema, $propertyName);
+            }
+        }
+    }
+
+    /**
+     * Returns the names of all properties that are guaranteed to be present by the given validator.
+     *
+     * @return string[]
+     */
+    private function collectPromotablePropertyNames(AbstractComposedPropertyValidator $validator): array
+    {
+        if ($validator instanceof ConditionalPropertyValidator) {
+            return $this->collectFromConditional($validator);
+        }
+
+        return $this->collectFromComposed($validator);
+    }
+
+    /**
+     * For if/then/else: a property is guaranteed only when both then and else are present and
+     * both require the property.
+     *
+     * @return string[]
+     */
+    private function collectFromConditional(ConditionalPropertyValidator $validator): array
+    {
+        $branches = $validator->getConditionBranches();
+
+        if (count($branches) < 2) {
+            return [];
+        }
+
+        $requiredPerBranch = array_map(
+            static fn($branch): array =>
+                $branch->getNestedSchema()?->getJsonSchema()->getJson()['required'] ?? [],
+            $branches,
+        );
+
+        return array_values(array_intersect(...$requiredPerBranch));
+    }
+
+    /**
+     * For allOf: a property is guaranteed when it is required in any branch.
+     * For anyOf/oneOf: a property is guaranteed when it is required in every branch.
+     *
+     * @return string[]
+     */
+    private function collectFromComposed(ComposedPropertyValidator $validator): array
+    {
+        $branches = $validator->getComposedProperties();
+
+        if (empty($branches)) {
+            return [];
+        }
+
+        $requiredPerBranch = array_map(
+            static fn($branch): array =>
+                $branch->getNestedSchema()?->getJsonSchema()->getJson()['required'] ?? [],
+            $branches,
+        );
+
+        if (is_a($validator->getCompositionProcessor(), AllOfProcessor::class, true)) {
+            return array_values(array_unique(array_merge(...$requiredPerBranch)));
+        }
+
+        return array_values(array_intersect(...$requiredPerBranch));
+    }
+
+    /**
+     * Strips the nullable flag from the property's type if the property is not already required
+     * at root level and has a type that can be promoted.
+     */
+    private function promoteProperty(Schema $schema, string $propertyName): void
+    {
+        $property = array_find(
+            $schema->getProperties(),
+            static fn (PropertyInterface $property): bool => $property->getName() === $propertyName,
+        );
+
+        if (!$property || $property->isRequired()) {
+            return;
+        }
+
+        $type = $property->getType();
+        $outputType = $property->getType(true);
+
+        if ($type === null) {
+            return;
+        }
+
+        $property->setType(
+            new PropertyType($type->getNames(), false),
+            new PropertyType($outputType->getNames(), false),
+        );
+    }
+}

src/Utils/PropertyMerger.php

@@ -69,6 +69,19 @@ public function merge(
 
         // Use getType(true) for the stored output type.
         // getType(false) post-Phase-5 returns a synthesised union and cannot be decomposed.
+        //
+        // For allOf: a truly-untyped incoming branch (no type keyword, not an explicit null-type
+        // branch) adds no type constraint — all allOf branches apply simultaneously, so the
+        // existing type is unaffected. Skip mergeNullableBranch in that case to avoid wrongly
+        // wiping the existing type.
+        if (
+            $isAllOf
+            && $incoming->getType(true) === null
+            && !str_contains($incoming->getTypeHint(), 'null')
+        ) {
+            return;
+        }
+
         if ($this->mergeNullableBranch($existing, $incoming) || $this->mergeIntoExistingNull($existing, $incoming)) {
             return;
         }