bd-sink
Add a new sink to better-data — code that writes
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-sinkAbout this skill
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
DataObjectinstance withupdate_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 throughSinkProjection::prepareValuewhich recurses arrays and turns nestedDataObjects 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/savemethods on a sink class. - Adding a
saveAsXshortcut toHasWpSinks. - Reviewing a PR that calls
update_*_meta/wp_insert_*directly withoutwp_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
Read the complete source ↗