-
Notifications
You must be signed in to change notification settings - Fork 126
Notes for Developers
If you do not know what cHash is, read this first. This is a long reading and code is obsolete there but you will not find a better explanation anywhere. Each extension developer must know what a cHash is!
TYPO3 plugins can be either cached or uncached. For cached, when you supply GET parameters to the plugin, you need to make sure that there is a cHash in the URL. For non-cached, you do not supply cHash. This is important distinction because:
- If you do not supply cHash for cached plugin, your output will be a first cached version of the plugin output regardless of the plugin parameters
- If you supply cHash for non-cached plugin, you will pollute TYPO3 cache with many identical entries and make the site slower. You may also make RealURL slower because under certain conditions it re-creates cHash.
Unfortunately Extbase developers decided to make cHash on by default. Thus most Extbase-based plugins incorrectly use cHash even for non-cached plugins. If you are an extension developer, check how you use action viewhelper for forms. It is likely that you did not disable cHash there and your non-cached plugin gets a cHash. That's your error, which you should fix. Same for any other links for your plugin. You should always check whether you need cHash or not and disable cHash generation if not.
Another thing you must do as a developer, is to tell TYPO3 about parameters that should not be taken into account when calculating cHash. RealURL uses this information when it has to recalculate cHash. For example, if your plugin is always non-cached, you may produce a URL like /index.php?id=123&tx_myrandomnews[topic]=456, which translates to /fun/random-news/jokes (assuming 456 maps to jokes). Now if somebody clears general caches in TYPO3, URL cache will be cleared. Suppose somebody comes to /fun/random-news/jokes. RealURL checks the cache, finds nothing and starts re-creating the original URL. It successfully makes /index.php?id=123&tx_myrandomnews[topic]=456 and sees the parameter in the URL. Since the URL was re-build and there is a parameter, the question is: should there be a cHash or not? If the developer did not tell TYPO3 that cHash os not needed, RealURL will create a cHash.
Now, how do you tell TYPO3 that cHash is not needed for certain parameters? It is easy in the ext_localconf.php of your extension:
// TYPO3 6.x
$GLOBALS['TYPO3_CONF_VARS']['FE']['cHashExcludedParameters'] .= ',tx_myrandomnews[topic]';
// TYPO3 7.x
$GLOBALS['TYPO3_CONF_VARS']['FE']['cacheHash']['excludedParameters'][] = 'tx_myrandomnews[topic]';
Mind the comma!
That's it for correct handling of cHash in your extensions.
Some extension need to implement banning of their URLs from RealURL cache. These are extensions, whose URLs meet one or more of the following criteria:
- Their parameters contain random strings. Typical examples are search extensions (indexed search, solr). Note that RealURL knows about indexed search and solr already.
- Extension with never ending URLs. A typical example is a calendar-like extension with a week view. Its URLs can look like
/index.php?id=123&tx_mycal[week]=52&tx_mycal[year]=2016. When Google indexes the site, it may go very far and this will create a lot of URLs that are practically usesless in the RealURL cache but will slow down lookup of useful URLs.
Note that you do not have to be paranoid here. RealURL cache is a good thing and you should never ever switch it off or ban URls from it unless for reasons given above.
How do you ban a URL from the cache?
In your RealURL configuration you add an an entry like this:
$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['realurl'] = array (
'_DEFAULT' => array(
'cache' => array(
banUrlsRegExp' => '/tx_solr|tx_indexedsearch|(?:^|\?|&)q=|tx_mycal\[/',
),
...
);
Default value for banUrlsRegExp is /tx_solr|tx_indexedsearch|(?:^|\?|&)q=/ and you should keep it there.
Make sure that your regular expression is correct (validate them). If it is not, you will have warnings for each page request and no URLs will be banned.
Caching framework is a great TYPO3 feature but it does not fully meet requirements for the RealURL cache. RealURL uses the following types of caches:
- URL cache. Unlike version 1.x, version 2.x uses a single cache for encoding and decoding. When encoding, it needs to fetch a cache entry using original URL as a key. When decoding, it needs to fetch a cache entry using speaking URL.
- Path cache. When encoding, RealURL needs to fetch the entry using language and page id with no (zero) expiration time. When decoding, it needs to fetch a cache entry using root page id and segments of the path with longest expiration time.
- Alias cache uses multiple conditions when decoding and encoding.
From the cache requirements it is clear that using a single cache key it is not possible to meet those requirements. Theoretically it is possible by using tags but that would make extra overhead: currently there is a single optimized query for each cache operation while with caching framework it will take several database operations. When using non-database caches, certain systems (like memcached) do not guarantee that tags and data will both present. Thus cache can be corrupted.
You can implement an interface named \DmitryDulepov\Realurl\Cache\CacheInterface in your own class and configure cache in the RealURL configuration. Note that you will loose Backend modules. You'll have to make your own cache management in the Backend.
I know that changing interfaces is bad. I will try hard not to change them unless it is not possible to fix a bug without changing the interface. If inetrfaces change, I will announce it.
RealURL is now developed at GitHub because GitHub is faster and allows better collaboration. Forge project is no longer active.
Forge issues were for RealURL 1.x. That version is no longer maintained or supported. Use version 2.x and submit issues to GitHub project.