Altimiser for WordPress

Connects a WordPress site to Altimiser. It implements the receiver protocol, and it is held to that document rather than to the Statamic receiver, with which it shares no code.

It applies the changes Altimiser sends to titles, meta descriptions and Open Graph text, by writing to Yoast SEO's own fields. Without Yoast SEO active a site can still connect, but GET /health advertises no checks, Altimiser reports the gap as receiver.no_seo_plugin, and nothing on the site is changed.

Requirements

WordPress 6.8 or newer, PHP 8.1 or newer, and Yoast SEO for anything to be applied. The plugin has no runtime Composer dependencies, because vendor classes in a plugin can collide with another plugin's copies.

Installing

Put this repository in wp-content/plugins/altimiser and activate the plugin.

Then add a shared secret to wp-config.php, above the line that says to stop editing:

define('ALTIMISER_SECRET', 'a long random string');

With WP-CLI, this generates one and writes it there:

wp config set ALTIMISER_SECRET "$(openssl rand -hex 32)"

Every request is refused until the secret is set, so an install without one is inert rather than open.

Connecting

From Altimiser, using the same secret:

php artisan altimiser:connect https://example.com https://example.com/wp-json/altimiser/v1 <secret>

Use the address the site actually answers at, including https and any www. Altimiser follows redirects, which works for this GET, but a POST that gets redirected arrives as a GET and fails later on.

A successful connection shows the receiver as wordpress with the plugin's version and the WordPress version. Without Yoast SEO active a warning appears: "advertises no checks".

Connect again after activating Yoast SEO, so Altimiser reads what the site can now apply.

What gets changed

These are written to the post, page, custom post type or taxonomy term the URL belongs to. A shared template is never edited and a meta title is never written to post_title.

canonical.missing is left to a developer. Yoast SEO prints a canonical itself except on noindex pages, so a missing one points to something else on the site.

A change is refused rather than guessed at, and the finding goes to a person:

If Yoast SEO is not active when a change arrives, nothing is attempted and the change comes back as failed with the reason seo_plugin_inactive. That keeps its approval, so it goes out again on the next apply.

A page that inherits from a template goes back to inheriting when the change is reverted, rather than keeping a copy of the template's text.

Each request attempts up to 10 changes within 45 seconds and hands the rest back as deferred, for Altimiser to send again. The altimiser_batch_size and altimiser_time_budget filters change those numbers. The time budget is also held to half of max_execution_time.

Page caches

A request that applies something, or finds it already in place, purges the page cache once, during the request, after Yoast has rebuilt what the page prints. A dry run never does.

Any other page cache is not purged, so a change appears there once the cache expires.

GET /health is marked as uncacheable, because a cached copy would answer later requests without checking their signature. Breeze 2.1.11 ignores the usual signals on REST responses, so the plugin also makes the check that one version does make come out as not cacheable. Without that, a signed request left a cache file behind on a local install.

The review queue in wp-admin

This is optional. Add Altimiser's address to wp-config.php, and an Altimiser item appears in the admin menu for editors and administrators:

define('ALTIMISER_URL', 'https://altimiser.example.com');

The page shows the queue in a frame that fills the space beside the menu. Altimiser only allows framing by the origin of the site's URL, so the queue will not load for an admin served from another origin, or in a browser that refuses the frame. The frame's link is signed on the server, carries the email address of whoever is signed in, which is who an approval gets recorded against, and expires. Reloading the page gets a new one.

The menu item and a dashboard widget show how many changes are waiting for review. The number is kept for five minutes, so it can lag behind the queue. If Altimiser cannot be reached the number is left out, and it is not asked again for five minutes, so one admin page waits at most five seconds rather than all of them.

Two more constants are available:

Updates

WordPress's own updater offers new versions, from the latest release on GitHub. The View details link in the update notice says the plugin was not found, because it is not in the WordPress directory. The update itself works.

A site that keeps its plugins in git should commit the update instead, or the next deploy puts the old version back.

To publish a release, change Version in altimiser.php, then push a tag naming that version, such as v0.2.0. The release workflow builds altimiser.zip and publishes it, and fails if the tag and the version disagree.

When the connection fails

altimiser:connect prints the status and the start of the response.

Each row was reproduced on a local install except the firewall row and the missing headers, which are inferred.

Two common security plugins need nothing doing. From reading their source, and not from testing on a running site: the REST API restriction in Kadence Security 9.0.3 (formerly iThemes Security) covers only wp routes, and the REST hooks in Wordfence 8.2.2 cover only user routes.

Testing

The tests run against a real WordPress, which Composer installs into wordpress/, and a real Yoast SEO from wpackagist, in vendor/wp-plugins/. They need MySQL at 127.0.0.1 as root with no password.

composer install
mysql -h127.0.0.1 -uroot -e "CREATE DATABASE IF NOT EXISTS altimiser_wordpress_tests"
vendor/bin/phpunit

GitHub Actions runs them on PHP 8.1 to 8.4, against WordPress 6.8 and the latest release.

SignatureTest computes the signature from the protocol document rather than taking it from the plugin or from Altimiser, and checks that calculation against the document's worked examples. Requests go through WordPress's own REST server, so permission_callback is what is under test.

NoSecretTest runs each test in a process of its own, because a constant cannot be undefined or redefined. PageCacheTest does the same, and defines stand-ins for the cache plugins' purge functions in tests/fixtures/page-cache-plugins.php.