State of TYPO3 URL handling

Categories: Development, TYPO3 CMS Created by Benni Mack
URL handling is by far the biggest topic on our road to TYPO3 v9, and the most wanted functionality to be integrated in the TYPO3 Core. We'd like to keep you updated on what happened so far and what we're working on next.

Past Achievements

The biggest obstacle in our mind was the limitation of multi-language pages. All page translations were previously stored in the database on "pages_language_overlay". This has been migrated into the main "pages" database table with TYPO3 v9.0. For multi-language installations, this is the biggest change in a long time, especially for custom extensions querying the database directly. A change which was long overdue in TYPO3 development in order to streamline page translations the same way as other record translations are handled.

In order to overcome some previously tightly coupled functionality regarding domain handling and its redirecting capabilities, a new redirects functionality was integrated into TYPO3 v9.1 - this allowed the core development to replace the existing domain handling which continues to be working. Domain handling however was previously not built to handle SEO friendly URLs, but only to define which entrypoints to a multi-site TYPO3 installations were given.

All previous solutions about URL handling in TYPO3 had the following downsides:

  • Previous solutions are built by changing the generated URL from index.php?id=123 to /products/my-vacuum-cleaner/ or similar. Thus, the canonical path of a page now had to be resolved in frontend and backend and CLI environments the same way every time - something that was not possible with the information provided by TYPO3 Core. To solve this, URLs should be built “speaking” by default - no additional resolving necessary - but still allow to call everything via index.php?id=123 to stay backwards-compatible.
  • Language / Translation handling is currently done with a GET variable (most commonly known as the "L" parameter) and resolved in TypoScript. This is very error-prone and not integrator-friendly. Additionally, TypoScript cannot be parsed completely with all variations beforehand to find out certain information about translation handling, as it can depend on TypoScript conditions like [hour > 18] - allowing to actually switch the page language from english to french after 6pm.
  • Due to the internal knowledge of TYPO3 using index.php?id=123 under the hood, it was never possible to create a predictable URL - thus, also not specifying a truly canonical base URL. This is especially an issue when TYPO3 Backend runs with a separate domain, or a URL should be created via CLI (e.g. in email templates) where there was no guessing of the current domain name.

Some may claim this is actually supercool, as TYPO3 allows so many possibilities, however, we believe that URL handling must be unified and simpler to configure, but with possibilities to extend this base functionality.

Introducing Site Handling

This lead us to work on the configuration of sites, actually defining a configuration for all entry points of a TYPO3 installation, which is available in all contexts - Frontend, Backend and CLI. We built a new backend module to configure a site / entrypoint. This data is stored in a site configuration file, automatically written into a new folder structure, called typo3conf/sites/ with a unique identifier. We currently chose to persist this as Yaml file, as it allows having it human-readable. The folder can be committed to a versioning system, allowing for various deployment strategies. As a paradigm in the past years, configuration should be stored in files first, and not in the database by default - although this could be overloaded at a later stage, if necessary. We've implemented file storage as best practices for TypoScript and Backend Layouts already, and consider the "sites" concept a start to move site-specific configuration into a place where it can be writable, but also deployable (like typo3conf/ext/).

The configuration module allows to configure the entrypoint for a site, and the definition of all languages relevant for a site - removing the need to do any further TypoScript configuration when it comes to language configuration. The same configuration is used for the resolving of backend-related language handling as well.

The current functionality is currently under review for inclusion in TYPO3 Core.

We know this might limit edge-cases people are using, so feedback on the URL handling is very welcome, especially when it comes to nested domains, or special handling of mountpoints across multiple domains. Please use our slack channel #routing-initiative or our issue tracker on forge for feedback.

Further enhancement

The configuration of “Sites” will ship with TYPO3 9.2, and work as a test-bed. For now, site handling is built in TYPO3 Core as beta and acts as "opt-in". Websites without a sites configuration continue to work as before.

For the full speaking URL functionality on a per-page level, which we think will become reality in TYPO3 9.3, this feature-set will be expanded to configure any special path handling on a per-site level.

Handling of extensions and additional variants will follow until TYPO3 9 LTS - it will still be possible to keep an installation with TYPO3 v9 LTS running without using native URL handling, to ease the migration process. With TYPO3 10.0, site handling becomes mandatory, allowing to remove any special fallback logic in TypoScript, TSconfig etc. We will still provide ways to keep using RealURL or CoolURI for upgradeability.

Keep an eye on our further sprint releases to discover the latest progress in this area.

We hope that you all get your champagne bottles ready for the LTS release in October to truly celebrate one of the most wanted features in TYPO3 Core.