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

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 · 已有静态检查记录

安装与使用

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

npx skills add Lonsdale201/wp-agent-skills --skill bd-source-adapter

技能说明


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_User directly with new WP_User($id) in a hot loop." Wrong — bypasses object cache. Use get_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 call update_meta_cache(...) (and _prime_post_caches for 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 in src/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 to HasWpSources.
  • Reviewing a PR that calls get_*_meta($key, true) without a metadata_exists guard 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),
        $
阅读完整来源 ↗