Migration from wp-toolkit

This guide helps you migrate from studiometa/wp-toolkit to studiometa/foehn. It covers every common pattern with before/after examples, common pitfalls, and a step-by-step checklist.

Overview

Føhn replaces wp-toolkit's Manager pattern with attribute-based auto-discovery powered by Tempest Framework.

Concept Mapping

wp-toolkit	Føhn	Notes
`ThemeManager::init()`	`Kernel::boot()`	Single entry point
`PostTypeManager`	`#[AsPostType]` on Timber\Post class	Auto-registers Timber classmap
`TaxonomyManager`	`#[AsTaxonomy]` on Timber\Term class	Auto-registers Timber classmap
`BlockManager`	`#[AsAcfBlock]` + `AcfBlockInterface`	Fields, compose, render in one class
`ManagerInterface::run()`	Attribute + auto-discovery	No manual registration needed
Manual `add_action()`/`add_filter()`	`#[AsAction]`/`#[AsFilter]`	On class methods
Manual `register_nav_menus()`	`#[AsMenu]`	Auto-adds to Timber context
Manual `add_image_size()`	`#[AsImageSize]`	Auto-enables `post-thumbnails`
Repository classes	Use Timber directly	Timber is the data layer
`timber/context` filter	`#[AsContextProvider]`	Scoped to specific templates
Manual `template_include` filter	`#[AsTemplateController]`	WordPress template hierarchy support
Manual `register_rest_route()`	`#[AsRestRoute]`	DI + permission management
Manual `add_shortcode()`	`#[AsShortcode]`	DI support
Manual `register_block_pattern()`	`#[AsBlockPattern]`	Twig templates for patterns
Manual Twig extension registration	`#[AsTwigExtension]`	Priority-based ordering
No equivalent	`#[AsBlock]`	Native Gutenberg + Interactivity API
No equivalent	`#[AsCliCommand]`	WP-CLI commands with DI
No equivalent	`#[AsAcfFieldGroup]`	Standalone ACF field groups
No equivalent	`#[AsAcfOptionsPage]`	ACF options pages with fields

What's Removed

These wp-toolkit patterns are intentionally not carried over:

Deprecated Pattern	Replacement
Repository classes	Use `Timber::get_posts()` / `Timber::get_post()` directly
`BaseModel` classes	Extend `Timber\Post` or `Timber\Term` directly
Manual service locator	Tempest's DI container (constructor injection)
`$theme->register()`	Auto-discovery (no registration needed)

Step 1: Install Føhn

bash

composer require studiometa/foehn
composer remove studiometa/wp-toolkit

Important: Keep both packages installed temporarily if you need a gradual migration.

Step 2: Update Theme Bootstrap

Before (wp-toolkit):

php

<?php
// functions.php

use Studiometa\WPToolkit\Managers\ThemeManager;

$theme = new ThemeManager();
$theme->init();

After (foehn):

php

<?php
// functions.php

require_once __DIR__ . '/vendor/autoload.php';

use Studiometa\Foehn\Kernel;

Kernel::boot(__DIR__ . '/app');

That's it — all your classes in app/ are now auto-discovered.

Step 3: Migrate Post Types

Before (wp-toolkit):

php

<?php
// app/PostTypes/ProductPostType.php

namespace App\PostTypes;

use Studiometa\WPToolkit\Managers\PostTypeManager;

class ProductPostType extends PostTypeManager
{
    public static string $post_type = 'product';

    public function run(): void
    {
        register_post_type(self::$post_type, [
            'label' => 'Products',
            'public' => true,
            'has_archive' => true,
            'menu_icon' => 'dashicons-cart',
            'supports' => ['title', 'editor', 'thumbnail'],
            'show_in_rest' => true,
        ]);
    }
}

After (foehn):

php

<?php
// app/Models/Product.php

namespace App\Models;

use Studiometa\Foehn\Attributes\AsPostType;
use Timber\Post;

#[AsPostType(
    name: 'product',
    singular: 'Product',
    plural: 'Products',
    public: true,
    hasArchive: true,
    menuIcon: 'dashicons-cart',
    supports: ['title', 'editor', 'thumbnail'],
    showInRest: true,
)]
final class Product extends Post
{
    public function price(): ?float
    {
        return $this->meta('price') ? (float) $this->meta('price') : null;
    }
}

Key changes:

