Feature Guide

A quick orientation block that answers the essential questions: what this feature does, how it works, why it matters, and the key concepts behind it.

What this does

A single endpoint serves JSON, HTML, or other formats depending on the Accept header or ?_format= query parameter.

How it works

The produces array in #[AsPayload] declares which Content-Types the endpoint supports. The framework negotiates the best match against the client Accept header and selects the appropriate response serializer.

Why it matters

Content negotiation lets one route serve both browser and API clients. The handler stays format-agnostic — it populates the resource DTO, and the framework handles serialization.

Key concepts

produces: Declares the Content-Types an endpoint can return, enabling content negotiation.
Accept header: HTTP header the client sends to indicate preferred response formats.

Negotiation

One endpoint, multiple representations

The same handler output can render as HTML for browsers or JSON for API consumers.

GET /demo/routing/content-negotiation Single endpoint

Accept: text/html or Accept: application/json Representation switch

HTML response

Wireless Headphones

Rendered as a normal SSR page fragment for the browser.

$79.99

Mechanical Keyboard

Rendered as a normal SSR page fragment for the browser.

$129.99

Ultra-wide Monitor

Rendered as a normal SSR page fragment for the browser.

$549.99

{
    "products": [
        {
            "id": "1",
            "name": "Wireless Headphones",
            "price": 79.99
        },
        {
            "id": "2",
            "name": "Mechanical Keyboard",
            "price": 129.99
        },
        {
            "id": "3",
            "name": "Ultra-wide Monitor",
            "price": 549.99
        }
    ]
}

Try ?_format=json

?_format= override ContentNegotiator

Verified against Semitexa Ultimate 2026.09.19.1020

Content Negotiation

A single endpoint serves JSON, HTML, or other formats depending on the Accept header or ?_format= query parameter.

How it works

The produces array on the payload's access attribute (#[AsPublicPayload], #[AsProtectedPayload], or #[AsServicePayload]) declares which Content-Types the endpoint supports. The framework negotiates the best match against the client Accept header and selects the appropriate response serializer.

Why this matters

Content negotiation lets one route serve both browser and API clients. The handler stays format-agnostic — it populates the resource DTO, and the framework handles serialization.

1<?php23declare(strict_types=1);45namespace App\Application\Payload\Routing;67use App\Application\Resource\Page\ProductCollectionPageResource;8use Semitexa\Core\Attribute\AsPublicPayload;910#[AsPublicPayload(11    path: '/products',12    methods: ['GET'],13    responseWith: ProductCollectionPageResource::class,14    produces: ['text/html', 'application/json'],15)]16final class ContentNegotiationPayload17{18}19

<?php

declare(strict_types=1);

namespace App\Application\Payload\Routing;

use App\Application\Resource\Page\ProductCollectionPageResource;
use Semitexa\Core\Attribute\AsPublicPayload;

#[AsPublicPayload(
    path: '/products',
    methods: ['GET'],
    responseWith: ProductCollectionPageResource::class,
    produces: ['text/html', 'application/json'],
)]
final class ContentNegotiationPayload
{
}

1<?php23declare(strict_types=1);45namespace App\Application\Handler\Routing;67use App\Application\Payload\Routing\ContentNegotiationPayload;8use App\Application\Resource\Page\ProductCollectionPageResource;9use App\Domain\Catalog\ProductCatalogReaderInterface;10use Semitexa\Core\Attribute\AsPayloadHandler;11use Semitexa\Core\Attribute\InjectAsReadonly;12use Semitexa\Core\Contract\TypedHandlerInterface;1314#[AsPayloadHandler(payload: ContentNegotiationPayload::class, resource: ProductCollectionPageResource::class)]15final class ContentNegotiationHandler implements TypedHandlerInterface16{17    #[InjectAsReadonly]18    protected ProductCatalogReaderInterface $catalogReader;1920    public function handle(ContentNegotiationPayload $payload, ProductCollectionPageResource $resource): ProductCollectionPageResource21    {22        return $resource->fromProducts($this->catalogReader->listVisibleProducts());23    }24}25

<?php

declare(strict_types=1);

namespace App\Application\Handler\Routing;

use App\Application\Payload\Routing\ContentNegotiationPayload;
use App\Application\Resource\Page\ProductCollectionPageResource;
use App\Domain\Catalog\ProductCatalogReaderInterface;
use Semitexa\Core\Attribute\AsPayloadHandler;
use Semitexa\Core\Attribute\InjectAsReadonly;
use Semitexa\Core\Contract\TypedHandlerInterface;

#[AsPayloadHandler(payload: ContentNegotiationPayload::class, resource: ProductCollectionPageResource::class)]
final class ContentNegotiationHandler implements TypedHandlerInterface
{
    #[InjectAsReadonly]
    protected ProductCatalogReaderInterface $catalogReader;

    public function handle(ContentNegotiationPayload $payload, ProductCollectionPageResource $resource): ProductCollectionPageResource
    {
        return $resource->fromProducts($this->catalogReader->listVisibleProducts());
    }
}

How it works

Why it matters

Content negotiation lets one route serve both browser and API clients. The handler stays format-agnostic — it populates the resource DTO, and the framework handles serialization.

Key concepts

produces: Declares the Content-Types an endpoint can return, enabling content negotiation.
Accept header: HTTP header the client sends to indicate preferred response formats.