studiometa / foehn
đ A modern WordPress framework powered by Tempest, featuring attribute-based auto-discovery for hooks, post types, blocks, and more.
Requires
- php: ^8.5
- druidfi/mysqldump-php: ^2
- psr/simple-cache: ^3
- studiometa/twig-toolkit: ^2.1
- tempest/container: ^3.18
- tempest/discovery: ^3.18
- tempest/generation: ^3.18
- tempest/support: ^3.18
- timber/timber: ^2.5
- vlucas/phpdotenv: ^5.6
Requires (Dev)
- league/flysystem-aws-s3-v3: ^3.0
- league/glide: ^4.1
- studiometa/ui: ^1.10
Suggests
- league/flysystem-aws-s3-v3: Lets GlideTransformer read and cache in the same bucket as humanmade/s3-uploads
- league/glide: Self-hosted image transforms for GlideTransformer (with league/flysystem-aws-s3-v3 when uploads live in a bucket)
- studiometa/ui: Twig UI components, auto-registered under the @ui and @svg namespaces
- studiometa/webpack-config: Required for WebpackManifest asset helper
Provides
None
Conflicts
None
Replaces
None
README
A modern WordPress framework powered by Tempest Framework, featuring attribute-based auto-discovery for hooks, post types, blocks, and more.
Note This package is part of the Føhn Framework monorepo. Please report issues and submit pull requests in the main repository.
Requirements
- PHP 8.5+
- WordPress 6.4+
- Composer
Installation
composer require "nette/php-generator:4.2.3 as 4.2.1" studiometa/foehn
The nette/php-generator alias is necessary until Tempest fixes its requirement. See Installation.
Quick Start
Bootstrap Føhn in your theme's functions.php:
<?php declare(strict_types=1); use Studiometa\Foehn\Kernel; Kernel::boot(__DIR__ . '/app');
That's it! Føhn will automatically discover and register all your classes in the app/ directory.
Features
Hooks
Register WordPress actions and filters directly on your methods:
<?php use Studiometa\Foehn\Attributes\AsAction; use Studiometa\Foehn\Attributes\AsFilter; final class ThemeHooks { #[AsAction('after_setup_theme')] public function setup(): void { add_theme_support('post-thumbnails'); add_theme_support('title-tag'); } #[AsFilter('excerpt_length')] public function excerptLength(): int { return 30; } }
Post Types
Define custom post types as classes with automatic Timber classmap integration:
<?php use Studiometa\Foehn\Attributes\AsPostType; use Studiometa\Foehn\Models\Post; #[AsPostType( name: 'product', singular: 'Product', plural: 'Products', public: true, hasArchive: true, menuIcon: 'dashicons-cart', supports: ['title', 'editor', 'thumbnail'], )] final class Product extends Post { public function price(): ?float { return $this->meta('price') ? (float) $this->meta('price') : null; } }
Taxonomies
<?php use Studiometa\Foehn\Attributes\AsTaxonomy; #[AsTaxonomy( name: 'product_category', singular: 'Category', plural: 'Categories', postTypes: ['product'], hierarchical: true, )] final class ProductCategory {}
ACF Blocks
ACF blocks, field groups and options pages come from the separate studiometa/foehn-acf package. Install it with the same version as studiometa/foehn. Create ACF blocks with dependency injection:
<?php use Studiometa\Foehn\Attributes\AsAcfBlock; use Studiometa\Foehn\Contracts\AcfBlockInterface; use Studiometa\Foehn\Contracts\ViewEngineInterface; use StoutLogic\AcfBuilder\FieldsBuilder; #[AsAcfBlock( name: 'hero', title: 'Hero Banner', category: 'design', icon: 'cover-image', )] final readonly class HeroBlock implements AcfBlockInterface { public function __construct( private ViewEngineInterface $view, ) {} public static function fields(): FieldsBuilder { return (new FieldsBuilder('hero')) ->addImage('background') ->addWysiwyg('content') ->addLink('cta'); } public function compose(array $block, array $fields): array { return [ 'background' => $fields['background'] ?? null, 'content' => $fields['content'] ?? '', 'cta' => $fields['cta'] ?? null, ]; } public function render(array $context, bool $isPreview = false): string { return $this->view->render('blocks/hero', $context); } }
Typed DTOs for Block Context
Instead of returning plain arrays from compose(), use typed DTOs for autocompletion and type safety:
<?php use Studiometa\Foehn\Concerns\HasToArray; use Studiometa\Foehn\Contracts\Arrayable; use Studiometa\Foehn\Data\ImageData; use Studiometa\Foehn\Data\LinkData; final readonly class HeroContext implements Arrayable { use HasToArray; public function __construct( public string $title, public ?ImageData $background = null, public ?LinkData $cta = null, public string $height = 'medium', ) {} }
Then use it in your block:
public function compose(array $block, array $fields): HeroContext { return new HeroContext( title: $fields['title'] ?? '', background: ImageData::fromAttachmentId($fields['background'] ?? null), cta: LinkData::fromAcf($fields['cta_link'] ?? null), height: $fields['height'] ?? 'medium', ); }
The DTO is automatically flattened to a snake_case array before reaching render() and Twig templates. Property names like imageUrl become image_url in the template context.
Built-in DTOs:
| DTO | Description | Factory |
|---|---|---|
LinkData |
Link/button fields | LinkData::fromAcf($acfLink) |
ImageData |
Image/attachment fields | ImageData::fromAttachmentId($id) |
SpacingData |
Spacing fields | SpacingData::fromAcf($fields['spacing']) |
All compose() methods on AcfBlockInterface, BlockInterface and BlockPatternInterface accept either array or Arrayable return types.
Native Gutenberg Blocks with Interactivity API
<?php use Studiometa\Foehn\Attributes\AsBlock; use Studiometa\Foehn\Contracts\InteractiveBlockInterface; use WP_Block; #[AsBlock( name: 'theme/accordion', title: 'Accordion', category: 'widgets', interactivity: true, )] final readonly class AccordionBlock implements InteractiveBlockInterface { public static function attributes(): array { return [ 'items' => ['type' => 'array', 'default' => []], 'allowMultiple' => ['type' => 'boolean', 'default' => false], ]; } public static function initialState(): array { return []; } public function initialContext(array $attributes): array { return [ 'openItems' => [], 'allowMultiple' => $attributes['allowMultiple'] ?? false, ]; } public function compose(array $attributes, string $content, WP_Block $block): array { return ['items' => $attributes['items'] ?? []]; } public function render(array $attributes, string $content, WP_Block $block): string { // ... } }
Context Providers
Inject data into the views that match a view name, such as pages/single:
<?php use Studiometa\Foehn\Attributes\AsContextProvider; use Studiometa\Foehn\Contracts\ContextProviderInterface; use Studiometa\Foehn\Views\TemplateContext; #[AsContextProvider(['pages/single', 'pages/single-*'])] final readonly class SingleContext implements ContextProviderInterface { public function provide(TemplateContext $context): TemplateContext { $post = $context->post; return $context ->with('reading_time', $this->calculateReadingTime($post->content())) ->with('related_posts', $this->getRelatedPosts($post)); } }
Template Controllers
Handle template rendering with full control:
<?php use Studiometa\Foehn\Attributes\AsTemplateController; use Studiometa\Foehn\Contracts\TemplateControllerInterface; use Studiometa\Foehn\Contracts\ViewEngineInterface; use Studiometa\Foehn\Views\TemplateContext; #[AsTemplateController(['single', 'single-*'])] final readonly class SingleController implements TemplateControllerInterface { public function __construct( private ViewEngineInterface $view, ) {} public function handle(TemplateContext $context): ?string { return $this->view->renderFirst([ "pages/single-{$context->post?->post_type}", 'pages/single', ], $context); } }
Block Patterns
Register block patterns with Twig templates:
<?php use Studiometa\Foehn\Attributes\AsBlockPattern; use Studiometa\Foehn\Contracts\BlockPatternInterface; #[AsBlockPattern( name: 'theme/hero-full-width', title: 'Hero Full Width', categories: ['heroes'], )] final readonly class HeroFullWidth implements BlockPatternInterface { public function compose(): array { return [ 'heading' => __('Welcome', 'theme'), 'cta_text' => __('Learn more', 'theme'), ]; } }
REST API Routes
<?php use Studiometa\Foehn\Attributes\AsRestRoute; use WP_REST_Request; final class ProductsApi { #[AsRestRoute('theme/v1', '/products', method: 'GET', permission: 'public')] public function index(WP_REST_Request $request): array { return ['products' => []]; } #[AsRestRoute('theme/v1', '/products/(?P<id>\d+)', method: 'GET', permission: 'public')] public function show(WP_REST_Request $request): array { return ['product' => []]; } }
Shortcodes
<?php use Studiometa\Foehn\Attributes\AsShortcode; final class ButtonShortcode { #[AsShortcode('button')] public function render(array $atts, ?string $content = null): string { $atts = shortcode_atts([ 'url' => '#', 'style' => 'primary', ], $atts); return sprintf( '<a href="%s" class="btn btn--%s">%s</a>', esc_url($atts['url']), esc_attr($atts['style']), esc_html($content) ); } }
CLI Commands
Føhn provides WP-CLI commands for scaffolding:
# Generate a new native block wp foehn make:block Hero # Generate a new ACF block (needs studiometa/foehn-acf) wp foehn-acf make:acf-block Hero # Generate a new post type wp foehn make:post-type product # Generate a new taxonomy wp foehn make:taxonomy ProductCategory --post-types=product # Clear discovery cache wp foehn discovery:clear # Scan every location and write the discovery cache wp foehn discovery:generate
See CLI Commands for every command.
Dependency Injection
All discovered classes support constructor injection via Tempest's container:
<?php use Studiometa\Foehn\Attributes\AsAction; final readonly class NewsletterHooks { public function __construct( private NewsletterService $newsletter, ) {} #[AsAction('user_register')] public function onUserRegister(int $userId): void { $user = get_user_by('id', $userId); $this->newsletter->subscribe($user->user_email); } }
Configuration
Føhn reads each *.config.php file of the app/ directory. app/foehn.config.php returns the core configuration:
<?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], );
Other files configure Timber, REST routes, query filters, the page cache and more. See Configuration.
Documentation
For complete documentation, see the Føhn documentation.
For AI agents, this package ships the foehn Agent Skill in skills/foehn/SKILL.md. See AI Agents to install it.
License
GNU General Public License v3.0 or later. See LICENSE for details.