Upgrading

Upgrading

From 1.0.0 or earlier — read this first

Releases up to 1.0.0 installed a generated advanced-cache.php that hard-codes the list of runtime files it loads. Later releases moved those files around. When the plugin files are replaced but that old drop-in is still on disk, it loads a class list that no longer matches and raises a fatal from wp-settings.php — before WordPress can catch it, so the front end and wp-admin go down together.

The safe order

Replace the drop-in first, then update. Either:

• Run the repair script before updating: https://gist.github.com/wpgaurav/03d61d313df00b4127db92393ed74681

  php gt-performance-migrate.php /path/to/wordpress          # dry run
  php gt-performance-migrate.php /path/to/wordpress --apply

• Or delete wp-content/advanced-cache.php by hand, update, then sign in to wp-admin once.

If you already updated and the site is down

rm wp-content/advanced-cache.php

That restores the site immediately — an absent drop-in just means no page cache. Sign in to wp-admin once and a correct drop-in is republished.

You cannot fix this with WP-CLI, because WP-CLI boots WordPress and hits the same fatal. It has to be the filesystem.

The build distributed from gauravtiwari.org

That build carries a migrator that handles this automatically when updating from 1.0.4 or later. It cannot help when updating from a version older than itself: WordPress fires the upgrade hook in a request whose plugin code was loaded before the swap, so a version that predates the migrator has nothing registered to run. Coming from 1.0.0, use the repair script.

Renamed constants

Everything moved from GTP_ to GTPERF_ in 1.0.1, with no compatibility shim. If you set any of these in wp-config.php, rename them:

// before                          after
GTP_REDIS_HOST                  →  GTPERF_REDIS_HOST
GTP_CLOUDFLARE_API_TOKEN        →  GTPERF_CLOUDFLARE_API_TOKEN
GTP_XCLOUD_API_TOKEN            →  GTPERF_XCLOUD_API_TOKEN
GTP_FLEET_SIGNING_SECRET        →  GTPERF_FLEET_SIGNING_SECRET
GTP_LICENSE_KEY                 →  GTPERF_LICENSE_KEY   (store build only)

Settings saved in the dashboard need no action. Licenses saved in the dashboard still decrypt.

The Private Islands shortcode also changed:

[gtp_private_island id="cart_count"]      →  [gtperf_private_island id="cart_count"]

If you placed it in post content or a template, update it.

What changes on disk

Before 1.0.1	1.0.1 onward
cache/gt-performance/config.php	config.json.php
cache/gt-performance/redis-config.php	redis-config.json.php
pages/**/<hash>.meta.php	<hash>.meta.json
generated advanced-cache.php	copied from dropins/
tables wp_gtp_*	wp_gtperf_*

Cached pages regenerate on their own. The repair script removes the leftovers.

Version history worth knowing

Version	Why it matters
1.0.5	Uninstall now removes the cache directory when data removal is enabled
1.0.4	Upgrade compatibility code removed; store build gained a migrator
1.0.3	Fixed the License screen's buttons returning a blank page
1.0.2	Fixed every admin button returning a blank page on 1.0.1
1.0.1	Configuration and metadata became inert JSON; drop-in became a copied file; :focus-visible no longer pruned from CSS

If you are on 1.0.1, update — its admin controls do not work.

Related

Architecture · Constants Reference · Troubleshooting