Merge pull request #147 from wol-soft/fix/composed-schema-branch-defaults

Add branch default handling for composed schemas (#140)

Author: wol-soft

docs/source/combinedSchemas/allOf.rst

@@ -98,3 +98,13 @@ The thrown exception will be a *PHPModelGenerator\\Exception\\ComposedValue\\All
     **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.
+
+.. note::
+
+    Properties in object-level ``allOf`` branches may carry a ``"default"`` value. Because all
+    branches apply simultaneously, defaults from every branch are combined. When multiple branches
+    define a default for the same property, those defaults must agree; the generator throws a
+    ``SchemaException`` at generation time if they differ.
+
+    See `Default values <../generic/default.html#branch-defaults-in-compositions>`__ for the full
+    explanation.

docs/source/combinedSchemas/anyOf.rst

@@ -88,3 +88,15 @@ The thrown exception will be a *PHPModelGenerator\\Exception\\ComposedValue\\Any
     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.
+
+.. note::
+
+    Properties in object-level ``anyOf`` branches may carry a ``"default"`` value. The generator
+    applies the branch default only when that branch is among the active ones — determined at
+    construction time by which branches the provided data satisfies. When multiple matching branches
+    define a default for the same property, those defaults must agree; the generator throws a
+    ``SchemaException`` at generation time if they differ. Branch defaults are **not** included in
+    ``getRawModelDataInput()``.
+
+    See `Default values <../generic/default.html#branch-defaults-in-compositions>`__ for the full
+    explanation.

docs/source/combinedSchemas/if.rst

@@ -194,3 +194,18 @@ When only a ``then`` block is present (no ``else``), the branch may not apply at
     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.
+
+.. note::
+
+    Properties in object-level ``then`` or ``else`` branches may carry a ``"default"`` value. The
+    generator applies the branch default only when the relevant branch is active — the ``then``
+    default applies when the ``if`` condition is satisfied, and the ``else`` default applies when it
+    is not. A user-supplied value always overrides the branch default. Branch defaults are **not**
+    included in ``getRawModelDataInput()``.
+
+    When a ``then`` or ``else`` branch default conflicts with a root ``properties`` default or a
+    ``patternProperties`` default for the same property, the generator throws a ``SchemaException``
+    at generation time.
+
+    See `Default values <../generic/default.html#branch-defaults-in-compositions>`__ for the full
+    explanation.

docs/source/combinedSchemas/oneOf.rst

@@ -98,3 +98,17 @@ The thrown exception will be a *PHPModelGenerator\\Exception\\ComposedValue\\One
     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.
+
+.. note::
+
+    Properties in object-level ``oneOf`` branches may carry a ``"default"`` value. The generator
+    applies the branch default only when that branch is the active one — determined at construction
+    time by which branch the provided data satisfies. A user-supplied value always overrides the
+    branch default. Branch defaults are **not** included in ``getRawModelDataInput()``.
+
+    When two ``oneOf`` branches define a default for the same property, or when a branch default
+    conflicts with a root ``properties`` default or a ``patternProperties`` default, the generator
+    throws a ``SchemaException`` at generation time.
+
+    See `Default values <../generic/default.html#branch-defaults-in-compositions>`__ for the full
+    explanation and examples.

docs/source/generic/default.rst

@@ -37,3 +37,125 @@ Behaviour with different inputs:
     If no value for a property with a default value is defined the default value will be validated against all rules defined in the schema. Consequently you may get a validation error if the default value doesn't match your constraints.
 
     If you use a `filter <../nonStandardExtensions/filter.html>`__ on a property with a default value the default value will be filtered if no value is provided for the property. If the filter is a `transforming filter <../nonStandardExtensions/filter.html#transforming-filter>`__ the default value will be transformed.
+
+Branch defaults in compositions
+--------------------------------
+
+Properties declared inside ``oneOf``, ``anyOf``, ``allOf``, ``if``/``then``/``else`` branches may
+also carry a ``"default"`` value. The generator supports branch-level defaults and applies them
+conditionally depending on the composition keyword.
+
+**oneOf / anyOf / if–then–else**
+
+For compositions where a single branch (or conditional branch) is active at a time, the branch
+default is applied only when that branch is the active one. A user-supplied value always takes
+precedence over the branch default.
+
+.. code-block:: json
+
+    {
+        "$id": "example",
+        "type": "object",
+        "oneOf": [
+            {
+                "properties": {
+                    "kind": {
+                        "type": "string",
+                        "enum": ["A"]
+                    }
+                },
+                "required": ["kind"]
+            },
+            {
+                "properties": {
+                    "kind": {
+                        "type": "string",
+                        "enum": ["B"]
+                    },
+                    "timeout": {
+                        "type": "integer",
+                        "default": 30
+                    }
+                },
+                "required": ["kind"]
+            }
+        ]
+    }
+
+.. code-block:: php
+
+    // Branch B is active — timeout defaults to 30
+    $example = new Example(['kind' => 'B']);
+    $example->getTimeout();   // returns 30
+
+    // Branch A is active — timeout has no default; returns null
+    $example = new Example(['kind' => 'A']);
+    $example->getTimeout();   // returns null
+
+    // User-supplied value overrides the branch default
+    $example = new Example(['kind' => 'B', 'timeout' => 60]);
+    $example->getTimeout();   // returns 60
+
+Branch defaults are **not** included in ``getRawModelDataInput()``. Only values explicitly
+supplied by the caller appear in the raw input:
+
+.. code-block:: php
+
+    $example = new Example(['kind' => 'B']);
+    $example->getRawModelDataInput();   // returns ['kind' => 'B']
+
+**allOf**
+
+For ``allOf`` compositions, all branches apply simultaneously. When multiple branches define a
+default for the same property, the defaults must agree; a generation-time ``SchemaException`` is
+thrown if they differ.
+
+**Conflict detection**
+
+The generator detects conflicting defaults at schema-processing time and throws a
+``SchemaException`` when:
+
+- Two ``oneOf`` or ``anyOf`` branches define the same property with different default values.
+- A branch default disagrees with a default on the matching root ``properties`` entry.
+- A ``patternProperties`` default disagrees with a branch or root default for the same property.
+- Two ``patternProperties`` patterns both match the same named property and specify different
+  defaults.
+
+**patternProperties defaults**
+
+A ``"default"`` value on a ``patternProperties`` entry propagates to every named property whose
+key matches the pattern:
+
+- If the named property is declared in the root ``properties`` section, it receives the default
+  unconditionally — equivalent to placing the default directly on the property.
+- If the named property exists only inside a composition branch, it receives the default
+  conditionally — the same branch-default mechanism applies.
+
+.. code-block:: json
+
+    {
+        "$id": "example",
+        "type": "object",
+        "properties": {
+            "retry_count": {
+                "type": "integer"
+            }
+        },
+        "patternProperties": {
+            "^retry_": {
+                "type": "integer",
+                "minimum": 1,
+                "default": 3
+            }
+        }
+    }
+
+.. code-block:: php
+
+    // retry_count matches the pattern; default 3 is propagated
+    $example = new Example([]);
+    $example->getRetryCount();   // returns 3
+
+    // User-supplied value overrides the pattern default
+    $example = new Example(['retry_count' => 5]);
+    $example->getRetryCount();   // returns 5

src/Draft/Modifier/DefaultValueModifier.php

@@ -25,6 +25,23 @@ public function modify(
             return;
         }
 
+        // Scalar branch defaults are unreachable: the property value itself is what the
+        // composition branch discriminates on, so a default can only fire when no value is
+        // provided — but without a value there is no signal to select the branch in the
+        // first place. Warn and drop rather than applying the default unconditionally.
+        if ($this->isScalarInsideCompositionBranch($propertySchema)) {
+            if ($schemaProcessor->getGeneratorConfiguration()->isOutputEnabled()) {
+                echo sprintf(
+                    "Warning: property '%s' declares a default value inside a composition branch"
+                        . " in file '%s'. Scalar branch defaults are unreachable and will be ignored.\n",
+                    $property->getName(),
+                    $propertySchema->getFile(),
+                );
+            }
+
+            return;
+        }
+
         $default = $json['default'];
         $types   = isset($json['type']) ? (array) $json['type'] : [];
 
@@ -56,4 +73,46 @@ public function modify(
             ),
         );
     }
