[catagits/Catalyst-Plugin-RequireSSL.git] / README

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

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

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

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.

  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.

    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.

    dispatch (extended)
        Bypass the dispatch phase and send cached content if available

    finalize (extended)
        Cache the page output if requested.

    setup
        Setup default values.

    _page_cache_key
        Returns a cache key for the current page.

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"

COPYRIGHT
    This program is free software, you can redistribute it and/or modify it
    under the same terms as Perl itself.
Commit	Line	Data
1763fe29	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