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.
To read a setting, inject its config class in a constructor, or get it from the container with app(TimberConfig::class). Føhn has no config('key') helper.
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 |
imageTransformer | ?class-string | null | The ImageTransformer class image_url() uses. null gives back the URL unchanged. See Images |
debug | bool | false | Raise PHP warnings: each class discovery skips, a discovery cache it cannot write, a missing block editor registrar |
recordErrors | ?bool | null | Write errors to the log wp foehn errors reads. null records them in the local and development environments |
traceRequests | ?bool | null | Store a trace of each front-end request for wp foehn trace. null traces them in local and development |
cliNamespace | string | 'app' | The WP-CLI command the project's #[AsCliCommand] classes go under: wp app <name> |
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. The class comes from studiometa/foehn-acf, which also ships its default. Without that package, app/acf.config.php fails with a class-not-found error.
<?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.
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.
PageCacheConfig — Page Cache
Controls the static page cache: when it is on, how long a page stays, and where pages are stored.
<?php
// app/page-cache.config.php
use Studiometa\Foehn\Config\PageCacheConfig;
return new PageCacheConfig(enabled: true, ttl: 8 * HOUR_IN_SECONDS, environments: ['production']);See PageCacheConfig API and Guide: Page Cache for details.
DatabaseExportConfig — Database Export
Controls what wp foehn db:export keeps: the tables to export with or without rows, and the columns to anonymize.
<?php
// app/db-export.config.php
use Studiometa\Foehn\Config\DatabaseExportConfig;
return new DatabaseExportConfig(
structureOnlyTables: ['actionscheduler_*'],
allowedEmailDomains: ['example.com'],
);See Guide: Database Export for details.
Override Priority
When multiple sources provide the same config:
- Environment config file (
app/*.{environment}.config.php) — highest priority - Config file (
app/*.config.php) - Package config file — defaults an installed package ships
- Kernel::boot() array — legacy fallback (only for
FoehnConfig) - 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
│ ├── query-filters.config.php # Query filter rules
│ ├── page-cache.config.php # Page cache
│ ├── db-export.config.php # Database export
│ ├── foehn.production.config.php # Read in production only
│ ├── Hooks/
│ ├── Models/
│ └── ...
└── functions.php