bd-hydration-coercion

better-data: Hydration and coercion

For library maintainers fixing or extending how stored / incoming values become typed property values on a DataObject. The coercion layer sits between the source's raw fetch and the constructor's typed parameters; modifying it touches every DTO that goes through ::fromArray.

Misconception this skill corrects

"I'll just settype($value, 'int') or (int) $value inside the hydrator — same effect."

Wrong. PHP's silent casts paper over invalid input — (int) 'abc' === 0, (int) '12foo' === 12, (bool) 'false' === true. better-data's coercion is intentionally strict: surprising input becomes TypeCoercionException with the field name, expected type, and offending value. Verified at src/Internal/TypeCoercer.php:46-58 and the per-helper throws (toString:197, toInt:218, toFloat:235, toBool:254).

The discipline is:

// WRONG inside coercion code
$intValue = (int) $value;

// RIGHT
$intValue = TypeCoercer::toInt($dtoClass, $fieldName, $value);
// throws TypeCoercionException if $value isn't a coercible int — caller gets the field
// name and value in the message instead of silently storing 0.

Other AI-prone misconceptions:

• "I'll add a WP function call inside TypeCoercer — it makes the code shorter." Wrong — TypeCoercer is the one engine that MUST stay WP-free so its tests can run without a WP runtime. WP-aware logic goes in DataObject::coerceParameter or in the source.
• "I'll add the Encrypted decryption to TypeCoercer." Wrong layer — attribute-aware coercion lives ABOVE TypeCoercer in DataObject::coerceParameter (src/DataObject.php:168). The pattern is: handle the attribute (decrypt, walk the list), then call TypeCoercer::coerce with the simpler value.

When to use this skill

Trigger when ANY of the following is true:

• A bug report says "fromArray hydrates with the wrong type" or "casting issue".
• The diff modifies src/Internal/TypeCoercer.php or src/DataObject.php::coerceParameter.
• Adding support for a new primitive type or a new attribute that affects coercion.
• Reviewing a PR that calls settype(), intval(), (int), or (string) inside coercion code.
• Hitting TypeCoercionException at runtime and triaging.