Experiment child node manipulation

[overclokk]

Node Manipulation Methods & Storage Synchronization Improvements

New Features

• Added node manipulation methods (appendTo(), prependTo(), insertAt(), deleteFrom()) for working with lists at nested paths using dot/array notation
• Created NodeManipulationInterface to formalize the contract for list manipulation operations
• Added typed validations via assertList() helper that throws RuntimeException with descriptive error messages when operating on non-array values

Bug Fixes

• Fixed storage synchronization issue: All mutation methods now correctly sync internal $this->storage with parent ArrayObject via parent::exchangeArray(). This ensures consistent behavior when accessing data through ArrayAccess, Iterator, getArrayCopy(), count(), and property access after mutations
• Fixed exchangeArray() override in ArrayObjectTrait to properly read from $this->storage before replacement
• Fixed traverse() method to sync storage after modifications

Performance Improvements

• Optimized node manipulation methods by calling buildLevels() once per operation instead of multiple times (~25-35% performance improvement)
• Added comprehensive benchmarks in ConfigNodeManipulationBench.php with 28 scenarios covering all node manipulation methods

Testing

• Expanded test coverage to 220 tests with 557 assertions
• Added StorageSynchronizationTest with 48+ test cases ensuring consistent behavior across all access patterns after mutations
• Added NodeManipulationTest with extensive coverage including edge cases, associative arrays, and error conditions

Documentation

• Updated 03_node-manipulation.md with:
  • Comprehensive method documentation
  • Practical usage examples
  • Important notes section explaining:
    • List-only operation constraint
    • Duplicate handling behavior
    • First occurrence removal semantics
    • deleteFrom() searches by VALUE, not by KEY
    • Strict type comparisons
• Updated example.php with runnable examples for all new methods

Breaking Changes

None. All changes are backward compatible.