Class extends Timber\Post directly (auto-registered in Timber's classmap)
No manual register_post_type() call
Labels are auto-generated from singular/plural
Custom methods are available in Twig: {{ post.price }}

Step 4: Migrate Taxonomies

Before (wp-toolkit):

php

<?php

namespace App\Taxonomies;

use Studiometa\WPToolkit\Managers\TaxonomyManager;

class ProductCategoryTaxonomy extends TaxonomyManager
{
    public static string $taxonomy = 'product_category';

    public function run(): void
    {
        register_taxonomy(self::$taxonomy, 'product', [
            'label' => 'Categories',
            'hierarchical' => true,
            'show_in_rest' => true,
        ]);
    }
}

After (foehn):

php

<?php
// app/Taxonomies/ProductCategory.php

namespace App\Taxonomies;

use Studiometa\Foehn\Attributes\AsTaxonomy;
use Timber\Term;

#[AsTaxonomy(
    name: 'product_category',
    postTypes: ['product'],
    singular: 'Category',
    plural: 'Categories',
    hierarchical: true,
    showInRest: true,
)]
final class ProductCategory extends Term
{
    public function icon(): ?string
    {
        return $this->meta('category_icon');
    }
}

Key changes:

Class extends Timber\Term (auto-registered in Timber's classmap)
postTypes links the taxonomy to post types declaratively

Step 5: Migrate ACF Blocks

Before (wp-toolkit):

php

<?php
// app/Blocks/HeroBlock.php

namespace App\Blocks;

use Studiometa\WPToolkit\Managers\BlockManager;
use StoutLogic\AcfBuilder\FieldsBuilder;

class HeroBlock extends BlockManager
{
    public static string $name = 'hero';
    public static string $title = 'Hero';

    public function fields(): FieldsBuilder
    {
        return (new FieldsBuilder('hero'))
            ->addText('title')
            ->addWysiwyg('content');
    }

    public function data(array $block): array
    {
        return [
            'title' => get_field('title'),
            'content' => get_field('content'),
        ];
    }
}

After (foehn):

php

<?php
// app/Blocks/Hero/HeroBlock.php

namespace App\Blocks\Hero;

use Studiometa\Foehn\Attributes\AsAcfBlock;
use Studiometa\Foehn\Contracts\AcfBlockInterface;
use Studiometa\Foehn\Contracts\ViewEngineInterface;
use StoutLogic\AcfBuilder\FieldsBuilder;

#[AsAcfBlock(
    name: 'hero',
    title: 'Hero',
    category: 'layout',
)]
final readonly class HeroBlock implements AcfBlockInterface
{
    public function __construct(
        private ViewEngineInterface $view,
    ) {}

    public static function fields(): FieldsBuilder
    {
        return (new FieldsBuilder('hero'))
            ->addText('title')
            ->addWysiwyg('content');
    }

    public function compose(array $block, array $fields): array
    {
        return [
            'title' => $fields['title'] ?? '',
            'content' => $fields['content'] ?? '',
        ];
    }

    public function render(array $context, bool $isPreview = false): string
    {
        return $this->view->render('blocks/hero', $context);
    }
}

Key changes:

data() is split into compose() (prepare data) and render() (output HTML)
Fields are passed to compose() directly — no more get_field() calls
Constructor injection for services (ViewEngine, etc.)
ACF fields are automatically transformed to Timber objects (configurable via AcfConfig)

Step 6: Migrate Hooks

Before (wp-toolkit):

php

<?php
// functions.php or scattered across multiple files

add_action('after_setup_theme', function () {
    add_theme_support('post-thumbnails');
    add_theme_support('title-tag');
    add_theme_support('html5', ['search-form', 'comment-form']);
});

add_filter('excerpt_length', fn () => 30);
add_filter('excerpt_more', fn () => '…');

// In another file...
add_action('wp_enqueue_scripts', function () {
    wp_enqueue_style('theme-style', get_stylesheet_uri());
});

After (foehn):

php

<?php
// app/Hooks/ThemeHooks.php

namespace App\Hooks;

use Studiometa\Foehn\Attributes\AsAction;
use Studiometa\Foehn\Attributes\AsFilter;

final class ThemeHooks
{
    #[AsAction('after_setup_theme')]
    public function setupTheme(): void
    {
        add_theme_support('post-thumbnails');
        add_theme_support('title-tag');
        add_theme_support('html5', ['search-form', 'comment-form']);
    }

    #[AsFilter('excerpt_length')]
    public function excerptLength(): int
    {
        return 30;
    }

    #[AsFilter('excerpt_more')]
    public function excerptMore(): string
    {
        return '…';
    }
}

