nolimit-cache-dist/docs/CONTRACT.md

Hooks and integration

What Nolimit Cache offers to other code, and what it listens to. Written for developers who want to extend the plugin or sit next to it; nothing here is needed to use it.

Hooks prefixed nlcac_ are this plugin's own and are stable: a rename is a breaking change and will be called out in the release notes. Hooks prefixed wpmgr_ are shared by name with the other Nolimit plugins (see section 2).

A note on the words: for a filter, add_filter() is how you answer it, by supplying a value. The headings below describe the mechanism, who calls apply_filters() and who calls add_filter(), because that cannot be misread.

---

1. Extension points this plugin OFFERS — nlcac_*

apply_filters() / do_action() in our code: we run everyone's callbacks.

Hook	Type	Signature	Fired from
nlcac_reason_not_to_cache	filter	( string $reason, … ) — return a non-empty string to refuse to cache this request	page cache
nlcac_page_cached	action	( string $path ) — a page was just written to disk	page cache
nlcac_purge_urls_for_post	filter	( array $urls, int $post_id ) — the URLs about to be purged for a post	purging
nlcac_preload_urls	filter	( array $urls ) — the queue the preloader will walk	preloader
nlcac_exclude_script	filter	( bool $exclude, string $handle ) — keep a script out of defer	optimiser
nlcac_ai_payload	filter	( array $payload ) — what the assistant is about to send	assistant
nlcac_images_skip	filter	( bool $skip, string $img_tag ) — return true to keep one <img> out of the WebP/AVIF rewrite	images

If this plugin is absent, none of these fire. A consumer must not assume its callback ever runs; has_filter() is not a substitute for the plugin being active.

A consumer must not do slow or networked work in nlcac_reason_not_to_cache. It runs on every request, before WordPress, in the drop-in — which is the whole reason the cache is fast.

2. The family's shared hooks — wpmgr_*

Shared by name across the Nolimit plugins, so load order decides who wins for anything that declares itself once.

Offered here — we call apply_filters() / do_action()

Hook	Type	Notes
wpmgr_cache_cleared	action	( int $removed ). Fired when the page cache is emptied, so a sibling holding derived state can drop it in the same click. Our own object cache listens to it and only calls wp_cache_flush(), so there is no path back into purge.
wpmgr_dashboard_cards	filter	Provided by the shared menu file, which every Nolimit plugin carries identically.
wpmgr_menu_title	filter	Same.
wpmgr_menu_glyph	filter	Same. It exists so the glyph can be overridden.

Answered here — we register a callback with add_filter() / add_action()

Hook	Type	What we do	If nobody offers it
wpmgr_dashboard_cards	filter	Add this plugin's card	The card is not drawn; nothing breaks
wpmgr_menu_title	filter	Answer the shared menu's title	Shared file's default
wpmgr_cache_cleared	action	Flush our object cache	— (we also fire it)
wpmgr_signals	filter	Supply this plugin's health signals to a family-wide collection. We answer it; we never read it	Only Nolimit Assistant applies this filter. With it absent or inactive, our signals are contributed to nothing and no error is raised.
wpmgr_setup_recommendations	filter	Offer three setup items to the Assistant's Setup screen: turn the page cache on, warm it in the background, keep the basket rule on. Every done is read from the stored setting, never measured.	Nothing is offered and nothing breaks. Only Nolimit Assistant applies this filter, so without it these items are shown nowhere

3. WordPress and WooCommerce core

The plugin also attaches to WordPress and WooCommerce core hooks. They are listed by area rather than one row each, because none of them is a contract anyone else needs to honour: they are how the plugin attaches to WordPress.

Area	Hooks
Boot	init, plugins_loaded
Admin	admin_init, admin_menu, admin_notices, admin_head, admin_footer, admin_bar_menu, admin_enqueue_scripts, plugin_action_links_{file}
Purging	transition_post_status, post_updated, deleted_post, edit_term, delete_term, comment_post, transition_comment_status, update_option_sidebars_widgets, shutdown
Front end	template_redirect, wp_head, wp_enqueue_scripts, script_loader_tag, script_loader_src, style_loader_src, the_content, wp_get_attachment_url, wp_calculate_image_srcset, embed_oembed_discover, tiny_mce_plugins
Updates	site_transient_update_plugins, plugins_api, upgrader_process_complete
Media	wp_update_attachment_metadata, wp_delete_file
Settings	update_option_nlcac_settings
Scheduling	cron_schedules
REST	rest_api_init
WooCommerce	woocommerce_new_product, woocommerce_update_product, woocommerce_order_status_changed, woocommerce_product_set_stock, woocommerce_product_set_stock_status, woocommerce_variation_set_stock, woocommerce_variation_set_stock_status, wc_after_products_starting_sales, wc_after_products_ending_sales

🔴 site_transient_update_plugins is the dangerous one. The filter name is built from the update host, so every plugin updating from gitea.nolimit.dk lands on the same one and WordPress runs every callback for every plugin. Answering unconditionally offers our zip to a sibling. The guard is two halves and both are required — register with 3 arguments, and return $update untouched unless $plugin_file is ours. Registering with 2 leaves the argument unset and the guard silently does nothing, which is the same shape of bug it exists to fix.

If you write a plugin that updates from the same host, apply the same guard.