[wol-soft]

Summary

Stacked on #192 (base branch claude/sweet-wright-0c9raw, GitHub retargets to master once #192 is merged). #192 still has to be merged: this PR changes parts of what #192 introduced (see "Changes to tests of #192").

A filter on a property declared in a then, else or oneOf branch ran on the generated parent class for every input, because the transferred copy of the branch property kept the executing FilterValidator. #192 documents this as a known limitation; this PR fixes it.

Behaviour

• if/then/else, oneOf: the branch class owns the filter. The active branch hands its filtered value to the parent (also through an allOf and through nested compositions); while the branch is inactive the property keeps the value as provided. A setter or populate() which switches the active branch validates the dependent properties again (also when populate() re-passes the filtered property unchanged).
• Atomic updates: the values which the active branches hand over, and the dependent properties which are validated again after a branch switch, are prepared without assigning anything and only applied once the whole update was validated (constructor, setter, populate()). A rejected setter or populate() leaves the model untouched (also in collect-errors mode), including the case where the dependent property rejects the update.
• if condition: the filter keeps running inside the condition, but it is neither applied to the parent nor handed over. Filters in a schema dependency behave the same way.
• Transforming filters: the property holds the raw or the transformed value, so the getter/setter types (native and docblock) are the raw type plus the types returned by the filters of all branches. then and else (or the branches of a oneOf) may use different transforming filters or the same filter with different options on one property; such a property remembers which filter produced its value and is serialized by exactly that filter (otherwise the serializer only applies to a value of the filter's output type).
• allOf: the filter of a single branch applies to every value. Several branches may declare an identical filter list (filters, options and order); the filters run once.
• Filter adoption: if the schema declares the property without a filter and the filter of an allOf branch (or the identical filter of every anyOf branch) applies to every value, the schema property adopts the filter (the filter runs first, the schema's validators check the filtered value). Before, such a filter was silently dropped.
• anyOf: several branches can match, so a filtered property is only accepted when every branch declares the property with the same filter. Every other filtered property in an anyOf branch is rejected with a SchemaException, including a oneOf branch nested below an anyOf.
• Filtered more than once (SchemaException): a property which is filtered by declarations that can apply to the same value: the schema itself plus a branch (also an identical repeat), allOf branches with diverging filter lists or with values forwarded from nested compositions, the branches of different compositions, or a matching patternProperties filter on a property which is filtered already (by itself, a branch or another pattern). then/else and the branches of one oneOf exclude each other and may filter the same property differently.
• Shared $ref definitions: a property referencing a definition is detached from the definition before it is transferred from a branch or merged with a branch declaration, so other properties referencing the same definition keep their filters, validators and types.
• Class deduplication: nested schemas which only differ in the order of a list whose order matters (filter, tuple items/prefixItems, composition branches) are no longer mapped to the same class. Lists which are sets (type, required, enum, the dependants of a property dependency) are still compared order-insensitive.

Implementation

• FilterValidator::withoutExecution() is a non-executing copy that still describes the filter, so the output type and serialization post processors keep working. getIdentifier() identifies a filter including its options; it is rendered into the generated code as the filter token, followed by an md5 of the options if the filter has options (e.g. 'dateTime_899030ba…').
• AbstractComposedPropertyValidator::getBranchFilteredKeyMap() / publishesFilteredValueOf() decide which branch properties hand a value over. The compositions publish the filtered values (and, where needed, the producing filter, see getFilterSourceMap()) and stage them; _prepareBranchFilteredValues() validates the dependent properties and computes the new state without assigning, _applyBranchFilteredValues() assigns it. A BranchFilteredValueValidator (a template validator, BranchFilteredValue.phptpl, which substitutes the value by reference in an IIFE like the filter validators) takes the value in front of the other validators of the property.
• Utils\BranchFilterScope (used by SchemaProcessor) converts the transferred copy, lets the schema property adopt filters executed for every value, adds the substitution to the property which is registered after the merge and rejects ambiguous filters.
• PropertyProxy::detach(); Schema::addProperty() replaces a registered property which a definition shares (a proxy, or the resolved property of a definition which every proxy delegates to, see ResolvedDefinitionsCollection::isShared()) by a copy of its own before a branch declaration is merged into it. Other registered properties keep their identity.
• Utils\SchemaSignatureNormalizer sorts only the set-like lists before the class signature is hashed.

Breaking changes (release note)

1. Branch properties are no longer filtered while their branch is inactive.
2. Schemas which worked before now throw a SchemaException at generation time: a filtered property in an anyOf branch (unless every branch declares the same filter), a property which is filtered more than once, and a patternProperties filter matching a property which is filtered already (before, the filters were stacked; only two transforming filters were rejected, with a different message). Previously the filters were silently dropped, stacked or applied regardless of the branch.
3. A filter of an allOf branch (or of every anyOf branch) is now applied to a property which the schema declares without a filter. Before, it was silently dropped.
4. Type hints (from Accept filters in nested allOf object branches; widen conditional-only properties to mixed #192): a property which is declared only in then or only in else changes from ?T to mixed. A transforming filter in a branch widens the getter/setter types of the property to the raw type plus the filter's output types.
5. More classes may be generated for nested schemas which only differ in the order of a filter list, tuple items or composition branches (they were wrongly merged before).
6. A setter called with the current value records it as raw input (meta()->rawInput()), before the early return left the previous raw value.

Review fixes

A first combined review of #192 + #193 found three problems in this PR (serialization with the wrong filter options, a partially applied update when a dependent property rejects it, a silently dropped allOf filter) plus a pre-existing class signature bug (a tuple [string, integer] reused the class of [integer, string]), all fixed here.

A second combined review (against master including #195-#197) found four more, fixed with a failing test first:

1. A filtered $ref definition used in a oneOf / if/then/else branch was changed while the branch property was transferred: the filter was dropped, other properties referencing the definition crashed on valid input, received the branch's filter, transforming type or the mixed widening of Accept filters in nested allOf object branches; widen conditional-only properties to mixed #192.
2. The docblock of a property with branch-owned transforming filters listed only the first type, so the builder class didn't import DateTime and rejected it.
3. A setter returning early (value equal to the filtered value) kept the previous raw input, which a later branch switch validated again.
4. A patternProperties filter stacked with a branch filter (now rejected together with every other stacking, see breaking change 2).

Code review notes on the rendering: the substitution is rendered from a template instead of a special case in RenderHelper, the set-up code of the compositions is collected in arrays, the rendered filter identifier is a token plus hash instead of JSON. Tests which asserted generated code or internal state were removed (covered by the executed tests), and tests generating the same or an identical schema with the same configuration were merged.

Changes to tests of #192 and master

• The playlist test now expects the title to stay untouched while its then branch is inactive (it previously pinned the leak).
• The nested-compositions schema no longer filters its anyOf branch property (now rejected); the original shape is covered as a rejection test.
• The accepted static row for a filtered property in a root allOf branch moved to the rejection tests (parent filter plus branch filter).
• PatternPropertiesTest::testMultipleTransformingFiltersForPatternPropertiesAndObjectPropertyThrowsAnException asserts the "filtered more than once" message which replaced the transforming-filter-only check.
• ComposedIfTest::testCrossTypedThenOnly… (renamed in Accept filters in nested allOf object branches; widen conditional-only properties to mixed #192) is removed: testThenOnlyPropertyKeepsValueOfAnyTypeWhileTheBranchIsInactive covers the same schema shape including the mixed types.

Merging with master

Master (up to #197) is merged into #192 and, through #192, into this branch. The one conflict was Schema::addProperty() (#197 changed the merge call). Resolution: keep the copy of a shared registered property before the merge and assign the merge result as #197 does ($replacesExisting = $this->propertyMerger->merge(...), plus the $compositionProcessor === null argument).

Documentation

filter.rst ("Filters on properties of object branches": adoption, identical allOf lists, atomic updates, serialization by the producing filter, pattern property filters), notes on the anyOf, allOf and if pages, the dependency schema note in object.rst, and the list order rule for class re-usage in namespaces.rst. The docs were not built locally (Sphinx is not installed in the sandbox).

Test plan

Developed test-first (the commits show it).

• Full suite on PHP 8.4.26 (built from source) with PHPUnit 13.4.1, run in per-directory chunks, on this branch and on Accept filters in nested allOf object branches; widen conditional-only properties to mixed #192 after merging master: all green except the 4 ReferencePropertyTest cases which fetch raw.githubusercontent.com (blocked in the sandbox).
• phpcs --standard=phpcs.xml on all changed PHP files: clean
• FilterCompositionBranchScopeTest, FilterCompositionRuntimeTest, ComposedIfTest, JsonSchemaSignatureTest, IdenticalNestedSchemaTest (tuple order)
• Not run locally: PHP 8.5, coverage, qlty.sh (needs a manual trigger on the PR page)

🤖 Generated with Claude Code

https://claude.ai/code/session_01GXn5VCTemp5rnjGrXMMvJs

[coveralls]

Coverage Report for CI Build 39933508518

Coverage increased (+0.2%) to 99.18%

Details

• Coverage increased (+0.2%) from the base build.
• Patch coverage: 3 uncovered changes across 1 file (686 of 689 lines covered, 99.56%).
• No coverage regressions found.

Uncovered Changes

File	Changed	Covered	%
src/Utils/SchemaSignatureNormalizer.php	34	31	91.18%
Total (19 files)	689	686	99.56%

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	8656
Covered Lines:	8585
Line Coverage:	99.18%
Coverage Strength:	588.04 hits per line

---

💛 - Coveralls