Resource Buckets

Perch 2.1 introduced the ability to have multiple places in which to store resources. We call these resource buckets – you can think of them as multiple resource folders.

Basic buckets

The resource bucket to use can be set on any individual template tag using the bucket attribute.

    <perch:content id="report" type="file" label="Annual report PDF" bucket="reports">

Without any configuration, you can use a bucket name as above. If that bucket doesn’t exist, it will be created as a subfolder of the default resources folder. In this case, /perch/resources/reports/. You can create that folder yourself, or Perch will do it for you.

Setting a default bucket

You can declare any of your buckets as the default from your config/config.php file.

define('PERCH_DEFAULT_BUCKET','images');

Bucket list

For more advanced use, you can define a bucket using the bucket list. This is a PHP configuration file which you need to create as perch/config/buckets.php

A bucket list item has a name (max 16 characters) and defines the following:

Key	Value
type	The type of bucket. Defaults to `file` for basic buckets, and uses values like `amazon_s3`, `dropbox` etc for cloud storage.
web_path	The path (either absolute or from your website root) to use when creating links to images and files in the website.
file_path	The file system path to the folder where the files are saved.
role	If set, can have the value of `backup` to indicate that the bucket is used for backups only.

Specific bucket types may also define additional properties as per their own documentation. For example, Amazon S3 buckets need a region option setting.

An example bucket list takes this format. It defines three buckets, images, whitepapers and backup.

<?php
    return [
        'images' => [
            'type'      => 'file',
            'web_path'  => '/images',
            'file_path' => '/var/www/mysite/public_html/images',
        ],
        'whitepapers' => [
            'type'      => 'file',
            'web_path'  => '/whitepapers',
            'file_path' => '/var/www/mysite/public_html/whitepapers',
        ],
        'backup' => [
            'type'      => 'dropbox',
            'web_path'  => '',
            'file_path' => 'backups',
            'role'      => 'backup',
        ],
    ];
?>

Using the bucket list, you could define a bucket which stored files outside of the web root, and then delivered them using a script. This can be used to, for example, only give access to a file to someone who is authorised to view it. You would set the web_path to be a path to your script. The file name will be appended to it, so it could be e.g. /secure-download.php?file=