claude-plugin-wordpress-manager 1.4.0 → 1.7.0

package/skills/wp-headless/references/webhooks.md

@@ -0,0 +1,277 @@
+# Content Webhooks
+
+Use this file when implementing webhooks to keep a headless frontend in sync with WordPress content changes.
+
+## Why webhooks
+
+In a headless setup, the frontend caches content (SSG/ISR). When editors publish or update content in WordPress, the frontend must be notified to rebuild or revalidate the affected pages.
+
+```
+Editor publishes post → WordPress fires webhook → Frontend revalidates page
+```
+
+## WordPress webhook implementation
+
+### Using action hooks
+
+```php
+// mu-plugins/headless-webhooks.php
+
+add_action('transition_post_status', 'headless_notify_frontend', 10, 3);
+add_action('edited_term', 'headless_notify_frontend_term', 10, 3);
+add_action('wp_update_nav_menu', 'headless_notify_frontend_menu');
+
+function headless_notify_frontend($new_status, $old_status, $post) {
+    // Only fire for published/updated/unpublished content
+    $trigger_statuses = ['publish', 'trash'];
+    if (!in_array($new_status, $trigger_statuses) && !in_array($old_status, $trigger_statuses)) {
+        return;
+    }
+
+    // Skip revisions and autosaves
+    if (wp_is_post_revision($post) || wp_is_post_autosave($post)) {
+        return;
+    }
+
+    $path = get_permalink_path($post);
+    send_revalidation_webhook($path, [
+        'action'    => 'post_updated',
+        'post_id'   => $post->ID,
+        'post_type' => $post->post_type,
+        'slug'      => $post->post_name,
+        'status'    => $new_status,
+    ]);
+}
+
+function headless_notify_frontend_term($term_id, $tt_id, $taxonomy) {
+    $term = get_term($term_id, $taxonomy);
+    send_revalidation_webhook("/category/{$term->slug}", [
+        'action'   => 'term_updated',
+        'term_id'  => $term_id,
+        'taxonomy' => $taxonomy,
+        'slug'     => $term->slug,
+    ]);
+}
+
+function headless_notify_frontend_menu($menu_id) {
+    send_revalidation_webhook('/', [
+        'action'  => 'menu_updated',
+        'menu_id' => $menu_id,
+    ]);
+}
+
+function get_permalink_path($post) {
+    $permalink = get_permalink($post);
+    $parsed = wp_parse_url($permalink);
+    return $parsed['path'] ?? '/';
+}
+
+function send_revalidation_webhook($path, $payload = []) {
+    $webhook_url = defined('HEADLESS_WEBHOOK_URL')
+        ? HEADLESS_WEBHOOK_URL
+        : '';
+
+    $webhook_secret = defined('HEADLESS_WEBHOOK_SECRET')
+        ? HEADLESS_WEBHOOK_SECRET
+        : '';
+
+    if (!$webhook_url) return;
+
+    $body = array_merge($payload, ['path' => $path]);
+
+    wp_remote_post($webhook_url, [
+        'timeout' => 5,
+        'headers' => [
+            'Content-Type'        => 'application/json',
+            'X-Revalidate-Secret' => $webhook_secret,
+        ],
+        'body' => wp_json_encode($body),
+    ]);
+}
+```
+
+### wp-config.php constants
+
+```php
+define('HEADLESS_WEBHOOK_URL', 'https://app.example.com/api/revalidate');
+define('HEADLESS_WEBHOOK_SECRET', 'your-shared-secret-here');
+```
+
+## Frontend webhook receivers
+
+### Next.js (App Router)
+
+```js
+// app/api/revalidate/route.js
+import { revalidatePath, revalidateTag } from 'next/cache';
+
+export async function POST(request) {
+    const secret = request.headers.get('x-revalidate-secret');
+    if (secret !== process.env.REVALIDATE_SECRET) {
+        return Response.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    const body = await request.json();
+    const { action, path, post_type, slug } = body;
+
+    // Revalidate the specific page
+    if (path) {
+        revalidatePath(path);
+    }
+
+    // Revalidate related pages
+    switch (action) {
+        case 'post_updated':
+            revalidatePath('/blog'); // blog listing
+            if (post_type === 'post') {
+                revalidatePath(`/blog/${slug}`);
+            }
+            break;
+        case 'term_updated':
+            revalidatePath('/blog'); // categories affect listings
+            break;
+        case 'menu_updated':
+            revalidatePath('/', 'layout'); // menus are in layout
+            break;
+    }
+
+    return Response.json({
+        revalidated: true,
+        path,
+        action,
+        timestamp: Date.now(),
+    });
+}
+```
+
+### Nuxt 3
+
+```js
+// server/api/revalidate.post.js
+export default defineEventHandler(async (event) => {
+    const secret = getHeader(event, 'x-revalidate-secret');
+    if (secret !== process.env.REVALIDATE_SECRET) {
+        throw createError({ statusCode: 401, message: 'Unauthorized' });
+    }
+
+    const body = await readBody(event);
+
+    // Clear Nuxt cache for the path
+    // For Nitro with built-in caching:
+    const storage = useStorage('cache');
+    await storage.clear(); // or selectively clear by path
+
+    return { revalidated: true, path: body.path };
+});
+```
+
+### Astro (with SSR adapter)
+
+```js
+// src/pages/api/revalidate.js
+export async function POST({ request }) {
+    const secret = request.headers.get('x-revalidate-secret');
+    if (secret !== import.meta.env.REVALIDATE_SECRET) {
+        return new Response(JSON.stringify({ error: 'Unauthorized' }), { status: 401 });
+    }
+
+    // Astro SSG: trigger rebuild via deployment hook
+    const body = await request.json();
+
+    // Example: trigger Vercel deploy hook
+    if (import.meta.env.VERCEL_DEPLOY_HOOK) {
+        await fetch(import.meta.env.VERCEL_DEPLOY_HOOK, { method: 'POST' });
+    }
+
+    return new Response(JSON.stringify({ revalidated: true }));
+}
+```
+
+## Deployment platform hooks
+
+### Vercel
+
+```php
+// WordPress: trigger Vercel deploy on major changes
+function trigger_vercel_deploy() {
+    $hook_url = defined('VERCEL_DEPLOY_HOOK') ? VERCEL_DEPLOY_HOOK : '';
+    if (!$hook_url) return;
+
+    wp_remote_post($hook_url, ['timeout' => 5]);
+}
+add_action('save_post', function($post_id, $post) {
+    if ($post->post_status === 'publish' && !wp_is_post_revision($post_id)) {
+        trigger_vercel_deploy();
+    }
+}, 10, 2);
+```
+
+### Netlify
+
+```php
+define('NETLIFY_BUILD_HOOK', 'https://api.netlify.com/build_hooks/YOUR_HOOK_ID');
+
+function trigger_netlify_build() {
+    wp_remote_post(NETLIFY_BUILD_HOOK, ['timeout' => 5]);
+}
+```
+
+## WP-CLI webhook testing
+
+```bash
+# Simulate a webhook fire
+wp eval "do_action('transition_post_status', 'publish', 'draft', get_post(1));"
+
+# Test webhook endpoint manually
+curl -X POST https://app.example.com/api/revalidate \
+  -H "Content-Type: application/json" \
+  -H "X-Revalidate-Secret: your-shared-secret" \
+  -d '{"action":"post_updated","path":"/blog/hello-world","slug":"hello-world"}'
+```
+
+## Using WP Webhooks plugin (alternative)
+
+For non-developers or complex workflows:
+
+```bash
+wp plugin install wp-webhooks --activate
+```
+
+The plugin provides a UI for configuring webhook endpoints, triggers, and authentication.
+
+## Security
+
+1. **Always use a shared secret** — validate on the receiver side
+2. **Use HTTPS** — webhook payloads may contain content data
+3. **Rate limit** — debounce rapid-fire saves (WordPress autosave triggers frequently)
+4. **Timeout** — set short timeouts (5s) to avoid blocking WordPress
+5. **Async processing** — use `wp_schedule_single_event` for non-critical webhooks
+
+### Debouncing
+
+```php
+function send_revalidation_webhook_debounced($path, $payload = []) {
+    $key = 'webhook_debounce_' . md5($path);
+
+    // Skip if webhook was sent for this path in the last 10 seconds
+    if (get_transient($key)) return;
+
+    set_transient($key, true, 10);
+    send_revalidation_webhook($path, $payload);
+}
+```
+
+## Verification
+
+```bash
+# Check webhook constant is defined
+wp config get HEADLESS_WEBHOOK_URL
+
+# Test webhook fires on post save
+wp post update 1 --post_title="Webhook Test $(date +%s)"
+# Check frontend logs for incoming webhook
+
+# Verify revalidation worked
+curl -s -o /dev/null -w "%{http_code}" https://app.example.com/blog/hello-world
+# Should return 200 with updated content
+```

