1Catalyst::Plugin::PageCUascehre(C3o)ntributed Perl DocumCeanttaaltyisotn::Plugin::PageCache(3)
2
3
4

NAME

6       Catalyst::Plugin::PageCache - Cache the output of entire pages
7

SYNOPSIS

9           use Catalyst;
10           MyApp->setup( qw/Cache::FileCache PageCache/ );
11
12           __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
22                   # 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
27                   # 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
37           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
45           # in a controller method
46           $c->cache_page( '3600' );
47
48           $c->clear_cached_page( '/list' );
49
50           # Expire at a specific time
51           $c->cache_page( $datetime_object );
52
53
54           # 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

DESCRIPTION

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
68       This plugin requires that you also load a Cache plugin.  Please see the
69       Known Issues when choosing a cache backend.
70

WARNINGS

72       PageCache should be placed at the end of your plugin list.
73
74       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
80       Note that pages that result from POST requests will never be cached.
81

PERFORMANCE

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

CONFIGURATION

88       Configuration is optional.  You may define the following configuration
89       values:
90
91           expires => $seconds
92
93       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
96           cache_headers => 1
97
98       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
103           set_http_headers => 1
104
105       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
112           auto_cache => [
113               $uri,
114           ]
115
116       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
122           disable_index => 1
123
124       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
129       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
134           index_page_key => '...'
135
136       The key string used for the index, Defaults to a string that includes
137       the name of the Catalyst app class.
138
139           busy_lock => 10
140
141       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
153           debug => 1
154
155       This will print additional debugging information to the Catalyst log.
156       You will need to have -Debug enabled to see these messages.
157
158           auto_check_user => 1
159
160       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
164           cache_hook => 'cache_hook_method'
165           cache_finalize_hook => 'cache_finalize_hook_method'
166           cache_dispatch_hook => 'cache_dispatch_hook_method'
167
168       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
173           package MyApp;
174
175           ...
176
177           sub cache_hook_method { return shift->debug; }
178
179       Or, if you want to not cache for certain roles, say "admin":
180
181           sub cache_hook_method {
182               my ( $c ) = @_;
183               return !$c->check_user_roles('admin');
184           }
185
186       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
189       To override the generation of page keys:
190
191           __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
200       "key_maker" can also be the name of a method, which will be invoked as
201       "<$c-"$key_maker>>.
202
203       In most cases you would use a single cache_hook method for consistency.
204
205       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
209       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

METHODS

216   cache_page
217       Call cache_page in any controller method you wish to be cached.
218
219           $c->cache_page( $expire );
220
221       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
228       Pass in a DateTime object to make the cache expire at a given point in
229       time.
230
231           $two_hours = DateTime->now->add( hours => 2 );
232           $c->cache_page( $two_hours );
233
234       The page will be stored in the page cache until this time.
235
236       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
239       Pass in a list or hash reference for finer control.
240
241           $c->cache_page(
242               last_modified   => $last_modified,
243               cache_seconds   => 24 * 60 * 60,
244               expires         => 30,
245           );
246
247       This allows separate control of the page cache and the header cache
248       values sent to the client.
249
250       Possible options are:
251
252       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
258       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
263           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
267           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
272       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
276   clear_cached_page
277       To clear the cached pages for a URI, you may call clear_cached_page.
278
279           $c->clear_cached_page( '/view/userlist' );
280           $c->clear_cached_page( '/view/.*' );
281           $c->clear_cached_page( '/view/.*\?.*\bparam=value\b' );
282
283       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
287       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
290       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

INTERNAL EXTENDED METHODS

295   dispatch
296       "dispatch" decides whether or not to serve a particular request from
297       the cache.
298
299   finalize
300       "finalize" caches the result of the current request if needed.
301
302   setup
303       "setup" initializes all default values.
304

I18N SUPPORT

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

KNOWN ISSUES

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
316       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
321       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

SEE ALSO

329       Catalyst, Catalyst::Plugin::Cache::FastMmap,
330       Catalyst::Plugin::Cache::FileCache, Catalyst::Plugin::Cache::Memcached
331

AUTHOR

333       Andy Grundman, <andy@hybridized.org>
334

THANKS

336       Bill Moseley, <mods@hank.org>, for many patches and tests.
337
338       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.
343
344
345
346perl v5.34.0                      2022-01-21    Catalyst::Plugin::PageCache(3)
Impressum