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.

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/page-2 — list, page 2
  • /conferences/typo3camp-2025 — detail view
EXT:my_extension/Configuration/Sets/Main/route-enhancers.yaml
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
Copied!

Key points:

  • The pagination route /page-{page} uses a static prefix page- to distinguish it from the detail route /{conference_slug} . 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 2025.
  • The first page has its own route / and no defaults entry for page . A link without currentPage generates /conferences/ — see Separate routes instead of defaults.
  • fallbackValue: null on the PersistedAliasMapper means a deleted or hidden conference returns null to 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 — limitToPages must point to the correct page for each, and links between them need setTargetPageUid() or pageUid in Fluid.

EXT:my_extension/Configuration/Sets/Main/route-enhancers.yaml
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
Copied!

In the list template, link to the detail page explicitly:

EXT:my_extension/Resources/Private/Templates/Conference/List.fluid.html
<f:link.action
  action="show"
  controller="Conference"
  arguments="{conference: conference}"
  pageUid="{settings.detailPageUid}"
>
  {conference.title}
</f:link.action>
Copied!

Store the detail page UID in TypoScript settings so it is configurable without touching PHP:

EXT:my_extension/Configuration/Sets/Main/setup.typoscript
plugin.tx_myextension_conferences.settings.detailPageUid = 42
Copied!

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/typo3camp-2025 — conference detail
  • /conferences/typo3camp-2025/talks — talk list for that conference
  • /conferences/typo3camp-2025/talks/extbase-routing-demystified — talk detail
EXT:my_extension/Configuration/Sets/Main/route-enhancers.yaml
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
Copied!

The {conference_slug} placeholder appears in both the Conference::show 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 /{year} , a link with a year and a month fits /{year}/{month} .

The link has to pass the month in the format of the map , such as 03. For the value 3 the StaticValueMapper finds no entry, and TYPO3 appends the month as a query parameter instead.

URLs produced:

  • /conferences/2025/march — conferences in March 2025
  • /conferences/2025/march/page-2 — paginated
  • /conferences/2025 — all conferences in 2025
EXT:my_extension/Configuration/Sets/Main/route-enhancers.yaml
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: '/'
Copied!

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 NewsTitle , NewsCategory , and NewsTag mappers — all thin wrappers around PersistedAliasMapper that add extension-specific defaults and fallback handling.

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 limitToPages .
setTargetPageUid() missing
Links from a list plugin point back to the list page instead of the detail page. Always set setTargetPageUid() in PHP or pageUid in Fluid when list and detail are on separate pages.
Wrong route order
A placeholder route without an aspect ( /{slug} ) is listed before a more specific route ( /page-{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.
limitToPages missing
Without limitToPages , TYPO3 evaluates the enhancer for every page on the site. Performance degrades and unintended matches on unrelated pages become possible.
URL ends in /page instead of the list URL
The enhancer sets defaults for the page placeholder of a route like /page-{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 defaults entry and keep the route / for the first page — see Separate routes instead of defaults.
cHash still appearing
A placeholder has a requirements regex but neither an aspect nor a static declaration. A regex requirement alone does not suppress cHash. Add an aspect, or declare the placeholder in 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.yaml or config/sites/<site-identifier>/config.yaml, clear all caches via Admin Tools > Maintenance.

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.