From URL to HTML: Following a Semitexa Request

01 / Payload · Name the input

The URL becomes a typed request

BlogArticlePayload declares that GET /blog/{slug} produces HTML and answers with a BlogArticleResource. The path segment arrives through setSlug(). Optional query values arrive the same way, and each setter decides what a valid value is.

#[AsPublicPayload(
    path: '/blog/{slug}',
    methods: ['GET'],
    responseWith: BlogArticleResource::class,
    produces: ['text/html']
)]
final class BlogArticlePayload
{
    private string $slug = '';
    private string $scenario = 'boundary';

    public function setSlug(string $slug): void { $this->slug = $slug; }
    public function getSlug(): string { return $this->slug; }

    public function setScenario(string $scenario): void
    {
        $this->scenario = in_array($scenario, ['below', 'boundary', 'above'], true)
            ? $scenario
            : 'boundary';
    }
}

Compare it with step 1 of the controller. The scenario whitelist is the same code, but it lives next to the field it protects. When a value must be rejected rather than corrected, the setter throws a ValidationException and Semitexa answers with 422 before any handler runs.

Hands to HandlerBlogArticlePayload → slug: "from-url-to-html"

02 / Handler · Make the decision

The slug becomes an article

BlogArticleHandler receives the typed payload and a resource that Semitexa has already created for it. It asks BlogArticleResolver for the slug. An unknown slug throws NotFoundException, which becomes a 404 page. For this request, the main path reads like this:

#[AsPayloadHandler(
    payload: BlogArticlePayload::class,
    resource: BlogArticleResource::class
)]
final class BlogArticleHandler implements TypedHandlerInterface
{
    #[InjectAsReadonly]
    protected BlogArticleResolver $articles;

    public function handle(
        BlogArticlePayload $payload,
        BlogArticleResource $resource
    ): BlogArticleResource {
        $resolved = $this->articles->resolve($payload->getSlug());
        $article = $resolved->metadata;

        return $resource
            ->pageTitle($article['title'] . ' — Semitexa')
            ->seoTag('description', $article['description'])
            ->withArticle($article)
            ->renderArticle($resolved->template);
    }
}

Look at what is missing. The signature names no Request and no Response; Semitexa rejects a handler that returns a raw HTTP response. The handler cannot read a header by accident or set a status code on the side. It gets typed input and fills a typed output, which is what makes it the one place to read when you want to know what this page decides.

The lifetimes are explicit too. #[InjectAsReadonly] gives the handler one resolver shared by the worker. The handler itself is a fresh clone for every request, so nothing it holds leaks into the next visitor's page.

Hands to Resourcetitle + description + article + template

03 / Resource · Shape the response

The article becomes response data

BlogArticleResource is the contract for what goes out. Each with…() method adds one named value to the render context; withArticle() exposes the article to Twig as article.

#[AsResource(
    handle: 'site_blog_article',
    template: '@project-layouts-semitexa-site/pages/blog-article.html.twig'
)]
final class BlogArticleResource extends HtmlResponse
    implements ResourceInterface
{
    public function withArticle(array $article): self
    {
        return $this->with('article', $article);
    }

    public function renderArticle(string $template): self
    {
        $this->disableAutoRender();
        return $this->renderTemplate($template);
    }
}

Most resources never call a render method. #[AsResource(template: …)] names the view, and Semitexa renders it after the handler returns. The blog is the exception: every article has its own template, so renderArticle() renders the one the resolver chose. Metadata and template come from the same catalog entry, so the view and its data cannot drift apart.

Hands to Templatearticle.title + article.description + article.path

04 / Template · Make it visible

The response becomes a page

The article template reads the resource's article value. It extends the shared blog layout, which supplies navigation, styling and the canonical URL. The result is the HTML the browser displays: this heading, this story and the site around it.

{% extends '@project-layouts-semitexa-site/layouts/blog.html.twig' %}

{% block blog_main %}
  <article class="blog-article">
    <h1>{{ article.title }}</h1>
  </article>
{% endblock %}

Semitexa then turns the resource into the HTTP response: status, text/html and the rendered body. That was the last three lines of the controller, and no page code writes them here.

Returns to browser200 OK · text/html · a complete page