Reference: Interfaces

Public interfaces in the `FriendsOfTYPO3Headless` namespace. Inject these rather than the concrete classes — it keeps your code testable and DI-friendly.

Interface	What it gives you
`UtilityHeadlessModeInterface`	Detect / switch headless mode for a request. Methods: `isEnabled()`, `isEnabledFor($request)`, `withRequest($request)`, `overrideBackendRequestBySite($site, $language)`.
`UtilityHeadlessFrontendUrlInterface`	URL rewriting from backend to frontend. Methods: `withSite()`, `withRequest()`, `getFrontendUrl()`, `getFrontendUrlWithSite()`, `getFrontendUrlForPage()`, `getProxyUrl()`, `getStorageProxyUrl()`, `resolveKey()`, `prepareRelativeUrlIfPossible()`. (`withLanguage()` exists only on the concrete `UrlUtility`.)
`UtilityFileUtilityInterface`	File / image rendering. Methods: `setRequest()`, `processFile()`, `process()`, `processImageFile()`, `processCropVariants()`, `getAbsoluteUrl()`, `getErrors()`. `process()` returns the same shape that ships in `content.*.media` by default.
`JsonJsonEncoderInterface`	`encode($data, $options = 0)`. Wraps `json_encode` with HTML-safe flags and the `headless.prettyPrint` feature flag. Does not throw on invalid data: encoding errors are caught, logged as critical, and `"[]"` is returned.
`JsonJsonDecoderInterface`	`decode(array)` recursively unwraps JSON strings nested inside arrays. `isJson($mixed)` detects JSON by fully decoding the value after cheap pre-checks.
`SeoMetaHandlerInterface`	`process($request, $content)` — runs the SEO meta-tag pipeline (page title, meta registry, hreflang) and merges it under `content.seo`.
`DataProcessingRootSiteProcessingSiteProviderInterface`	Strategy for `RootSitesProcessor` to discover sites.
`DataProcessingRootSiteProcessingSiteSchemaInterface`	Strategy for shaping the JSON each site produces.
`DataProcessingRootSiteProcessingSiteSortingInterface`	Strategy for sorting sites in the output.
`FormCustomOptionsInterface`	Dynamic options for a form select/radio/checkbox. See EXT:form.
`FormDecoratorDefinitionDecoratorInterface`	Custom JSON shape for an EXT:form definition.

DI wiring

FileUtilityInterface, HeadlessFrontendUrlInterface, JsonEncoderInterface, JsonDecoderInterface and MetaHandlerInterface are aliased in the extension's Services.php; HeadlessModeInterface via #[AsAlias] on HeadlessMode. Plain constructor injection works for those:

final readonly class MyService
{
    public function __construct(
        private HeadlessModeInterface $headlessMode,
        private HeadlessFrontendUrlInterface $urlUtility,
        private JsonEncoderInterface $jsonEncoder,
    ) {}
}

The remaining interfaces (RootSiteProcessing*, FormCustomOptionsInterface, DefinitionDecoratorInterface) are contracts you implement and hand to the extension via TypoScript or form YAML — they carry no container alias.

UrlUtility and HeadlessMode are shared services; state safety comes from their wither methods (withRequest() / withSite() return clones), not from share: false.