php

<?php
// app/Hooks/AssetHooks.php

namespace App\Hooks;

use Studiometa\Foehn\Attributes\AsAction;

final class AssetHooks
{
    #[AsAction('wp_enqueue_scripts')]
    public function enqueueAssets(): void
    {
        wp_enqueue_style('theme-style', get_stylesheet_uri());
    }
}

Key changes:

Hooks are organized in dedicated classes by concern
Priority and accepted args can be set via attribute parameters: #[AsAction('init', priority: 5)]
Hook classes support constructor injection

Step 7: Migrate Menus

Before (wp-toolkit):

php

add_action('after_setup_theme', function () {
    register_nav_menus([
        'primary' => 'Main Navigation',
        'footer'  => 'Footer Navigation',
    ]);
});

// And in Timber context:
add_filter('timber/context', function ($context) {
    $context['menu'] = Timber::get_menu('primary');
    return $context;
});

After (foehn):

php

<?php
// app/Menus/PrimaryMenu.php

namespace App\Menus;

use Studiometa\Foehn\Attributes\AsMenu;

#[AsMenu(location: 'primary', description: 'Main Navigation')]
final class PrimaryMenu {}

php

<?php
// app/Menus/FooterMenu.php

namespace App\Menus;

use Studiometa\Foehn\Attributes\AsMenu;

#[AsMenu(location: 'footer', description: 'Footer Navigation')]
final class FooterMenu {}

Menus are automatically registered and added to the Timber context under {{ menus.primary }} and {{ menus.footer }}.

Step 8: Migrate Template Routing

Before (wp-toolkit):

php

// In functions.php or a dedicated file
add_filter('template_include', function ($template) {
    if (is_singular('product')) {
        $product = Timber::get_post();
        $context = Timber::context();
        $context['product'] = $product;
        Timber::render('pages/single-product.twig', $context);
        return '';
    }
    return $template;
});

After (foehn):

php

<?php
// app/Controllers/ProductController.php

namespace App\Controllers;

use Studiometa\Foehn\Attributes\AsTemplateController;
use Studiometa\Foehn\Contracts\TemplateControllerInterface;
use Studiometa\Foehn\Contracts\ViewEngineInterface;
use Timber\Timber;

#[AsTemplateController(templates: ['single-product'])]
final readonly class ProductController implements TemplateControllerInterface
{
    public function __construct(
        private ViewEngineInterface $view,
    ) {}

    public function handle(): ?string
    {
        $product = Timber::get_post();

        return $this->view->render('pages/single-product', [
            'product' => $product,
        ]);
    }
}

Step 9: Migrate Context Providers

Before (wp-toolkit):

php

add_filter('timber/context', function ($context) {
    $context['site_settings'] = get_fields('options');
    $context['current_year'] = date('Y');
    return $context;
});

After (foehn):

php

<?php
// app/ContextProviders/GlobalContextProvider.php

namespace App\ContextProviders;

use Studiometa\Foehn\Attributes\AsContextProvider;
use Studiometa\Foehn\Contracts\ContextProviderInterface;
use Studiometa\Foehn\Views\TemplateContext;

#[AsContextProvider(templates: ['*'])]
final class GlobalContextProvider implements ContextProviderInterface
{
    public function provide(TemplateContext $context): TemplateContext
    {
        return $context
            ->with('site_settings', function_exists('get_fields') ? get_fields('options') : [])
            ->with('current_year', date('Y'));
    }
}

Use templates: ['*'] for global data, or scope to specific templates: templates: ['pages/single-*'].

Step 10: Migrate REST Endpoints

Before (wp-toolkit):

php

add_action('rest_api_init', function () {
    register_rest_route('theme/v1', '/products', [
        'methods'  => 'GET',
        'callback' => function (WP_REST_Request $request) {
            $posts = Timber::get_posts(['post_type' => 'product']);
            return array_map(fn($p) => ['id' => $p->ID, 'title' => $p->title], $posts);
        },
        'permission_callback' => '__return_true',
    ]);
});

After (foehn):

php

<?php
// app/Rest/ProductsEndpoint.php

namespace App\Rest;

use Studiometa\Foehn\Attributes\AsRestRoute;
use Timber\Timber;
use WP_REST_Request;

