Settings & feature flags

Layered config

Config::get() resolves a dot-notation key across three layers, first match wins: .env (project root) → WordPress options → shipped defaults (config/*.php).

What the project root is

It is the directory two levels above the real location of the corex-core plugin, and the .env is read from nowhere else. Where the plugin is linked into WordPress (a development checkout, a release directory on a server) that is the repository, outside the web root. Where it is copied into wp-content/plugins/ (the shared-host package) that is wp-content/, inside the web root: do not create a .env there, set options instead. Environment variables of the server are not read. The deployment guide has the detail: docs/en/05-deployment/secrets-backups-zero-downtime.md.

use Corex\Support\Facades\Config;

Config::get('app.name');             // 'Corex' from defaults
Config::get('forms.email.recipient', '');

A dot key maps to an option corex_<key_with_underscores> and an env var KEY_WITH_UNDERSCORES (app.name → option corex_app_name, env APP_NAME). Shipped namespaces: app, query, security, theme, features, updates.

The settings UI

corex-config registers a top-level Corex admin menu with a server-rendered settings screen (brand / mail / forms / captcha). It persists each field to the corex_* option the Config option layer reads — so a saved setting flows into the framework with no extra wiring.

Two companion screens sit under the same Corex menu (all share the AdminGuard capability + nonce check):

• Add-ons — enable/disable each Corex add-on (its plugin and its feature flag, together), dependency-aware (it refuses a toggle that would break a dependency, e.g. disabling corex-ui while a kit needs it).
• Setup Wizard — pick a starter kit and apply it: it enables the kit’s flags, activates its modules, and creates the kit’s pages (a composed front page + About/Contact, etc.) idempotently. The seeded pages are tracked so wp corex reset removes exactly them.
• Data — a DataViews table of your form submissions (and any registered Corex custom-table source), with sorting, pagination, and delete. Served by the cap-gated corex/v1/data REST routes. Custom tables appear automatically: mark a Corex-managed table managed (register a ManagedTable with the ManagedTables registry) and it shows up here like a post-type list — no admin code, opt-in, with prepared + bounded queries (spec 038).
• Insights — performance (PageSpeed/Lighthouse) + agent-readiness cards with a Run button (see Insights).

Feature flags

features.* flags gate optional or edition behaviour through the same layered engine:

Config::enabled('mail_queue');   // false until enabled
// or inject the service:
$flags = $container->make(\Corex\Support\Config\FeatureFlags::class);
$flags->enabled('pro');
$flags->all();                    // ['pro' => false, 'mail_queue' => false, …]

Only a truthy value (1 true on yes) enables a flag. Flip one per-site by an option (corex_features_<flag>) or env (FEATURES_<FLAG>) — no code change. Registered flags live in config/features.php: pro, mail_queue, dataviews_admin, woocommerce_kit.

Free vs Pro

The Free/Pro split rides on features.pro — Free builds leave it off; Pro distributions enable it. One codebase, gated by a flag.

The control panel

The Corex settings screen is a control panel (spec 044): the settings are grouped into domains (Branding, Mail, Forms, Captcha, Insights, …), each shown as a card with a status — configured, needs setup, or error — conveyed by an icon and text (not color alone). A domain that needs attention shows what is missing and a “how to set this up” link, and the dashboard carries an onboarding checklist of the steps still to do (with an “all set” state when nothing remains). Status is derived from your existing settings — nothing new is stored.

Captcha

Pick a driver (none / honeypot / reCAPTCHA v3 / Turnstile / hCaptcha). Key-based drivers show a site key and a write-only secret, plus a score threshold and action for reCAPTCHA v3. reCAPTCHA v3 shows a visitor nothing; Turnstile and hCaptcha show their widget above a protected form’s button. Once a provider and both of its keys are saved, a Test verification button (added by the Corex Captcha add-on, under the secret field) asks the provider about the secret key and says the answer in words, in a region a screen reader announces: it works, the key is wrong, a key is missing, or the provider cannot be reached. The site key is checked when the widget loads for a visitor. Until both keys are saved the button is not offered, and the field says what is needed. The secret is used only in the outbound probe and never appears in a response or on screen.

Insights similarly has a per-provider Run check button. A PageSpeed run that could not complete (a local address, a quota, a refused key, no answer) says Could not run with the reason and a Retry button, and has no score or grade.