Files
yoapuesto/wp-content/plugins/seo-by-rank-math/vendor/cmb2/cmb2/CONVENTIONS.md
T
2026-09-25 12:02:42 -06:00

8.8 KiB

CMB2 Conventions & Blast-Radius Notes

CMB2 is an opinionated, 10+-year-old library bundled inside hundreds of themes and plugins. This file is the compounding knowledge base of its conventions, architectural seams, and back-compat blast radii — written for both human contributors and AI agents.

Reading rule: consult this file before changing anything under includes/, bootstrap.php, or init.php.

Capture rule: when a code review catches a convention violation or a back-compat near-miss, the fix must land alongside a new or updated entry here, on the same branch. Each entry cites the canonical in-code example — the code is the spec; this file is the index to it.

Delegation rule (AI agents): subagents don't inherit this context. Work orders delegating changes must quote the relevant entries verbatim.


C1 — Per-box features hook up via cmb2_init_hookup_{$cmb_id}

Rule: A feature that attaches to boxes (hookup, REST, notices, anything box-aware) registers a maybe_init_and_hookup( CMB2 $cmb ) static on the box-specific cmb2_init_hookup_{$cmb_id} action, added in the CMB2 constructor. The feature class self-guards: it receives every box and decides for itself whether it applies (e.g. CMB2_REST checks show_in_rest).

Canonical example: includes/CMB2.php constructor (the CMB2_Hookup/CMB2_REST add_action pair); fired from bootstrap.php's cmb2_init_hookup_{$cmb->cmb_id} loop; contract in CMB2_Hookup_Base::maybe_init_and_hookup().

Anti-pattern: registering a global hook elsewhere and scanning CMB2_Boxes::get_all() to find relevant boxes. Two sources of truth for "which boxes does this apply to", misses late-registered boxes, and bypasses the per-box action seam developers use to unhook features from a single box.

Blast radius: extenders unhook/re-order cmb2_init_hookup_* callbacks per box; a feature wired outside that seam won't respect their customizations.

C2 — bootstrap.php is generic lifecycle only

Rule: bootstrap.php contains only the init ceremony: do_action / apply_filters lifecycle events and the box-instantiation loops. No feature-specific class references, ever. Feature wiring belongs in the CMB2 constructor (per-box features, see C1) or in the feature's own file.

Canonical example: bootstrap.php — note it ends "End. That's it, folks!" and has barely changed since 2.2.0.

C3 — The self-electing loader makes every behavior change site-wide

Rule: init.php version-elects: when multiple copies of CMB2 are bundled (themes + plugins commonly each ship one), the newest copy wins and serves ALL registered boxes on the site. Any default-behavior change therefore propagates to every bundling product the moment one of them updates.

Consequence: behavior flips ship staged — opt-in first (default-off filter

  • notice + docs), default-on only in a later release. Never flip a default in the same release that introduces the switch.

Canonical example: init.php (the CMB2_Bootstrap_* priority dance); staged-rollout example: the cmb2_rest_enforce_options_page_read_permissions filter (default false).

C4 — REST reads are public by design; permission filters are the escape hatch

Rule: Boxes with show_in_rest readable expose reads publicly — this mirrors WP core's show_in_rest semantics for object meta and is intentional, not an oversight. Per-request overrides go through the existing cmb2_api_get_box_permissions_check / cmb2_api_get_field_permissions_check filters, which always run last and have final say. New permission logic must run before them and must not remove them.

Canonical example: CMB2_REST_Controller_Boxes::get_item_permissions_check_filter(); pinned by tests in tests/test-cmb-rest-controllers.php.

