wp-pods

Pods Framework

Pods 用于管理 WordPress 自定义内容类型（CPT）、分类法和自定义数据库表（高级内容类型）。它是 U of Digital 网站的主要数据结构层——所有自定义内容模型、字段定义和关联数据都通过 Pods 处理。

适用场景

• 创建或修改自定义文章类型或分类法
• 使用 Pods 自定义字段（读取、写入、填充、同步）
• 编写查询 Pods 管理数据的 PHP 代码（务必先声明使用 ACT 还是 postmeta）
• 为内容类型设置双向关联
• 将 Pods 字段开放给 WordPress REST API 或 Abilities API
• 将 Pods 与 Gravity Forms 集成（pods-gravity-forms 附加组件）
• 为 AI 助手提供针对特定 Pod 选择正确查询方式的建议

⚠️ 关键提示 — 务必向 AI Agent 声明存储类型

编写任何涉及 Pods 数据的代码之前，请向 AI 助手声明 Pod 使用的存储类型：

存储类型	数据库位置	查询方法
postmeta（默认）	wp_postmeta	WP_Query、get_post_meta()、pods_field()
ACT（高级内容类型）	wp_pods_<name>（自定义表）	仅限 pods_field() — 绝不要使用 get_post_meta()

规则：绝不要对 ACT Pod 使用 get_post_meta()——它会查询错误的数据表，并且不会返回任何内容，也不会报错。

Always tell your AI assistant:
"This Pod stores data as an ACT (custom table wp_pods_program)"
OR
"This Pod uses standard wp_postmeta storage"

官方文档

资源	URL
文档主页	https://pods.io/docs/
快速入门	https://pods.io/docs/build/
开发者快速入门	https://pods.io/docs/build/creating-pods/
代码参考	https://pods.io/docs/code/
pods_field()	https://pods.io/docs/code/pods-field/
Pods API 类	https://pods.io/docs/code/pods/
REST API 集成	https://pods.io/docs/build/rest-api/
WordPress.org 插件	https://wordpress.org/plugins/pods/

GitHub

仓库	用途
pods-framework/pods	核心插件
pods-framework/pods-gravity-forms	Gravity Forms 集成附加组件

• https://github.com/pods-framework/pods
• https://github.com/pods-framework/pods-gravity-forms

---

流程

1) 安装

# Free on WordPress.org
wp plugin install pods --activate

# Verify
wp plugin status pods

2) ACT 与 postmeta — 关键决策

创建新 Pod 时，请选择存储类型：

• postmeta（默认）：最适合字段少于 50 个的标准 CPT。兼容大多数 WP 工具。
• ACT：最适合高数据量、复杂关联查询和字段较多的场景。自定义表性能更佳，也能减少 wp_postmeta 膨胀。

在任何处理 Pod 数据的文件中声明这一点：

/**
 * Pod: 'program'
 * Storage: ACT (custom table: wp_pods_program)
 * Query: Use pods_field() — NOT get_post_meta()
 */

3) 正确的字段访问模式

// ✅ Correct for BOTH storage types
$value = pods_field('program', $post_id, 'start_date');

// ✅ Using the Pods object
$pod = pods('program', $post_id);
$value = $pod->field('start_date');

// ❌ WRONG for ACT pods (silently returns nothing)
$value = get_post_meta($post_id, 'start_date', true);

// ❌ WRONG for ACT pods (wrong table)
global $wpdb;
$value = $wpdb->get_var("SELECT start_date FROM wp_postmeta WHERE post_id=$post_id...");

4) 关联字段 — 使用 ID，而非标题

通过 AI Agent 填充或同步关联字段时：

// ✅ Correct — raw arrays of IDs
pods_save('program', [
    'id'              => $program_id,
    'related_courses' => [42, 87, 103],  // IDs only
]);

// ❌ Wrong — text titles break relational integrity
pods_save('program', [
    'related_courses' => 'Course A, Course B',
]);

5) 将 Pods 开放给 REST API

add_action('init', function() {
    register_rest_field('program', 'start_date', [
        'get_callback'    => fn($obj) => pods_field('program', $obj['id'], 'start_date'),
        'update_callback' => fn($val, $obj) => pods_save('program', ['id' => $obj->ID, 'start_date' => $val]),
        'schema'          => ['type' => 'string', 'format' => 'date'],
    ]);
});

6) Pods + Gravity Forms 集成

pods-gravity-forms 附加组件可将表单提交直接关联到 Pods 数据：

wp plugin install pods-gravity-forms --activate

• 在提交时将 Gravity Forms 字段映射到 Pod 字段
• 根据表单条目自动创建或更新 Pod 项目
• 支持关联关系——将多选字段映射到相关 Pod 项目
• 文档：https://github.com/pods-framework/pods-gravity-forms

7) 开放给 WordPress Abilities API

// Allow LLM workflows to read/write Pod data via Abilities API
wp_register_ability('program.read', [
    'description' => 'Read program custom fields',
    'callback'    => fn($args) => pods_field('program', $args['id'], $args['field']),
    'schema'      => ['id' => 'integer', 'field' => 'string'],
]);

---

AI 代码生成的上下文

凡是希望生成涉及 Pods 数据的代码，请在提示词中始终包含以下内容：

Context: This Pod named 'program' uses ACT storage (custom table wp_pods_program).
Use pods_field('program', $post_id, 'field_name') — never get_post_meta().
For relationships, always pass raw integer ID arrays, never text labels.

参考资料

• wp-gravity-forms 技能 — Gravity Forms + pods-gravity-forms 附加组件集成
• wp-gravity-stack — SatisPress 配置、.cursorrules、llms.txt 模板
• 参考指南：wp-gravity-stack/references/wordpress-ai-gravity-reference.md