+
+    /**
+     * Returns true when the given property schema is a scalar branch schema (not an object
+     * with declared sub-properties) that sits directly at a composition branch level.
+     *
+     * Two cases must be distinguished:
+     *
+     * - A *named property inside an object-typed branch* (e.g. `sandbox` in
+     *   `oneOf/1/properties/sandbox`) — its pointer ends with `/properties/<name>`.
+     *   This is the object-level branch default handled by Phase 2; it must not be dropped.
+     *
+     * - A *branch schema that is itself scalar* (e.g. `oneOf/0` → `{type:string, default:"x"}`
+     *   where the property value IS the discriminant) — its pointer ends with a branch-index
+     *   segment, not `/properties/<name>`. This default is unreachable and must be dropped.
+     *
+     * A property whose pointer ends with `/properties/<name>` is always in the first category.
+     * For the remaining pointers, stripping all `/properties/<name>` segments removes noise
+     * from intermediate object-nesting, and the regex tests whether a composition keyword
+     * segment is present in the structural path.
+     */
+    private function isScalarInsideCompositionBranch(JsonSchema $propertySchema): bool
+    {
+        if (isset($propertySchema->getJson()['properties'])) {
+            return false;
+        }
+
+        $pointer = $propertySchema->getPointer();
+
+        // A pointer ending in /properties/<name> means this is a named property inside an
+        // object-typed branch — handled by per-branch runtime application, not warned about.
+        if (preg_match('#/properties/[^/]+$#', $pointer)) {
+            return false;
+        }
+
+        // Strip intermediate /properties/<name> segments to prevent false positives from
+        // root properties coincidentally named after a composition keyword, then append '/'
+        // so end-of-string branch segments are catchable by the regex.
+        $structuralPointer = preg_replace('#/properties/[^/]+#', '', $pointer) . '/';
+
+        return preg_match('#/(allOf|anyOf|oneOf)/\d+/#', $structuralPointer)
+            || preg_match('#/(if|then|else)/#', $structuralPointer);
+    }
 }