Blast radius: headless/decoupled front-ends read box data anonymously for public display. Tightening reads by default breaks them — hence the staged approach in C3, scoped only to options-page boxes (matching core's settings-vs-meta distinction).

C5 — The capability box prop means "who sees the admin screen"

Rule: capability (default manage_options for options pages) governs the admin page. Reusing it for other gates (REST, front-end) conflates concerns — acceptable only where the semantic genuinely matches (e.g. options-page REST reads mirror the settings screen), and even then behind its own switch.

Canonical example: includes/CMB2.php $mb_defaults['capability'] usage in CMB2_Options_Hookup.

Where the semantic does match: an options-page target's object id is the option name the data lands in, so "may write this option" and "may use this settings screen" are the same question — see CMB2_Ajax::can_cache_for_options_page(). Note the shape: the box that declared the option key is also the only place a capability for it exists, so looking the box up both supplies the check and bounds the accepted option keys to ones a box declared. An id no box claims has no capability to consult, and is therefore not a target.

C6 — Autoloader paths are case-sensitive by prefix

Rule: cmb2_autoload_classes() maps CMB2_REST/CMB2_REST_* (exact case) to includes/rest-api/, CMB2_Type* to includes/types/, everything else to includes/. A class named CMB2_Rest_Foo (lowercase "est") deliberately lands in includes/ — name classes with full awareness of which directory the prefix routes to, and match filename to class name exactly.

Canonical example: includes/helper-functions.php cmb2_autoload_classes().

C7 — PHP floor is 7.4; local tests don't prove it

Rule: All code must run on PHP 7.4. Local npm run phptests runs PHP 8.3 only; the 7.4 floor is guarded exclusively by the CI matrix (phpunit.yml). "Passes locally" is necessary, never sufficient. (Tooling details: CLAUDE.md "Testing Strategy".)

C8 — Configuration over code: box props are the primary interface

Rule: A new per-box behavior must be reachable as a box registration property. The registration array is the interface CMB2 developers actually use — and the one a bundling theme/plugin can ship per box — so it is the primary layer; filters are the secondary, site-wide layer for cross-cutting policy. When a behavior has both, the box prop wins outright and the filter governs only the boxes that left the prop unset. That way a box declares its intent once, in the array where it was registered, and keeps it across a later default flip (C3).

Canonical examples: includes/CMB2.php $mb_defaults — show_in_rest, capability, and rest_read_capability. The last one is the shape to copy, reading exactly as plain English: false = "no" (REST reads disabled for everyone, via core's do_not_allow); true = "yes, everyone" (alias of 'exist', the capability WP grants every visitor); 'box-capability' = the box's own capability prop (the only non-duplicating spelling — naming the cap copies a value that lives elsewhere and can drift); any other capability string = only its holders; unset = the default policy (and the staged flip, C3). It cascades field → box → default like show_in_rest. Precedence is resolved in one place, CMB2_REST::get_rest_read_capability(), and consumed by CMB2_REST_Controller::maybe_gate_read_by_capability().

Value semantics — a prop value must read correctly in plain English. A config value is documentation; if its plain-English reading is ambiguous or contradicts its behavior, it's the wrong value. rest_read_capability went through this exact wringer: false originally meant "reads are public (no capability required)" — but it reads as "REST read capability? no", i.e. reads disabled. The fix wasn't banning the boolean; it was making the meaning match the reading (false now disables reads; true now means everyone). Corollaries: booleans are fine only when yes/no is the honest answer to the prop's name read as a question; when the answer is a which (which capability?), every value is a real answer; and prefer WP-canonical vocabulary over invented sentinels — 'exist' (granted to everyone) and do_not_allow (denied to everyone) bound the range, so neither "public" nor "disabled" needs special-casing.

Anti-pattern: shipping a filter-only interface for per-box behavior. It forces every developer to write a callback that re-derives "which box is this?" from the filter args, cannot be expressed in the registration array a theme or plugin already ships, and leaves no way to declare per-box intent — the filter answers site-wide, so a site with a single box needing the old behavior has to special-case every box by hand.

Blast radius: props are public API forever — name them for the behavior, not the implementation. Adding one to $mb_defaults also changes the array pinned by Test_CMB2_Core::test_defaults_set(); update that fixture in the same commit.