wp-pods

Pods Framework

Pods は、WordPress のカスタムコンテンツタイプ（CPT）、タクソノミー、カスタムデータベーステーブル（Advanced Content Types）を管理します。U of Digital サイトの主要なデータ構造レイヤーです。カスタムコンテンツモデル、フィールド定義、リレーショナルデータはすべて Pods を介して処理されます。

使用する場面

• カスタム投稿タイプまたはタクソノミーを作成・変更する
• Pods カスタムフィールドを扱う（読み取り、書き込み、シード、同期）
• Pods が管理するデータをクエリする PHP を記述する（必ず最初に ACT か postmeta かを宣言する）
• コンテンツタイプ間の双方向リレーションシップを設定する
• Pods フィールドを WordPress REST API または Abilities API に公開する
• Pods を Gravity Forms と統合する（pods-gravity-forms アドオン）
• 特定の Pod に適したクエリ方法について AI アシスタントに助言する

⚠️ 重要 — AI エージェントには必ずストレージタイプを宣言してください

Pods データに触れるコードを少しでも記述する前に、その Pod が使用するストレージタイプを AI アシスタントに宣言してください。

ストレージタイプ	DB の場所	クエリ方法
postmeta（デフォルト）	wp_postmeta	WP_Query、get_post_meta()、pods_field()
ACT（Advanced Content Type）	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 エージェントを介してリレーションシップフィールドをシードまたは同期する場合：

// ✅ 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