Skip to content

Installing and enabling the extension

Jump to bottom
Dmitry Dulepov edited this page Sep 17, 2018 · 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. Also there cannot be subpages with "Use as a root page" flag set inside a page with "Use as a root page" set. RealURL does not support nested domains! If you have nested domains, your URLs will look weird and there is no fix or workaround for that.
  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 and only one page with "Use as root page" flag set in page properties.
  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 is 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.

Update to RealURL 2.3.0 or newer from lower 2.x versions

RealURL 2.3.0 changes tx_realurl_urldata table structure. It is strongly recommended that you update that table manually just before upgrading to RealURL 2.3.0 from earlier versions ("just before" means "a moment before" here). Otherwise your site may be locked up or show wrong results until RealURL finishes update online. Here is what you need to execute in mysql console:

ALTER TABLE tx_realurl_urldata DISABLE KEYS;
ALTER TABLE tx_realurl_urldata ADD COLUMN original_url_hash int(11) unsigned DEFAULT '0' NOT NULL;
ALTER TABLE tx_realurl_urldata ADD COLUMN speaking_url_hash int(11) unsigned DEFAULT '0' NOT NULL;
UPDATE tx_realurl_urldata SET original_url_hash=CRC32(original_url), speaking_url_hash=CRC32(speaking_url);
ALTER TABLE tx_realurl_urldata DROP KEY pathq1;
ALTER TABLE tx_realurl_urldata DROP KEY pathq2;
ALTER TABLE tx_realurl_urldata ADD KEY pathq1 (rootpage_id,original_url_hash,expire);
ALTER TABLE tx_realurl_urldata ADD KEY pathq2 (rootpage_id,speaking_url_hash,expire);
ALTER TABLE tx_realurl_urldata ENABLE KEYS;

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

To make sure that URLs work correctly, you also need the following option in TypoScript:

config.absRefPrefix = /

If you link across various domains, you also need this:

config.typolinkEnableLinksAcrossDomains = 1
Clone this wiki locally