TYPO3 Site Routing: Map Clean URLs to Page IDs and Extbase Controllers

If you need a clean URL like /blog/my-first-post to load a specific TYPO3 page and pass the slug to an Extbase controller, configure a site route in config/sites/{site_identifier}/config.yaml. TYPO3 v9+ resolves the incoming path against the site configuration, sets the frontend page ID, and injects matched parameters into the PSR-7 Request for the controller.

How the built-in router resolves a request

Routing is per site, not global. The Site Management module stores a YAML file per site. On a request TYPO3:

• Matches the path against routes defined for the site.
• For a page route, it sets $GLOBALS['TSFE']->id to the configured pageId.
• For an Extbase route, it builds an Extbase request with extensionName, pluginName, controller and action, and merges aspect values from the URL into the request arguments.

Parameters are defined as aspects. An aspect declares the type and validation for a placeholder like {slug}.

Worked configuration for /blog/{slug}

Example site configuration for a blog extension. Run as a site admin with file write access to config/sites/example/.

rootPageId: 1
base: 'https://example.com/'
routes:
  - routePath: '/blog/{slug}'
    _type: Extbase
    extensionName: Blog
    pluginName: Blog
    controller: Post
    action: show
    defaults:
      slug: ''
    aspects:
      slug:
        type: slug
        # optional: regexp: '^[a-z0-9-]+$'
  - routePath: '/blog'
    _type: page
    pageId: 42

routePath is the URL pattern. _type: Extbase tells TYPO3 to dispatch to an extension controller instead of a static page. aspects.slug.type: slug enables the built-in slug matcher. The second route provides a fallback list page.

After editing the file, clear the frontend cache so the routing cache is rebuilt. In the TYPO3 backend use Maintenance > Flush caches, or via CLI as the web user:

vendor/bin/typo3 cache:flush --group frontend

Risk: flushing caches is safe in development but causes a brief performance hit in production. Incorrect extensionName or controller values produce a 404 even when the pattern matches.

Limits and common mistakes

Site routing is powerful but bounded.

Limits

• Routes are evaluated per site. A route cannot change the site base URL after deployment; base is fixed in the site configuration.
• The matcher does not rewrite URLs that contain query strings. Query arguments are passed through but are not part of the route pattern.
• Nested routes and wildcards are supported via additional routePath entries and custom aspects, but each route must resolve to a single page or Extbase target.

Common mistakes

• Forgetting to clear caches. Route changes are cached in the frontend cache. Without a flush the old URL map persists.
• Mis-specifying pageId or controller name. The route appears to match in the inspector but resolves to the wrong page or throws 404. Verify the page exists in the current site tree and the controller class is available.
• Using a placeholder name that collides with Extbase arguments. Keep aspect names consistent with the action method signature.

Verification without assuming success

Check the configuration is parsed.

1. Open Site Management > Sites > {site} > Routes. The route inspector shows the parsed pattern and the resolved target.
2. Request the URL in a test environment. Confirm the correct page is loaded and the controller receives the slug argument via the Request object.
3. Inspect typo3temp/var/logs/debug.log for routing warnings after the request. Look for entries about unmatched routes or aspect errors.

Rollback is a file revert. Restore the previous config.yaml from version control and flush caches again to return to the prior routing map.