Skip to content

Installing and enabling the extension

Jump to bottom
Dmitry Dulepov edited this page May 31, 2017 · 28 revisions

Requirements

There are certain constraints and requirements that must be followed to ensure that RealURL works correctly. If any of them are not met, correct behavior cannot be guaranteed.

  1. There must be no "nested domains". This means that there can be only one domain record from the current page down to the root of the page tree. RealURL does not support nested domains!
  2. Each root page of the site must have a "Use as Root page" option checked. This option is located on the Behavior tab of page properties.
  3. If you have multiple root pages with multiple domains, domain records for all domains must be placed to proper root pages. "All" means that you must have really all domains, which you use to access the site (including "www" and non-"www" versions if necessary).

Limitations

TYPO3 has no native support for speaking URLs. RealURL is a hack that makes speaking URLs possible. Therefore RealURL has certain limitations:

  1. Nested domains are not supported. This means you can have only one domain from any page up to the root of the page tree.
  2. You may not use shortcut of type "Random subpage" with RealURL. If you do, RealURL behaviour is undefined.
  3. RealURL does not support workspaces and it will not support them in future. It is too much trouble to support them.
  4. There must be no pages with the same name on one level for the same parent page. In particular this means you cannot have "News" page and "News" sysfolder under the same parent page. Having pages with the same name under one parent page this will not resolve URLs correctly. "Name" here means page title, alias, navigation title or RealURL path segment field. This also applies to pages excluded from the URL. Read more with examples here.
  5. If you use Exclude from speaking URL checkbox, previous rule for same page title applies as well but in that case it works like there is no excluded page.
  6. Backend modules are available only in TYPO3 7.6 or newer. In general, you do not need them at all because all what they do is cache and alias manipulation. You should let RealURL handle that automatically.
  7. You should not use numbers in the Alias field of page properties. Doing so will confuse RealURL. See issue #145.
  8. If you use a shortcuts for the home page, see here for limitations.
  9. Realurl uses URL parameters as is. It does not and will not change values of URL parameters that you pass to it. This means that it is completely your responsibility to configure your installation properly. The most overlooked configuration is config.linksVars (example). Make sure that you only allow a valid range of integers there.

Installing the extension

To install the extension you can either download it from TER (the latest official version) using the TYPO3 Backend, or you can clone it from the GitHub repository. Note that installing through the Extension Manager is the preferred way. GitHub versions are “bleeding edge” and can be unstable.

After the installation RealURL will prompt you to set some options and update the database. It is safe (and recommended!) to leave all options to their default values. The database must be updated for correct work of RealURL.

If you install via composer, it it recommended to use dmitryd/typo3-realurl instead of typo3-ter/realurl.

Updating to newer versions

When the new version comes out, it is strongly recommended to update. New versions usually contain important fixes. If the bug report is not about the latest version, most likely it will be closed with the recommendation to try the latest version. Statistics show that more 90% of problems are solved simply by updating.

Updating usually does not require database changes but it is recommended to check database using the TYPO3 install tool for consistency.

Cache clearing is not required and not recommended while installing a new version unless specifically requested by the new version.

Enabling the extension

By default the extension is disabled and will not encode URLs. It will still decode URLs but the encoding must be enabled with the following TypoScript setup option:

config.tx_realurl_enable = 1
Clone this wiki locally