Skip to content

Configuration reference

Jump to bottom
Dmitry Dulepov edited this page May 20, 2021 · 43 revisions

This page serves as a reference-only. If you do not know how to configure RealURL, visit a "Manual configuration" page to see how to configure the extension.

Table of contents

cache section

The cache section controls the behavior of RealURL related to the cache.

banUrlsRegExp

type: string
default: /tx_solr|tx_indexed_search|(?:^|\?|&)q=/
This option defines a regular expressions for URLs that should not be cached. Typically those are URLs with unpredictable, free form search strings, like ones from EXT:solr or EXT:indexed_search. The default expression bans URLs from those search engines from polluting the cache.

Note that there is no check for validity of the expression. If the expression is invalid, the cache will behave unpredictably.

Do not ban normal parameters (like page browser numbers, etc). If you do, realurl will not cache URLs with those parameters and it will take much longer to resolve these URLs in Frontend.

ignoredGetParametersRegExp

type: string
default: /^(?:gclid|utm_[a-z]+|pk_campaign|pk_kwd|TSFE_ADMIN_PANEL.*)$/
Lists parameters that will not appear in the RealURL cache. RealURL will remove them before encoding URLs and append back after encoding. To avoid issues with cHash, you also need to exclude them from cHash generation in the TYPO3 configuration using FE|cHashExcludedParameters option.

init section

The init section contains options that define generic behaviour of RealURL.

appendMissingSlash

type: boolean/string
default: ifNotFile,redirect[301]
If set, the a trailing slash will be added internally to the path if it was not set by the user. For instance someone writes "http://the.site.url/contact" with no slash in the end. "contact" will be interpreted as the filename by RealURL – and the user wanted it to be the directory. So this option fixes that problem. Note that usually such redirection is handled by the Apache web server, so just setting this to true does not make much sense.

Keywords are separated by comma. There must be no spaces between keywords. The order of keywords in this directive is not significant. Notice that this directive processed after the processing hook but before any other directive (even before redirects). Therefore all other directives will see URL with the appended slash if this directive is set. For redirects it means that redirect patterns must have slashes in the end (“/path/”, not just “/path”) to be recognized.

The option works for decoding only!

Keyword: "ifNotFile"
You can specify the option as the keyword "ifNotFile". If you use that string as value the slash gets prepended only if the last part of the path doesn't look like a filename (based on the existence of a dot "." character). Note that this option should be followed by a redirect, otherwise it will have only internal effect.

Keyword: "redirect"
This keyword will force RealURL to redirect to the location with appended slash. This will ensure that pages do not appear doubled in the Google index (and therefore page rank does not suffer). Notice that it is not the same as redirect action described in the ->actionConfig later in this manual. The keyword can be optionally followed by the HTTP status code to use for redirect in the square brackets (for example, “redirect[301]”). The following codes are allowed: 301, 302, 303, 307.

calculateChashIfMissing

type: boolean
default: false
since: 2.1.0
see also: cache/disable
This option has no effect currently.

Allows RealURL to calculate cHash if it is potentially required but missing. For example, if URL cache is disabled but decoded URL contains parameters, those parameters may require cHash. If this option is set to false, re-calculation will not happen.

Warning! This option may cause overflow of the page cache (until TYPO3 learns to manage its caches under control). For more details see here and here. Use at your own risk! Generally, you need not this option if you have URL cache enabled and do not clear it manually. It should be primarily used for development only when you want to disable URL cache for some reason.

emptySegmentValue

