Feature: the customization layer
- Version
- 3.x
- Updated
Extend CBX without forking it. Most configurator projects don't fail at launch — they fail
at the second update, when a year of ad-hoc core edits collides with a new release. CBX's
answer is a supported, upgrade-safe customization layer: one directory (data/customization/
in the component; on WordPress its own folder next to the plugin, configbox-customization/) that
holds all of a site's own code, that the framework resolves at well-defined extension points, and
that updates never touch. Your customizations and our releases stay out of each other's way,
by design.
This page is the showcase; the engineering documentation lives in the customization track, starting with the overview & extension-point map.
What you can build — every extension point is a supported contract
| You want to… | The mechanism | The guide |
|---|---|---|
| Restyle or restructure any screen | Template overrides (your file shadows the core template) | Views & templates |
| Add fields to stock admin forms/lists | Model property injection (merged, not copied) | Extending stock models |
| Invent a new admin field type/widget | Custom Kenedo properties | Custom properties |
| React to orders, logins, saves… | Event observers (additive, runs alongside core) | Events & observers |
| Add a payment provider | PSP connector folders | Payment connectors |
| Add new "if…" vocabulary to the rule editor | Custom rule condition types | Custom rule conditions |
| Ship frontend behavior/styling | CSS + AMD JS modules (configbox/custom namespace, no build step) | Assets & AMD |
| Change any displayed text | Per-language override files | Language overrides |
| Add operator/cron tooling | Custom CLI commands (wp configbox custom <command>) | Custom CLI commands |
| Evolve your own DB schema | A customization migration track, versioned like core's | Migrations |
| Change core behavior itself (escape hatch) | System overrides, eagerly loaded at boot | System overrides & boot hooks |
New controllers, models and views get their own slots too — the overview maps every mechanism, how each one resolves in code, and includes a decision guide ("I want to change X → use mechanism Y") that always steers you to the smallest mechanism that works.
Why it survives updates
- One directory, never shipped, never overwritten. Updates replace core files; they do not know
or care what is in
data/customization/. Your code is yours — it is not even part of the CBX release package. - Contracts, not patches. Each extension point is a naming/return-value contract the framework resolves at runtime (shadow, merge, register, or boot-time pre-emption — documented per mechanism). You are not maintaining diffs against our source.
- Additive mechanisms first. The decision guide prefers mechanisms that combine with core (observers, property injection, language overrides) over ones that replace it — so most customizations cannot drift out of sync at all.
- Breaking changes are documented as a contract, too. When a major release does change an extension point, the migration playbooks record every breaking change and the conversion procedure per customization kind.
Spotlight: your own CLI commands, with a safety guarantee
The newest extension point shows the design philosophy well. Drop one file —
cli/commands.php in the customization layer — and your site gains its own commands next to the
stock CBX CLI suite, under a reserved namespace:
wp configbox custom # list the commands installed on this site
wp configbox custom order-export 30 --format=csv
Your command runs with CBX fully booted (database, models, helpers all available), receives
parsed arguments and options, and returns an exit code cron/deploy scripts can gate on. And the
isolation is deliberate: the file is loaded only when the custom namespace is invoked, behind
a catch-everything guard — so a broken custom command (even a PHP parse error in the file) can
never take down the stock commands you would need to diagnose and recover. Stock tooling stays
solid no matter what the customization layer does.
Contract, worked example and conventions: Custom CLI commands.
Who this is for
- Agencies delivering customized stores that must keep receiving product updates.
- In-house developers wiring CBX to an ERP, a PIM, or a bespoke fulfillment flow (observers + custom CLI commands cover most integration shapes).
- AI-assisted teams: the whole documentation set — these contracts included — ships inside the
component, so an assistant pointed at
app/docs/works against the same contracts you do.
Back to the Features overview.