Development

Changeset 7788

You must first sign up to be able to contribute.

Changeset 7788

Show
Ignore:
Timestamp:
03/09/08 18:04:20 (9 months ago)
Author:
francois
Message:

[doc 1.1] Updated Caching chapter to document r7787 changes

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • doc/branches/1.1/book/12-Caching.txt

    r7705 r7788  
    327327    } 
    328328 
    329 Removing cached partials, components, and component slots is a little trickier. As you can pass them any type of parameter (including objects), it is almost impossible to identify their cached version after the fact. Let's focus on partials, as the explanation is the same for the other template components. Symfony identifies a cached partial with a special prefix (`sf_cache_partial`), the name of the module, and the name of the partial, plus a hash of all the parameters used to call it, as follows: 
     329Removing cached partials, components, and component slots is a little trickier. As you can pass them any type of parameter (including objects), it is almost impossible to identify their cached version afterwards. Let's focus on partials, as the explanation is the same for the other template components. Symfony identifies a cached partial with a special prefix (`sf_cache_partial`), the name of the module, and the name of the partial, plus a hash of all the parameters used to call it, as follows: 
    330330 
    331331    [php] 
    …… 
    334334 
    335335    // Is identified in the cache as 
    336     /sf_cache_partial/user/_my_partial/sf_cache_key/bf41dd9c84d59f3574a5da244626dcc8 
     336    @sf_cache_partial?module=user&action=_my_partial&sf_cache_key=bf41dd9c84d59f3574a5da244626dcc8 
    337337 
    338338In theory, you could remove a cached partial with the `remove()` method if you knew the value of the parameters hash used to identify it, but this is very impracticable. Fortunately, if you add a `sf_cache_key` parameter to the `include_partial()` helper call, you can identify the partial in the cache with something that you know. As you can see in Listing 12-10, clearing a single cached partial --for instance, to clean up the cache from the partial based on a modified `User`-- becomes easy. 
    …… 
    347347 
    348348    // Is identified in the cache as 
    349     /sf_cache_partial/user/_my_partial/sf_cache_key/12 
    350  
    351     // Clear _my_partial for a specific user in the cache with $cacheManager->remove('@sf_cache_partial?module=user&action=_my_partial&sf_cache_key='.$user->getId()); 
    352  
    353 You cannot use this method to clear all occurrences of a partial in the cache. You will learn how to clear these in the "Clearing the Cache Manually" section later in this chapter. 
     349    @sf_cache_partial?module=user&action=_my_partial&sf_cache_key=12 
     350 
     351    // Clear _my_partial for a specific user in the cache with 
     352    $cacheManager->remove('@sf_cache_partial?module=user&action=_my_partial&sf_cache_key='.$user->getId()); 
    354353 
    355354To clear template fragments, use the same `remove()` method. The key identifying the fragment in the cache is composed of the same `sf_cache_partial` prefix, the module name, the action name, and the `sf_cache_key` (the unique name of the cache fragment included by the `cache()` helper). Listing 12-11 shows an example. 
    …… 
    365364 
    366365    // Is identified in the cache as 
    367     /sf_cache_partial/user/list/sf_cache_key/users 
     366    @sf_cache_partial?module=user&action=list&sf_cache_key=users 
    368367 
    369368    // Clear it with 
    …… 
    393392>And, if you don't want to damage your brain with too difficult an analysis, you can always clear the whole cache each time you update the database . . . 
    394393 
    395 ### Template Cache Key 
    396  
    397 Whatever caching storage strategy you use, symfony will use common naming rules for identifying template cache parts. Put it simply, symfony uses the external URL form of the internal URI as a key to a template cache part. For instance, the template cache key of a page called with: 
    398  
    399     http://www.myapp.com/user/show/id/12 
    400  
    401 is: 
    402  
    403     www_myapp_com/all/user/show/id/12 
    404  
    405 The first part of the cache key is the host name, where dots are replaced by underscores for compatibility with file systems. Then comes the list of VARY headers (usually a single `all/` keyword), and then the page external URL. 
    406  
    407 What the cache engine does with htis key depends no the caching strategy defined in the `factories.yml`. Let's see what happens with the default cache factory: `sFileCache`. When using the filesystem to store cache parts, symfony writes all template cache files under a special subdirectory of the `cache/` directory called `sf_template_cache_dir`: 
    408  
    409     cache/                 # sf_root_cache_dir 
    410       [APP_NAME]/          # sf_base_cache_dir 
    411         [ENV_NAME]/        # sf_cache_dir 
    412           template/        # sf_template_cache_dir 
    413  
    414 For instance, the template cache of the `user/show/id/12` page is stored in: 
    415  
    416     cache/frontend/prod/template/www_myapp_com/all/user/show/id/12.cache 
    417     \----filecache config----/\---unique template cache key---/ 
    418  
    419 ### Clearing template cache from a cache key (new in symfony 1.1) 
    420  
    421 If you know the cache key of a template cache part, symfony offers an alternative to using the `remove` method of the view cache manager, called `removePattern`: 
    422  
    423     [php] 
    424     $cacheManager->remove('user/show?id=12');                           // Uses internal URI 
    425     // Is equivalent to 
    426     $cacheManager->removePattern('www_myapp_com/all/user/show/id/12');  // Uses cache key 
    427  
    428 The great advantage of `removePattern` is that it accepts keys with wildcards. You can do for instance: 
    429  
    430     [php] 
    431     $cacheManager->removePattern('*/all/user/show/id/12');  // Remove for all hosts 
    432     $cacheManager->removePattern('*/all/user/show/*/*');    // Remove for all user records 
    433  
    434 Another good example if with applications handling several languages, where the language code appears in all URLs. The link to a user profile page should look like this: 
     394### Clearing several cache parts at once (new in symfony 1.1) 
     395 
     396The `remove()` method accepts keys with wildcards. It allows you to remove several cache parts with a single call. You can do for instance: 
     397 
     398    [php] 
     399    $cacheManager->remove('user/show?id=*');    // Remove for all user records 
     400 
     401Another good example is with applications handling several languages, where the language code appears in all URLs. The URL to a user profile page should look like this: 
    435402 
    436403    http://www.myapp.com/en/user/show/id/12 
    …… 
    439406 
    440407    [php] 
    441     $cache->removePattern('*/all/*/user/show/id/12'); 
    442  
    443 The `removePattern()` method is available for all the caching strategies that you can define in the `factories.yml` (not only `sfFileCache`, but also `sfAPCCache`, `sfEAcceleratorCache`, `sfMemcacheCache`, `sfSQLiteCache`, and `sfXCacheCache`). 
     408    $cache->removePattern('user/show?sf_culture=*&id=12'); 
     409 
     410This also works for partials: 
     411 
     412    [php] 
     413    $cacheManager->remove('@sf_cache_partial?module=user&action=_my_partial&sf_cache_key=*');    // Remove for all keys 
     414 
     415The `remove()` method accepts two additional parameters, allowing you to define which hosts and vary headers you want to clear the cache for. This is because symfony keeps one cache version for each host and vary headers, so that two applications sharing the same code base but not the same hostname use different caches. This can be of great use, for instance, when an application interprets the subdomain as a request parameter (like `http://php.askeet.com` and `http://life.askeet.com`). If you don't set the last two parameters, symfony will remove the cache for the current host and for the `all` vary header. Alternatively, if you want to remove the cache for another host, call `remove()` as follows: 
     416 
     417    [php] 
     418    $cacheManager->remove('user/show?id=*');                     // Remove for all user records for the current host 
     419    $cacheManager->remove('user/show?id=*', 'life.askeet.com');  // Remove for all user records for the host life.askeet.com 
     420    $cacheManager->remove('user/show?id=*', '*');                // Remove for all user records for every hosts 
     421 
     422The `remove()` method works in all the caching strategies that you can define in the `factories.yml` (not only `sfFileCache`, but also `sfAPCCache`, `sfEAcceleratorCache`, `sfMemcacheCache`, `sfSQLiteCache`, and `sfXCacheCache`). 
    444423 
    445424### Clearing cache across applications (new in symfony 1.1) 
    …… 
    449428    [php] 
    450429    $cacheManager = sfContext::getInstance()->getViewCacheManager(); // Retrieves the view cache manager of the backend 
    451     $cacheManager->removePattern('*/all/user/show/id/12');   // The pattern is not found, since the template is cached in the frontend 
     430    $cacheManager->removePattern('user/show?id=12');                 // The pattern is not found, since the template is cached in the frontend 
    452431 
    453432The solution is to initialize a `sfCache` object by hand, with the same settings as the frontend cache manager. Fortunately, all cache classes in symfony provide the save `removePattern` method as the view cache manager. 
    …… 
    458437    $frontend_cache_dir = sfConfig::get('sf_root_cache_dir') . DIRECTORY_SEPARATOR . 'frontend' . DIRECTORY_SEPARATOR . SF_ENV . DIRECTORY_SEPARATOR . 'template'; 
    459438    $cache = new sfFileCache(array('cache_dir' => $frontend_cache_dir)); // Use the same settings as the ones defined in the frontend factories.yml 
    460     $cache->removePattern('*/all/user/show/id/12'); 
     439    $cache->removePattern('user/show?id=12'); 
    461440 
    462441For different caching strategies, you just need to change the cache object initialization, but the cache removal process remains the same: 
    …… 
    464443    [php] 
    465444    $cache = new sfMemcacheCache(array('prefix' => 'frontend')); 
    466     $cache->removePattern('*/all/user/show/id/12'); 
     445    $cache->removePattern('user/show?id=12'); 
    467446 
    468447Testing and Monitoring Caching