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

Semitexa can also serve GraphQL-first APIs. The public entrypoint is still POST /graphql, but the use case behind each field remains explicit through payload and output contracts.

How it works

A GraphQL-first operation declares #[ExposeAsGraphql(...)] on a dedicated payload and returns a typed output DTO. The transport may be GraphQL-only, but the application structure still avoids the usual resolver sprawl of ad-hoc field classes and improvised arrays.

Why it matters

This keeps GraphQL honest. Teams get the graph they want without paying for a second hidden application layer made of resolver glue.

Key concepts

POST /graphql: The public transport endpoint used by GraphQL clients.
GraphQL-first: A use case that is exposed only through the graph and does not need a public REST route.
typed output DTO: A concrete class that owns the public GraphQL response shape.

Transport POST /graphql

GraphQL field query.productMetrics

Returns ProductMetricsGraphqlView

Example query

query {
  productMetrics {
    total
    active
    archived
    averagePrice
  }
}

Example response

{
  "data": {
    "productMetrics": {
      "total": 128,
      "active": 117,
      "archived": 11,
      "averagePrice": 189.4
    }
  }
}

#[ExposeAsGraphql] typed output DTOs

Verified against Semitexa Ultimate 2026.09.19.1020

GraphQL API

If your public API is GraphQL-first, Semitexa still keeps the application layer explicit and typed.

How it works

A GraphQL-only endpoint uses #[ExposeAsGraphql] on the Payload DTO to register the operation into the GraphQL schema under a declared field name and root type (Query or Mutation). The handler returns a typed output DTO — a plain PHP class — and the framework serializes it into the GraphQL response shape. No resolver classes, no schema-first string parsing, no separate type registry to maintain.

Why this matters

GraphQL-first Semitexa APIs still use typed payloads and typed output DTOs. The application logic lives in the handler, which keeps business code away from transport concerns. Adding a new GraphQL field means adding one Payload DTO with the attribute — the schema updates automatically on the next boot.

1<?php23declare(strict_types=1);45namespace App\Api\Graphql;67use App\Api\Graphql\Output\ProductMetricsGraphqlView;8use Semitexa\Core\Attribute\AsPublicPayload;9use Semitexa\Core\Http\Response\ResourceResponse;10use Semitexa\Graphql\Attribute\ExposeAsGraphql;1112#[AsPublicPayload(13    path: '/__graphql/products/metrics',14    methods: ['POST'],15    responseWith: ResourceResponse::class,16)]17#[ExposeAsGraphql(18    field: 'productMetrics',19    rootType: 'query',20    output: ProductMetricsGraphqlView::class,21)]22final class ProductMetricsPayload23{24    protected string $status = 'active';2526    public function getStatus(): string { return $this->status; }27    public function setStatus(string $status): void { $this->status = trim($status); }28}29

<?php

declare(strict_types=1);

namespace App\Api\Graphql;

use App\Api\Graphql\Output\ProductMetricsGraphqlView;
use Semitexa\Core\Attribute\AsPublicPayload;
use Semitexa\Core\Http\Response\ResourceResponse;
use Semitexa\Graphql\Attribute\ExposeAsGraphql;

#[AsPublicPayload(
    path: '/__graphql/products/metrics',
    methods: ['POST'],
    responseWith: ResourceResponse::class,
)]
#[ExposeAsGraphql(
    field: 'productMetrics',
    rootType: 'query',
    output: ProductMetricsGraphqlView::class,
)]
final class ProductMetricsPayload
{
    protected string $status = 'active';

    public function getStatus(): string { return $this->status; }
    public function setStatus(string $status): void { $this->status = trim($status); }
}

1<?php23declare(strict_types=1);45namespace App\Api\Graphql\Output;67final readonly class ProductMetricsGraphqlView8{9    public function __construct(10        public int $total,11        public int $active,12        public int $archived,13        public float $averagePrice,14    ) {}15}16

<?php

declare(strict_types=1);

namespace App\Api\Graphql\Output;

final readonly class ProductMetricsGraphqlView
{
    public function __construct(
        public int $total,
        public int $active,
        public int $archived,
        public float $averagePrice,
    ) {}
}

1query {2  productMetrics {3    total4    active5    archived6    averagePrice7  }8}9

query {
  productMetrics {
    total
    active
    archived
    averagePrice
  }
}

GraphQL-First

What this page is proving

Question	Semitexa answer
Do I need a public REST route first?	No. The public story can be `POST /graphql` from day one.
Does GraphQL push me into resolver classes everywhere?	No. The use case still hangs on explicit payload and output contracts.
Where does the response shape live?	In a typed output DTO instead of improvised arrays and field-by-field resolver glue.

How it works

Why it matters

This keeps GraphQL honest. Teams get the graph they want without paying for a second hidden application layer made of resolver glue.

Key concepts

POST /graphql: The public transport endpoint used by GraphQL clients.
GraphQL-first: A use case that is exposed only through the graph and does not need a public REST route.
typed output DTO: A concrete class that owns the public GraphQL response shape.

Find a concept, task, or command

GraphQL API

What this does

How it works

Why it matters

Key concepts

GraphQL-first without resolver sprawl

GraphQL API

How it works

Why this matters

What this page is proving

How it works

Why it matters

Key concepts