Most WordPress security plugins ask you to take what the vendor offers. BotBlocker Security ships an add-on contract instead, with a manifest, a validator and a working sample, so a site owner can add a check the core team never planned.
Code: BotBlocker-Add-on-Developer-Kit, GPL-3.0 licensed.
That flexibility has a cost. An add-on runs before or next to a firewall, and a mistake that would be a bug in a normal plugin becomes a hole in protection. The contract exists to keep those mistakes visible before a ZIP reaches a production site.
What an add-on actually is
A BotBlocker add-on is a small WordPress plugin with a manifest called bbcs-addon.json. The manifest declares the slug, version, requirements, settings, optional abilities, and which runtime features the add-on needs.
The baseline is BotBlocker 1.7.5 and up, WordPress 5.9 and up, and PHP 7.4 and up. Add-on API version 2 is the current contract, and everything below assumes it.
Step 1: copy the sample, rename everything
The kit ships three examples: a canonical sample, an advanced one that hooks into traffic decisions, and a minimal one that wires an external captcha.
Start from the canonical sample. Copy the folder, then rename the folder, the manifest slug, the root PHP file, the text domain, the function prefix, the option name, the asset handles, and the CSS classes. A leftover prefix from the sample is how two add-ons end up fighting over one option in a year.
Step 2: put behaviour in core, controls in settings
Two files carry the work: one for behaviour and one for the admin screen.
Behaviour belongs in the core file. Settings belong in the settings file, under a single option array such as vendor_addon_settings. The manifest declares the sanitizer, and the sanitizer has to be the one the manifest names, not a second copy written later.
Visitor and request data come from the documented core object, not from $_SERVER reads scattered through your code. That rule matters: the core object normalises proxy headers and bot checks, and reading the raw superglobal reintroduces exactly the spoofing problem the firewall exists to stop.
Step 3: decide whether you need the traffic contract
Normal add-ons load after the main request check. They can log, add headers, extend the admin, run their own cron.
An add-on that wants to decide about traffic has to join earlier, through the pre-run contract. The manifest lists traffic_decision_provider in its features, and the runtime section names a pre-run file that exposes a readiness marker and a registration callback.
This is the part to think about twice. A bad rule can redirect real visitors, break a payment callback, hide a challenge page, or create a redirect loop. The kit’s guidance is to ship it disabled by default, support a dry-run mode, document the rollback, and require an admin to review before production redirects or blocks.
If a normal post-check hook solves the problem, use the hook.
Step 4: validate the source folder
The kit includes validate-addon.php. Point it at the folder and it reports manifest problems, naming collisions, sanitizer mismatches, and missing files before packaging.
Run it on every change. The validator is faster than a staging install and it catches the class of error that produces a white screen on activation.
Step 5: package as one folder, not a folder of files
The ZIP has to contain exactly one root folder whose name matches the slug. BotBlocker validates the archive, installs it to the uploads runtime directory, and leaves it inactive until an admin activates it.
On Windows, do not use Compress-Archive. It writes backslash separators, WordPress does not normalise them, and Linux hosting extracts files with literal backslashes in their names. The install fails with an error that says nothing about archives.
Use the included package-addon.ps1, or zip -r from a Linux shell, then run the validator against the ZIP as well.
What the kit contains
A runtime contract document, the API v2 reference, the request-data and core-object references, the settings reference and UI patterns, the traffic and redirect guidance, the lifecycle and code-quality standards, packaging and testing notes, a compatibility matrix, and a list of known gaps in the core contract.
Read the runtime contract first. It is short and it explains the load order, which is the source of most “my add-on does nothing” reports.
The public kit is GPL-3.0 and lives on GitHub: BotBlocker Add-on Developer Kit. The plugin itself is on WordPress.org, and the documentation hub is at botblocker.top/docs.
Background on plugin security: WordPress plugin handbook.
