# Configuration Reference

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](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](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.

```php
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.

```php
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.

```php
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.

```php
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.

```php
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](hooks) is the authoritative list of every hook's exact arguments, order, and source location; this page covers the configuration-shaped subset.
</content>