Search by

studiometa / foehn

titouanmathis

🍃 A modern WordPress framework powered by Tempest, featuring attribute-based auto-discovery for hooks, post types, blocks, and more.

Package info

github.com/studiometa/foehn

Homepage

pkg:composer/studiometa/foehn

Statistics

Installs: 794

Dependents: 2

Suggesters: 0

Stars: 4

Open Issues: 1

0.11.4 2026-11-18 10:22 UTC

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.