The Caching Model (SWR)

TableCrafter renders tables instantly by serving cached output and refreshing the source in the background. This page explains the two transient layers, the one-hour cache lifetime, the five-minute stale window, and how to purge the cache.

Why SWR

Most of TableCrafter's data lives on slow third parties: remote JSON APIs, Google Sheets, CSV files, and Airtable. Hitting those on every page view would make your tables wait on someone else's server. The stale-while-revalidate (SWR) strategy avoids that: the first visitor pays the fetch cost, every visitor after that gets the cached HTML immediately, and the cache quietly updates itself in the background once it gets old enough.

The net effect is an instant time-to-first-byte for the [tablecrafter] shortcode while the underlying data still tracks the source within a few minutes.

The Two Cache Layers

TableCrafter keeps two separate caches, both stored as standard WordPress transients (so an object cache like Redis or Memcached is used automatically when present, otherwise the wp_options table).

The HTML cache is what gives you the instant render. The data cache sits one level down and is reused by the AJAX proxy, the background refresher, and the cron warmer so a single fetch can feed several callers.

Cache Lifetime & the Stale Window

Three constants in includes/class-tc-cache.php govern the timing:

The distinction matters: an entry is stale after 5 minutes but expired only after 60 minutes. Between those two marks, TableCrafter keeps serving the stale copy while it refreshes — that is the "stale-while-revalidate" behaviour. Airtable sources cap their data cache at 5 minutes instead of an hour, because Airtable's API enforces tighter rate limits.

How a Request Flows

When the [tablecrafter] shortcode renders, the engine builds a cache key and checks the HTML transient first.

1. Cache miss (cold). The source is fetched synchronously, the table is rendered server-side, and the result is stored under the tc_html_ key for one hour. This is the only request that waits on the source.
2. Cache hit, fresh (< 5 min). The stored HTML is returned as-is. No fetch, no cron.
3. Cache hit, stale (> 5 min, < 1 hour). The stale HTML is still returned immediately, but a one-off background job is scheduled to rebuild it:

   if (time() - $timestamp > (5 * MINUTE_IN_SECONDS)) {
       if (!wp_next_scheduled('tc_refresh_single_source', [$atts])) {
           wp_schedule_single_event(time(), 'tc_refresh_single_source', [$atts]);
       }
   }

   The visitor never sees the fetch — the next visitor gets the refreshed copy.

The HTML cache key is a hash of the source plus the attributes that change the rendered output, so two shortcodes with different settings never collide:

// Distinct cache keys for distinct configurations
[tablecrafter source="https://api.example.com/products.json" include="name,price" sort="price:desc"]
[tablecrafter source="https://api.example.com/products.json" search="true" per_page="25"]

The key folds in source, include, exclude, search, filters, export, per_page, sort, and the plugin version. Note the version is part of every key — upgrading TableCrafter naturally invalidates every cached entry, so you never serve markup from an old release.

Background Refresh & Cache Warming

Two scheduled actions keep caches warm so visitors rarely hit a cold miss:

Source URLs are remembered automatically. Whenever the AJAX proxy fetches a URL, TableCrafter records it in the tc_tracked_urls option (capped at the 50 most recent). The hourly cron walks that list and warms each one, so popular tables stay fresh without anyone waiting.

Manually Purging the Cache

The fastest way to force everything to rebuild is the bundled WP-CLI command:

# Delete every TableCrafter transient (tc_html_, tc_cache_, tc_export_, tc_rate_)
wp tablecrafter clear-cache

# Re-fetch and re-cache all tracked source URLs right now
wp tablecrafter warm-cache

clear-cache reports how many transients it removed. A clean purge-then-rebuild is simply the two commands run back to back. If you do not have shell access, the same effect is reached by:

• Editing the shortcode. Changing any cache-key attribute (include, sort, per_page, etc.) produces a new key, so the old cache is bypassed.
• Updating the plugin. A new TABLECRAFTER_VERSION invalidates every key at once.
• Waiting out the hour. All transients expire on their own after HTML_CACHE_TTL / DATA_CACHE_TTL.

For programmatic control, the TC_Cache singleton exposes the underlying methods used by the CLI: clear_all() (purges every TableCrafter transient and returns the count), clear_source( $url ) (drops the data cache for one source), and warm_cache() (re-fetches all tracked URLs).

// Purge from a plugin, snippet, or a deploy hook
$cache = TC_Cache::get_instance();
$cache->clear_source('https://api.example.com/products.json'); // one source
$removed = $cache->clear_all(); // everything

Server Cache vs. Live Auto-Refresh

Do not confuse the server-side SWR cache with the optional client-side auto-refresh. They are independent. The SWR cache decides how fresh the initial server render is; auto-refresh polls the source from the browser after the page loads, on its own interval.

[tablecrafter source="https://api.example.com/live-scores.json"
             auto_refresh="true" refresh_interval="60000" refresh_countdown="true"]

The indicator's manual button calls refreshNow(), which runs performRefresh() immediately and resets the interval. Auto-refresh smart-pauses while a user is interacting with the table and when the browser tab is hidden, then resumes automatically. Because the browser fetch goes through the same AJAX proxy, it still benefits from the data cache.

Inspecting & Tuning

• Admin path. The dashboard at WordPress Admin → TableCrafter hosts the shortcode generator and live preview; previews render through the same cache and proxy as the front end.
• Find the transients. Look in wp_options for rows whose option_name begins _transient_tc_html_ or _transient_tc_cache_ (or query your object cache) to confirm what is stored.
• Lifetime is fixed. The TTL and stale constants live in includes/class-tc-cache.php; there is no public filter to change them, so override behaviour by purging or by changing cache-key attributes rather than expecting a settings toggle.
• On uninstall. Removing the plugin deletes all tc_* transients and the tc_tracked_urls option, leaving no cache residue behind.

Next, see data-sources.html for how each source type is fetched and parsed before it is cached, and shortcode-reference.html for the full list of attributes that influence the cache key.