nolimit-discounts/docs/CONTRACT.md

Contract

Every hook this plugin offers, and every family hook it answers. Version 1.7.0.

A contract is a name somebody else has to know. Core hooks this plugin merely listens to — init, admin_menu, wp_enqueue_scripts — are not here; WordPress documents those, and listening to init is not a promise to anyone. The exception is at the bottom, and it is there because it is shared with every sibling plugin on the same update host.

The tables and the source are compared in both directions by ci/check-docs.php, which runs in CI. A hook added without a row here fails the build, and so does a row whose name no longer exists in the source.

Hooks this plugin provides

All six are filters, all read a setting that has a working default, and all are answered from apply_filters() in shipped code. A shop that adds no code gets the default and never needs this table.

hook	signature	default	if you are absent
wc_edm_audit_log_enabled	bool $enabled	true	the audit log records admin actions
wc_edm_audit_log_retention_days	int $days	30	rows older than 30 days are pruned daily; the value is floored at 1, so 0 means 1 day, not "keep forever"
wc_edm_client_ip	string $ip	the resolved address	the plugin's own resolution is used — override this behind a proxy
wc_edm_rate_limit_enabled	bool $enabled	true	REST routes are rate limited
wc_edm_rate_limit_max_requests	int $default, string $method	per method	the built-in allowance applies; floored at 1
wc_edm_rate_limit_window	int $seconds, string $method	MINUTE_IN_SECONDS	a 60-second window; floored at 1

What a consumer must not do. Do not return a non-scalar: each of these is cast ((bool), (int), (string)) and a bad type becomes a wrong value rather than an error. Do not assume wc_edm_rate_limit_* can switch limiting off by returning 0 — they are floored at 1; use wc_edm_rate_limit_enabled. Returning false from wc_edm_audit_log_enabled on a shop that has a compliance reason to keep the log is a decision, not a performance tweak.

The family's shared hooks

These cross a repository boundary, which is the class of value nobody's checks cover, so both directions are written out.

hook	this plugin	what that means
wpmgr_menu_title	answers it (main file) and provides it (our copy of shared-menu.php)	returns Nolimit, so the shared parent menu is labelled the same whichever sibling registered it
wpmgr_dashboard_cards	answers it (class-admin.php) and provides it (our copy of shared-menu.php)	adds this plugin's card — colour #1a7a52, two counts, cached 5 minutes
wpmgr_menu_glyph	provides it only, via our copy of shared-menu.php	this plugin does not override the glyph; it answers with the shared default ∞

Why "provides" and "answers" are both true. includes/shared-menu.php is byte-identical in all eight family plugins and frozen at a SHA in ci/plugin.conf. Whichever copy loads first is the one that runs, so this plugin is simultaneously one of the eight possible providers of these three hooks and a consumer of whichever copy won. That is why the label is set with a filter and not by editing the shared file: editing it would make a site with three of eight plugins updated show a different menu title depending on activation order, and change its mind when a plugin is deactivated.

What a consumer must not do. Do not edit shared-menu.php to change any of these — it reaches every site in activation order and the frozen SHA will fail the build in all eight trees. Answer the filter from your own plugin. wpmgr_menu_title must be idempotent: every sibling adds a callback and the order is not defined.

One core hook, because it is shared

hook	this plugin	why it is in a contract document
update_plugins_{$hostname}	answers it, add_filter( …, 10, 3 )	🔴 the filter name is built from the hostname, not the repository, so every plugin updating from gitea.nolimit.dk lands on the same hook and WordPress runs every callback for every one of them

Answer it unconditionally and you offer your release to your neighbour. On a live shop in September 2026 the subscriptions plugin was told version 1.4.4 was an update for itself; 1.4.4 was this plugin's. Load order decides who wins, so a rename is enough to flip which plugin gets corrupted — and flipped toward one with auto-updates on, it installs a stranger's zip over itself unattended.

The guard is two halves and both are required:

add_filter( "update_plugins_{$host}", array( $this, 'offer_update' ), 10, 3 );

// and inside offer_update():
if ( '' !== $plugin_file && plugin_basename( WC_EDM_PLUGIN_FILE ) !== $plugin_file ) {
    return $update;
}

Leave the argument count at 2 and $plugin_file never arrives, so the guard silently does nothing — the same shape of bug it fixes. No integration test can catch this, because a test site installs one plugin from that host and the collision cannot arise; the assertion is the defence.

plugins_api is also answered and is safe, because it guards on $args->slug.

What the checker cannot see, and is therefore listed by hand

ci/check-docs.php reads hook names out of the shipped source as string literals. Two names in this tree are not literals at the call site:

hook	how it is written	why it is missed
wc_edm_prune_audit_log	add_action( self::CRON_HOOK, … )	a class constant, resolved at runtime
update_plugins_{$hostname}	add_filter( "update_plugins_{$host}", … )	interpolated from a variable

Both rows above are real and both would survive a rename of the constant or the variable without the checker noticing. wc_edm_prune_audit_log is the daily audit-log prune event; it is internal wiring rather than an extension point, but it is a name that appears in wp_next_scheduled() output and in any cron viewer, so it is written down.

This section exists because the instrument's blind spot is worth stating next to its results. A generated list is better than a remembered one, and it is still a list of what the generator can see.