Installing and upgrading

Installing Stash

1. Download the latest version of Stash, un-zip it, and move the system/expressionengine/third_party/stash folder to ./system/expressionengine/third_party/

2. In the CP, navigate to Add-ons > Modules and click the 'Install' link for the Stash module and the Stash extension

3. Create a folder to contain your Stash template files, e.g. 'stash_templates'. Ideally this should be above the public webroot of your website.

4. Create a folder to contain your Stash static cache files, e.g. 'static_cache'. This must be below the public webroot of your website. Set permissions to 777 or change the owner of the directory (CHOWN) to the user PHP runs as.

5. Open your ./system/expressionengine/config/config.php file (EE2) or ./system/user/config/config.php (EE3), add the following lines at the bottom of the file:

    $config['stash_file_basepath'] = '/path/to/stash_templates/';
    $config['stash_file_sync'] = FALSE; // set to TRUE to sync stash embed file changes during development
    $config['stash_file_extensions'] = array('html', 'md', 'css', 'js', 'rss', 'xml');
    $config['stash_static_basepath'] = '/path/to/static_cache/';
    $config['stash_static_url'] = '/static_cache/'; // should be a relative url
    $config['stash_static_cache_enabled'] = FALSE; // set to TRUE to enable static caching
    $config['stash_static_cache_index'] = TRUE; // set to TRUE to use Stash as an index only when static caching (variable value not saved)
    $config['stash_static_character_blacklist'] = array('{', '}', '<', '>', ':', '"', '\\', '|', '*', '.');
    $config['stash_query_strings'] = FALSE; // set to TRUE to cache query strings when referencing the current uri with @URI
    $config['stash_cookie'] = 'stashid'; // the stash cookie name
    $config['stash_cookie_expire'] = 0; // seconds - 0 means expire at end of session
    $config['stash_cookie_enabled'] = TRUE; // set to FALSE if not using 'user' scope and cache pruning is disabled
    $config['stash_default_scope'] = 'local'; // default variable scope if not specified
    $config['stash_default_refresh'] = 0; // default cache refresh period in minutes
    $config['stash_limit_bots'] = FALSE; // stop database writes by bots to reduce load on busy sites
    $config['stash_bots'] = array('bot', 'crawl', 'spider', 'archive', 'search', 'java', 'yahoo', 'teoma');
    $config['stash_prune_enabled'] = TRUE; // set FALSE if you trigger pruning with a CRON/scheduled task (via Mustash API)
    $config['stash_prune_probability'] = 4;  // % chance that a request initiates cache pruning
    $config['stash_invalidation_period']  = 0;  // duration of cache invalidation in seconds
    $config['stash_parse_if_in']  = FALSE;  // enable parsing of {if var IN (1|2|3)...{/if} style conditionals in Stash templates
    # $config['stash_var_prefix'] = 'preview-'; // apply a prefix to all saved variables, useful for entry previews
   
   (of course if you're using a custom config bootstrap file, add the config items there instead)
   

6. If you want to use static file caching with Stash, follow the static cache setup guide.

7. Follow the cache pruning configuration guide to calculate appropriate configuration values for your website.

Upgrading Stash

1. Copy the stash folder to ./system/expressionengine/third_party/
2. In the CP, navigate to Add-ons > Modules and click the 'Run module upgrades' link
3. Check that you have all the config settings listed above in your webroot index.php file (or config bootstrap, if you use one)