Skip to content

Site Configuration as a base for Routing in TYPO3 v9 and newer

Since version 9.5, TYPO3 supports 'speaking URLs' natively. And all you need is a Site Configuration.

This tutorial will explain the basic setup of a Site Configuration. After that we can deal with an important part of Routing Enhancers: the Extbase Plugin Enhancer. If you're already familiar with Site Configurations, you can skip this tutorial.

For those who want to learn how to get a trailing slash or .html at the end of the URL, the answer is in the third part of the Routing series.

Introduction

'Speaking URLs' are optimized, human-readable addresses of a website. In the past, you had to use third-party extensions like RealURL or CoolURI to get rewritten URLs in TYPO3. But the new version 9.5 LTS is able to manage these out-of-the-box.

Table of contents

Some facts about the new Routing:

  • It is based on the Symfony Routing Component.
  • The routing of pages is enabled as soon as you configured a Site Configuration ("example.org/home" instead of "example.org/index.php?id=1").
  • With a Site Configuration, all pages will receive a new field in the page properties: the URL Segment (which is generally comparable with the former realurl_pathsegment).
  • Translations of pages are handled, too.
  • You'll need so-called Routing Enhancers to rewrite Extbase plugins (like News) or other URL parameters.
  • Routing Enhancers are added manually to the Site Configuration (config.yaml).

As the handling of translated pages has changed fundamentally in TYPO3 v9, RealURL will not support this or future versions of TYPO3! So it's about time to deal with the new Routing in TYPO3.

Benefits and scope of the Site Configuration:

  • Convenient management of multiple websites within a TYPO3 installation (all pages with setting is_siteroot).
  • Setting up languages and fallbacks per website. Very useful: You can add language abbreviations to the existing domain ('my-domain.com/fr/') or even assign a different domain to a language ('mon-domain.fr').
  • Handling of HTTP error codes (e.g. 'Display content from Page' or a custom Fluid template).
  • Also useful: the so-called Static Routes allow, for example, to provide a different robots.txt for each site.
  • All configuration of a website is stored in a single YAML file.
  • Domain Records become superfluous.

Setting up a new Site Configuration

Open the TYPO3 backend module 'Site Management > Sites'. All root pages get listed here. Click the button 'Add new site configuration for this site' to do just that.

The mandatory details of a new Site Configuration are as followed:

  1. The Site Identifier (this will be the name of a new subdirectory in typo3conf/sites/, so please note the recommendations given there).
  2. The Entry Point: it's best to use a full URL with protocoll and domain. If you just use a slash there may be issues with the Error Handling! For local development environments you can create variants.
  3. Setting up the language: even if your website only uses a single frontend language, this has to be configured! This information is used by TYPO3 to e.g. render the HTML tag (<html lang="en">).

I restrict myself to the necessary configuration for the Routing. You can find further information about the possibilities here: https://docs.typo3.org/typo3cms/CoreApiReference/ApiOverview/SiteHandling/Index.html

After you saved your Site Configuration you can find it in /typo3conf/sites/your_identifier/config.yaml

The created config.yaml will look something like this:

rootPageId: 7
base: 'https://mydomain.de/'
baseVariants:
  -
    base: 'http://mydomain.test/'
    condition: 'applicationContext == "Development"'
languages:
  -
    title: English
    enabled: true
    languageId: '0'
    base: /
    typo3Language: default
    locale: en_US.UTF-8
    iso-639-1: en
    navigationTitle: English
    hreflang: en-US
    direction: ''
    flag: en-us-gb
errorHandling: {  }
routes: {  }

Wait a minute! 'applicationContext'?

For local development I specified an alternative Entry Point (baseVariants). This will be used if TYPO3 is running in the given applicationContext, which can be set e.g. in a .htaccess file. The default .htaccess of TYPO3 already has some rules prepared which you can adapt and activate:

  RewriteCond %{HTTP_HOST} ^mydomain\.test$
  RewriteRule .? - [E=TYPO3_CONTEXT:Development]

The current Application Context status can be checked in the TYPO3 Backend by opening the Application Information (topbar):

TYPO3: Application Context 'Development' in the Backend

Besides, you can use baseVariants in the config.yaml for your website's languages, too. An example can be found in the associated changelog entry.

About the URL Segment

If a Site Configuration is present, TYPO3 will automatically create URL Segments for the associated page tree.

For this, the page title will be copied and converted to lowercase letters. Spaces are replaced by hyphens, special characters are omitted.

Optimized, human-readable URL paths are also called slugs, especially in the field of Search Engine Optimization (SEO).

If two or more pages on the same level in the page tree share the same name, TYPO3 will add suffixes to the URL Segments in order to keep all URL paths unique (e.g. /pagetitle-1).

All URL Segments can be customized in the page properties:

  • You can either use a button to automatically recalculate the path by the current page title(s)
  • or entirely by hand

This way, you could have a subpage in the page tree under 'Bookselling > Non-Book > Poster', but set the speaking URL to 'domain.de/poster'. Or something entirely different.

And of course there are dedicated fields for URL Segments of translated pages.

TYPO3 page properties: editing the URL Segment

FAQ about the new TYPO3 Routing

There are some differences between TYPO3 v9 and v10, which are described in the individual sections.

How do I get a slash (or .html) at the end of each URL?

I have answered this question in a separate tutorial.

Does the URL segment change when I rename a page?

No. Although the URL segment is initially generated from the page title, TYPO3 will then handle both data independently from each other. You can change the URL segment at any time in the page properties, by manual input or by using the "Recalculate" button at the input field.

This procedure has not changed with TYPO3 v10.

How can I update the URL Segment of all subpages (at once) after renaming a parent page?

Slug notification in the TYPO3 backend
In TYPO3 v10, the slugs of all subpages are automatically updated and redirects are added. You can use the buttons to revert both changes or just the redirects.

In TYPO3 v10, this is done automatically: if you change the URL segment of a page, the slugs of all subpages are updated as well. Besides, redirects for the current page and all subpages are automatically created in the Redirects backend module. As an editor, you will be informed about this in a system message and can revert one or both adjustments, if necessary.

TYPO3 v9 does not offer this functionality. You will have to update the slug for every single page. Unfortunately, it's also not possible to change the URL segments together in the Single Table View (at least the 'recalculate' button doesn't work). It seems that TYPO3 lacks the necessary context there.

But there are two extensions which could help you managing your slugs in TYPO3 v9:

Can I exclude a page completely from the URL Segment of its subpages?

Only manually, one by one. Currently it's not supported to exclude a normal page from slug generation. A possible workaround: page types with a doktype value of 200 or higher are always ignored in URL Segments. These are folders, menu separators (spacer) and recycler. Keep in mind though that these page types cannot be called in the frontend!