---
title: "Routing for Extbase plugins"
manual: "TYPO3 Explained"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3coreapi:extbase-arguments@main"
source: "ExtensionArchitecture/Extbase/Routing/Index.rst"
rendered: "2026-09-24T12:36:55+00:00"
---

# Routing for Extbase plugins {#extbase-arguments}

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

```none
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:

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

TYPO3's routing system is built on top of Symfony routing components. The
Extbase plugin enhancer is a specialized 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](https://docs.typo3.org/permalink/t3coreapi:extbase-routing-enhancer-chash@main) 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.

> [!NOTE]
> **See also**
>
> -   [Routing — readable, SEO-friendly URLs](https://docs.typo3.org/permalink/t3coreapi:routing@main) —
>     overview of TYPO3 routing, terminology (slug, enhancer, aspect), and page-based routing.
> -   [Route Enhancements and Aspects](https://docs.typo3.org/permalink/t3coreapi:routing-advanced-routing-configuration@main) —
>     the full reference for all enhancer types and aspects available in TYPO3 Core.

## How TYPO3 routing works with Extbase {#extbase-routing-how-it-works}

TYPO3 resolves a request in two stages:

1.  **Page routing** — maps the URL path to a page (using page slugs defined in the site tree).
1.  **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](https://docs.typo3.org/permalink/t3coreapi:site-sets@main) is the
recommended way to provide it — but it only takes effect once the site activates that
set. The [section below](https://docs.typo3.org/permalink/t3coreapi:extbase-routing-where-configured@main) covers placement.

## Plugin argument namespaces {#extbase-routing-namespace}

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

```none
tx_myextension_conferences
```

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

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

The [Extbase plugin enhancer](https://docs.typo3.org/permalink/t3coreapi:extbase-routing-enhancer@main) 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 {#extbase-routing-where-configured}

Place routing configuration in a [site set](https://docs.typo3.org/permalink/t3coreapi:site-sets@main) file inside your
extension:

```none
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**

```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**

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

> [!NOTE]
> **See also**
>
> -   [Site sets](https://docs.typo3.org/permalink/t3coreapi:site-sets@main) —
>     site sets and what they can ship.
> -   [Using imports in YAML files](https://docs.typo3.org/permalink/t3coreapi:routing-tips@main) —
>     how to split routing configuration across files without site sets.

## Prerequisites {#extbase-routing-prerequisites}

Before routing can work:

-   The plugin must be [registered and placed on a page](https://docs.typo3.org/permalink/t3coreapi:extbase-registration-frontend-plugin@main).
-   A [slug](https://docs.typo3.org/m/typo3/reference-tca/main/en-us/ColumnsConfig/Type/Slug/Index.html#columns-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.