Jun 9, 2008

RealURL made easy: part 2

This a part two of the “RealURL made easy” series. In the first part we reviewed how url is constructed using RealURL and saw what are main configuration directives. This part will show practical steps to create a good RealURL configuration. The next (3rd) part will teach you some neat configuration tricks. But first we have to create the configuration.
From RealURL perspective all installations can be divided into to groups: single-domain tree and multi-domain tree. Single domain tree is the simplest and we already saw how to configure single domains for RealURL using _DEFAULT keyword.
Multi-domain configuration is more complex. Typically sites in a multi-domain setup share the same set of preVars and postVarSets. fixedPostVars (if used at all) are different because fixedPostVars should be specified for the specific page (this is covered in part 1). Therefore we will concentrate on this typical case here.
The steps for setting up multi-domain RealURL configuration are:
  • create a prototype for configuration
  • collect all domain names and root page id values
  • configure main domains
  • efficiently configure aliased domains

Creating configuration prototype

Firsts, we create a common base for all domains. As shown in part 1, we do it in the separate file.
The prototype is created as variable, which contains all properties common for all domains. The variable should have tx_realurl_ prefix to avoid conflicts with any other variables in the system:
$tx_realurl_config = array(
  'init' => array(
    'enableCHashCache' => true,
    'appendMissingSlash' => 'ifNotFile',
    'enableUrlDecodeCache' => true,
    'enableUrlDecodeCache' => true,
    'emptyUrlReturnValue' => '/',
  'preVars' => array(
  'postVarSets' => array(
     '_DEFAULT' => array(
  'pagePath' => array(
    'type' => 'user',
    'userFunc' => 'EXT:realurl/class.tx_realurl_advanced.php:&tx_realurl_advanced->main',
    'spaceCharacter' => '-',
    'languageGetVar' => 'L',
    'expireDays' => 3,

Let's see what we have here. init section enables cHash processing. This is necessary if you use extensions like tt_news, whose output depends on the URL parameters. For more details see “Linking properly in your TYPO3 code” article.

Next there is appendMissingSlash option. This will append slash to the end of generated URL if the last segment does not look like a file. It is not required but makes URL look better for users.

Next two options enable caches. This significally improves RealURL performance.
The last option in init section sets the value of “empty” URL. Usually URL is empty when it refers to home page.

Next two sections are empty in our ptototype but you can add something there as was described in part 1 of these series. We will also see some examples in part 3 of these series.

The last section (pagePath) seldomly change. Sometimes people change the value of spaceCharacter option to underscore character. Notice that value of languageGetVar should not be changed.
expireDays sets expiration value for cache entries if page is moved or renamed. RealURL will continue to accept old path to page for these amount of days and redirect to a new address. This is very useful for users who bookmarked pages. Search engines (like Google) will also notice a change and properly update their index.

Creating configuration for domains

Next we collect domain names and corresponding page id values. If one page shares more than one domain, we will voluntary choose one domain as main and we will treat others as aliased domains.

The following code goes before the closing PHP tag in the file:

$TYPO3_CONF_VARS['EXTCONF']['realurl'] = array(
  'www.domain1.tld' => $tx_realurl_config,
  'domain1.tld' => 'www.domain1.tld',
  'www.domain2.tld' => $tx_realurl_config,
  'domain1.tld' => 'www.domain2.tld',

Notice how main and aliased domains are configured. Main domains have full configuration and aliased just point to main domains. This has two advantages over separate configuration:
  • saves PHP memory
  • ensures that aliased domain always have the same configuration as main domain
You will be surprised but we are almost done! The only thing left is to specify proper root page id values.

Specifying rootpage id values

Specifying root page id values is necessary in multidomain setup. Otherwise RealURL will not be able to trace the path and resolve it to page id. We do it very easily. We add the following code after previous code:

$TYPO3_CONF_VARS['EXTCONF']['realurl']['www.domain1.tld']['pagePath']['rootpage_id'] = 123;
$TYPO3_CONF_VARS['EXTCONF']['realurl']['www.domain2.tld']['pagePath']['rootpage_id'] = 456;

Last final cosmetic step is to unset $tx_realurl_config because it is not longer needed:


That's all. You now have proper multi-domain setup for RealURL.

What you did not know about _DEFAULT

There is one important issue with using _DEFAULT in multi-domain environment.
When RealURL searches for domains, it does walks domains in the configuration sequentally until the first match. _DEFAULT matches always. It means that if any domain is placed after _DEFAULT, it will never be reached. Remember that! But better avoid using _DEFAULT at all in multi-domain configuration.


In this part we saw how easy it is to create a working configuration for RealURL in multi-domain environment. In the next article we will talk more about preVars and postVarSets and see how to make them better.


  1. Thank you for this great tutorial :)

    I\'m glad your Internet connection is back !

    And a big thank to you for sharing your TYPO3 knowledge :)

  2. Thank you for this great article!

    But here is a question:

    Automatic serialized configuration is good or bad? Does it really faster? or it doesen\'t matter? (0.1ms vs 0.01ms for example)

  3. Ph, serialized - yes, it is much faster. Imagine that 1000 visitors visit the page at the same time. 0.1 vs 0.01 matters a lot in this case.

    The difference here is PHP parsing vs data parsing. Data parsing is faster.

  4. So the last paragraph of last part of the tuturial will be \"and now you can serialize configuration for maximum performance\"?

  5. In the first box you used \'enableUrlDecodeCache\' two times. Did you mean \'enableUrlEncodeCache\'?

    Whats going on with the \'enableUrlEncodeHash\'-param. i\'ve found in some example configurations?

  6. Thomas, yes, it should be enableUrlDecodeCache. My mistake, I\'ll fix it next week.

    enableUrlEncodeHash does not exist.

    Ph, yes, that will defintely improve performance.

  7. thanks for the great tutorial! it seems that I start to understand what I do with realurl at last...

    but i have one issue, I\'m not sure if you encountered it before:

    I defined the $tx_realurl_config array variable and try to fill that in the domain specific arrays. but realurl does not fetch this configuration what leads to the URL patch just being the page IDs. looking in the BE info area, speaking url management -> configuration, I get an error saying \"Passed variable is not an array or object\" and the configuration is empty. when dumping $tx_realurl_config i get a working config set though.

    any idea what this might be?

    i use a typo3 4.1.1 and realurl 1.4.0 in a multi-domain enviroment. no _DEFAULT set!

    thanks a lot!

  8. me again... i\'ve been through some testing and it seems that the missing _DEFAULT value leads to this error. may that be an indicator to a broken domain record configuration?

  9. Thank you for this tutorial ;) realUrl is great

    thanks mate

  10. Dmitry, thank\'s for that very good tutorial. I have watched and listen your tutorials at the T3DD08. It was great, thank\'s!



  11. hi Dimitry


    i want just


    is this possible with realurl?

  12. Hi Dmitry

    I like this tutorial very much. When can we expect part 3? So much left to say...


  13. Thankyou so much for this. I was having huge problems with a multi-domain site using the auto config. It seems autoconfig only recognises the first domain record in a page (or at least in some pages), so if www.example.com and example.com are used, only www.example.com will have the correct URLs while example.com will have just page numbers. This is obviously a problem when the pages are cached as the urls from one domain do not exist for the other.



  14. Thank you for sharing your great wisdom! After you have installed the smiley thing, the code looks very happy too ;)

  15. Dmirty,

    the realurl doc mentions decodeSpURL_postProc hook here: http://typo3.org/documentation/document-library/extension-manuals/realurl/1.5.3/view/1/3/#id4164182

    the hook is missing in v 1.5.3

    Is it intentional?

    If so what is idea behind taking that hook out?

    Are there other hooks in the core may be that would let me add logic before realurl kicks in?


  16. realurl version 1.5.3 postVarSets does not convert forward slash to anything else. This causes broken links if one tries to use postVarSets on strings that have forward slash.

    One way to fix this is to add a userFunc that replaces forward slash with underscore for instance.

  17. russian, please

  18. Thanks for the tutorials. They are nice. However, I am getting one problem with realurl and its weird one. It seems sometime realurl is working fine but the other time I am getting "Reason: Segment "XX" was not a keyword for a postVarSet as expected!" error. But surprisingly, this goes away when I clear the cache in the BE. Any suggestion or recommendation on this be appreciated. Thanks in advance.

  19. i followed the configuration in your article but dint work kindly guide please. i am working on a multidomain system.do i have to set a virtual host on localmachine to make it work?

    please guide

  20. if i hide the other domains and work it with single domain using default parameter it works.what is being passed in the default parameter.please reply as soon as possible

  21. I got the "Reason: Segment "xy" was not a keyword for a postVarSet as expected!"

    Is it possible, that I have to create a configuration line for every page I have?

  22. Thanks Dmitry!!!! Perfect tutorials! :)

  23. together with hmenu special=language it works like a charm. Thanks a lot!

  24. Hi

    I seem to have a similar problem as jeetendra.

    I am using the auto conf with a two domain setup. whenever the second domain is called without additional parameters, it shows the first domain. when I call a sub page (like www.domain.com/page/) it works fine. Does anybody have a solution for that?

  25. Shouldn't one of the be Encode?

    'enableUrlDecodeCache' => true,
    'enableUrlDecodeCache' => true,

  26. This comment has been removed by the author.

  27. The following code can be used as a standard routine for single-/multi-domain configuration:

    # array($domain => $rootpage_id)
    $tx_realurl_domains = array(
    '_DEFAULT' => 1, // any domain
    # 'www.domain1-4site1.tld' => 1,
    # 'www.domain2-4site1.tld' => 1,
    # 'www.domain1-4site2.tld' => 100,
    # 'www.domain2-4site2.tld' => 100,

    foreach ($tx_realurl_domains as $val_domain => $key_rootpage_id) {
    $TYPO3_CONF_VARS['EXTCONF']['realurl'][$val_domain] = $tx_realurl_config; // defined above
    $TYPO3_CONF_VARS['EXTCONF']['realurl'][$val_domain]['pagePath']['rootpage_id'] = $key_rootpage_id;