bd-source-adapter
Add a new source adapter to better-data — code that reads from a WordPress data store the library doesn't cover yet (comments, attachments, transients, custom tables). Mirror the canonical shape PostSource / UserSource / TermSource use — a non-final class with static hydrate(int|object, $dtoClass) and hydrateMany(int[], $dtoClass) methods. Critical contract — the meta fetcher closure passed to the AttributeDrivenHydrator must return null when the meta key does not exist (use metadata_exists guard) and the stored value otherwise. Without this guard you cannot distinguish "missing meta → use default" from "stored empty string → preserve emptiness", and Reflection-default fallback breaks. Bulk hydration must prewarm caches with the equivalent of update_meta_cache + (where applicable) _prime_post_caches. Use when integrating a new WP store. Triggers on creating a class in src/Source/, hydrate / hydrateMany method signatures, references to AttributeDrivenHydrator from a source.
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-source-adapterAbout this skill
name: bd-source-adapter description: Add a new source adapter to better-data — code that reads from a WordPress data store the library doesn't cover yet (comments, attachments, transients, custom tables). Mirror the canonical shape PostSource / UserSource / TermSource use — a non-final class with static hydrate(int|object, $dtoClass) and hydrateMany(int[], $dtoClass) methods. Critical contract — the meta fetcher closure passed to the AttributeDrivenHydrator must return null when the meta key does not exist (use metadata_exists guard) and the stored value otherwise. Without this guard you cannot distinguish "missing meta → use default" from "stored empty string → preserve emptiness", and Reflection-default fallback breaks. Bulk hydration must prewarm caches with the equivalent of update_meta_cache + (where applicable) _prime_post_caches. Use when integrating a new WP store. Triggers on creating a class in src/Source/, hydrate / hydrateMany method signatures, references to AttributeDrivenHydrator from a source. 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 source adapter
For library maintainers integrating a new WordPress data store with better-data — comments, attachments, transients, custom tables, taxonomy hierarchies. Sources hydrate stored data into typed DataObjects via AttributeDrivenHydrator; the work is wiring up the bridge between WP's storage idioms and the hydrator's closure contract.
Misconception this skill corrects
"I'll call
get_post_meta($id, $key, true)directly — empty string means 'not set'."
Wrong. WordPress get_meta($key, true) returns '' (empty string) for both "key does not exist" AND "key exists with empty-string value". The AttributeDrivenHydrator distinguishes these because the default-value fallback at src/Internal/AttributeDrivenHydrator.php:90-95 needs to know "missing → use the parameter's default" vs "present-but-empty → coerce as empty string". Without the distinction, every nullable meta-backed field with a non-null default falls back incorrectly.
The contract: the closure you pass to the hydrator returns:
null→ key does not exist (hydrator falls back to parameter default / parameter nullable)- the stored value (including
'') → key exists, hydrator coerces
Verified pattern from src/Source/PostSource.php:91-93:
if (\function_exists('metadata_exists')
&& !\metadata_exists('post', $postId, $key)) {
return null; // key does not exist
}
return \get_post_meta($postId, $key, true); // exists; could be ''
Other AI-prone misconceptions:
- "I'll instantiate
WP_Userdirectly withnew WP_User($id)in a hot loop." Wrong — bypasses object cache. Useget_user_by('id', $id)so the per-request cache participates. - "Bulk hydration is just
array_map($id => hydrate($id))." Wrong — without prewarming, that's N+1 queries. Always callupdate_meta_cache(...)(and_prime_post_cachesfor posts) first. - "I'll write the WP-touching code in
src/Internal/." Wrong —src/Internal/is the WP-free engine zone (so it's unit-testable without a WP runtime). Source adapters live insrc/Source/and CAN call WP functions.
When to use this skill
Trigger when ANY of the following is true:
- Creating a new file under
src/Source/. - The diff adds a
hydrate(...)/hydrateMany(...)method that reads from a WP table. - Adding a
::fromComment($id)/::fromAttachment($id)etc. shortcut toHasWpSources. - Reviewing a PR that calls
get_*_meta($key, true)without ametadata_existsguard inside a source.
Workflow
1. File location
Public source adapter: src/Source/<Name>Source.php. The pure, WP-free engine that does the attribute-driven work already lives in src/Internal/AttributeDrivenHydrator.php — DON'T duplicate it. Your job is to feed the hydrator a fetcher closure.
2. Method shape — match the existing sources
Every source has the same two static methods:
public static function hydrate(int|\WP_Comment $record, string $dtoClass): DataObject;
/**
* @template T of DataObject
* @param list<int> $ids
* @param class-string<T> $dtoClass
* @return list<T>
*/
public static function hydrateMany(array $ids, string $dtoClass): array;
Why static: the source has no per-instance state. Why this exact shape: HasWpSources wires Dto::fromComment($id) to CommentSource::hydrate($id, static::class); deviating breaks the trait contract.
3. The fetcher closure contract
Every source ends up calling (or fakes a call to) AttributeDrivenHydrator::hydrate($dtoClass, $primary, $metaFetcher). The third arg is a closure:
$metaFetcher = static function (string $key) use ($commentId): mixed {
if (\function_exists('metadata_exists')
&& !\metadata_exists('comment', $commentId, $key)) {
return null; // CRUCIAL — distinguishes missing from empty
}
return \get_comment_meta($commentId, $key, true);
};
Without the metadata_exists guard, the closure returns '' for both missing and stored-empty, and the hydrator can't apply default-fallback logic correctly.
4. Bulk path: prewarm caches first
public static function hydrateMany(array $commentIds, string $dtoClass): array
{
if ($commentIds === []) {
return [];
}
// Prewarm WP's per-request comment cache.
if (\function_exists('_prime_comment_caches')) {
\_prime_comment_caches($commentIds);
}
// Prewarm meta cache (single SELECT for all comments × all keys).
if (\function_exists('update_meta_cache')) {
\update_meta_cache('comment', $commentIds);
}
return \array_map(
static fn (int $id): DataObject => self::hydrate($id, $dtoClass),
$
Read the complete source ↗