typo3bloke.net

People often complain that RealURL is hard to configure. In my opinion it happens because RealURL manual is written as a reference guide, not like a tutorial. Therefore there is nothing for beginner to start from. Recent RealURL versions include automatic configuration, which is good for simple web sites. However it is not flexible enough. Manual configuration would always win over automatic one. This article provides a simple guide for manual RealURL configuration. It is not short, so reserve some time for reading it.

The whole guide is divided to several parts. The first part describes configuration in general. Other parts will describe details, tips&tricks and best practices.

Basics

This section covers general principles of RealURL functionality.

RealURLed URL

Before we start with configuration, it must be clear what parts RealURLed URLs can contain.

Typical RealURLed URL consists from several segments:

Segments are (in the order of appearance):

• preVars
  These are prepended to page path. Typically it is language identifiers. They should not be long.
• Page path
  This is a path to the page. It is created by traversing a page tree from the root of web site to the target page. There are several fields that can be used to create segments. Typically it is page title, alias, subtitle and special RealURL field named “Path segment”
• fixedPostVars
  These are non-prefixed parameters to the page. They are very similar to preVars but go after page path. Typically they are set for specific pages only, not for the whole site.
• postVars
  These are prefixed parameters to the page. For example, tx_ttnews[tt_news]=5 can be converted to /news/test-news-item/. Here “news” identifies tx_ttnews[tt_news] and 5 is replaced by encoded news item title.

Each segment (except page path) can have several variables.

Configuration basics

Normally RealURL configuration is stored in the separate file. This file is usually included into typo3conf/localconf.php.

RealURL configuration is a nested PHP array. Configuration is created per a web site. Logically it looks like:

$TYPO3_CONF_VARS['EXTCONF']['realurl'] = array(
    'www.domain1.com' => array(
        ...
    ),
    'domain1.com' => 'www.domain1.com',
    'www.domain2.com' => array(
        ...
    ),
    'domain2.com' => 'www.domain1.com',
);

There are two types of entries here. Domain name can either point to another domain name or to a configuration array.

If domain name points to another domain name, RealURL will take configuration of the pointed domain. There can be several pointers in the chain.

If domain name points to an array, it is configuration. We will look to it in a moment.
If there is only one domain, there is no need to specify it name. The whole configuration then may look like:

$TYPO3_CONF_VARS['EXTCONF']['realurl'] = array(
    '_DEFAULT' => array(
        ...
    ),
);

This case is valid also if domain.com is an alias for www.domain.com.

The configuration array for each domain (or for _DEFAULT) consists from subarrays, called configuration sections.

Configuration sections

There are six configuration sections. None of them is mandatory but at least two are usually used. Here is a “bird view” to the sections:

• init
  This section describes general RealURL options, such as caches, empty URL return value and some other options.
• preVars
  This section defines preVars (see URL example above!). As simple as that.
• fixedPostVars
  This section defines fixedPostVars.
• postVarSets
  This section defines postVarsSets. This is the most trickier configuration part.
• pagePath
  This section is usually copy/paste section. It does not change much between various servers. However it has one parameter (rootpage_id), which has ultimate importance in multidomain configuration.
• fileName
  This section allows to end URLs with something like “rss.xml” or “print.html”. Mostly it is also copy/paste section.

Creating init section

init section normally contains cache configuration directives and some other useful options. Here is a short list that you should have in your configuration:

• 'enableCHashCache' => true
  Use this if web site uses any extension with URL parameters. Details about cHash can be found here and here.
• 'appendMissingSlash' => 'ifNotFile'
  This appends slash to the end of URL. Just looks nicer.
• 'enableUrlDecodeCache' => true
  Enables to use fast database-based cache when user visits a page. This is a huge performance improvement comparing to when cache is disabled.
• 'enableUrlEncodeCache' => false
  Same as above but for encoding. This is used when creating links. There is no reason why you may want to disable this or above cache. None at all.

This list is not complete. You can find some other directives in RealURL manual.

Making preVars section

The section consists from one or more parts. Each part is an array itself and it defines a single preVar. Example:

array(
    'GETvar' => 'L',
    'valueMap' => array(
        'en' => 0,
        'de' => 1,
    ),
    'noMatch' => 'bypass'
),

In this example, preVar is associated with “L” URL parameter. valueMap says that L=0 is mapped to /en/, L=1 is mapped to /de/. noMatch says that any other L value will be silently ignored.

It is possible to specify also default value or do other conversions. For details reader is encouraged to read RealURL manual.

Creating fixedPostVars section

fixedPostVars are very similar to preVars. There are only two differences:

• fixedPostVars are placed after page path in URL.
• fixedPostVars must have either a page id or _DEFAULT keyword (for all pages)

Take a look to example:

35 => array(
    array(
        'GETvar' => 'tx_myext_pi1[no_comments]',
        'valueMap' => array(
            'no-comments'  => 1
        ),
        'noMatch' => 'bypass',
    )
),

Here there is one more wrapping array around real fixedPostVar definition. This wrapping array tells that page with id 35 has this fixedPostVar. So “no-comments” fixedPostVar will not apply to other pages (unless added also there). There is also 'noMatch' to skip this variable completely when it does not make sense to have it.
If there should be more than one fixedPostVar on this page, it will follow the first one like this:

35 => array(
    array(
        ...
    ),
    array(
        ...
    )
)

fixedPostVars will appear in the defined order. It is important to think about the order and keep it once it is defined or decoding will not happen properly.

Making postVars sets

postVarsSets look similar to fixedPostVars but they have prefixes that identifies a postVar. It allows to put postVars in any order in the URL. It also allows to have a very flexible set of postVars.

One postVar in the URL can actually define several real GET parameters. For example:

'_DEFAULT' => array(
    'myparam' => array(    // postVar start
        array(
            'GETvar' => 'tx_mext_pi1[p1]',
        ),
        array(
            'GETvar' => 'tx_mext_pi1[p2]',
        ),
    ),    // postVar end, Other postVar definitions may follow
),

Now, suppose non-encoded URL looks like:

http://domain.com/index.php?id=25&tx_myext_pi1[p1]=12&tx_myext_pi1[p2]=34

Encoded URL will look like:

http://domain.com/page/path/myparam/12/34/

It is even possible to convert numbers to strings if they refer to database tables. Also PHP code can be provided to map real GET parameters to encoded parameters and back. The system is extremely flexible and allows you do almost anything!

pagePath section

pagePath section is typically used to enhance RealURL even further. By default RealURL creates URLs like this:

http://domain.com/35/myparam/12/34/

To replace page id (35 in the example about) with a real path to page, the following content should be placed to pagePath section:

'type' => 'user',
'userFunc' => 'EXT:realurl/class.tx_realurl_advanced.php:&tx_realurl_advanced->main',

There are other directives. The most important of them is rootpage_id. This directive points to the page, which is the root (home page) of the current web site. It must be set for multidomain configurations and it is recommended to set it even in single domain configuration (or RealURL will have to find it). Forgetting this directive in multidomain configuration always results in incorrect RealURL behaviour!

fileName section

It is safe to skip this section in your configuration. Generally it is not needed unless you have to create nice looking ending file names in URL.

Conclusion

In this article we reviewed RealURL configuration. Next article will show how to make this configuration effective. It will show some tips and tricks that are not obvious from the manual and that you should know. So, watch this site for the next article!