bd-hydration-coercion
Modify how raw values become typed property values in
Lonsdale201 · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add Lonsdale201/wp-agent-skills --skill bd-hydration-coercionAbout this skill
name: bd-hydration-coercion description: Modify how raw values become typed property values in better-data — work in TypeCoercer (primitives + DateTime + Enum + Secret) or DataObject::coerceParameter (attribute-aware — ListOf, Encrypted, etc.). Critical layering — TypeCoercer is pure, must stay callable from a no-WordPress unit test, no side effects, no global reads, no WP function calls; attribute-driven coercion lives ABOVE TypeCoercer (read attribute → do the rich-type dance → optionally delegate to TypeCoercer with a simpler value). Use the explicit helpers (toString, toInt, toFloat, toBool, toArray, toEnum), never settype() / intval() / unchecked casts — and throw TypeCoercionException on anything surprising. Use when fixing a hydration bug, adding a new primitive coercion, or extending attribute-aware coercion. Triggers on changes to TypeCoercer.php, DataObject::coerceParameter, AttributeDrivenHydrator, TypeCoercionException, "hydration bug", "fromArray throws". metadata: wp-skills-author: "Soczó Kristóf" wp-skills-contact: "mailto:lonsdale201@hotmail.com" wp-skills-plugin: "better-data" wp-skills-plugin-version-tested: "phase-9" wp-skills-php-min: "8.3" wp-skills-last-updated: "2026-04-29"
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) $valueinside 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 —TypeCoerceris the one engine that MUST stay WP-free so its tests can run without a WP runtime. WP-aware logic goes inDataObject::coerceParameteror in the source. - "I'll add the
Encrypteddecryption toTypeCoercer." Wrong layer — attribute-aware coercion lives ABOVETypeCoercerinDataObject::coerceParameter(src/DataObject.php:168). The pattern is: handle the attribute (decrypt, walk the list), then callTypeCoercer::coercewith 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.phporsrc/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
TypeCoercionExceptionat runtime and triaging.
Workflow
1. Choose the layer
| Change type | Layer |
|---|---|
| New primitive (decimal type, IPv4 stored as string <-> int) | TypeCoercer (pure) |
New WP-builtin handling (e.g. coerce WP_Term to a term ID) | TypeCoercer (still pure — WP_Term is just a class shape; check instanceof doesn't require WP runtime) |
New attribute affects coercion (#[Slug] lowercase before string-coerce) | DataObject::coerceParameter (above TypeCoercer) |
| New attribute affects encryption / list coercion | DataObject::coerceParameter |
The acid test: "Can my code run inside a unit test that does NOT bootstrap WordPress?" If yes, it can live in TypeCoercer. If no (calls wp_remote_get, reads $wpdb, looks up WP_User), it must live elsewhere.
2. Adding a primitive coercion
Inside TypeCoercer::coerce (src/Internal/TypeCoercer.php:83-88):
return match ($targetTypeName) {
'string' => self::toString(...),
'int' => self::toInt(...),
'float' => self::toFloat(...),
'bool' => self::toBool(...),
'array' => self::toArray(...),
// your new branch:
'decimal' => self::toDecimal($dataObjectClass, $fieldName, $value),
default => throw TypeCoercionException::unsupportedType(...),
};
The helper:
private static function toDecimal(string $cls, string $field, mixed $value): Decimal
{
if ($value instanceof Decimal) {
return $value;
}
if (is_string($value) && \preg_match('/^-?\d+(\.\d+)?$/', $value)) {
return new Decimal($value);
}
if (is_int($value) || is_float($value)) {
return new Decimal((string) $value);
}
throw TypeCoercionException::for($cls, $field, 'decimal', $value);
}
Three rules:
- Accept the type-as-input shortcut.
$value instanceof Decimalreturns it unchanged — caller passes back what they got. - Convert from common neighbors. Decimal accepts strings, ints, floats; rejects arrays, booleans, objects of other types.
- Throw
TypeCoercionException::for(...)with class + field + target + offending value when nothing matches.
3. Adding an attribute-aware coercion
Inside DataObject::coerceParameter (src/DataObject.php:168-220) BEFORE the TypeCoercer::coerce final delegation:
private static function coerceParameter(ReflectionParameter $parameter, mixed $value): mixed
{
// Existing #[Encryp
Read the complete source ↗