type: string
default: empty
If the segment is empty when encoding, use this value. This may prevent empty segments from appearing in the URL (path/to////page). Note that generally empty segments is a sign of a bad configuration.

When empty segments appear in the URL, decoding can be complicated and may fail unless the URL is in the cache.

emptyUrlReturnValue

type: string
default: empty
If you set this value to a string, that will be the URL returned if the URL is otherwise empty (usually empty URL means home page).

postVarSet_failureMode

type: string
default: empty
When the postVarSet is not found fo the URL segment, this option defines how to handle it. Possible solutions are defined by one of the keywords listed below.

redirect_goodUpperDir
With this keyword RealURL will stop processing URL segments and will immediately redirect the request to a good processed part of the path.

ignore
With this keyword RealURL will just stop processing URL segments. Potentially this mode is not good for SEO because it can create duplicate content issues.

empty value
Empty value (default) will cause the 404 page with the message that looks like Segment "test" was not a keyword for a postVarSet as expected on page with id=12345. Usually this is the best solution because produces the expected result for the URL that does not exist.

reapplyAbsRefPrefix

type: boolean
default: false
If config.absRefPrefix is set in TypoScript setup, RealURL will strip this prefix before making the final URL. Use this option to reapply the prefix. By default it is not set, so prefix will be lost by default. If you use linking across domains, do not put full domain name in config.absRefPrefix. Use only “/” as prefix.

fileName section

The fileName section defines how RealURL treats the last segment of the URL. It is possible to make the URL look like /path/to/news/item/ or /path/to/news/item.html or have something like rss.xml in the end and to decode it to a certain page type.

acceptHTMLsuffix

type: boolean/string
default: true
If set to boolean, defines whether RealURL will treat URLs ending to / or .html identically. It can also be set to a string to limit the suffix to a certain value. The value must include a dot (example: .html)

defaultToHTMLsuffixOnPrev

type: boolean/string default: false
Identical to acceptHTMLsuffix for decoding (and overrides it) but also used for encoding of URLs. Same format as acceptHTMLsuffix.

fileName/index/keyValues

type: array
default: empty

Allows to encode/decode request variables to a file name. For example:

'fileName' => array (
	'index' => array(
		'print.html' => array(
			'keyValues' => array(
				'type' => 98
			)
		),
		'rss.xml' => array(
			'keyValues' => array(
				'type' => 76
			)
		)
	)
)

This configuration will convert 'type' GET parameter to either print.html or rss.xml depending on the value of the parameter. Decoding will set the value of $_GET accordingly.

pagePath

This section defines parameters that help RealURL to determine correct root page of the site.

Note: version 1.x of RealURL required a userFunc parameter in this section. RealURL 2.x does not use this parameter any more and it has no effect. Also languageGetVar is not used and its value is always assumed to be standard TYPO3 L.

languageExceptionUids

(RealURL ≥ 2.1.0)

This entry contains a comma-separate list of system languages (entries in the sys_language table) that will not be used for page path translation. This is useful for CJK languages. Instead the default language will be used.

rootpage_id

type: integer
default: empty
This option is strongly recommended to be set in all cases. While RealURL is often able to discover root page id correctly from domain records, it is better to set this value manually in the configuration.

preVars

This section defines the configuration of preVars. It is an array of variable definitions.

Note: preVars apply to all pages and cannot be set per page. Typically preVars should be limited to simple variables like L or no_cache.

Example:

'preVars' => array(
	array(
		'GETvar' => 'L',
		'valueMap' => array(
			'de' => 0,
			'fr' => 1,
			'it' => 2,
		),
		'noMatch' => 'bypass',
	),
	array(
		'GETvar' => 'no_cache',
		'valueMap' => array(
			'nc' => 1,
		),
		'noMatch' => 'bypass',
	),
),

Read also: Setting up languages

fixedPostVars

Fixed postVars are defined for specific pages. Usually they are not defined for all pages of the site. 'Fixed' means that they must be set. Typical examples are detail ("single view") pages for extensions like news or addresses, where you always need to show only the detail view and do not want an extra prefix in the URL like for postVarSets.

This section is an array. Keys are either page ids or aliases. Values are either strings or arrays. If it is a string, it is assumed to be an alias that points either to another alias or to an array with variable definitions. There is a limit to 10 nesting of aliases.

Aliases are useful if you want to reuse the configuration for more than one page.

Example:

'fixedPostVars' => array(
	'newsDetail' => array(
		array(
			'GETvar' => 'tx_news_pi1[news]',
			'lookUpTable' => array(
				'table' => 'tx_news_domain_model_news',
				'id_field' => 'uid',
				'alias_field' => 'title',
				'useUniqueCache' => 1,
				'useUniqueCache_conf' => array(
					'strtolower' => 1,
					'spaceCharacter' => '-',
				),
			),
		),
	),
	10 => 'newsDetail',
	384 => 'newsDetail',
),

Note that you could also have 10 set to the variable definition and 384 => 10 as an alias.

You should not use fixedPostVars for all pages!

postVarSets

This section describes postVarsSets – the most frequently used part of RealURL.

postVarsSets define a group of variables with the common prefix. One such group is a postVarSet. For example, you could combine all variables for news detail view like this:

'postVarSets' => array(
	'_DEFAULT' => array(
		'news' => array(
			array(
				'GETvar' => 'tx_news_pi1[controller]',
				'valueMap' => array(
					'news' => 'News',
				)
			),
			array(
				'GETvar' => 'tx_news_pi1[action]',
			),
			array(
				'GETvar' => 'tx_news_pi1[news]',
				'lookUpTable' => array(
					'table' => 'tx_news_domain_model_news',
					'id_field' => 'uid',
					'alias_field' => 'title',
					'useUniqueCache' => 1,
					'useUniqueCache_conf' => array(
						'strtolower' => 1,
						'spaceCharacter' => '-',
					),
				),
			),
		),
	),
),

news is a postVarSet prefix. The URL produced by this configuration will look like /..../news/news/detail/my-news-item-title/. Here the first news segment is a postVarSet prefix, the second comes from the 'GETvar' => 'tx_news_pi1[controller]' and so on.

Notice the _DEFAULT keyword at the second line of the example above. It tells RealURL that postVarSets under it can be used for any page. If you want to limit postVarSets to specific pages, use exact page ids. For example:

'postVarSets' => array(
	'_DEFAULT' => array(
		'news' => array(
			array(
				'GETvar' => 'tx_news_pi1[controller]',
				'valueMap' => array(
					'news' => 'News',
				)
			),
			array(
				'GETvar' => 'tx_news_pi1[action]',
			),
			array(
				'GETvar' => 'tx_news_pi1[news]',
				'lookUpTable' => array(
					'table' => 'tx_news_domain_model_news',
					'id_field' => 'uid',
					'alias_field' => 'title',
					'useUniqueCache' => 1,
					'useUniqueCache_conf' => array(
						'strtolower' => 1,
						'spaceCharacter' => '-',
					),
				),
			),
		),
	),
	35 => array(
		'news' => array(
			array(
				'GETvar' => 'tx_anothernews_plugin[newsId]',
				'lookUpTable' => array(
					'table' => 'tx_anothernews_domain_model_news',
					'id_field' => 'uid',
					'alias_field' => 'title',
					'useUniqueCache' => 1,
					'useUniqueCache_conf' => array(
						'strtolower' => 1,
						'spaceCharacter' => '-',
					),
				),
			),
		),
	)
),

RealURL first checks for the current page id. If it exists, it uses that configuration and _DEFAULT is ignored. If no configuration exist for the current page, _DEFAULT is used. Aliases can be used too. See description of fixedPostVars for more information about aliases.

Request Variable Definition

Request variable definitions are used for preVars, fixedPostVars and postVarSets. Each definition is an array with one mandatory entry that defines the name of the variable and zero or more transformation entries. Each transformation entry is processed according to priority:

If no transformations are set or triggered, the value is used as is. Note that for "as is" there is no any kind of conversion except for the usual rawurlencode. If one transofmration triggered, other transformations are skipped.

GETvar

type: string
This is a mandatory option. It defines the name of a request variable that will be mappend to a URL segment. Example:

array(
	'GETvar' => 'tx_news_pi1[news]'
)

valueMap

valueMap maps segment value to the raw value. For example:

array(
	'GETvar' => 'L',
	'valueMap' => array(
		'de' => 0,
		'fr' => 1,
		'it' => 2,
	),
),

In this example, $_GET['L'] will be transformed to either de, or fr, or it during the decoding depending on the value of $_GET['L']. During the decoding, the segment will be converted back to the request variable.

If you use empty string on either side of the mapping, the behaviour is undefined.

noMatch

If valueMap did not trigger, noMatch will attempt to trigger. noMatch transformation has two possible states:

bypass

On encoding it will simply ignore non-matching parameter. This is useful if you want to have the segment only in for exact values. For example:

array(
	'GETvar' => 'L',
	'valueMap' => array(
		'fr' => 1,
		'it' => 2,
	),
	'noMatch' => 'bypass',
),

This will create URLs with /fr/ and /it/ when $_GET['L'] is 1 or 2 but will not create anything for 0. This is useful for having shorter URLs for the default language, for example.

In decoding it will return the current value for further processing.

null

On encoding this will set the segment to the empty string for the non-matching value. For decoding it will just do nothing with encountered segment (the segment will be ignored). This mode is rarely used.

userFunc

userFunc allows to transform the variable though the custom PHP code.

For decoding the function receives an array with the following parameters:

  • decodeAlias – true
  • isFakeValue – true if there were no actual values left in the URL. The value will be empty string if this is true.
  • pObj – a reference to the calling class
  • value – current variable value
  • pathParts – a reference to the array with segments. The function must remove processed segments for decoding and append them for encoding.
  • setup - a configuration for the current variable.

The returned value must be either numeric or string otherwise it will be ignored.

For encoding the function receives an array with the following parameters:

  • pObj – a reference to the calling class
  • value – the value
  • decodeAlias – false
  • pathParts' – a reference to the array with segments
  • setup – a configuration for the current variable.

The returned value must be either numeric or a string otherwise it will be ignored.

lookUpTable

lookUpTable allows to convert an id value to a readable string. Typically uid value is converted to a record of the title.

The following options can be set:

  • table sets the name of the table to use for transoformation
  • id_field is the name of the field to use. For standard TYPO3 tables this will be the uid field
  • alias_field is a field to use to create a string. You can also use MySQL function here like CONCAT('title', '-', uid)
  • addWhereClause is an additional WHERE clause that must start with ' AND'. For example: ' AND deleted=0 AND hidden=0'.
  • maxLength is the maximum possible length of the alias
  • useUniqueCache should be set to true. If set to false, there can be problems during decoding
  • languageField is an options field that defines what field in th table contains language id of the record. Typically it is sys_language_uid. Same as [ctrl][languageField] in $TCA
  • transOrigPointerField is the same as [ctrl][transOrigPointerField] in $TCA for the table
  • languageExceptionUids defines languages where translation will not be used (you may want to use language title for asian languages, for example). See also (languageExceptionUids for page path)[#languageexceptionuids].
  • useUniqueCache_conf['strtolower'] passed to encodeTitle_userProc. If encodeTitle_userProc is not used, alias will be always lowercase.
  • useUniqueCache_conf['spaceCharacter'] currently only passed to encodeTitle_userProc and has no other effect.
  • useUniqueCache_conf['encodeTitle_userProc'] is currently undocumented.
  • enable404forInvalidAlias will produce a 404 page in case if the alias cannot be resolved

Example:

array(
	'GETvar' => 'tx_news_pi1[news]',
	'lookUpTable' => array(
		'table' => 'tx_news_domain_model_news',
		'id_field' => 'uid',
		'alias_field' => 'title',
		'useUniqueCache' => true,
		'useUniqueCache_conf' => array(
			'strtolower' => true,
			'spaceCharacter' => '-',
		),
	),
),

valueDefault

If none of previous transformations triggered, allows to set a default value. Note that the value is a URL segment value. RealURL will try to look in the valueMap for this value when decoding. If the value is not found, it will set it as is.

_DOMAINS

This configuration entry is described on a separate page.

Clone this wiki locally