Run filters of branch properties only while their branch is active

[wol-soft]

Summary

Stacked on #192 (base branch claude/sweet-wright-0c9raw, GitHub retargets to master once #192 is merged).

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 which switches the active branch validates the dependent properties again.
• Atomic updates: the values which the active branches hand over are staged and only adopted after the update succeeded (constructor, setter, populate()). A failing setter or populate() leaves the model, including the properties which depend on the active branch, untouched (also in collect-errors mode).
• if condition: the filter keeps running inside the condition, but it is neither applied to the parent nor handed over.
• Transforming filters: the property holds the raw or the transformed value, so the getter/setter types are the raw type plus the types returned by the filters of all branches, and the generated serializer only serializes a value of the filter's output type. then and else may use different transforming filters on one property.
• anyOf: several branches can match, so a filtered property is only accepted when every branch declares the property with the same filter (the outcome does not depend on the matching branch, the filter keeps being applied to the property as before). 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 more than once by declarations that can apply to the same value (the schema itself plus a branch, several allOf branches, or the branches of different compositions). Until now only the first filter took effect and the others were silently dropped. then/else and the branches of one oneOf exclude each other and may filter the same property differently.
• A single filtered property in an allOf branch and filters on object branches of property level compositions that are not merged into a parent class (single anyOf object branch, merged class, oneOf) are unchanged and pinned by tests.

Implementation

• FilterValidator::withoutExecution() is a non-executing copy that still describes the filter, so the output type and serialization post processors keep working.
• AbstractComposedPropertyValidator::getBranchFilteredKeyMap() / publishesFilteredValueOf() decide which branch properties hand a value over. The compositions publish the filtered values from the $modifiedValues they already compute and stage them (_stagedBranchFilteredValues); _commitBranchFilteredValues() moves them into the internal branchFilteredValues holder (keyed by property name) from the constructor / setter / populate() after hooks. A BranchFilteredValueValidator takes the value in front of the other validators of the property.
• SchemaProcessor converts the transferred copy (marker for publishing branches, filter dropped for the if condition), adds the substitution to the property which is registered after the merge (since PropertyMerger drops the validators of a later copy) and rejects ambiguous filters.

Behaviour change

A value in an inactive branch is no longer filtered, and schemas which filter a property in an anyOf branch (unless every branch filters it in the same way) or more than once now fail at generation time instead of silently dropping filters. Worth a release note.

Changes to tests of #192

• 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).

Documentation

filter.rst ("Filters on properties of object branches" rewritten, the "also runs while inactive" warning removed), notes with links on the anyOf, allOf and if pages. The docs were not built locally (Sphinx is not installed in the sandbox).

Test plan

Developed test-first (the commits show it): the failing tests came first, then building blocks, runtime, transforming filters, rejections and docs; a review round added the atomicity and anyOf follow-ups.

• Full suite on PHP 8.4.26 (built from source) with PHPUnit 13.4.1, run in per-directory chunks: 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
• New FilterCompositionBranchScopeTest (31 tests), BranchFilteredKeyMapTest, FilterValidatorTest
• 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 38052883874

Coverage increased (+0.02%) to 98.907%

Details

• Coverage increased (+0.02%) from the base build.
• Patch coverage: 3 uncovered changes across 2 files (427 of 430 lines covered, 99.3%).
• No coverage regressions found.

Uncovered Changes

File	Changed	Covered	%
src/Model/Validator/BranchFilteredValueValidator.php	14	12	85.71%
src/SchemaProcessor/SchemaProcessor.php	165	164	99.39%
Total (11 files)	430	427	99.3%

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	8420
Covered Lines:	8328
Line Coverage:	98.91%
Coverage Strength:	585.27 hits per line

---

💛 - Coveralls