#206 - Fix AdvancedStatCounterTask, IterableBatchTask, ConditionTrait and ColumnAggregatorTask edge cases

[njoubert-cleverage]

Description

Fixes #206.

Four tasks or helpers fail on edge cases:

1. AdvancedStatCounterTask tests counter % show_every before incrementing the counter: the first counted execution is never logged and the reported item count is one behind. With show_every: 1, 3 executions give: nothing, "1 items processed", "2 items processed".
2. IterableBatchTask only accepts an integer batch_count: the null !== $batchCount branch ("only flush at the end", as in SimpleBatchTask) is dead code, and batch_count: ~ throws.
3. ConditionTrait::checkValue(), checkEmpty() and getValue() are typed object|array: as soon as a condition is set, a scalar input raises a TypeError. The documented '' path, which targets the whole value, is therefore unusable on scalars, e.g. array_filter on a list of strings.
4. ColumnAggregatorTask uses isset() to detect missing columns, so a column whose value is null counts as missing and throws an UnexpectedValueException.

This PR:

• AdvancedStatCounterTask: increment the counter before the show_every test, so statistics are logged on the N-th, 2N-th… counted execution, with the right item count.
• IterableBatchTask: allow ['integer', 'null'] for batch_count; null buffers every input and outputs them one by one on flush, like SimpleBatchTask.
• ConditionTrait: type $input as mixed; the '' path targets the whole value, even a scalar; any other path on a scalar gives null, like a missing key.
• ColumnAggregatorTask: detect missing columns with array_key_exists() for array inputs, so null columns are aggregated (ArrayAccess inputs keep the isset() check).
• Update the reference documentation (AdvancedStatCounterTask, IterableBatchTask, ColumnAggregatorTask, FilterTask, ConditionTrait, ArrayFilterTransformer), add unit tests.

The new regression tests fail on main and pass with this fix. PHPUnit, PHPStan, PHP-CS-Fixer and Rector pass.

Requirements

• Documentation updates
  • Reference
  • Cookbooks
  • Changelog
• Unit tests

Breaking changes

None intended (bug fixes), but behaviour changes slightly:

• AdvancedStatCounterTask now logs one execution earlier (on the N-th counted execution instead of the (N+1)-th), with correct item counts.
• ColumnAggregatorTask now aggregates rows whose column value is null instead of throwing (or only warning with ignore_missing: true).
• ConditionTrait methods now declare a mixed $input: a class overriding checkValue(), checkEmpty() or getValue() with the old object|array signature must widen it.

🤖 Generated with Claude Code