1Catalyst::Plugin::PageCUascehre(C3o)ntributed Perl DocumCeanttaaltyisotn::Plugin::PageCache(3)
2
6 Catalyst::Plugin::PageCache - Cache the output of entire pages
7
9 use Catalyst;
10 MyApp->setup( qw/Cache::FileCache PageCache/ );
11 __PACKAGE__->config(
13 'Plugin::PageCache' => {
14 expires => 300,
15 set_http_headers => 1,
16 auto_cache => [
17 '/view/.*',
18 '/list',
19 ],
20 debug => 1,
21 # Optionally, a cache hook method to be called prior to dispatch to
23 # determine if the page should be cached. This is called both
24 # before dispatch, and before finalize.
25 cache_hook => 'some_method',
26 # You may alternatively set different methods to be used as hooks
28 # for dispatch and finalize. The dispatch method will determine
29 # whether the currently cached page will be displayed to the user,
30 # and the finalize hook will determine whether to save the newly
31 # created page.
32 cache_dispatch_hook => 'some_method_for_dispatch',
33 cache_finalize_hook => 'some_method_for_finalize',
34 }
35 );
36 sub some_method {
38 my $c = shift;
39 if ( $c->user_exists and $c->user->some_field ) {
40 return 0; # Don't cache
41 }
42 return 1; # Cache
43 }
44 # in a controller method
46 $c->cache_page( '3600' );
47 $c->clear_cached_page( '/list' );
49 # Expire at a specific time
51 $c->cache_page( $datetime_object );
52 # Fine control
55 $c->cache_page(
56 last_modified => $last_modified,
57 cache_seconds => 24 * 60 * 60, # once a day
58 expires => 300, # allow client caching
59 );
60
62 Many dynamic websites perform heavy processing on most pages, yet this
63 information may rarely change from request to request. Using the
64 PageCache plugin, you can cache the full output of different pages so
65 they are served to your visitors as fast as possible. This method of
66 caching is very useful for withstanding a Slashdotting, for example.
67 This plugin requires that you also load a Cache plugin. Please see the
69 Known Issues when choosing a cache backend.
70
72 PageCache should be placed at the end of your plugin list.
73 You should only use the page cache on pages which have NO user-specific
75 or customized content. Also, be careful if caching a page which may
76 forward to another controller. For example, if you cache a page behind
77 a login screen, the logged-in version may be cached and served to
78 unauthenticated users.
79 Note that pages that result from POST requests will never be cached.
81
83 On my Athlon XP 1800+ Linux server, a cached page is served in 0.008
84 seconds when using the HTTP::Daemon server and any of the Cache
85 plugins.
86
88 Configuration is optional. You may define the following configuration
89 values:
90 expires => $seconds
92 This will set the default expiration time for all page caches. If you
94 do not specify this, expiration defaults to 300 seconds (5 minutes).
95 cache_headers => 1
97 Enable this value if you need your cached responses to include custom
99 HTTP headers set by your application. This may be necessary if you
100 operate behind an edge cache such as Akamai. This option is disabled
101 by default.
102 set_http_headers => 1
104 Enabling this value will cause Catalyst to set the correct HTTP headers
106 to allow browsers and proxy servers to cache your page. This will
107 further reduce the load on your server. The headers are set in such a
108 way that the browser/proxy cache will expire at the same time as your
109 cache. The Last-Modified header will be preserved if you have already
110 specified it. This option is disabled by default.
111 auto_cache => [
113 $uri,
114 ]
115 To automatically cache certain pages, or all pages, you can specify
117 auto-cache URIs as an array reference. Any controller within your
118 application that matches one of the auto_cache URIs will be cached
119 using the default expiration time. URIs may be specified as absolute:
120 '/list' or as a regex: '/view/.*'
121 disable_index => 1
123 To support the "clear_cached_page" method, PageCache attempts keep an
125 index of all cached pages. This adds overhead by performing extra cache
126 reads and writes to maintain the (possibly very large) page index. It's
127 also not reliable, see "KNOWN ISSUES".
128 If you don't intend to use "clear_cached_page", you should enable this
130 config option to avoid the overhead of creating and updating the cache
131 index. This option is currently disabled (i.e. the page index is
132 enabled) by default but that may change in a future release.
133 index_page_key => '...'
135 The key string used for the index, Defaults to a string that includes
137 the name of the Catalyst app class.
138 busy_lock => 10
140 On a high traffic site where page re-generation may take many seconds,
142 a common problem encountered is the "dog-pile" effect, where many
143 concurrent connections all hit a page where the cache has expired and
144 all perform the same expensive operation to rebuild the cache. To
145 prevent this situation, you can set the busy_lock option to the maximum
146 number of seconds any of your pages can be expected to take to rebuild
147 the cache. Then, when the cache expires, the first request will
148 rebuild the cache while also extending the expiration time by the
149 number of seconds specified, allowing other requests that arrive before
150 the cache has been rebuilt to use the previously cached page. This
151 option is disabled by default.
152 debug => 1
154 This will print additional debugging information to the Catalyst log.
156 You will need to have -Debug enabled to see these messages.
157 auto_check_user => 1
159 If this option is enabled, automatic caching is disabled for logged in
161 users i.e., if the app class has a user_exists() method and it returns
162 true.
163 cache_hook => 'cache_hook_method'
165 cache_finalize_hook => 'cache_finalize_hook_method'
166 cache_dispatch_hook => 'cache_dispatch_hook_method'
167 Calls a method on the application that is expected to return a true or
169 false. This method is called before dispatch, and before finalize so
170 you can short circuit the pagecache behavior. As an example, if you
171 want to disable PageCache while running under debug mode:
172 package MyApp;
174 ...
176 sub cache_hook_method { return shift->debug; }
178 Or, if you want to not cache for certain roles, say "admin":
180 sub cache_hook_method {
182 my ( $c ) = @_;
183 return !$c->check_user_roles('admin');
184 }
185 Note that this is called BEFORE auto_check_user, so you have more
187 flexibility to determine what to do for not logged in users.
188 To override the generation of page keys:
190 __PACKAGE__->config(
192 'Plugin::PageCache' => {
193 key_maker => sub {
194 my $c = shift;
195 return $c->req->base . '/' . $c->req->path;
196 }
197 }
198 );
199 "key_maker" can also be the name of a method, which will be invoked as
201 "<$c-"$key_maker>>.
202 In most cases you would use a single cache_hook method for consistency.
204 It is possible to achieve background refreshing of content by disabling
206 caching in cache_dispatch_hook and enabling caching in
207 cache_finalize_hook for a specific IP address (say 127.0.0.1).
208 A cron of wget "http://localhost/foo.html" would cause the content to
210 be generated fresh and cached for future viewers. Useful for content
211 which takes a very long time to build or pages which should be
212 refreshed at a specific time such as always rolling over content at
213 midnight.
214
216 cache_page
217 Call cache_page in any controller method you wish to be cached.
218 $c->cache_page( $expire );
220 The page will be cached for $expire seconds. Every user who visits the
222 URI(s) referenced by that controller will receive the page directly
223 from cache. Your controller will not be processed again until the
224 cache expires. You can set this value to a low value, such as 60
225 seconds, if you have heavy traffic, to greatly improve site
226 performance.
227 Pass in a DateTime object to make the cache expire at a given point in
229 time.
230 $two_hours = DateTime->now->add( hours => 2 );
232 $c->cache_page( $two_hours );
233 The page will be stored in the page cache until this time.
235 If set_http_headers is set then Expires and Cache-Control headers will
237 also be set to expire at the given date as well.
238 Pass in a list or hash reference for finer control.
240 $c->cache_page(
242 last_modified => $last_modified,
243 cache_seconds => 24 * 60 * 60,
244 expires => 30,
245 );
246 This allows separate control of the page cache and the header cache
248 values sent to the client.
249 Possible options are:
251 cache_seconds
253 This is the number of seconds to keep the page in the page cache,
254 which may be different (normally longer) than the time that client
255 caches may store the page. This is the value set when only a
256 single parameter is passed.
257 expires
259 This is the length of time in seconds that a client may cache the
260 page before revalidating (by asking the server if the document has
261 changed).
262 Unlike above, this is a fixed setting that each client will see.
264 Regardless of how much longer the page will be cached in the page
265 cache the client still sees the same expires time.
266 Setting zero (0) for expires will result in the page being cached,
268 but headers will be sent telling the client to not cache the page.
269 Allows caching expensive content to generate, but any changes will
270 be seen right away.
271 last_modified
273 Last modified time in epoch seconds. If not set will use either
274 the current Last-Modified header, or if not set, the current time.
275 clear_cached_page
277 To clear the cached pages for a URI, you may call clear_cached_page.
278 $c->clear_cached_page( '/view/userlist' );
280 $c->clear_cached_page( '/view/.*' );
281 $c->clear_cached_page( '/view/.*\?.*\bparam=value\b' );
282 This method takes an absolute path or regular expression. Returns the
284 number of matching entries found in the index. A warning will be
285 generated if the page index is disabled (see "CONFIGURATION").
286 The argument is matched against all the keys in the page index. The
288 page index keys include the request path and query string, if any.
289 Typically you'd call this from a different controller than the cached
291 controller. You may for example wish to build an admin page that lets
292 you clear page caches.
293
295 dispatch
296 "dispatch" decides whether or not to serve a particular request from
297 the cache.
298 finalize
300 "finalize" caches the result of the current request if needed.
301 setup
303 "setup" initializes all default values.
304
306 If your application uses Catalyst::Plugin::I18N for localization, a
307 separate cache key will be used for each language a page is displayed
308 in.
309
311 The page index, used to support the "clear_cached_page" method is
312 unreliable because it uses a read-modify-write approach which will
313 loose data if more than one process attempts to update the page index
314 at the same time.
315 It is not currently possible to cache pages served from the Static
317 plugin. If you're concerned enough about performance to use this
318 plugin, you should be serving static files directly from your web
319 server anyway.
320 Cache::FastMmap does not have the ability to specify different
322 expiration times for cached data. Therefore, if your
323 MyApp->config->{cache}->{expires} value is set to anything other than
324 0, you may experience problems with the clear_cached_page method,
325 because the cache index may be removed. For best results, you may wish
326 to use Cache::FileCache or Cache::Memcached as your cache backend.
327
329 Catalyst, Catalyst::Plugin::Cache::FastMmap,
330 Catalyst::Plugin::Cache::FileCache, Catalyst::Plugin::Cache::Memcached
331
333 Andy Grundman, <andy@hybridized.org>
334
336 Bill Moseley, <mods@hank.org>, for many patches and tests.
337 Roberto Henríquez, <roberto@freekeylabs.com>, for i18n support.
339
341 This program is free software, you can redistribute it and/or modify it
342 under the same terms as Perl itself.
343perl v5.30.0 2019-07-26 Catalyst::Plugin::PageCache(3)