Configuration

Each config class is customized by creating a *.config.php file in your app directory.

How Config Files Work

Føhn reads every file matching the *.config.php pattern in the directories it discovers. Each file must return a config class instance:

<?php
// app/timber.config.php

use Studiometa\Foehn\Config\TimberConfig;

return new TimberConfig(
    templatesDir: ['views', 'templates'],
);

Føhn registers the returned instance in the container, under its own class and any interface it implements, so anything asking for a TimberConfig receives yours. If no config file is found, sensible defaults are used.

Installed packages are read before your own files, so a package can ship defaults that your project overrides.

Per-environment files

A file can be named for an environment, and is then read only in that one, as reported by wp_get_environment_type():

File	Read when the environment is
foehn.config.php	always
foehn.local.config.php	local
foehn.dev.config.php	development
foehn.staging.config.php	staging
foehn.production.config.php	production

The environment's own file wins over the plain file beside it, so the plain one holds what every environment shares:

<?php
// app/foehn.config.php — the default everywhere

use Studiometa\Foehn\Config\FoehnConfig;
use Tempest\Discovery\DiscoveryCacheStrategy;

return new FoehnConfig(discoveryCacheStrategy: DiscoveryCacheStrategy::NONE);

<?php
// app/foehn.production.config.php — production caches discovery

use Studiometa\Foehn\Config\FoehnConfig;
use Tempest\Discovery\DiscoveryCacheStrategy;

return new FoehnConfig(discoveryCacheStrategy: DiscoveryCacheStrategy::FULL);

WARNING

A config file replaces the object, it does not merge into it. Kernel::boot()'s configuration array is a default that a foehn.config.php overrides wholesale — prefer the file.

Available Config Classes

FoehnConfig — Core Settings

Controls the bootstrap process: discovery caching, debug mode, and opt-in hooks.

<?php
// app/foehn.config.php

use Studiometa\Foehn\Config\FoehnConfig;
use Studiometa\Foehn\Hooks\Cleanup\CleanHeadTags;
use Tempest\Discovery\DiscoveryCacheStrategy;

return new FoehnConfig(
    discoveryCacheStrategy: DiscoveryCacheStrategy::FULL,
    hooks: [CleanHeadTags::class],
    debug: false,
);

Property	Type	Default	Description
discoveryCacheStrategy	DiscoveryCacheStrategy	NONE	Discovery cache strategy
discoveryCachePath	?string	null	Custom cache path
hooks	class-string[]	[]	Opt-in hook classes
debug	bool	false	Enable discovery debug logging

See FoehnConfig API for details.

TimberConfig — Templates

Controls where Timber looks for .twig template files.

<?php
// app/timber.config.php

use Studiometa\Foehn\Config\TimberConfig;

return new TimberConfig(
    templatesDir: ['views'],
);

Property	Type	Default	Description
templatesDir	string[]	['templates']	Template directory names

See TimberConfig API for details.

AcfConfig — ACF Integration

Controls how ACF fields are handled in blocks.

<?php
// app/acf.config.php

use Studiometa\Foehn\Config\AcfConfig;

return new AcfConfig(
    transformFields: true,
);

Property	Type	Default	Description
transformFields	bool	true	Auto-convert ACF values to Timber objects

See AcfConfig API for details.

RestConfig — REST API

Controls default permissions for #[AsRestRoute] endpoints.

<?php
// app/rest.config.php

use Studiometa\Foehn\Config\RestConfig;

return new RestConfig(
    defaultCapability: 'edit_posts',
);

Property	Type	Default	Description
defaultCapability	?string	'edit_posts'	Default capability for routes

See RestConfig API for details.

RenderApiConfig — Server-side Rendering

Controls the REST endpoint for server-side template rendering.

<?php
// app/render-api.config.php

use Studiometa\Foehn\Config\RenderApiConfig;

return new RenderApiConfig(
    templates: ['partials/*', 'components/*'],
    cacheMaxAge: 3600,
);

Property	Type	Default	Description
templates	string[]	[]	Allowed template patterns
cacheMaxAge	int	0	Cache-Control max-age in seconds
debug	bool	false	Include exception details in errors

See RenderApiConfig API for details.

QueryFiltersConfig — URL Query Filtering

Controls which custom taxonomies and query vars are exposed via URL parameters.

<?php
// app/query-filters.config.php

use Studiometa\Foehn\Config\QueryFiltersConfig;

return new QueryFiltersConfig(
    taxonomies: [
        'genre' => ['in', 'not_in'],
        'product_cat' => ['in'],
    ],
    publicVars: [
        'posts_per_page' => [12, 24, 48],
    ],
);

See Guide: Query Filters for details.

Override Priority

When multiple sources provide the same config:

1. Environment config file (app/*.{environment}.config.php) — highest priority
2. Config file (app/*.config.php)
3. Package config file — defaults an installed package ships
4. Kernel::boot() array — legacy fallback (only for FoehnConfig)
5. Defaults — built-in defaults from the config class constructor

Environment-Specific Configuration

Use PHP logic in your config files for environment-specific settings:

<?php
// app/foehn.config.php

use Studiometa\Foehn\Config\FoehnConfig;
use Tempest\Discovery\DiscoveryCacheStrategy;

$isDev = defined('WP_DEBUG') && WP_DEBUG;

return new FoehnConfig(
    discoveryCacheStrategy: $isDev
        ? DiscoveryCacheStrategy::NONE
        : DiscoveryCacheStrategy::FULL,
    debug: $isDev,
);

File Structure Example

theme/
├── app/
│   ├── foehn.config.php         # Core configuration
│   ├── timber.config.php        # Template directories
│   ├── acf.config.php           # ACF settings
│   ├── rest.config.php          # REST API defaults
│   ├── render-api.config.php    # Render API allowlist
│   ├── query-filters.config.php # Query filter rules
│   ├── foehn.production.config.php # Read in production only
│   ├── Hooks/
│   ├── Models/
│   └── ...
└── functions.php

Related

• API: FoehnConfig
• API: TimberConfig
• API: AcfConfig
• API: RestConfig
• API: RenderApiConfig
• Guide: Theme Conventions