# Cloudflare Edge Cache Setup

Access at **Settings > AjaxPress > Cache**. Requires a Pro license.

## Overview

AjaxPress can deploy a Cloudflare Worker that caches your WordPress pages at Cloudflare's edge network. This serves cached HTML directly from the nearest Cloudflare data center, bypassing your origin server entirely for cached requests.

## Prerequisites

- An active AjaxPress Pro license
- A Cloudflare account with your domain added
- A Cloudflare API token with the following permissions:
  - **Account > Workers Scripts > Edit**
  - **Zone > Workers Routes > Edit**
  - **Zone > Cache Purge > Purge**

## Setup Steps

### 1. Create a Cloudflare API Token

1. Go to [Cloudflare Dashboard > My Profile > API Tokens](https://dash.cloudflare.com/profile/api-tokens)
2. Click **Create Token**
3. Use **Custom Token** template
4. Add the permissions listed above
5. Set Zone Resources to your specific zone or all zones
6. Create the token and copy it

### 2. Connect in AjaxPress

1. Go to **Settings > AjaxPress > Cache**
2. Paste your API token
3. Click **Verify Token**
4. Select your zone (domain) from the list -- AjaxPress auto-detects the matching zone
5. Click **Deploy**

### 3. Verify Deployment

After deployment, the status panel shows:
- Connection status (green = connected)
- Zone name and route pattern
- Worker name (`ajaxpress-cache`)

Test by visiting your site and checking the response headers for `X-AjaxPress-Cache`:
- `HIT` -- Served from edge cache
- `MISS` -- Fetched from origin (will be cached for next request)
- `BYPASS` -- Request matched a bypass rule

## Cache Management

### Auto-Purge

**Setting:** `cf_auto_purge`

When enabled, the cache is automatically purged when content changes in WordPress:

- Post create/update/delete/trash
- Term (category/tag) edit/delete
- Comment add/edit/approve/unapprove

Related URLs are collected (post permalink, archives, author page, home page) and purged in a single batch.

### Manual Purge

**Admin Bar:** When connected, the admin bar shows a cache menu:
- **Purge This Page** -- Purges the current URL
- **Purge All Cache** -- Purges the entire zone

**Settings Page:** The Cache status panel includes a "Purge All" button.

**PHP:** Use the global helper from themes or plugins:

```php
// Purge specific pages
ajaxpress_purge_cache(['https://example.com/page/']);

// Purge everything
ajaxpress_purge_cache();
```

### Bypass Rules

#### URL Patterns

**Setting:** `cf_bypass_patterns`

URL patterns (one per line) that should never be cached. The worker checks each request URL against these patterns.

Example:
```
/cart
/checkout
/my-account
/members
```

#### Cookie Bypass

**Setting:** `cf_bypass_cookies`

Cookie names (one per line) that indicate the request should bypass cache. If any listed cookie is present, the response is served fresh from origin.

By default, WordPress authentication cookies (`wordpress_logged_in_*`, `wp-settings-*`, `wordpress_sec_*`) always bypass cache.

## Teardown

To disconnect Cloudflare caching:

1. Go to **Settings > AjaxPress > Cache**
2. Click **Disconnect** or **Teardown**
3. This removes the worker script, deletes the route, and clears all stored Cloudflare settings

Always teardown before uninstalling the plugin to clean up Cloudflare resources.

## Troubleshooting

**Token verification fails:**
- Ensure the token has the correct permissions (Workers Scripts, Workers Routes, Cache Purge)
- Check that the token hasn't expired
- Verify the token is for the correct account

**Zone not detected:**
- Your WordPress site URL must match a zone in your Cloudflare account
- Subdomain sites are supported (e.g., `blog.example.com` matches zone `example.com`)

**Pages not caching:**
- Check for bypass cookies (logged-in users are always bypassed)
- Verify the URL doesn't match a bypass pattern
- Static assets (.js, .css, images) are intentionally not cached by the worker
- Check the `X-AjaxPress-Cache` response header for the bypass reason