final class ProductsEndpoint
{
    #[AsRestRoute(
        namespace: 'theme/v1',
        route: '/products',
        method: 'GET',
        permission: 'public',
    )]
    public function list(WP_REST_Request $request): array
    {
        $posts = Timber::get_posts(['post_type' => 'product']);

        return array_map(
            fn($p) => ['id' => $p->ID, 'title' => $p->title],
            $posts,
        );
    }
}

Step 11: Migrate Repository Classes

wp-toolkit projects often use Repository classes for data access. These are no longer needed — use Timber directly.

Before (wp-toolkit):

php

<?php

namespace App\Repositories;

class ProductRepository
{
    public function findAll(): array
    {
        return Timber::get_posts(['post_type' => 'product', 'posts_per_page' => -1]);
    }

    public function findByCategory(string $category): array
    {
        return Timber::get_posts([
            'post_type' => 'product',
            'tax_query' => [['taxonomy' => 'product_category', 'field' => 'slug', 'terms' => $category]],
        ]);
    }
}

After (foehn):

If you still want to encapsulate queries, use a plain service class with DI:

php

<?php
// app/Services/ProductService.php

namespace App\Services;

use App\Models\Product;
use Timber\Timber;

final class ProductService
{
    /** @return Product[] */
    public function findAll(): array
    {
        return Timber::get_posts(['post_type' => 'product', 'posts_per_page' => -1]);
    }

    /** @return Product[] */
    public function findByCategory(string $category): array
    {
        return Timber::get_posts([
            'post_type' => 'product',
            'tax_query' => [['taxonomy' => 'product_category', 'field' => 'slug', 'terms' => $category]],
        ]);
    }
}

The service is automatically injectable via Tempest's DI container:

php

public function __construct(
    private readonly ProductService $products,
) {}

Step 12: Update Directory Structure

Before (wp-toolkit):

theme/
├── app/
│   ├── Blocks/
│   │   └── HeroBlock.php
│   ├── PostTypes/
│   │   └── ProductPostType.php
│   ├── Repositories/
│   │   └── ProductRepository.php
│   └── Taxonomies/
│       └── ProductCategoryTaxonomy.php
├── views/
│   └── blocks/
│       └── hero.twig
└── functions.php

After (foehn):

theme/
├── app/
│   ├── Blocks/
│   │   └── Hero/
│   │       └── HeroBlock.php
│   ├── Controllers/
│   │   ├── HomeController.php
│   │   └── ProductController.php
│   ├── ContextProviders/
│   │   └── GlobalContextProvider.php
│   ├── Hooks/
│   │   ├── ThemeHooks.php
│   │   └── AssetHooks.php
│   ├── Models/
│   │   └── Product.php
│   ├── Rest/
│   │   └── ProductsEndpoint.php
│   ├── Services/
│   │   └── ProductService.php
│   ├── Taxonomies/
│   │   └── ProductCategory.php
│   └── foehn.config.php
├── templates/
│   └── blocks/
│       └── hero.twig
└── functions.php

Common Pitfalls

1. Taxonomy class must extend Timber\Term

php

// ❌ Won't work
#[AsTaxonomy(name: 'genre', singular: 'Genre', plural: 'Genres')]
final class Genre {}

// ✅ Correct
#[AsTaxonomy(name: 'genre', singular: 'Genre', plural: 'Genres')]
final class Genre extends \Timber\Term {}

2. Post type class must extend Timber\Post

php

// ❌ Won't work
#[AsPostType(name: 'product', singular: 'Product', plural: 'Products')]
final class Product {}

// ✅ Correct
#[AsPostType(name: 'product', singular: 'Product', plural: 'Products')]
final class Product extends \Timber\Post {}

3. ACF block fields method must be static

php

// ❌ Won't work
public function fields(): FieldsBuilder { ... }

// ✅ Correct
public static function fields(): FieldsBuilder { ... }

4. Hook methods must be public

php

// ❌ Won't be discovered
#[AsAction('init')]
private function onInit(): void { ... }

// ✅ Correct
#[AsAction('init')]
public function onInit(): void { ... }

5. Abstract classes and traits are skipped

Discovery only inspects concrete classes. If you have base classes with attributes, the attributes on concrete subclasses will be discovered, but the base class itself is skipped.

6. Config files must return an instance

php

// ❌ Won't work
return [
    'templatesDir' => ['views'],
];

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

7. Don't mix old and new registration

If you keep manual register_post_type() calls alongside #[AsPostType], you'll get duplicate registrations. Remove the old code when migrating.

8. Timber classmap is automatic

With wp-toolkit, you might have manually configured Timber's classmap:

php

