README

   1 NAME
   2     Catalyst::Plugin::PageCache - Cache the output of entire pages
   3
   4 SYNOPSIS
   5         use Catalyst 'PageCache';
   6
   7         MyApp->config->{page_cache} = {
   8             expires => 300,
   9             set_http_headers => 1,
  10             auto_cache => [
  11                 '/view/.*',
  12                 '/list',
  13             ],
  14             debug => 1,
  15         };
  16
  17         $c->cache_page( '3600' );
  18
  19         $c->clear_cached_page( '/list' );
  20
  21 DESCRIPTION
  22     Many dynamic websites perform heavy processing on most pages, yet this
  23     information may rarely change from request to request. Using the
  24     PageCache plugin, you can cache the full output of different pages so
  25     they are served to your visitors as fast as possible. This method of
  26     caching is very useful for withstanding a Slashdotting, for example.
  27
  28     This plugin requires that you also load a Cache plugin. Please see the
  29     Known Issues when choosing a cache backend.
  30
  31 WARNINGS
  32     PageCache should be placed at the end of your plugin list.
  33
  34     You should only use the page cache on pages which have NO user-specific
  35     or customized content. Also, be careful if caching a page which may
  36     forward to another controller. For example, if you cache a page behind a
  37     login screen, the logged-in version may be cached and served to
  38     unauthenticated users.
  39
  40     Note that pages that result from POST requests will never be cached.
  41
  42 PERFORMANCE
  43     On my Athlon XP 1800+ Linux server, a cached page is served in 0.008
  44     seconds when using the HTTP::Daemon server and any of the Cache plugins.
  45
  46 CONFIGURATION
  47     Configuration is optional. You may define the following configuration
  48     values:
  49
  50         expires => $seconds
  51
  52     This will set the default expiration time for all page caches. If you do
  53     not specify this, expiration defaults to 300 seconds (5 minutes).
  54
  55         set_http_headers => 1
  56
  57     Enabling this value will cause Catalyst to set the correct HTTP headers
  58     to allow browsers and proxy servers to cache your page. This will
  59     further reduce the load on your server. The headers are set in such a
  60     way that the browser/proxy cache will expire at the same time as your
  61     cache. The Last-Modified header will be preserved if you have already
  62     specified it.
  63
  64         auto_cache => [
  65             $uri,
  66         ]
  67
  68     To automatically cache certain pages, or all pages, you can specify
  69     auto-cache URIs as an array reference. Any controller within your
  70     application that matches one of the auto_cache URIs will be cached using
  71     the default expiration time. URIs may be specified as absolute: '/list'
  72     or as a regex: '/view/.*'
  73
  74         debug => 1
  75
  76     This will print additional debugging information to the Catalyst log.
  77     You will need to have -Debug enabled to see these messages.
  78
  79   METHODS
  80     cache_page
  81         Call cache_page in any controller method you wish to be cached.
  82
  83             $c->cache_page( $expire );
  84
  85         The page will be cached for $expire seconds. Every user who visits
  86         the URI(s) referenced by that controller will receive the page
  87         directly from cache. Your controller will not be processed again
  88         until the cache expires. You can set this value to as low as 60
  89         seconds if you have heavy traffic to greatly improve site
  90         performance.
  91
  92     clear_cached_page
  93         To clear the cached value for a URI, you may call clear_cached_page.
  94
  95             $c->clear_cached_page( '/view/userlist' );
  96             $c->clear_cached_page( '/view/.*' );
  97
  98         This method takes an absolute path or regular expression. For
  99         obvious reasons, this must be called from a different controller
 100         than the cached controller. You may for example wish to build an
 101         admin page that lets you clear page caches.
 102
 103     dispatch (extended)
 104         Bypass the dispatch phase and send cached content if available
 105
 106     finalize (extended)
 107         Cache the page output if requested.
 108
 109     setup
 110         Setup default values.
 111
 112     _page_cache_key
 113         Returns a cache key for the current page.
 114
 115 KNOWN ISSUES
 116     It is not currently possible to cache pages served from the Static
 117     plugin. If you're concerned enough about performance to use this plugin,
 118     you should be serving static files directly from your web server anyway.
 119
 120     Cache::FastMmap does not have the ability to specify different
 121     expiration times for cached data. Therefore, if your
 122     MyApp->config->{cache}->{expires} value is set to anything other than 0,
 123     you may experience problems with the clear_cached_page method, because
 124     the cache index may be removed. For best results, you may wish to use
 125     Cache::FileCache or Cache::Memcached as your cache backend.
 126
 127 SEE ALSO
 128     Catalyst, Catalyst::Plugin::Cache::FastMmap,
 129     Catalyst::Plugin::Cache::FileCache, Catalyst::Plugin::Cache::Memcached
 130
 131 AUTHOR
 132     Andy Grundman, "andy@hybridized.org"
 133
 134 COPYRIGHT
 135     This program is free software, you can redistribute it and/or modify it
 136     under the same terms as Perl itself.
 137