wp-pods

Pods Framework

Pods manages WordPress custom content types (CPTs), taxonomies, and custom database tables (Advanced Content Types). It is the primary data structure layer for the U of Digital site — all custom content models, field definitions, and relational data flow through Pods.

When to use

Creating or modifying custom post types or taxonomies
Working with Pods custom fields (reading, writing, seeding, syncing)
Writing PHP that queries Pods-managed data (always declare ACT vs postmeta first)
Setting up bi-directional relationships between content types
Exposing Pods fields to the WordPress REST API or Abilities API
Integrating Pods with Gravity Forms (pods-gravity-forms add-on)
Advising an AI assistant on the correct query approach for a given Pod

⚠️ Critical — always declare storage type to AI agents

Before writing any code that touches Pods data, declare to your AI assistant which storage type the Pod uses:

Storage type	DB location	Query method
postmeta (default)	`wp_postmeta`	`WP_Query`, `get_post_meta()`, `pods_field()`
ACT (Advanced Content Type)	`wp_pods_<name>` (custom table)	`pods_field()` only — never `get_post_meta()`

Rule: Never use get_post_meta() on an ACT Pod — it queries the wrong table and silently returns nothing.

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"

Official documentation

Resource	URL
Docs home	https://pods.io/docs/
Quick starts	https://pods.io/docs/build/
Developer quick start	https://pods.io/docs/build/creating-pods/
Code reference	https://pods.io/docs/code/
pods_field()	https://pods.io/docs/code/pods-field/
Pods API class	https://pods.io/docs/code/pods/
REST API integration	https://pods.io/docs/build/rest-api/
WordPress.org plugin	https://wordpress.org/plugins/pods/

GitHub

Repo	Purpose
`pods-framework/pods`	Core plugin
`pods-framework/pods-gravity-forms`	Gravity Forms integration add-on

Procedure

1) Install

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

# Verify
wp plugin status pods

2) ACT vs postmeta — the critical decision

When creating a new Pod, choose storage type:

postmeta (default): best for standard CPTs with <50 fields. Compatible with most WP tools.
ACT: best for high-volume data, complex relational queries, many fields. Custom table = better performance, less wp_postmeta bloat.

Declare this in any file that handles the Pod's data:

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

3) Correct field access patterns

// ✅ 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) Relationship fields — use IDs, not titles

When seeding or syncing relationship fields via AI agents:

// ✅ 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) Expose Pods to 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 integration

The pods-gravity-forms add-on links form submissions directly to Pods data:

wp plugin install pods-gravity-forms --activate

Maps Gravity Forms fields to Pod fields on submission
Auto-creates or updates Pod items from form entries
Supports relationships — maps multi-select fields to related Pod items
Docs: https://github.com/pods-framework/pods-gravity-forms

7) Exposing to 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'],
]);

Context for AI code generation

Always include this in any prompt where you want code that touches Pods data:

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.

References

wp-gravity-forms skill — Gravity Forms + pods-gravity-forms add-on integration
wp-gravity-stack — SatisPress config, .cursorrules, llms.txt templates
Reference guide: wp-gravity-stack/references/wordpress-ai-gravity-reference.md