跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
数据与分析

bd-hydration-coercion

Modify how raw values become typed property values in

Lonsdale201 · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add Lonsdale201/wp-agent-skills --skill bd-hydration-coercion

技能说明


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

Workflow

1. Choose the layer

Change typeLayer
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 coercionDataObject::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:

  1. Accept the type-as-input shortcut. $value instanceof Decimal returns it unchanged — caller passes back what they got.
  2. Convert from common neighbors. Decimal accepts strings, ints, floats; rejects arrays, booleans, objects of other types.
  3. 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
阅读完整来源 ↗