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

bd-sink

Add a new sink to better-data — code that writes

Lonsdale201 · 已有静态检查记录

安装与使用

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

npx skills add Lonsdale201/wp-agent-skills --skill bd-sink

技能说明


name: bd-sink description: Add a new sink to better-data — code that writes DataObjects back to a WordPress data store the library doesn't cover yet (comment meta, REST upload, custom taxonomy hierarchy). Mirror PostSink's two-mode shape — projection methods (toArgs / toMeta) return raw arrays for caller-managed writes, convenience methods (insert / update / save) commit everything internally and MUST pass values through wp_slash() because WP's write pipeline calls wp_unslash() on inbound data. Critical contract — null DTO value deletes the meta entry, non-null updates it; encryption MUST route through EncryptionEngine::encrypt symmetrically with the matching source's decrypt; never silently skip encryption (every Phase-8.7 OptionSink Secret bug came from asymmetric write/read). Use when integrating writes for a new WP store. Triggers on creating a class in src/Sink/, toArgs / toMeta / insert / update / save method shape, references to SinkProjection or wp_slash in the diff. 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: Adding a sink

For library maintainers integrating WRITE-side support for a new WordPress data store with better-data — comment meta, attachments, custom taxonomies, plugin-specific tables. The shape is set by PostSink and OptionSink; deviating breaks the HasWpSinks trait API and surprises consumers who've internalized the dual projection-vs-convenience model.

Misconception this skill corrects

"I'll write the values directly to update_post_meta — slashing is the caller's problem."

Wrong direction. WordPress's write pipeline calls wp_unslash() on inbound data on the way to the DB. If you pass a raw value through update_post_meta($id, $key, 'a"b') without slashing first, WP unslashes a string with no slashes and stores 'ab' (the " survives, but escaped/quoted values get mangled). Convenience methods (insert, update, save) MUST wp_slash() before calling any WP write function. Verified in src/Sink/PostSink.php:144 ($args = \wp_slash($args);), PostSink.php:183 (\wp_update_post(\wp_slash($args), true)), PostSink.php:191 (\update_post_meta($postId, $key, \wp_slash($value))).

The mirror trap on the projection side: toArgs/toMeta MUST return raw values, NOT pre-slashed. Callers that take projections and pass them to their OWN WP write calls (wp_insert_post) would double-slash and corrupt every backslash on round-trip.

So: convenience slashes, projection does not. The two paths share SinkProjection::prepareValue (src/Internal/SinkProjection.php:193) which handles type-shaping, encryption, and DataObject unwrapping but never slashes.

Other AI-prone misconceptions:

  • "Asymmetric write/read is fine — encrypt on write, store as plain on read." Wrong. Every asymmetric encryption bug in Phase-8.7's OptionSink came from this pattern. If you encrypt, the matching source MUST decrypt.
  • "Storing a DataObject instance with update_post_meta($id, 'thing', $dto) — WP will serialize it." Technically true, but stores a class name in the DB; on class rename or removal you have unrecoverable garbage. Always project through SinkProjection::prepareValue which recurses arrays and turns nested DataObjects into plain arrays.
  • "I'll do my own slashing inside prepareValue." Wrong layer — projection stays raw. Slashing is the boundary concern at the WP-call site.

When to use this skill

Trigger when ANY of the following is true:

  • Creating a new file under src/Sink/.
  • Adding toArgs / toMeta / insert / update / save methods on a sink class.
  • Adding a saveAsX shortcut to HasWpSinks.
  • Reviewing a PR that calls update_*_meta / wp_insert_* directly without wp_slash().
  • Reviewing a PR that adds at-rest encryption to one sink without verifying the matching source decrypts.

Workflow

1. File location

Sinks live in src/Sink/. The pure projection logic (no WP calls) lives in src/Internal/SinkProjection.php — DON'T duplicate it. Your sink delegates type shaping there and adds the WP-specific calls.

2. The two-mode contract

Every sink ships TWO modes that share one projection:

Projection mode (caller drives the write):

public static function toArgs(
    DataObject $dto,
    ?array $only = null,
    bool $strict = false,
    bool $skipNullDeletes = false,
): array;

/**
 * @return array{write: array<string, mixed>, delete: list<string>}
 */
public static function toMeta(
    DataObject $dto,
    ?array $only = null,
    bool $strict = false,
    bool $skipNullDeletes = false,
): array;

toArgs returns the array shape wp_insert_<thing> / wp_update_<thing> accepts. toMeta returns ['write' => [k => v, ...], 'delete' => [k, k, ...]] — split because the meta write loop is "set non-nulls, delete nulls".

Convenience mode (sink drives the write):

public static function insert(DataObject $dto, ?array $only = null, bool $strict = false): int;
public static function update(DataObject $dto, ?array $only = null, bool $strict = false): bool;
public static function save(DataObject $dto, ?array $only = null, bool $strict = false): int;

All three internally call toArgs + toMeta, then issue WP function calls with wp_slash() applied at the boundary. save is the smart router: positive DTO id → update, otherwise insert.

3. Slashing policy — the rule that breaks every refactor

// Inside convenience methods (insert / update / save):
$args = \wp_slash($args);
\wp_insert_post($args, true);

\update_post_meta($postId, $key, \wp_slash($value));

// Inside projection methods (toArgs / toMeta):
return $args;  // RAW, no slashing

Reason ([PostSi

阅读完整来源 ↗