package/skills/wp-headless/references/wpgraphql.md

@@ -0,0 +1,331 @@
+# WPGraphQL
+
+Use this file when setting up and using WPGraphQL for headless WordPress.
+
+## Installation
+
+```bash
+wp plugin install wp-graphql --activate
+
+# Verify
+wp graphql --help
+curl -s http://localhost:8888/graphql -H "Content-Type: application/json" \
+  -d '{"query": "{ generalSettings { title } }"}' | jq
+```
+
+GraphQL IDE: `http://localhost:8888/wp-admin/admin.php?page=graphiql-ide`
+
+## Common queries
+
+### Posts
+
+```graphql
+# List posts with pagination
+query GetPosts($first: Int = 10, $after: String) {
+  posts(first: $first, after: $after) {
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+    nodes {
+      id
+      databaseId
+      title
+      slug
+      date
+      excerpt
+      content
+      uri
+      featuredImage {
+        node {
+          sourceUrl(size: LARGE)
+          altText
+          mediaDetails {
+            width
+            height
+          }
+        }
+      }
+      author {
+        node {
+          name
+          avatar {
+            url
+          }
+        }
+      }
+      categories {
+        nodes {
+          name
+          slug
+        }
+      }
+      tags {
+        nodes {
+          name
+          slug
+        }
+      }
+    }
+  }
+}
+```
+
+### Single post by slug
+
+```graphql
+query GetPost($slug: ID!) {
+  post(id: $slug, idType: SLUG) {
+    title
+    content
+    date
+    modified
+    seo {
+      title
+      metaDesc
+      opengraphImage {
+        sourceUrl
+      }
+    }
+    author {
+      node {
+        name
+        description
+      }
+    }
+  }
+}
+```
+
+### Pages
+
+```graphql
+query GetPage($uri: String!) {
+  pageBy(uri: $uri) {
+    title
+    content
+    template {
+      templateName
+    }
+    children {
+      nodes {
+        ... on Page {
+          title
+          uri
+        }
+      }
+    }
+  }
+}
+```
+
+### Menus
+
+```graphql
+query GetMenu {
+  menus(where: { location: PRIMARY }) {
+    nodes {
+      menuItems(first: 50) {
+        nodes {
+          id
+          label
+          url
+          parentId
+          cssClasses
+          target
+        }
+      }
+    }
+  }
+}
+```
+
+### Custom Post Types
+
+```php
+// Register CPT with GraphQL support
+register_post_type('product', [
+    'label'               => 'Products',
+    'public'              => true,
+    'show_in_graphql'     => true,
+    'graphql_single_name' => 'product',
+    'graphql_plural_name' => 'products',
+]);
+```
+
+```graphql
+query GetProducts {
+  products(first: 12) {
+    nodes {
+      title
+      slug
+      productFields {   # ACF field group
+        price
+        sku
+      }
+    }
+  }
+}
+```
+
+### Custom Taxonomies
+
+```php
+register_taxonomy('product_category', 'product', [
+    'label'               => 'Product Categories',
+    'show_in_graphql'     => true,
+    'graphql_single_name' => 'productCategory',
+    'graphql_plural_name' => 'productCategories',
+]);
+```
+
+## ACF integration
+
+```bash
+wp plugin install wpgraphql-acf --activate
+```
+
+ACF fields are automatically exposed when the field group's "Show in GraphQL" setting is enabled.
+
+```graphql
+query GetPostWithACF {
+  post(id: "hello-world", idType: SLUG) {
+    title
+    customFields {       # ACF field group name (camelCase)
+      subtitle
+      heroImage {
+        sourceUrl
+        altText
+      }
+      features {         # Repeater field
+        title
+        description
+      }
+    }
+  }
+}
+```
+
+## Custom resolvers
+
+```php
+// Add custom field to existing type
+add_action('graphql_register_types', function() {
+    register_graphql_field('Post', 'readingTime', [
+        'type'        => 'Int',
+        'description' => 'Estimated reading time in minutes',
+        'resolve'     => function($post) {
+            $content = get_post_field('post_content', $post->databaseId);
+            $word_count = str_word_count(strip_tags($content));
+            return max(1, ceil($word_count / 200));
+        },
+    ]);
+});
+
+// Add custom root query
+add_action('graphql_register_types', function() {
+    register_graphql_field('RootQuery', 'siteOptions', [
+        'type'        => 'SiteOptions',
+        'description' => 'Global site options',
+        'resolve'     => function() {
+            return [
+                'phone'   => get_option('site_phone'),
+                'address' => get_option('site_address'),
+            ];
+        },
+    ]);
+
+    register_graphql_object_type('SiteOptions', [
+        'fields' => [
+            'phone'   => ['type' => 'String'],
+            'address' => ['type' => 'String'],
+        ],
+    ]);
+});
+```
+
+## Mutations
+
+```graphql
+# Create a comment (authenticated)
+mutation CreateComment($input: CreateCommentInput!) {
+  createComment(input: $input) {
+    success
+    comment {
+      id
+      content
+      date
+      author {
+        node {
+          name
+        }
+      }
+    }
+  }
+}
+```
+
+Variables:
+```json
+{
+  "input": {
+    "commentOn": 1,
+    "content": "Great post!",
+    "author": "John"
+  }
+}
+```
+
+## Performance
+
+### Query complexity limits
+
+WPGraphQL enforces query depth and complexity limits by default.
+
+```php
+// Adjust limits in wp-config.php or plugin
+add_filter('graphql_max_query_amount', function() {
+    return 100; // max nodes per query (default: 100)
+});
+```
+
+### Persisted queries
+
+```php
+// Register a persisted query
+add_action('graphql_register_types', function() {
+    register_graphql_query_alias('homepage', '
+        query Homepage {
+            posts(first: 6) { nodes { title slug excerpt } }
+            menus(where: { location: PRIMARY }) { nodes { menuItems { nodes { label url } } } }
+        }
+    ');
+});
+```
+
+### Object caching
+
+WPGraphQL integrates with WordPress object cache. Use Redis or Memcached for production:
+
+```bash
+wp plugin install wp-graphql-smart-cache --activate
+```
+
+## Verification
+
+```bash
+# Test GraphQL endpoint
+curl -s http://localhost:8888/graphql \
+  -H "Content-Type: application/json" \
+  -d '{"query": "{ posts(first: 1) { nodes { title } } }"}' | jq
+
+# Check schema introspection
+curl -s http://localhost:8888/graphql \
+  -H "Content-Type: application/json" \
+  -d '{"query": "{ __schema { types { name } } }"}' | jq '.data.__schema.types | length'
+
+# Verify CPT is registered in schema
+curl -s http://localhost:8888/graphql \
+  -H "Content-Type: application/json" \
+  -d '{"query": "{ __type(name: \"Product\") { name fields { name } } }"}' | jq
+```