All page names need to be in English.
en da  de  fr  it  ja  km  nl  ru  zh


From TYPO3Wiki
Jump to: navigation, search

<- Back to blueprints overview

Blueprint: Speaking URLs

Proposal Integrate management of nice, speaking URLs into the TYPO3 core
Owner/Starter Andreas Wolf
Participants/Members Benni Mack, …
Status Draft, Discussion, Voting Phase, Accepted, Declined, Withdrawn
Current Progress Unknown, Started, Good Progress, Bad Progress, Stalled, Review Needed
Topic for Gerrit ###gerrit_topic###

Target Versions/Milestones

  • started during TYPO3 CMS 9.0 development
  • first implementation targeted at CMS 9 LTS, further improvements for the next LTS versions

Goals / Motivation

make working with URLs easier for editors, administrators and developers than it currently is:

  • editors
    • should instantly see which URL(s) a page or record has
    • should be able to modify them without harming their search engine rankings
  • administrators
    • should be able to more easily setup speaking URLs and configure any URL structure
  • developers
    • should be able to customize routing for records to specific needs and deliver predefined URL generators with their extensions, if necessary

to achieve that:

  1. integrate a new URL routing/generation mechanism that relies on precalculated URLs instead of auto-generation on the fly
  2. generate URLs not only for pages, but also for records (or rather views of records)
  3. make it possible to define one plugin that renders the main content of that page (e.g. news single view) and gets control of the URLs (required to generate URLs for records)
  4. add a new API for plugins that allows for returning not only rendered content, but also status information (required to e.g. properly implement canonical URLs and finally get rid of cHash)


  • pre-calculate and store URLs for pages and records, do not create URLs on the fly
    • auto-generation should be configurable (i.e. URL patterns, …)
  • allow central management of URLs for a page/record from the backend, clearly and easily visible for an editor
  • when creating a new URL for a page/record, existing URLs must continue to live
    • these URLs can be "phased out", e.g. deleted after 90 days or if there was no hit for 30+ days
    • behaviour should be configurable
  • there should be automatic checks for URL collisions that either bail out to a warning to the editor, or automatically solve the conflict by changing the URL
  • "dynamic" parameters like pagination, filters etc. will not be supported in the first phase
    • these add much complexity, e.g. for automatic collision checks, while bringing little benefit for most scenarios
  • the current site configuration (domains, TS templates, languages) is scattered around the system => this should be unified
    • this will also ease configuring the site and gives us opportunities to e.g. switch to locales instead of simple languages (together with the ongoing improvements in the language handling)
    • in the frontend processing, there should be clear steps to resolve the site root, language, … from the incoming request (as e.g. the language can come from the domain, domain + path prefix, or only from the full URL in case of a site with mixed languages on one domain)

Implementation Details

URL generation/management

  • do not forcibly create a speaking URL if it does not exist
    • auto-generation should be possible, but probably not implemented in the URL management logic (but as a separate, plugable component)
  • pre-calculating URLs…
    • for pages, this is relatively simple, even with mountpoints in the game (just create one+ URL(s) per mount point, with "no mount point" as the default case)
    • for records, this requires an information on which page(s)/with which plugin the record is to be shown => plugins should ḿake this available for the core in a dedicated method/class (basically similar to a repository)
    • additional parameters from other plugins cannot be part of the speaking URL (as these would make creating and storing the URLs hard or impossible, e.g. for an endless pagination the number of URLs would explode) -> this could be added later on for some use-cases
  • allow management of URLs at a place where it seems natural, e.g. within the page module for pages, as a separate FormEngine tab for records
    • with a new page/record, a URL should be suggested which can then be adjusted by the editor as required
  • to allow URL handling for records, the plugin for these records should be directly attached to the page (and not as a single content element)
    • alternatively, the "main plugin" of the page could be defined in the page properties, similar to the "contains plugin" field
    • this allows to clearly define which plugin takes control of URLs on this page, and reduces doubt when generating URLs or routing requests
    • technically, this could be a new page type "Plugin", which can have all the usual fields (or even inline a content element w/ the respective settings)

Managing record URLs

  • records need to get a URL for each of their dedicated "views", e.g. a single view within a plugin
    • if a record is shown in two plugins, it has to have two URLs
    • choosing a canonical URL should be handled in the central URL management for that record
  • each plugin needs to
    • have routes that define which URLs exist
    • be able to tell the core if it can show a record or not (because of its settings like storage page etc.)
      • if yes, URLs need to be generated => the plugin must tell the core which routes are relevant for that record


  • for pages, we handle routing (= resolving an incoming URI to a uid/language/mountpoint/…) internally in the core
  • for records, routes can be specified by the extension author
    • route = array of parameters, using placeholders like {record.uid} or {} to be filled with corresponding data upon resolution
    • routing can be the most basic first implementation that just acts as a parameter mapper similar to RealURL (but w/o the need to have every parameter represented in the URL)
    • these routes only specify which parameters need to be made available to the plugin, not what the URL looks like
      • URL stores plugin ID, record ID, route ID and can easily use that for routing
      • open question: how to handle URL generation with that approach?

Plugin API

  • the current interface core/plugin is too narrow/shallow: the core invokes a PHP function, which returns rendered content. All other things (404 handling etc.) are implemented as side effects on global objects, mainly TSFE
  • solution: implement proper subrequests/-responses that are dispatched to the object by the USER TS object
    • request contains resolved parameters (namespace has to be known to the outside)
    • response contains rendered content (or only view + variables), response code
      • based on response code, core can decide what to do:
        • if main plugin, the response code can be used directly
        • for minor plugins integrated e.g. via TS, errors can be ignored, content left out or replaced by a default/cached version etc.
  • implementation approach: new interface does not use userFunc, but a different parameter name (= no reflection necessary to get method parameters)
    • or implement a marker interface on the new classes (no reflection necessary in that case either)


  • to actually implement proper URL handling, the core needs to know which parameters are relevant in a URLs
    • implement an interface to register a parameter as used => all unused parameters are deemed irrelevant for the current page’s content
    • this will also eliminate the nede for using cHash
    • biggest problem: all plugins need to be compatible
      • easiest solution: integrate a new interface for plugins that can handle the new approach of "consuming" parameters


  • b/w compatibility for RealURL might break
    • as we will most likely not support every scenario RealURL supports in the first run, this must not happen, so people can continue using RealURL for the time being, if they want or need to
  • too much complexity for an editor
    • this is most likely only a matter of having a proper UI for creating URLs and some tools that give a good overview of the "URL landscape"
  • introducing plugins on a page is quite a big change conceptually
    • OTOH this could be a spark for integrating more possibilities for easier management of records (e.g. by having a customized management module for this extension’s records)

Issues and reviews

Dependencies upon other Blueprints

External links for clarification of technologies