Configuration Reference

View as Markdown

Divine is configured in three layers, and the right layer depends on who owns the value and where it should live. The theme-owned divine.json file carries performance intent and travels with the theme through worktrees, reviews, deploys, and exports. WordPress constants handle host and deployment wiring that belongs in wp-config.php or the process environment. The divine/* public filters let you drive performance configuration from code when it should come from a deployment pipeline rather than a file. As a rule, reach for divine.json for ordinary theme performance choices, for constants when behavior depends on the host or environment, and for filters when configuration is computed at runtime.

Theme Configuration

divine.json at the theme root is the source of truth for runtime performance behavior. The runtime reads its performance object, validates it strictly, and resolves it into the configuration that actually runs. Because it is a normal theme file, the same configuration drives plugin-managed themes and exported standalone themes alike, and it moves through worktrees, reviews, deploys, and exports like any other file change. The full object, its profiles, and every section are documented in Performance; this page covers the constant and filter layers that sit around it.

Constants

Constants are the right tool for values that belong with the host: paths, URLs, and lane markers that differ between environments and should not be committed alongside theme code. Define them before WordPress loads Divine. Divine reads some of these as real PHP constants and some from the process environment during bootstrap; the environment-sourced values are promoted to constants of the same name when present.

Constant	Source	Purpose
`DIVINE_VERSION`	Constant	The running Divine version. Defined at bootstrap and stamped into export provenance; integrations may read it but should not set it.
`DIVINE_RUNTIME_PUBLIC_URL`	Constant or `getenv`	Public base URL for runtime assets when the runtime is served from an alias rather than its on-disk location. Read from the environment at bootstrap and promoted to a constant.
`DIVINE_WP_LOAD_PATH`	Constant or `getenv`	Absolute path to the WordPress `wp-load.php` the runtime should bootstrap from. Read from the environment at bootstrap and promoted to a constant.
`DIVINE_AUTOLOAD`	Environment	Absolute path to a Divine autoloader the generated `dv` shim should require before walking up to find the plugin. Read by the generated theme CLI, not the in-process runtime.
`DIVINE_WORDPRESS_BOOTSTRAP`	Environment	Absolute path to a script that loads WordPress for the `dv check --full` and `dv show` CLI lanes. When it points at a readable file, the CLI requires it instead of probing wp-cli or walking up for `wp-load.php`.

Divine also defines DIVINE_PLUGIN_FILE, DIVINE_PLUGIN_PATH, DIVINE_RUNTIME_PATH, and DIVINE_RUNTIME_SOURCE_PATH at boot. Two further constants tune performance specifically: DIVINE_PERFORMANCE_PROFILE pins the active profile above the defaults, and DIVINE_PERFORMANCE_POLICY names a host policy file whose performance object merges after the theme. Both are covered in Performance.

Public Filters

Everything divine.json configures for performance is also exposed as a documented divine/* filter. Filters are the preferred extension point when configuration is computed at runtime or supplied by deployment tooling, because they let you derive a value rather than hard-code it into the theme. The table below is the canonical list; the sections that follow show each one with an example. None of these filters validate by themselves. The resolver validates the value every filter returns, so a callback that returns a malformed or non-array value is rejected and surfaced as a config error, leaving Divine on its previous value rather than breaking the merge.

Hook	Runs
`divine/performance/default_config`	Before profile, policy, and theme config merge.
`divine/performance/theme_root`	When choosing which theme directory to read `divine.json` from.
`divine/performance/raw_theme_config`	After `divine.json` is decoded, before the performance object is validated.
`divine/performance/theme_config`	After theme config validates, before profile and policy merge.
`divine/performance/effective_config`	On the final merged configuration, before validation and caching.

Default Config

Use divine/performance/default_config for platform-wide defaults that themes can still override. It runs before the profile, policy, and theme config merge, so it restates the baseline Divine starts from. Return an array shaped like Divine performance config; a non-array result is rejected and Divine falls back to its built-in defaults.

add_filter('divine/performance/default_config', function (array $defaults, array $context): array {
    $defaults['preload']['links'] = 'intent';

    return $defaults;
}, 10, 2);

Theme Root

Use divine/performance/theme_root when the physical theme path that holds divine.json differs from the active stylesheet directory, for example on a host that resolves themes through an alias. Return a non-empty absolute path string; a non-string or empty value is ignored and Divine keeps the stylesheet directory.

add_filter('divine/performance/theme_root', fn (string $themeRoot): string => '/srv/site/themes/active');

Raw Theme Config

Use divine/performance/raw_theme_config to adjust the theme’s performance object after divine.json is decoded but before it is validated, which makes it the right place for policy expansion or environment overlays. It receives the extracted performance config, the full decoded divine.json object, the absolute path to the file, and the runtime context. Return an array; a non-array result is rejected as a config error.

add_filter(
    'divine/performance/raw_theme_config',
    function (array $config, array $decoded, string $path, array $context): array {
        if (('production' === wp_get_environment_type())) {
            $config['profile'] = 'strict';
        }

        return $config;
    },
    10,
    4
);

Theme Config

Use divine/performance/theme_config to adjust the theme configuration after it has been validated and before profile and policy config merge into the effective result. It receives the validated config, the resolved theme root, and the runtime context. Return an array; a non-array result is rejected as a config error.

add_filter(
    'divine/performance/theme_config',
    function (array $config, string $themeRoot, array $context): array {
        return $config;
    },
    10,
    3
);

Effective Config

Use divine/performance/effective_config for the last word on the merged configuration. It runs after defaults, profile, policy, and theme config are merged and before Divine validates and caches the result, so it can enforce a value regardless of what the theme requested. Return an array; a non-array result is rejected and Divine falls back to its defaults.

add_filter('divine/performance/effective_config', function (array $config, array $context): array {
    $config['measurement']['enabled'] = false;

    return $config;
}, 10, 2);

Generated Hook Reference

The five filters above, together with Divine’s public actions such as divine/worktree/deployed, divine/worktree/destroyed, and divine/performance/measurement_enabled, are documented from PHPDoc into the generated hook reference. The generated hook reference is the authoritative list of every hook’s exact arguments, order, and source location; this page covers the configuration-shaped subset.