// ❌ No longer needed
add_filter('timber/post/classmap', function ($map) {
    $map['product'] = Product::class;
    return $map;
});

Føhn registers the classmap automatically when using #[AsPostType] or #[AsTimberModel].

Migration Checklist

Phase 1: Setup

[ ] Install studiometa/foehn
[ ] Update functions.php to use Kernel::boot()
[ ] Create app/foehn.config.php if needed
[ ] Verify autoloading works

Phase 2: Content Types

[ ] Migrate post types to #[AsPostType] on Timber\Post subclasses
[ ] Migrate taxonomies to #[AsTaxonomy] on Timber\Term subclasses
[ ] Remove old PostType/Taxonomy Manager classes
[ ] Remove manual Timber classmap filters

Phase 3: Blocks

[ ] Migrate ACF blocks to #[AsAcfBlock] + AcfBlockInterface
[ ] Update data() → compose() + render()
[ ] Remove get_field() calls (fields are passed to compose())
[ ] Verify block templates still render correctly

Phase 4: Hooks & Features

[ ] Consolidate scattered hooks into hook classes
[ ] Migrate menus to #[AsMenu]
[ ] Migrate image sizes to #[AsImageSize] (if applicable)
[ ] Migrate shortcodes to #[AsShortcode] (if applicable)

Phase 5: Views & Templates

[ ] Migrate timber/context filters to #[AsContextProvider]
[ ] Migrate template routing to #[AsTemplateController]
[ ] Update Twig templates for new context variables (e.g. {{ menus.primary }})

Phase 6: API & Services

[ ] Migrate REST endpoints to #[AsRestRoute]
[ ] Convert Repository classes to Service classes (or remove them)
[ ] Use constructor injection instead of service locators

Phase 7: Cleanup

[ ] Remove studiometa/wp-toolkit dependency
[ ] Remove unused Manager base classes
[ ] Remove manual registration code from functions.php
[ ] Run tests
[ ] Verify all functionality in browser

Need Help?

If you encounter issues during migration:

Check the Guide for detailed documentation
Review the API Reference for attribute parameters
See Theme Conventions for directory structure
See Configuration for config file setup
Open an issue on GitHub

Migration from wp-toolkit ​

Overview ​

Concept Mapping ​

What's Removed ​

Step 1: Install Føhn ​

Step 2: Update Theme Bootstrap ​

Step 3: Migrate Post Types ​

Step 4: Migrate Taxonomies ​

Step 5: Migrate ACF Blocks ​

Step 6: Migrate Hooks ​

Step 7: Migrate Menus ​

Step 8: Migrate Template Routing ​

Step 9: Migrate Context Providers ​

Step 10: Migrate REST Endpoints ​

Step 11: Migrate Repository Classes ​

Step 12: Update Directory Structure ​

Common Pitfalls ​

1. Taxonomy class must extend Timber\Term ​

2. Post type class must extend Timber\Post ​

3. ACF block fields method must be static ​

4. Hook methods must be public ​

5. Abstract classes and traits are skipped ​

6. Config files must return an instance ​

7. Don't mix old and new registration ​

8. Timber classmap is automatic ​

Migration Checklist ​

Phase 1: Setup ​

Phase 2: Content Types ​

Phase 3: Blocks ​

Phase 4: Hooks & Features ​

Phase 5: Views & Templates ​

Phase 6: API & Services ​

Phase 7: Cleanup ​

Need Help? ​

Migration from wp-toolkit

Overview

Concept Mapping

What's Removed

Step 1: Install Føhn

Step 2: Update Theme Bootstrap

Step 3: Migrate Post Types

Step 4: Migrate Taxonomies

Step 5: Migrate ACF Blocks

Step 6: Migrate Hooks

Step 7: Migrate Menus

Step 8: Migrate Template Routing

Step 9: Migrate Context Providers

Step 10: Migrate REST Endpoints

Step 11: Migrate Repository Classes

Step 12: Update Directory Structure

Common Pitfalls

1. Taxonomy class must extend Timber\Term

2. Post type class must extend Timber\Post

3. ACF block fields method must be static

4. Hook methods must be public

5. Abstract classes and traits are skipped

6. Config files must return an instance

7. Don't mix old and new registration

8. Timber classmap is automatic

Migration Checklist

Phase 1: Setup

Phase 2: Content Types

Phase 3: Blocks

Phase 4: Hooks & Features

Phase 5: Views & Templates

Phase 6: API & Services

Phase 7: Cleanup

Need Help?