src/Model/Schema.php

@@ -162,9 +162,11 @@ public function getProperties(): array
             return false;
         };
 
-        // order the properties to make sure properties with a SchemaDependencyValidator are validated at the beginning
-        // of the validation process for correct exception order of the messages
-        usort(
+        // Order the properties to make sure properties with a SchemaDependencyValidator are validated at the beginning
+        // of the validation process for correct exception order of the messages.
+        // uasort preserves the string keys (property names) that getProperty() relies on;
+        // usort would reindex to 0,1,2,... and break all subsequent name-based lookups.
+        uasort(
             $this->properties,
             static function (
                 PropertyInterface $property,

src/Model/Validator/AbstractComposedPropertyValidator.php

@@ -5,6 +5,7 @@
 namespace PHPModelGenerator\Model\Validator;
 
 use PHPModelGenerator\Model\Property\CompositionPropertyDecorator;
+use PHPModelGenerator\SchemaProcessor\PostProcessor\RenderedMethod;
 
 /**
  * Class AbstractComposedPropertyValidator
@@ -17,6 +18,7 @@ abstract class AbstractComposedPropertyValidator extends ExtractedMethodValidato
     protected $compositionProcessor;
     /** @var CompositionPropertyDecorator[] */
     protected $composedProperties;
+    protected string $modifiedValuesMethod = '';
 
     public function getCompositionProcessor(): string
     {
@@ -30,4 +32,96 @@ public function getComposedProperties(): array
     {
         return $this->composedProperties;
     }
+
+    protected function initModifiedValuesMethod(): void
+    {
+        $this->modifiedValuesMethod = '_getModifiedValues_' . substr(md5(spl_object_hash($this)), 0, 5);
+    }
+
+    /**
+     * Returns true when at least one composition branch has a nested schema with declared
+     * properties, meaning the modified-values helper method may produce non-empty results.
+     */
+    protected function hasNestedSchemaWithProperties(): bool
+    {
+        foreach ($this->composedProperties as $compositionProperty) {
+            $nestedSchema = $compositionProperty->getNestedSchema();
+            if ($nestedSchema !== null && !empty($nestedSchema->getProperties())) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Sets up the allBranchDefaultAttributeMap template variable and registers the
+     * _getModifiedValues_* helper method on the schema scope. Properties that already carry
+     * a root-level (unconditional) default in the parent schema are excluded from the map;
+     * those defaults are applied via PHP field initializers and must not be reset by the
+     * per-branch mechanism.
+     *
+     * Returns true when the helper method was registered (at least one branch has a nested
+     * schema with properties), false otherwise.
+     */
+    protected function setupBranchDefaultHelpers(): bool
+    {
+        $hasNestedSchemaWithProperties = $this->hasNestedSchemaWithProperties();
+
+        $this->templateValues['hasModifiedValuesMethod'] = $hasNestedSchemaWithProperties;
+
+        if (!$hasNestedSchemaWithProperties) {
+            $this->templateValues['allBranchDefaultAttributeMap'] = var_export([], true);
+
+            return false;
+        }
+
+        $allBranchDefaultAttributeMap = [];
+        $componentDefaultValueMap = [];
+        $propertyAccessors = [];
+
+        foreach ($this->composedProperties as $branchIndex => $compositionProperty) {
+            if (!$compositionProperty->getNestedSchema()) {
+                continue;
+            }
+
+            foreach ($compositionProperty->getNestedSchema()->getProperties() as $branchProperty) {
+                $propertyAccessors[$branchProperty->getName()] = 'get' . ucfirst($branchProperty->getAttribute());
+
+                if ($branchProperty->getDefaultValue() === null) {
+                    continue;
+                }
+
+                $componentDefaultValueMap[$branchIndex][] = $branchProperty->getName();
+
+                // Do not include properties that already have a root-level default on the
+                // parent schema — root defaults are applied unconditionally via PHP field
+                // initializers and must not be overwritten or reset by the branch mechanism.
+                if ($this->scope?->getProperty($branchProperty->getName())?->getDefaultValue() !== null) {
+                    continue;
+                }
+
+                $allBranchDefaultAttributeMap[$branchProperty->getName()] = $branchProperty->getAttribute();
+            }
+        }
+
+        $this->templateValues['allBranchDefaultAttributeMap'] = var_export($allBranchDefaultAttributeMap, true);
+        $this->templateValues['modifiedValuesMethod'] = $this->modifiedValuesMethod;
+
+        $this->scope->addMethod(
+            $this->modifiedValuesMethod,
+            new RenderedMethod(
+                $this->scope,
+                $this->generatorConfiguration,
+                'GetModifiedValues.phptpl',
+                [
+                    'modifiedValuesMethod' => $this->modifiedValuesMethod,
+                    'componentDefaultValueMap' => var_export($componentDefaultValueMap, true),
+                    'propertyAccessors' => var_export($propertyAccessors, true),
+                ],
+            ),
+        );
+
+        return true;
+    }
 }