Routing examples and common mistakes
The following examples build on the concepts explained in the preceding pages. Each is a complete, working configuration you can adapt directly.
On this page
List, pagination, and detail
The most common Extbase plugin pattern: a list page with pagination and a detail view. The list and detail actions are on the same page here; for separate pages see List and detail on separate pages.
URLs produced:
/conferences/— list, first page/conferences/— list, page 2page- 2 /conferences/— detail viewtypo3camp- 2025
routeEnhancers:
ConferencesPlugin:
type: Extbase
limitToPages:
- 'page["module"] == "conferences"'
extension: MyExtension
plugin: Conferences
defaultController: 'Conference::list'
routes:
- routePath: '/'
_controller: 'Conference::list'
- routePath: '/page-{page}'
_controller: 'Conference::list'
_arguments:
page: currentPage
- routePath: '/{conference_slug}'
_controller: 'Conference::show'
_arguments:
conference_slug: conference
aspects:
page:
type: StaticRangeMapper
start: '1'
end: '100'
conference_slug:
type: PersistedAliasMapper
tableName: tx_myextension_domain_model_conference
routeFieldName: slug
routeValuePrefix: '/'
fallbackValue: null
Key points:
- The pagination route
/page-uses a static prefix{page} page-to distinguish it from the detail route/. TYPO3 rejects a URL without this prefix by a string comparison, before any aspect is asked. The prefix also keeps the routes apart for a conference whose slug is a number, such as{conference_ slug} 2025. - The first page has its own route
/and nodefaultsentry forpage. A link withoutcurrentgeneratesPage /conferences/— see Separate routes instead of defaults. fallbackon theValue: null Persistedmeans a deleted or hidden conference returnsAlias Mapper nullto the action rather than a 404. The action must declare the argument nullable and handle it explicitly — see Handling deleted or hidden records.- Route order matters: pagination before detail, most specific before most general — see Route order and specificity.
List and detail on separate pages
When the list plugin and the detail plugin live on different pages, each page
needs its own enhancer entry —
limit must point to the correct
page for each, and links between them need
set or
page in Fluid.
routeEnhancers:
ConferencesList:
type: Extbase
limitToPages:
- 'page["module"] == "conferences_list"'
extension: MyExtension
plugin: Conferences
defaultController: 'Conference::list'
routes:
- routePath: '/'
_controller: 'Conference::list'
- routePath: '/page-{page}'
_controller: 'Conference::list'
_arguments:
page: currentPage
aspects:
page:
type: StaticRangeMapper
start: '1'
end: '100'
ConferencesDetail:
type: Extbase
limitToPages:
- 42
extension: MyExtension
plugin: Conferences
defaultController: 'Conference::show'
routes:
- routePath: '/{conference_slug}'
_controller: 'Conference::show'
_arguments:
conference_slug: conference
aspects:
conference_slug:
type: PersistedAliasMapper
tableName: tx_myextension_domain_model_conference
routeFieldName: slug
routeValuePrefix: '/'
fallbackValue: null
In the list template, link to the detail page explicitly:
<f:link.action
action="show"
controller="Conference"
arguments="{conference: conference}"
pageUid="{settings.detailPageUid}"
>
{conference.title}
</f:link.action>
Store the detail page UID in TypoScript settings so it is configurable without touching PHP:
plugin.tx_myextension_conferences.settings.detailPageUid = 42
Multiple controllers in one plugin
A single plugin can expose actions from more than one controller — all under the same namespace, all in one enhancer. The key is that every controller/action combination that needs a clean URL gets its own route entry.
URLs produced:
/conferences/— conference list/conferences/— conference detailtypo3camp- 2025 /conferences/— talk list for that conferencetypo3camp- 2025/ talks /conferences/— talk detailtypo3camp- 2025/ talks/ extbase- routing- demystified
routeEnhancers:
ConferencesPlugin:
type: Extbase
limitToPages:
- 'page["module"] == "conferences"'
extension: MyExtension
plugin: Conferences
defaultController: 'Conference::list'
routes:
- routePath: '/'
_controller: 'Conference::list'
- routePath: '/page-{page}'
_controller: 'Conference::list'
_arguments:
page: currentPage
- routePath: '/{conference_slug}'
_controller: 'Conference::show'
_arguments:
conference_slug: conference
- routePath: '/{conference_slug}/talks'
_controller: 'Talk::list'
_arguments:
conference_slug: conference
- routePath: '/{conference_slug}/talks/{talk_slug}'
_controller: 'Talk::show'
_arguments:
conference_slug: conference
talk_slug: talk
aspects:
page:
type: StaticRangeMapper
start: '1'
end: '100'
conference_slug:
type: PersistedAliasMapper
tableName: tx_myextension_domain_model_conference
routeFieldName: slug
routeValuePrefix: '/'
fallbackValue: null
talk_slug:
type: PersistedAliasMapper
tableName: tx_myextension_domain_model_talk
routeFieldName: slug
routeValuePrefix: '/'
fallbackValue: null
The
{conference_ placeholder appears in both the
Conference:: route and the
Talk
routes. Each is a separate
route entry with its own
_controller
— the enhancer matches on the full
path and controller/action combination, not on the placeholder name alone.
Date-based conference archive
Filter the conference list by year and month using human-readable URL segments.
Each combination of arguments has its own route entry, so the configuration
needs no
defaults
: a link with a year only fits
/, a link
with a year and a month fits
/.
The link has to pass the month in the format of the
map
, such as 03.
For the value 3 the
Static finds no entry, and TYPO3
appends the month as a query parameter instead.
URLs produced:
/conferences/— conferences in March 20252025/ march /conferences/— paginated2025/ march/ page- 2 /conferences/— all conferences in 20252025
routeEnhancers:
ConferencesPlugin:
type: Extbase
limitToPages:
- 'page["module"] == "conferences"'
extension: MyExtension
plugin: Conferences
defaultController: 'Conference::list'
routes:
- routePath: '/'
_controller: 'Conference::list'
- routePath: '/page-{page}'
_controller: 'Conference::list'
_arguments:
page: currentPage
- routePath: '/{year}/{month}/page-{page}'
_controller: 'Conference::list'
_arguments:
year: overwriteDemand/year
month: overwriteDemand/month
page: currentPage
- routePath: '/{year}/{month}'
_controller: 'Conference::list'
_arguments:
year: overwriteDemand/year
month: overwriteDemand/month
- routePath: '/{year}'
_controller: 'Conference::list'
_arguments:
year: overwriteDemand/year
- routePath: '/article/{conference_slug}'
_controller: 'Conference::show'
_arguments:
conference_slug: conference
requirements:
page: '\d+'
year: '\d{4}'
aspects:
page:
type: StaticRangeMapper
start: '1'
end: '25'
month:
type: StaticValueMapper
map:
january: '01'
february: '02'
march: '03'
april: '04'
may: '05'
june: '06'
july: '07'
august: '08'
september: '09'
october: '10'
november: '11'
december: '12'
year:
type: StaticRangeMapper
start: '2000'
end: '2030'
conference_slug:
type: PersistedAliasMapper
tableName: tx_myextension_domain_model_conference
routeFieldName: slug
routeValuePrefix: '/'
Warning
TYPO3 limits the number of values a route can produce, to guard against brute-force requests and cache flooding:
- A single
Staticaccepts at most 1000 values. TYPO3 throws aRange Mapper \Lengthfor a larger range betweenException startandend. - TYPO3 multiplies the number of values of all
StaticandRange Mapper Staticaspects used in one route. If the product is larger than 10000, generating or resolving a URL of this route throws anValue Mapper \Overflow.Exception
The route
/ above combines 31 years,
12 months, and 25 pages, which makes 9300 combinations. With 50 pages it
would be 18600, and every URL of this route would fail. For a wider span,
narrow another range, or write a custom mapper that does not implement
\Countable
.
Beyond built-in aspects
The four built-in aspect types —
PersistedAliasMapper,
PersistedPatternMapper,
StaticValueMapper, and
StaticRangeMapper — cover the
majority of real-world cases. When they do not, TYPO3 allows extensions to
register fully custom aspect classes. A good example is
georgringer/news
, which ships its own
News,
News, and
News mappers — all thin wrappers around
Persisted
that add extension-specific defaults and fallback handling.
See also
Route Enhancements and Aspects — the Core routing reference covers custom aspect registration.
Common mistakes
- Plugin not placed on the target page
- The enhancer is configured, the URL looks right, but TYPO3 returns a 404.
Check that the plugin content element is actually present on the page
referenced in
limit.To Pages - setTargetPageUid() missing
- Links from a list plugin point back to the list page instead of the detail
page. Always set
setin PHP orTarget Page Uid () pagein Fluid when list and detail are on separate pages.Uid - Wrong route order
- A placeholder route without an aspect (
/) is listed before a more specific route ({slug} /page-). The placeholder accepts every value, so the specific route is never reached. Add an aspect, and list the routes with a static segment first — see Route order and specificity.{page} - limitToPages missing
- Without
limit, TYPO3 evaluates the enhancer for every page on the site. Performance degrades and unintended matches on unrelated pages become possible.To Pages - URL ends in /page instead of the list URL
- The enhancer sets
defaultsfor the page placeholder of a route like/page-. TYPO3 leaves out the default value, but not the static text, and uses this route even for a link without a page argument. Remove the{page} defaultsentry and keep the route/for the first page — see Separate routes instead of defaults. - cHash still appearing
- A placeholder has a
requirementsregex but neither an aspect nor astaticdeclaration. A regex requirement alone does not suppressc. Add an aspect, or declare the placeholder inHash static— see The cHash parameter. - Stale cache after config changes
- Site configuration is cached. After any change to
EXT:my_extension/Configuration/Sets/Main/route-enhancers.yamlorconfig/, clear all caches via Admin Tools > Maintenance.sites/<site- identifier>/ config. yaml
When a route does not behave as expected
A route enhancer that does not fit a URL or a link rarely raises an error. TYPO3 tries the next route and, in the end, uses the plain page URL. The symptom is a page where a 404 error was expected, or a URL that still contains query parameters.
Tip
The troubleshooting page of the routing chapter is organised by symptom and applies to Extbase plugins as well: