Routing for Extbase plugins

Every Extbase plugin action produces URLs with a namespaced query string when no routing configuration exists:

https://example.org/conferences?tx_myextension_conferences[action]=show&tx_myextension_conferences[controller]=Conference&tx_myextension_conferences[conference]=42&cHash=…

Routing configuration transforms these into readable, SEO-friendly URLs:

https://example.org/conferences/typo3camp-2025

TYPO3's routing system is built on top of Symfony routing components. The Extbase plugin enhancer is a specialised layer on top — it handles the controller/action namespace automatically. Moving plugin arguments out of the query string and into the path also simplifies cHash handling considerably — a fully routed URL needs no cHash at all. Understanding the general TYPO3 routing concepts first makes Extbase routing much easier to follow.

How TYPO3 routing works with Extbase

TYPO3 resolves a request in two stages:

Page routing — maps the URL path to a page (using page slugs defined in the site tree).
Route enhancement — a configured route enhancer parses the remainder of the URL and populates plugin arguments. A site can define many enhancers (one per plugin, each under its own key in routeEnhancers); TYPO3 tries each until one matches.

Only after both stages does Extbase dispatch the request to a controller action. Route enhancers are resolved as part of the site configuration. The configuration itself can still ship inside your extension — a site set is the recommended way to provide it — but it only takes effect once the site activates that set. The section below covers placement.

Plugin argument namespaces

Every Extbase plugin has an auto-generated namespace derived from its extension and plugin keys. For an extension my_extension and plugin Conferences:

tx_myextension_conferences

All plugin arguments appear under this namespace in the raw URL:

?tx_myextension_conferences[action]=show&tx_myextension_conferences[controller]=Conference&tx_myextension_conferences[conference]=42

The Extbase plugin enhancer uses exactly this namespace to match and generate URLs. You never need to write the namespace by hand — configure extension and plugin keys and the enhancer derives it.

Where routing is configured

Place routing configuration in a site set file inside your extension:

EXT:my_extension/Configuration/Sets/MyExtension/route-enhancers.yaml

The filename is fixed: a site set is scanned for a file named exactly route-enhancers.yaml at the set root, and TYPO3 picks it up automatically when the set is active — no additional declaration is needed. The file must use routeEnhancers as its single root key (TYPO3 raises an error on any other top-level key):

EXT:my_extension/Configuration/Sets/MyExtension/route-enhancers.yaml

routeEnhancers:
  MyExtensionPlugin:
    # … enhancer configuration

If the project does not use site sets, routing configuration lives directly in the site's config/sites/<site-identifier>/config.yaml, or is pulled in via a YAML import:

config/sites/my-site/config.yaml

imports:
  - { resource: "EXT:my_extension/Configuration/Routes/Default.yaml" }

Prerequisites

Before routing can work:

The plugin must be registered and placed on a page.
A slug must be set for the page (visible in the page properties).
The site must have a site configuration (config/sites/).

A detail page URL like /conferences/typo3camp-2025 requires both a /conferences page slug and a plugin instance placed on that page. If either is missing, TYPO3 cannot resolve the route.