wp-gravity-forms

Gravity Forms

为 WordPress 提供结构化表单处理和事务性输入。Gravity Forms 是 Gravity 技术栈中的主要数据收集端点，将条目传送至 SMTP 投递、GravityView 显示、Gravity Connect AI 处理和 GravityKit 工作流。

适用场景

• 通过 wp gf 安装、更新或验证 Gravity Forms 或官方扩展
• 从命令行管理表单和条目
• 将表单定义以 JSON 格式纳入版本控制
• 测试通知和确认消息
• 为 AI 机器人配置反垃圾邮件保护（Cloudflare Turnstile）
• 编写基于 GFAPI 的 PHP 代码（不直接写入数据库）
• 为 MCP/AI 流水线序列化表单架构

官方文档

资源	URL
文档主页	https://docs.gravityforms.com/
入门指南	https://docs.gravityforms.com/getting-started/
用户指南	https://docs.gravityforms.com/category/user-guides/
Gravity Forms 3.0 测试版	https://docs.gravityforms.com/category/user-guides/
WP-CLI 参考	https://docs.gravityforms.com/manage-gravity-forms-and-add-ons-with-wpcli/
扩展别名	https://docs.gravityforms.com/gravity-forms-add-on-slugs/
开发者 API（GFAPI）	https://docs.gravityforms.com/api-functions
开发者文档	https://docs.gravityforms.com/category/developers/
钩子和筛选器	https://docs.gravityforms.com/category/developers/hooks/
表单对象	https://docs.gravityforms.com/form-object
条目对象	https://docs.gravityforms.com/entry-object
字段对象	https://docs.gravityforms.com/field-object
合并标签	https://docs.gravityforms.com/category/user-guides/merge-tags-getting-started/
条件逻辑	https://docs.gravityforms.com/category/user-guides/conditional-logic/
垃圾信息与防护	https://docs.gravityforms.com/category/user-guides/spam-detection-and-protection/
扩展框架	https://docs.gravityforms.com/category/developers/php-api/add-on-framework/
REST API	https://docs.gravityforms.com/category/developers/rest-api/
演示	https://www.gravityforms.com/gravity-forms-demo/
定价和许可证	https://www.gravityforms.com/pricing/

GitHub

仓库	用途
gravityforms/gravityformscli	官方 WP-CLI 扩展（wp gf 命令）
gravitywiz/snippet-library	用于 AI 训练的 1000+ 个社区钩子和筛选器

• https://github.com/gravityforms/gravityformscli
• https://github.com/gravitywiz/snippet-library

---

操作流程

0) 安全准则

• 始终使用 GFAPI，绝不直接写入 wp_rg_lead_* 表
• 在 wp-config.php 中设置 GF_LICENSE_KEY，不要将其作为 CLI 参数
• 每次安装/更新后，运行 wp gf setup --force 以应用数据库迁移
• 运行 wp gf version gravitysmtp 并检查 CVE-2026-4020，参见 wp-gravity-smtp 技能

1) 安装和验证

# Requires GF_LICENSE_KEY constant in wp-config.php:
# define('GF_LICENSE_KEY', 'your-key-here');

wp gf install --force --activate
wp gf install gravityformscli --activate
wp gf install gravitysmtp --activate      # ⚠️  verify version ≥ 2.1.5 immediately
wp gf install gravityformsturnstile --activate
wp gf install gravityformsuserregistration --activate
wp gf install gravityformswebhooks --activate
wp gf setup --force
wp gf version

2) 表单管理

wp gf form list --active --format=table
wp gf form export 1 --path=./forms/contact-form.json   # commit to git
wp gf form import ./forms/contact-form.json
wp gf form duplicate 1

# Export all forms
mkdir -p forms
for id in $(wp gf form list --format=ids); do
  wp gf form export $id --path=forms/form-${id}.json
done

3) 条目管理

wp gf entry list --form_id=1 --status=active --format=table
wp gf entry get 42 --format=json
wp gf entry export 1 --dir=./exports --format=csv
wp gf entry export 1 --dir=./exports --start_date=2026-01-01
wp gf entry notification get 42 --event=form_submission   # test notifications

4) GFAPI — 正确的 PHP 模式

// ✅ Always use GFAPI
$entry  = GFAPI::get_entry($entry_id);
$form   = GFAPI::get_form($form_id);
$result = GFAPI::add_entry($entry_data);
GFAPI::update_entry($entry);

// ❌ Never write directly to wp_rg_lead_* tables
global $wpdb;
$wpdb->update('wp_rg_lead', [...]); // never

5) 兼容 MCP 的 JSON 架构

$form   = GFAPI::get_form(1);
$schema = ['form_id' => $form['id'], 'title' => $form['title'],
    'fields' => array_map(fn($f) => [
        'id' => $f->id, 'label' => $f->label,
        'type' => $f->type, 'required' => $f->isRequired,
        'choices' => $f->choices ?? null,
    ], $form['fields'])];
file_put_contents(ABSPATH . 'llms-form-schema.json', json_encode($schema, JSON_PRETTY_PRINT));

6) AI 机器人的反垃圾邮件保护

wp gf install gravityformsturnstile --activate
# Configure: Forms → Settings → Turnstile → "Managed" mode

7) 远程管理（WP Engine）

wp @production gf check-update
wp @production gf update
wp @production gf setup --force --skip-plugins --skip-themes
wp @production cache flush --skip-plugins --skip-themes

---

Agent 脚本

bash {baseDir}/scripts/gf-inspect.sh             # local audit
bash {baseDir}/scripts/gf-inspect.sh --remote    # WP Engine via SSH

参考资料

• references/gravity-forms-cli.md — 完整的 wp gf 命令参考
• wp-gravity-smtp 技能 — SMTP 投递和 CVE-2026-4020
• wp-gravity-connect 技能 — OpenAI 集成
• wp-gravityview 技能 — 前端条目显示
• wp-gravity-wiz 技能 — Spellbook、Perks、GP Populate Anything
• wp-wpcli-and-ops 技能 — 通用 WP-CLI 模式