Starter Theme
studiometa/foehn-starter is the minimum a new project needs: the boot, the configuration, the templates a theme cannot render without, and the front-end build. Nothing else.
That is deliberate. A starting point you delete half of is worse than one you add to, so the demonstrations live in the demo project — every attribute the framework ships, in a theme you can read and run.
Quick Start
With DDEV (Recommended)
composer create-project studiometa/foehn-starter my-project
cd my-project
ddev start
npm install && npm run buildcomposer create-project:
- Installs the dependencies
- Generates
web/, the symlinks andwp-config.php - Writes
.envfrom.env.example, with new security keys
ddev start:
- Starts PHP 8.5, MariaDB and nginx
- Runs
composer installwhenvendor/is missing (a fresh clone) - Installs WordPress with
admin/adminand activates the theme, when WordPress is not installed
The hook is in .ddev/config.yaml. It does not change a site that is already installed.
Open your site, and seed the menus:
ddev launch # Frontend
ddev launch /wp/wp-admin # Admin (admin / admin)
ddev wp foehn seed # The header, footer and legal menusWithout DDEV
composer create-project studiometa/foehn-starter my-project
cd my-project
# Edit .env: database credentials and WP_HOMEThen point the document root of your web server to the web/ directory, install WordPress (wp core install) and activate the theme (wp theme activate starter-theme).
Project Structure
my-project/
├── theme/ # WordPress theme (versioned)
│ ├── app/
│ │ ├── ContextProviders/ # GlobalContextProvider — data every template gets
│ │ ├── Controllers/ # single, page, archive, search, 404, and the password form
│ │ ├── Hooks/ # AssetHooks (Vite build), ThemeHooks (theme supports, excerpt)
│ │ ├── Menus/ # header, footer, legal
│ │ ├── Seeders/ # MenusSeeder — the three menus, for `wp foehn seed`
│ │ ├── foehn.config.php # Framework configuration
│ │ └── page-cache.config.php # Static page cache, production only
│ ├── assets/
│ │ ├── css/app.css # Tailwind entry point
│ │ └── js/app.js # js-toolkit entry point
│ ├── templates/ # Twig templates
│ │ ├── layouts/base.twig
│ │ ├── pages/ # single, page, archive, search, 404, password
│ │ ├── sections/ # posts — the archive list, which can render alone
│ │ └── components/ # header, footer, card, pagination
│ ├── functions.php # Single boot line
│ └── style.css # Theme header
│
├── public/ # Files copied into web/ (robots.txt, .well-known/)
├── web/ # Generated document root (gitignored)
│ ├── wp/ # WordPress core
│ ├── wp-content/ # Plugins, uploads
│ └── wp-config.php # Generated config
│
├── tests/
│ ├── php/ # Unit tests: composer test
│ └── smoke/ # Tests against the site in ddev: composer test:smoke, run.sh
├── .ddev/ # DDEV configuration
├── vite.config.js # Vite, with @studiometa/foehn-vite-plugin
├── .env # Environment variables
└── composer.json # DependenciesDo not put files in web/: the next composer install does not keep them. Put the files that must be at the document root, such as robots.txt or .well-known/security.txt, in public/. See Public Files.
What's Included
Every class in theme/app/ is one a theme needs before it renders anything:
| Class | Why it is here |
|---|---|
Controllers/ | Answer WordPress's template hierarchy — single, page, archive, search, 404 |
Menus/ | The three locations header.twig and footer.twig read |
Seeders/MenusSeeder | Creates the three menus with a Home link, so wp foehn seed fills an empty database |
ContextProviders/ | Puts current_year and is_home in every template |
Hooks/AssetHooks | Enqueues the Vite build |
Hooks/ThemeHooks | Theme supports, excerpt length and more |
foehn.config.php | The discovery cache, and the framework's cleanup and security hooks |
page-cache.config.php | The static page cache, on in production only |
There are no post types, blocks, taxonomies, settings pages or bindings. Add your own with the make: commands, or copy one from the demo.
Security & Cleanup Hooks
theme/app/foehn.config.php opts into the framework's own:
return new FoehnConfig(
discoveryCacheStrategy: DiscoveryCacheStrategy::FULL,
hooks: [
CleanHeadTags::class, // Remove unnecessary <head> tags
DisableEmoji::class, // Remove emoji scripts and styles
DisableFileEditor::class, // No theme or plugin file editor in the admin
DisableGlobalStyles::class, // No theme.json styles from core (the starter has no theme.json)
DisableOembed::class, // Remove oEmbed discovery
DisableVersionDisclosure::class, // Hide the WordPress version
DisableXmlRpc::class, // Disable XML-RPC and pingbacks
GenericLoginErrors::class, // Hide username enumeration on login
StudiometaUi::class, // The @ui and @svg Twig namespaces of studiometa/ui
YouTubeNoCookieHooks::class, // Use the no-cookie YouTube domain
],
);SecurityHeaders and RestApiAuth are opt-in. If you enable SecurityHeaders, or set security headers in the server, also set them in the page cache responseHeaders: a cache hit served by nginx does not send them. See Built-in Hooks and The headers of a hit.
DDEV Commands
ddev start # Start the environment
ddev stop # Stop the environment
ddev restart # Restart after config changes
ddev launch # Open site in browser
ddev ssh # SSH into the container
ddev composer <cmd> # Run Composer commands
ddev wp <cmd> # Run WP-CLI commands
ddev describe # Show URLs and infoUnit Tests
composer test runs the Pest suite in tests/php/ without WordPress. tests/php/bootstrap.php loads two files of WordPress function stubs, in this order:
tests/php/stubs.php: the stubs of your project.vendor/studiometa/foehn/tests/wp-stubs.php: the stubs of Føhn.
Each WordPress function in the Føhn file is defined only when it does not exist yet. So a function that you define in tests/php/stubs.php is the one your tests call. A Føhn release that adds a stub with the same name does not change this:
<?php
// tests/php/stubs.php
function get_posts(array $args = []): array
{
return $GLOBALS['test_posts'] ?? [];
}Do not load your stubs after the Føhn file. A function that Føhn already defined then stops your suite with "Cannot redeclare".
The Føhn stubs record their calls. wp_stub_reset() clears the recorded calls and the stored values, wp_stub_get_calls('add_action') returns the calls of one function, and wp_stub_set_conditional('is_single', true) sets the answer of a conditional tag. The other wp_stub_* helpers and the values that the stubs return can change in a release. When a test depends on one exact return value, define that function in tests/php/stubs.php.
Customizing the Starter
Rename the Theme
The name starter-theme or foehn-starter is in these files. Change each one:
composer.json:name, andextra.foehn.theme-name(the theme directory inweb/wp-content/themes/)package.json:nametheme/style.css:Theme NameandText Domaintheme/assets/js/app.js:packageNametheme/app/Hooks/AssetHooks.php: thestarter-stylesandstarter-apphandles.ddev/config.yaml:name, andWP_HOMEin.env.exampleand.env, together. A different name makes WordPress redirect to a host that ddev does not serve.
Then run composer install to regenerate the symlinks, ddev restart, and ddev wp theme activate <your-theme-name>.
Installer Options
studiometa/foehn-installer generates web/ on each composer install and composer update. Its options go in extra.foehn of composer.json. Each option is optional:
| Option | Default | Description |
|---|---|---|
web-dir | web | The document root it generates |
wp-dir | wp | The WordPress core directory in the web root |
theme-dir | theme | The theme source directory it links |
theme-name | theme | The theme directory name in wp-content/themes/ |
mu-plugins-dir | mu-plugins | The must-use plugins directory it links |
config-dir | config | The directory of the WordPress config files |
public-dir | public | The directory it copies into the web root |
The generated web/wp-config.php reads .env, then loads two optional files from the config directory:
config/wordpress.config.php, in every environment.config/wordpress.<environment>.config.php, for exampleconfig/wordpress.staging.config.php. The environment isWP_ENVIRONMENT_TYPE, orWP_ENVwhen it is empty, orproduction.
Put define() calls there for the constants that wp-config.php does not define, for example S3_UPLOADS_USE_INSTANCE_PROFILE. The files run before the rest of wp-config.php, so a constant it defines too, such as DB_NAME or WP_DEBUG, gives a PHP warning: set these in the environment instead. Do not edit web/wp-config.php: the next composer install writes it again. See the installer README.
Add Plugins
Add WordPress plugins via Composer using wpackagist:
ddev composer require wpackagist-plugin/wordpress-seoCommercial plugins are not on wpackagist. ACF Pro, for example, has its own Composer repository: see the ACF documentation.
Environment Variables
The .env file controls database connection and environment:
DB_NAME=db
DB_USER=db
DB_PASSWORD=db
DB_HOST=db
# local, development, staging or production
WP_ENVIRONMENT_TYPE=local
WP_DEBUG=true
WP_HOME=https://my-project.ddev.site
# Locally only: run WordPress cron on page loads
DISABLE_WP_CRON=falseWP_ENVIRONMENT_TYPE is the name WordPress itself uses, and the one every part of the framework reads through Env. Anything outside production is treated as non-production: the page cache stays inert and the indexing guard keeps the site out of search results.
The generated wp-config.php turns the WordPress pseudo-cron off unless DISABLE_WP_CRON=false. .env.example sets it to false, so cron runs in a local project. In production, remove the line and run a real cron (see Deployment).
Deployment
For each release in production:
- Set
WP_ENVIRONMENT_TYPE=productionandWP_DEBUG=falsein the environment. Remove theDISABLE_WP_CRON=falseline thatcomposer installcopies from.env.exampleinto a new.env: production uses a real cron. - Install the dependencies:
composer install --no-dev. The installer generatesweb/and copiespublic/into it. - Build the front-end:
npm ci && npm run build. - Write the nginx snippet of the page cache, and include it in the server block:
wp foehn cache:config --server=nginx --write. See Installing the fast path. - Clear the page cache:
wp foehn cache:clear. It is necessary with bucket storage: the bucket keeps the pages of the previous release. - Run WordPress cron from a real cron, every minute:
wp cron event run --due-now. See The real cron. - Check the release:
wp foehn verify --profile=production. A failed check exits with a status that is not0. See Verification.
The discovery cache is already on (DiscoveryCacheStrategy::FULL). composer install clears it, and the first request writes it again.
Behind a Proxy That Terminates TLS
When a load balancer or a CDN terminates TLS and sends the requests to nginx and PHP-FPM over HTTP, WordPress does not know that the visitor uses HTTPS: is_ssl() is false, and WordPress writes http:// URLs and redirects. Set this variable in the environment:
FOEHN_TRUST_FORWARDED_PROTO=trueThe generated wp-config.php then sets $_SERVER['HTTPS'] to on when the X-Forwarded-Proto header of the request says https. With a list such as https, http, the first value counts.
Only trust the header from the proxy. A client can send X-Forwarded-Proto itself. Turn this on only when the server accepts requests from the proxy alone (a firewall or a private network), and the proxy replaces the header with its own value. It is off by default.
The Docker image maps the header in its nginx configuration and does not need this variable.
Next Steps
- Read the demo for one worked example of every attribute
- Learn about Post Types to add your first one
- Declare custom fields with #[AsPostMeta], or add ACF when you want its editing UI
- Configure Template Controllers for complex layouts
- Review Theme Conventions for best practices