TemplateControllerInterface

Interface for template controllers that handle full template rendering.

Signature

<?php

namespace Studiometa\Foehn\Contracts;

use Studiometa\Foehn\Views\TemplateContext;

interface TemplateControllerInterface
{
    /**
     * Handle the template request.
     *
     * This method is called when WordPress would render a matching template.
     * It should return the rendered HTML or null to let WordPress handle it.
     *
     * @param TemplateContext $context Typed Timber context with post, site, user, etc.
     * @return string|null Rendered HTML or null to pass through
     */
    public function handle(TemplateContext $context): ?string;
}

Methods

handle(TemplateContext $context)

Handle the template request. The $context parameter is a typed object providing access to Timber globals and custom data. Return rendered HTML or null to let WordPress handle it normally.

public function handle(TemplateContext $context): ?string
{
    $post = $context->post;

    // Return null to pass through to WordPress
    if (!$post) {
        return null;
    }

    return $this->view->render('single', $context);
}

TemplateContext API

The TemplateContext object provides:

Typed Properties

$context->post;   // ?Post - current post
$context->posts;  // ?PostCollectionInterface - posts collection
$context->site;   // Site - site info
$context->user;   // ?User - current user

Post Type Casting

// Cast post to specific type with IDE support
$product = $context->post(Product::class); // ?Product

// Validate posts collection type
$products = $context->posts(Product::class); // ?PostCollectionInterface<Product>

Dynamic Keys

// Get dynamic keys
$context->get('key');              // mixed
$context->get('key', 'default');   // with default
$context->has('key');              // bool
$context['key'];                   // ArrayAccess

Immutable Updates

// Add single key
$context = $context->with('key', $value);

// Merge array or Arrayable
$context = $context->merge(['a' => 1, 'b' => 2]);

// Add typed DTO
$context = $context->withDto($myDto);
$context->dto(MyDto::class); // ?MyDto

Conversion

// Convert to array for ViewEngine
$context->toArray(); // array<string, mixed>

Usage

<?php

namespace App\Controllers;

use Studiometa\Foehn\Attributes\AsTemplateController;
use Studiometa\Foehn\Contracts\TemplateControllerInterface;
use Studiometa\Foehn\Contracts\ViewEngineInterface;
use Studiometa\Foehn\Views\TemplateContext;

#[AsTemplateController('single')]
final class SingleController implements TemplateControllerInterface
{
    public function __construct(
        private readonly ViewEngineInterface $view,
    ) {}

    public function handle(TemplateContext $context): ?string
    {
        $post = $context->post;

        $context = $context->with('related', $this->getRelatedPosts($post));

        return $this->view->render('single', $context);
    }

    private function getRelatedPosts($post): array
    {
        return \Timber\Timber::get_posts([
            'post_type' => $post->post_type,
            'posts_per_page' => 3,
            'post__not_in' => [$post->ID],
        ]);
    }
}

Custom Post Type

use App\Models\Product;

#[AsTemplateController('single-product')]
final class SingleProductController implements TemplateControllerInterface
{
    public function handle(TemplateContext $context): ?string
    {
        $product = $context->post(Product::class);

        if ($product === null) {
            return null;
        }

        $context = $context
            ->with('price', $product->formattedPrice())
            ->with('related', $product->relatedProducts(4));

        return $this->view->render('single-product', $context);
    }
}

With Typed DTO

use Studiometa\Foehn\Contracts\Arrayable;
use Studiometa\Foehn\Concerns\HasToArray;

final readonly class ProductPageData implements Arrayable
{
    use HasToArray;

    public function __construct(
        public array $related,
        public ?float $averageRating,
    ) {}
}

#[AsTemplateController('single-product')]
final class SingleProductController implements TemplateControllerInterface
{
    public function handle(TemplateContext $context): ?string
    {
        $product = $context->post(Product::class);

        if ($product === null) {
            return null;
        }

        $context = $context->withDto(new ProductPageData(
            related: $product->relatedProducts(4),
            averageRating: $product->averageRating(),
        ));

        return $this->view->render('single-product', $context);
    }
}

Related

• Guide: Template Controllers
• #[AsTemplateController]