NAME
    Catalyst::Plugin::PageCache - Cache the output of entire pages

SYNOPSIS
        use Catalyst;
        MyApp->setup( qw/Cache::FileCache PageCache/ );

        MyApp->config->{page_cache} = {
            expires => 300,
            set_http_headers => 1,
            auto_cache => [
                '/view/.*',
                '/list',
            ],
            debug => 1,
        };

        # in a controller method
        $c->cache_page( '3600' );

        $c->clear_cached_page( '/list' );

        # Expire at a specific time
        $c->cache_page( $datetime_object );

        # Fine control
        $c->cache_page(
            last_modified   => $last_modified,
            cache_seconds   => 24 * 60 * 60,    # once a day
            expires         => 300,             # allow client caching
        );

DESCRIPTION
    Many dynamic websites perform heavy processing on most pages, yet this
    information may rarely change from request to request. Using the
    PageCache plugin, you can cache the full output of different pages so
    they are served to your visitors as fast as possible. This method of
    caching is very useful for withstanding a Slashdotting, for example.

    This plugin requires that you also load a Cache plugin. Please see the
    Known Issues when choosing a cache backend.

WARNINGS
    PageCache should be placed at the end of your plugin list.

    You should only use the page cache on pages which have NO user-specific
    or customized content. Also, be careful if caching a page which may
    forward to another controller. For example, if you cache a page behind a
    login screen, the logged-in version may be cached and served to
    unauthenticated users.

    Note that pages that result from POST requests will never be cached.

PERFORMANCE
    On my Athlon XP 1800+ Linux server, a cached page is served in 0.008
    seconds when using the HTTP::Daemon server and any of the Cache plugins.

CONFIGURATION
    Configuration is optional. You may define the following configuration
    values:

        expires => $seconds

    This will set the default expiration time for all page caches. If you do
    not specify this, expiration defaults to 300 seconds (5 minutes).

        set_http_headers => 1

    Enabling this value will cause Catalyst to set the correct HTTP headers
    to allow browsers and proxy servers to cache your page. This will
    further reduce the load on your server. The headers are set in such a
    way that the browser/proxy cache will expire at the same time as your
    cache. The Last-Modified header will be preserved if you have already
    specified it.

        auto_cache => [
            $uri,
        ]

    To automatically cache certain pages, or all pages, you can specify
    auto-cache URIs as an array reference. Any controller within your
    application that matches one of the auto_cache URIs will be cached using
    the default expiration time. URIs may be specified as absolute: '/list'
    or as a regex: '/view/.*'

        debug => 1

    This will print additional debugging information to the Catalyst log.
    You will need to have -Debug enabled to see these messages. You can also
    specify an optional config parameter auto_check_user. If this option is
    enabled, automatic caching is disabled for logged in users.

METHODS
  cache_page
    Call cache_page in any controller method you wish to be cached.

        $c->cache_page( $expire );

    The page will be cached for $expire seconds. Every user who visits the
    URI(s) referenced by that controller will receive the page directly from
    cache. Your controller will not be processed again until the cache
    expires. You can set this value to as low as 60 seconds if you have
    heavy traffic to greatly improve site performance.

    Pass in a DateTime object to make the cache expire at a given point in
    time.

        $two_hours = DateTime->now->add( hours => 2 );
        $c->cache_page( $two_hours );

    The page will be stored in the page cache until this time.

    If set_http_headers is set then Expires and Cache-Control headers will
    also be set to expire at the given date as well

    Pass in a list or hash reference for finer control.

        $c->cache_page(
            last_modified   => $last_modified,
            cache_seconds   => 24 * 60 * 60,
            expires         => 30,
        );

    This allows separate control of the page cache and the header cache
    values sent to the client.

    Possible options are:

    last_modified
        Last modified time in epoch seconds. If not set will use either the
        current Last-Modified header, or if not set, the current time.

    cache_seconds
        This is the number of seconds to keep the page in the page cache,
        which may be different (normally longer) than the time that client
        caches may store the page.

    expires
        This is the lenght of time in seconds that a client may cache the
        page before revalidating (by asking the server if the document has
        changed).

        Unlike above, this is a fixed setting that each client will see.
        Regardless of how much longer the page will be cached in the page
        cache the client still sees the same expires time.

        Setting zero (0) for expires will result in the page being cached,
        but headers will be sent telling the client to not cache the page.
        Allows caching expensive content to generate, but any changes will
        be seen right away.

    To make the cache expire at a given point in time, pass in a DateTime
    object.

        $two_hours = DateTime->now->add( hours => 2 );
        $c->cache_page( $two_hours );

    If set_http_headers is set then Expires and Cache-Control headers will
    be set to expire at the given date.

    Pass in a list or hash reference for finer control.

        $c->cache_page(
            last_modified   => $last_modified,
            cache_seconds   => 24 * 60 * 60,
            expires         => 30,
        );

    Possible options are:

    last_modified
        Last modified time in epoch seconds. If not set will use either the
        current Last-Modified header or the current time.

    cache_seconds
        This is the number of seconds to keep the page in the page cache,
        which may be different (normally longer) then the time that client
        caches may use the page.

    expires
        This is the lenght of time in seconds that a client may cache the
        page before revalidating (by asking the server if the document has
        changed).

        Unlike the "expires" setting above

  clear_cached_page
    To clear the cached value for a URI, you may call clear_cached_page.

        $c->clear_cached_page( '/view/userlist' );
        $c->clear_cached_page( '/view/.*' );

    This method takes an absolute path or regular expression. For obvious
    reasons, this must be called from a different controller than the cached
    controller. You may for example wish to build an admin page that lets
    you clear page caches.

INTERNAL EXTENDED METHODS
  dispatch
    "dispatch" decides whether or not to serve a particular request from the
    cache.

  finalize
    "finalize" caches the result of the current request if needed.

  setup
    "setup" initializes all default values.

KNOWN ISSUES
    It is not currently possible to cache pages served from the Static
    plugin. If you're concerned enough about performance to use this plugin,
    you should be serving static files directly from your web server anyway.

    Cache::FastMmap does not have the ability to specify different
    expiration times for cached data. Therefore, if your
    MyApp->config->{cache}->{expires} value is set to anything other than 0,
    you may experience problems with the clear_cached_page method, because
    the cache index may be removed. For best results, you may wish to use
    Cache::FileCache or Cache::Memcached as your cache backend.

SEE ALSO
    Catalyst, Catalyst::Plugin::Cache::FastMmap,
    Catalyst::Plugin::Cache::FileCache, Catalyst::Plugin::Cache::Memcached

AUTHOR
    Andy Grundman, <andy@hybridized.org>

THANKS
    Bill Moseley, <mods@hank.org>, for many patches and tests.

COPYRIGHT
    This program is free software, you can redistribute it and/or modify it
    under the same terms as Perl itself.