README

This project was born in a need for faster pages rendering years ago. Now, we have much better techniques (CDNs, HTTP/2, SPAs) to deal with the problem. The code should work with Symfony 2 & 3, but newer versions of Symfony would need an overhaul.

This project is left here to stay for legacy apps still using it, as well as a historical piece.

Supercache Bundle

Static pages caching for Symfony Framework.

What is Supercache?

Some of you may be annoyed looking at simple pages loading times - exactly like me. There's a lot solution for that problem - this is extreme one. If you ever used Wordpress you probably seen WP Super Cache plugin. This bundle is build around similar principles (but it is not affiliated in any way) as that plugin.

Basically SupercacheBundle caches whole response to static files and serve them at no cost. It's very useful for pages where there're a lot of static routes visited often.

Installation

Before you start using this bundle you should carefully read HTTP Cache chapter of Symfony Cookbook - it provides a bunch of excellent techniques and tips about caching.

Bundle can be installed like any other Symfony bundle.

Open a command console, enter your project directory and execute following command:
composer require noflash/supercache-bundle
Enable the bundle by adding following line to app/AppKernel.php file:

<?php
// app/AppKernel.php

// ...
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...

            new noFlash\SupercacheBundle\SupercacheBundle(),
        );

        // ...
    }

    // ...
}

~~Execute following command and follow onscreen instructions app/console supercache:install~~ Currently manual installation is required. You should create webcache directory in root folder and than perform first two steps described in Troubleshooting section below.

Configuration

TBD Default configuration:

supercache:

    # Enable/disable cache while running prod environment
    enable_prod:          true

    # Enable/disable cache while running dev environment
    enable_dev:           false

    # Cache directory, must be http-accessible (so it cannot be located under app/)
    cache_dir:            '%kernel.root_dir%/../webcache'

    # Enable/disable adding X-Supercache header
    cache_status_header:  true

Troubleshooting

Installation command failed: Failed to create cache directory

Looks like specified cache directory cannot be created. It can be permission related problem. You can try creating it yourself. To do that simply create desired cache directory (by default it's set to ./webcache/). Next put following content in .htaccess inside cache directory:

RemoveHandler .php
RemoveType .php
Options -ExecCGI

<IfModule mod_php5.c>
    php_flag engine off
</IfModule>

<IfModule mod_headers.c>
    Header set Cache-Control 'max-age=3600, must-revalidate'
</IfModule>

<IfModule mod_expires.c>
    ExpiresActive On
    ExpiresByType text/html A3600
</IfModule>

<IfModule mod_mime.c>
    AddType application/javascript .js
    AddType text/html .html
    AddType application/octet-stream .bin
</IfModule>

Installation command failed: Failed to modify .htaccess (...)

If you (or some other bundle) modified web/.htaccess file, installer may be have trouble automatically applying required changes. You can add following lines manually - they should be placed just below RewriteRule ^app\.php(/(.*)|$) %{ENV:BASE}/$2 [R=301,L] (or similar):

### >>>SUPERCACHE BUNDLE 
RewriteCond %{REQUEST_METHOD} !^(GET|HEAD) [OR]
RewriteCond %{QUERY_STRING} !^$
RewriteRule . - [S=3]

RewriteCond %{DOCUMENT_ROOT}/../webcache/$1/index.html -f
RewriteRule ^(.*) %{DOCUMENT_ROOT}/../webcache/$1/index.html [L]

RewriteCond %{DOCUMENT_ROOT}/../webcache/$1/index.js -f
RewriteRule ^(.*) %{DOCUMENT_ROOT}/../webcache/$1/index.js [L]

RewriteCond %{DOCUMENT_ROOT}/../webcache/$1/index.bin -f
RewriteRule ^(.*) %{DOCUMENT_ROOT}/../webcache/$1/index.bin [L]
### <<<SUPERCACHE BUNDLE

Please note cache path need to be adjusted. Path is relative to web/ directory.

My server doesn't support .htaccess

You have two options: translate rewrite rules (specified above) to format supported by server you use or use PHP-PULL mode. SupercacheBundle contains fallback mode for servers without .htaccess support (e.g. CLI server issued using app/console server:run command). This mode works by attaching to Symfony HTTP kernel and trying locate cached response for given request. Of course it comes with a price - fallback will run PHP intepretter and initialize core of the framework. In my tests DIRECT mode returns response in 3-5ms while PHP-PULL mode need around 30ms.

There's no need to change any configuration options to enable PHP-PULL.

FAQ

Do all responses gets cached?

No, request & response must meet some criteria to be cached:

GET request method
No query string
Response code between 200 and 300 (excluding 204)
No private or no-store cache control directives
Route is not marked as excluded (see #3 for details)

Are there any limitations?

Yes, there are few:

It's impossible to serve different content on /sandbox and /sandbox/
You cannot have routes .. and . (they are illegal in HTTP RFC anyway)
There are no automatic check for authentication token (it's your responsibility to set private cache policy if you're presenting user-specific information)
Due to performance reasons files are served from cache with one of the following MIME-Types: text/html, application/javascript or application/octet-stream. See issue #2 for details.

noflash / supercache-bundle

Maintainers

Details