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 payload can keep the route contract in PHP while still letting operations move the public URL through .env.

How it works

AsPayload path values support env::VAR::/fallback syntax. During route discovery, Semitexa resolves the env key first and falls back to the inline path when the variable is absent.

Why it matters

This gives deployment flexibility without losing the architectural advantage of payload-owned routes. The route remains reviewable in code, but environment-specific URL decisions stop forcing PHP edits.

Key concepts

env::VAR_NAME::/fallback: Environment-aware attribute syntax that resolves to an env value with a safe inline default.
resolved route metadata: The runtime route definition after env placeholders, inherited attributes, and response metadata have been normalized.
payload-owned route contract: The payload DTO remains the canonical place where path, methods, response type, and alternates are declared.

Operational Flexibility

One payload, environment-specific URL

The payload class remains the canonical route owner, while ops can remap the public path with one env value and still keep the same handler, resource, alternates, and docs surface.

The attribute keeps a safe fallback path directly in PHP, so the route is still readable in code review.

If the env key is present, Semitexa resolves that value during route discovery and the live route moves without editing the payload source.

Because the payload still owns the route contract, the sidebar links, alternate JSON representation, and crawler inventory stay aligned with the resolved path.

DEMO_ENV_ROUTE_OVERRIDE_PATH=/demo/http/env-override

#[AsPublicPayload(
    path: 'env::DEMO_ENV_ROUTE_OVERRIDE_PATH::/demo/routing/env-route-override',
    methods: ['GET'],
    responseWith: DemoFeatureResource::class,
)]

Input	Value	Effect
Env key	`DEMO_ENV_ROUTE_OVERRIDE_PATH`	Controls the externally visible route path
Fallback path	`/demo/routing/env-route-override`	Used when the env key is absent
Resolved path now	`/demo/routing/env-route-override`	Running on fallback route

This is intentionally boring in the best way: the handler does not change, the resource does not change, and the payload still stays the single place where the route contract is declared.

env::VAR::/fallback path override .env-driven routing same payload boundary

Verified against Semitexa Ultimate 2026.09.19.1020

Env Route Override

A payload can keep the route contract in PHP while still letting operations move the public URL through .env.

How it works

The path: argument on the payload's access attribute supports env::VAR::/fallback syntax. During route discovery, Semitexa resolves the env key first and falls back to the inline path when the variable is absent.

Why this matters

What can be overridden

Any string field on #[AsPublicPayload] can use env resolution, but the most valuable ones for routing are:

path
name
responseWith

In practice, path is the main one you should expose for environment-level URL control.

Example: keep code stable, move the URL per environment

#[AsPublicPayload(
    path: 'env::DEMO_BASIC_ROUTE_PATH::/demo/routing/basic',
    methods: ['GET'],
    responseWith: DemoFeatureResource::class,
    produces: ['application/json', 'text/html'],
)]
final class BasicRoutePayload
{
}

.env:

DEMO_BASIC_ROUTE_PATH=/demo/http/basic-route

Without changing PHP code, the payload now resolves to:

/demo/http/basic-route

If the env key is absent, Semitexa falls back to:

/demo/routing/basic

Guidance

Prefer env::VAR::default over env::VAR so the route always has a safe fallback.
Use this for operational flexibility, not as a substitute for route design.
Keep the payload class name and handler stable even if the public URL changes.
When the route is an SSR page, its alternate links and route discovery continue to follow the resolved payload path.

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

<?php

declare(strict_types=1);

namespace App\Application\Payload\Routing;

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

#[AsPublicPayload(
    path: 'env::CATALOG_ROUTE_PATH::/catalog',
    methods: ['GET'],
    responseWith: CatalogLandingResource::class,
    produces: ['text/html'],
)]
final class EnvRouteOverridePayload
{
}

1<?php23declare(strict_types=1);45namespace App\Application\Handler\Routing;67use App\Application\Payload\Routing\EnvRouteOverridePayload;8use App\Application\Resource\Page\CatalogLandingResource;9use App\Domain\Catalog\CatalogRouteInspectorInterface;10use Semitexa\Core\Attribute\AsPayloadHandler;11use Semitexa\Core\Attribute\InjectAsReadonly;12use Semitexa\Core\Contract\TypedHandlerInterface;1314#[AsPayloadHandler(payload: EnvRouteOverridePayload::class, resource: CatalogLandingResource::class)]15final class EnvRouteOverrideHandler implements TypedHandlerInterface16{17    #[InjectAsReadonly]18    protected CatalogRouteInspectorInterface $routeInspector;1920    public function handle(EnvRouteOverridePayload $payload, CatalogLandingResource $resource): CatalogLandingResource21    {22        return $resource23            ->withTitle('Catalog')24            ->withSummary('The payload still owns the route contract, but operations can remap the public URL through one env key.')25            ->withResolvedPath($this->routeInspector->getResolvedPath(EnvRouteOverridePayload::class))26            ->withFallbackPath('/catalog');27    }28}29

<?php

declare(strict_types=1);

namespace App\Application\Handler\Routing;

use App\Application\Payload\Routing\EnvRouteOverridePayload;
use App\Application\Resource\Page\CatalogLandingResource;
use App\Domain\Catalog\CatalogRouteInspectorInterface;
use Semitexa\Core\Attribute\AsPayloadHandler;
use Semitexa\Core\Attribute\InjectAsReadonly;
use Semitexa\Core\Contract\TypedHandlerInterface;

#[AsPayloadHandler(payload: EnvRouteOverridePayload::class, resource: CatalogLandingResource::class)]
final class EnvRouteOverrideHandler implements TypedHandlerInterface
{
    #[InjectAsReadonly]
    protected CatalogRouteInspectorInterface $routeInspector;

    public function handle(EnvRouteOverridePayload $payload, CatalogLandingResource $resource): CatalogLandingResource
    {
        return $resource
            ->withTitle('Catalog')
            ->withSummary('The payload still owns the route contract, but operations can remap the public URL through one env key.')
            ->withResolvedPath($this->routeInspector->getResolvedPath(EnvRouteOverridePayload::class))
            ->withFallbackPath('/catalog');
    }
}

How it works

AsPayload path values support env::VAR::/fallback syntax. During route discovery, Semitexa resolves the env key first and falls back to the inline path when the variable is absent.

Why it matters

Key concepts

env::VAR_NAME::/fallback: Environment-aware attribute syntax that resolves to an env value with a safe inline default.
resolved route metadata: The runtime route definition after env placeholders, inherited attributes, and response metadata have been normalized.
payload-owned route contract: The payload DTO remains the canonical place where path, methods, response type, and alternates are declared.