[00] Subset PersonaMark, For developers
Developer reference
Subset PersonaMark's wp-config.php constants, hooks, WP-CLI commands and REST routes, the calls it makes to PersonaMark and the data it stores.
This page lists everything you can use to work with Subset PersonaMark from code: the constants, the hooks, the calls it makes to PersonaMark, its WP-CLI commands, its REST routes and what it stores. Every hook name starts with subset_personamark_.
How it talks to PersonaMark
Every call to PersonaMark’s API goes from your server, through wp_remote_request(), with the site API key as a bearer token. The key never reaches the browser: the editor panel calls the plugin’s own REST routes, and those call PersonaMark.
Each call is one attempt with a 10-second timeout and no retries, and redirects aren’t followed, so the key can’t be forwarded to another host. The user agent is SubsetPersonaMark/<version>. A successful GET is cached for five minutes in a transient. Connecting, checking the connection, a finished audit and an applied rewrite clear the cache.
| Call | When |
|---|---|
GET /api/v1/site | Connecting, checking the connection, the Overview tab, the panel |
POST /api/v1/site/verify | Connecting and checking the connection |
GET /api/v1/audits/<id> | The Overview tab, for the latest audit’s to-dos |
POST /api/v1/audits | Run audit |
GET /api/v1/jobs/<id> | The Overview tab, while an audit started from it runs. Never cached. |
GET /api/v1/audits/<id>/pages?url | The panel and Apply, with the post’s permalink as url |
Nothing else about a post is sent. No call is made until the site is connected, and the front end and Site Health read what’s stored, so a page view makes no request.
Constants
| Constant | Default | Notes |
|---|---|---|
SUBSET_PERSONAMARK_API_KEY | The site API key. Overrides the saved key and locks the field. On multisite it applies to every site in the network. | |
SUBSET_PERSONAMARK_API_URL | https://work.personamark.app | Where PersonaMark is, for development or staging. There’s no field for it. The key is sent only to an https:// address, or to http:// on localhost, 127.0.0.1, [::1] or a .test host. |
<?php
define( 'SUBSET_PERSONAMARK_API_KEY', 'pm_your-site-api-key' );
define( 'SUBSET_PERSONAMARK_API_URL', 'http://localhost:3000' ); // A local PersonaMark.
Choose Check connection after changing either one, so the plugin reads the site from the new key or address.
Choose where changes go
subset_personamark_seo_target picks where an applied title or description is written. It receives the target the plugin found: subset-seo, yoast, rank-math or core, in that order of preference. Return one of the four. Anything else keeps the one found.
<?php
// Yoast SEO and Rank Math are both active: write to Rank Math.
add_filter( 'subset_personamark_seo_target', function ( string $target ): string {
return 'yoast' === $target ? 'rank-math' : $target;
} );
| Target | Title | Description |
|---|---|---|
subset-seo | _subset_seo_title | _subset_seo_description |
yoast | _yoast_wpseo_title | _yoast_wpseo_metadesc |
rank-math | rank_math_title | rank_math_description |
core | post_title, through wp_update_post() | None: descriptions can’t be applied |
Subset SEO is written through its own Subset\SEO\Meta\PostMeta::update(), so its sanitising runs. The others are written with update_post_meta(). Every value goes through sanitize_text_field() first.
The target’s meta keys are added to wp_post_revision_meta_keys, so revisions keep them and restoring a revision restores them. Each revision saved while they’re kept is marked with the meta key _subset_personamark_seo_meta. Restoring a revision without that mark, from before the plugin was active, leaves the SEO fields as they are.
Hooks
| Hook | Type | Arguments | Notes |
|---|---|---|---|
subset_personamark_seo_target | filter | string $target | Where an applied title or description is written. See above. |
subset_personamark_loading | action | Plugin $plugin | Before any component registers. |
subset_personamark_booted | action | Bootstrap $bootstrap | After every component has registered. |
subset_personamark_activate | action | On activation, on each site. | |
subset_personamark_deactivate | action | On deactivation, on each site. | |
subset_personamark_upgrade | action | string|false $from, string $to | After an update, with the version before and after. |
subset_personamark_admin_tabs | filter | array $tabs | The tabs of Subset → PersonaMark, slug to label. |
subset_personamark_admin_tab_{slug} | action | Prints an added tab. |
WP-CLI
Every command is under wp subset personamark, from version 0.2.0. Each one runs the same code as the matching button in wp-admin or the editor panel. Run wp help subset personamark <command> for its options. On multisite, --url picks the site.
| Command | What it does |
|---|---|
status [--format=<table|json>] | Shows whether the site is connected, its PersonaMark domain, whether it’s verified, where the key comes from (option or constant), the key masked, and the latest audit’s score, date and address. |
connect | Connects the site, as Connect does. Reads the key from STDIN, or from a hidden prompt when nothing is piped in. There’s no argument for it, so it stays out of your shell history. A key in wp-config.php is used instead. |
verify | Checks the connection, as Check connection does, past the cache. |
disconnect [--yes] | Forgets the key and the cached answers, and removes the meta tag, as Disconnect does. Asks to confirm unless you pass --yes. |
todos [--format=<format>] | Lists the latest audit’s to-dos in PersonaMark’s order: ID, title, severity, pages affected and address. --format is table, json, csv, yaml or count. |
audit run [--wait] [--interval=<seconds>] | Starts an audit, as Run audit does, or follows the one already running. --wait prints its progress until it finishes, checking every --interval seconds (default 5). |
audit status [--format=<table|json>] | Shows the audit started from this site: running, succeeded or failed. A finished audit is shown once, then no longer followed. |
page <post> [--format=<table|json>] | Lists what the latest audit found on a published post’s page: its issues, and each rewrite once per field, with its ID, the current text, the suggestion and where apply saves it. json prints the panel’s data. |
apply <post> <rewrite-id> --field=<title|description> --user=<login> [--yes] | Applies one field of one rewrite, as the panel’s Apply does. See below. |
apply needs --user, set to someone who can edit the post. It shows the post, where the change goes, and the before and after, then asks to confirm unless you pass --yes. The text applied is the rewrite’s as PersonaMark has it now, fetched again on your server. A revision is saved before and after, and the success message names the one to restore to undo it. There’s no bulk apply: run the command once for each change.
Each command exits with status 1 when it fails, including when the site isn’t connected. status and todos show the last answer PersonaMark sent, with a warning, when it can’t be reached.
op read op://Sites/PersonaMark/key | wp subset personamark connect
wp subset personamark connect < personamark-key.txt
wp subset personamark audit run --wait
wp subset personamark todos --format=json
wp subset personamark page 42
wp subset personamark apply 42 rw_123 --field=title --user=admin
apply prints the before and after and asks first:
$ wp subset personamark apply 42 rw_123 --field=title --user=admin
Post: Hello world (42)
Title, saved to Subset SEO:
Before: Hello world
After: Hello world: a friendly first post
Apply this title? [y/n] y
Success: Applied. The title is now "Hello world: a friendly first post". To undo it, restore revision 57 (the one before 58).
REST API
The namespace is subset-personamark/v1. Both routes are for the editor panel and need permission to edit the post, through a logged-in cookie with an X-WP-Nonce header or an application password. A post that doesn’t exist is refused the same way as one you can’t edit.
| Route | Method | Notes |
|---|---|---|
/posts/<id>/page | GET | The panel’s data: state (not_connected, unpublished, no_audit, no_findings, findings or error), the target, the current values, issues and rewrites. |
/posts/<id>/apply | POST | Applies one field of a rewrite. Takes rewrite_id and field (title or description). The text comes from PersonaMark, and any text sent along is ignored. |
apply answers with the field, the stored value, the new revision ID (or null when none was saved), the target and its meta_key. A rewrite PersonaMark no longer has is 404 subset_personamark_unknown_rewrite. A description with nowhere to go is 400 subset_personamark_unsupported. An unpublished post or a site that isn’t connected is 409.
What it stores
| Name | Where | What |
|---|---|---|
subset_personamark_api_key | Option | The site API key, encrypted with a key derived from the site’s auth salt. |
subset_personamark_api_key_site_<id> | Option, on the main site | On multisite, each other site’s key, encrypted. Deleting the site deletes it. |
subset_personamark_connection | Option, autoloaded | The PersonaMark site’s ID and domain, whether it’s verified, the meta tag’s name and content, and when it was checked. |
subset_personamark_overview | Option | The last good answer for the Overview tab, shown while PersonaMark can’t be reached. |
subset_personamark_audit_job | Option | The audit started from wp-admin, followed for up to an hour. |
subset_personamark_api_cache | Option | The cache’s generation, which moves on to clear every cached answer. |
subset_personamark_api_* | Transients | Cached GET answers, for five minutes. |
_subset_personamark_seo_meta | Post meta, on revisions | Marks a revision that holds the SEO fields. |
Deleting the plugin deletes every subset_personamark_ option and transient on every site of a network. Applied titles and descriptions, and their revisions, stay.