Documentation

FilesBackendS3 extends FilesBackend
in package

Application

Backend for the files module which stores files in a local directory.

S3 can host public files in four ways:

using a default ACL like 'public-read'
using a bucket policy
using signed requests
using a cloudfront CDN (or other) proxy

Consider your project requirement and configure the backend as appropriate.

Note, all methods but proxies requires the 'public access override' in the bucket config to be disabled.

Constants

DEFAULT_SETTINGS : mixed = [ // Folder prefix for transformed images 'tran...: This is merged with the backend 'settings' defined in the 'file' config.

Properties

$backend_type : mixed: This should match the key in Kohana::config("file.file_backends")
$client : S3Client|null
$logging : bool|callable

Methods

absUrl() : string: Returns the absolute URL for a given file id, including domain.
baseDir() : string: Generate server files base directory path
cleanupLocalCopy() : bool: Remove a local copy of a file
clearCacheResponse() : void: Clear a cached file function response
clearCaches() : void: Clear all caches for a given file
copyExisting() : bool: Copy an existing file (within S3) to a new file in S3
createLocalCopy() : string|null: Create a copy of the file in a temporary directory.
delete() : bool: Delete a file
deleteDir() : mixed: Delete a directory
exists() : bool: Determine if a file exists
existsPublic() : bool: Determine if a file exists from the public side (quickly)
getCacheKey() : string: Get a repeatable and predictable rdb key for a file function response
getCacheResponse() : mixed: Get a cached file function response
getConfig() : array<string|int, mixed>: Get the config settings for the current backend
getHeadObject() : array<string|int, mixed>|null: Get the head object for a file.
getName() : string: Get the name for the current backend
getS3Client() : S3Client: The S3 client connection for this backend.
getS3Config() : array<string|int, mixed>: Config for the AWS client.
getSettings() : array<string|int, mixed>: Get the AWS config merge settings.
getStream() : StreamInterface|null: Get a PSR stream for a file.
getString() : string|false: Returns file content as a string. Basically the same as file_get_contents
getTransformFolderPrefix() : string
getType() : string: Get the 'type' key for the current backend
glob() : array<string|int, mixed>: Returns all files which match the specified mask.
imageSize() : array<string|int, mixed>|false: WARNING: SLOW ON S3 | Returns the size of an image, or false on failure.
makePrivate() : bool: Make a file private using ACL
makePublic() : bool: Make a file public using ACL
mkDir() : mixed: Create an empty directory
moveFile() : bool: Moves a file within the backend context.
moveUpload() : bool: Moves an uploaded file into the repository.
mtime() : int|false: Get the modified time, in unix timestamp format, of the specified file
putExisting() : bool: Saves file content from an existing (local) file
putStream() : bool: Saves file content from a stream. Basically just fopen/stream_copy_to_stream/fclose
putString() : bool: Saves file content as a string. Basically the same as file_put_contents
readfile() : int|false: This is the equivalent of the php readfile function
relUrl() : string: Returns the relative URL for a given file.
resizeUrl() : string: Returns the relative URL for a dynamically resized image.
setCacheResponse() : void: Set a cached file function response
setLogging() : void: Override the logging.
size() : int|false: Get the size, in bytes, of the specified file
touch() : bool: Sets access and modification time of file
log() : void: Log a mesasge or exception.
handleException() : false|null: Simple exception handling with logging

DEFAULT_SETTINGS

This is merged with the backend 'settings' defined in the 'file' config.


    public
        mixed
    DEFAULT_SETTINGS
    = [
    // Folder prefix for transformed images
    'transform_folder_prefix' => 'transformed/',
    // Time to cache file helpers responses, such as ::exists()
    'default_cache_ttl' => 86400,
    // Chunk size for processing streams
    'stream_chunk_size' => 1024 * 1024,
]

$backend_type

This should match the key in Kohana::config("file.file_backends")


        protected
            mixed
    $backend_type
     = 's3'

$client


        protected
            S3Client|null
    $client
     = null

$logging


        protected
            bool|callable
    $logging
     = !IN_PRODUCTION

absUrl()

Returns the absolute URL for a given file id, including domain.


    public
                    absUrl(mixed $filename[, bool $lazy = true ]) : string

Parameters

$filename : mixed
$lazy : bool = true

Return values

string —

e.g. http://example.com/files/filename.jpg

baseDir()

Generate server files base directory path


    public
                    baseDir() : string

Return values

string

cleanupLocalCopy()

Remove a local copy of a file


    public
                    cleanupLocalCopy(string $temp_filename) : bool

Parameters

$temp_filename : string: The filename returned by createLocalCopy

Return values

bool

clearCacheResponse()

Clear a cached file function response


    public
                    clearCacheResponse(string $function, string $filename) : void

Parameters

$function : string
$filename : string

clearCaches()

Clear all caches for a given file


    public
                    clearCaches(string $filename) : void

Parameters

$filename : string

copyExisting()

Copy an existing file (within S3) to a new file in S3


    public
                    copyExisting(string $src_filename, string $target_filename) : bool

Parameters

$src_filename : string
$target_filename : string

Return values

bool

createLocalCopy()

Create a copy of the file in a temporary directory.


    public
                    createLocalCopy(string $filename) : string|null

Parameters

$filename : string: The file to copy into a temporary location

Return values

string|null —

Temp filename or NULL on error

delete()

Delete a file


    public
                    delete(string $filename) : bool

Parameters

$filename : string

Return values

bool

deleteDir()

Delete a directory


    public
                    deleteDir(mixed $directory) : mixed

Parameters

$directory : mixed

exists()

Determine if a file exists


    public
                    exists(string $filename) : bool

Parameters

$filename : string: The file to check for

Return values

bool —

Returns TRUE if the file exists, and FALSE if it does not

existsPublic()

Determine if a file exists from the public side (quickly)


    public
                    existsPublic(string $filename) : bool

Parameters

$filename : string: The file to check for

Return values

bool —

Returns TRUE if the file exists, and FALSE if it does not

getCacheKey()

Get a repeatable and predictable rdb key for a file function response


    public
                    getCacheKey(string $function, string $filename) : string

Parameters

$function : string
$filename : string

Return values

string

getCacheResponse()

Get a cached file function response


    public
                    getCacheResponse(string $function, string $filename) : mixed

Parameters

$function : string
$filename : string

Return values

mixed —

Cache val or null if empty

getConfig()

Get the config settings for the current backend


    public
                    getConfig() : array<string|int, mixed>

Return values

array<string|int, mixed>

getHeadObject()

Get the head object for a file.


    public
                    getHeadObject(string $filename) : array<string|int, mixed>|null

This includes checks for delete markers.

Parameters

$filename : string

Return values

array<string|int, mixed>|null —

null if not found or deleted

getName()

Get the name for the current backend


    public
                    getName() : string

Return values

string

getS3Client()

The S3 client connection for this backend.


    public
                    getS3Client() : S3Client

Return values

S3Client

getS3Config()

Config for the AWS client.


    public
                    getS3Config() : array<string|int, mixed>

Return values

array<string|int, mixed>

getSettings()

Get the AWS config merge settings.


    public
                    getSettings() : array<string|int, mixed>

Return values

array<string|int, mixed>

getStream()

Get a PSR stream for a file.


    public
                    getStream(string $filename) : StreamInterface|null

Parameters

$filename : string

Return values

StreamInterface|null

getString()

Returns file content as a string. Basically the same as file_get_contents


    public
                    getString(string $filename) : string|false

Parameters

$filename : string

Return values

string|false

getTransformFolderPrefix()


    public
                    getTransformFolderPrefix() : string

Return values

string

getType()

Get the 'type' key for the current backend


    public
                    getType() : string

Return values

string

glob()

Returns all files which match the specified mask.


    public
                    glob(string $mask[, mixed $depth = 0 ]) : array<string|int, mixed>

Parameters

$mask : string: The search mask / string
$depth : mixed = 0

Return values

array<string|int, mixed> —

An array of results from the lookup

imageSize()

WARNING: SLOW ON S3 | Returns the size of an image, or false on failure.


    public
                    imageSize(string $filename) : array<string|int, mixed>|false

In S3 we can either store image size info as meta data

Output format is the same as getimagesize, but will be at a minimum: [0] => width, [1] => height, [2] => type

Parameters

$filename : string

Return values

array<string|int, mixed>|false —

depending if found

makePrivate()

Make a file private using ACL


    public
                    makePrivate(string $filename) : bool

Parameters

$filename : string

Return values

bool

makePublic()

Make a file public using ACL


    public
                    makePublic(string $filename) : bool

Will not work if 'block all public access' is enabled on the bucket

Parameters

$filename : string

Return values

bool

mkDir()

Create an empty directory


    public
                    mkDir(mixed $directory) : mixed

Parameters

$directory : mixed

moveFile()

Moves a file within the backend context.


    public
                    moveFile(string $src, string $dest) : bool

Parameters

$src : string: The source filename to move
$dest : string: The target filename to move it to

Return values

bool —

Returns TRUE on success, FALSE on failure.

moveUpload()

Moves an uploaded file into the repository.


    public
                    moveUpload(string $src, string $filename) : bool

Parameters

$src : string: The source file to move
$filename : string: The filename to move it to

Return values

bool —

Returns TRUE on success, FALSE on failure.

mtime()

Get the modified time, in unix timestamp format, of the specified file


    public
                    mtime(string $filename) : int|false

Parameters

$filename : string

Return values

int|false —

The modified file timestamp

putExisting()

Saves file content from an existing (local) file


    public
                    putExisting(string $filename, string $existing) : bool

Parameters

$filename : string
$existing : string

Return values

bool

putStream()

Saves file content from a stream. Basically just fopen/stream_copy_to_stream/fclose


    public
                    putStream(string $filename, mixed $stream) : bool

Parameters

$filename : string
$stream : mixed

Return values

bool

putString()

Saves file content as a string. Basically the same as file_put_contents


    public
                    putString(string $filename, string $content) : bool

Parameters

$filename : string
$content : string

Return values

bool

readfile()

This is the equivalent of the php readfile function


    public
                    readfile(string $filename) : int|false

Parameters

$filename : string

Return values

int|false

relUrl()

Returns the relative URL for a given file.


    public
                    relUrl(mixed $filename) : string

Parameters

$filename : mixed

Return values

string —

e.g. files/filename.jpg

resizeUrl()

Returns the relative URL for a dynamically resized image.


    public
                    resizeUrl(string $filename, string $size) : string

Size formatting is as per File::parseSizeString, e.g. c400x300

Parameters

$filename : string
$size : string: A code as per File::parseSizeString

Return values

string —

HTML-safe relative URL, e.g. file/resize/c400x300/123_example.jpg

setCacheResponse()

Set a cached file function response


    public
                    setCacheResponse(string $function, string $filename, mixed $response[, int $ttl = null ]) : void

Parameters

$function : string
$filename : string
$response : mixed
$ttl : int = null: Number of seconds to hold cache for. Defaults to one day

setLogging()

Override the logging.


    public
                    setLogging(bool|callable $logging) : void

By default logging is disabled in production environments. In non-production environments exceptions are logged to the error log.

Provide a callable to log other messages.

Parameters

$logging : bool|callable

size()

Get the size, in bytes, of the specified file


    public
                    size(string $filename) : int|false

Parameters

$filename : string

Return values

int|false

touch()

Sets access and modification time of file


    public
                    touch(string $filename) : bool

We achieve this in S3 by copying the file on top of itself

Parameters

$filename : string

Return values

bool

log()

Log a mesasge or exception.


    protected
                    log(mixed $message) : void

Parameters

$message : mixed

handleException()

Simple exception handling with logging


    private
                    handleException(Exception $e[, bool $permit_not_found = false ]) : false|null

Parameters

$e : Exception
$permit_not_found : bool = false

Return values

false|null —

false if not found, null otherwise

FilesBackendS3 extends FilesBackend in package Application

Table of Contents

Constants

Properties

Methods

Constants

DEFAULT_SETTINGS

Properties

$backend_type

$client

$logging

Methods

absUrl()

Parameters

Tags

Return values

baseDir()

Return values

cleanupLocalCopy()

Parameters

Return values

clearCacheResponse()

Parameters

clearCaches()

Parameters

copyExisting()

Parameters

Return values

createLocalCopy()

Parameters

Tags

Return values

delete()

Parameters

Tags

Return values

deleteDir()

Parameters

exists()

Parameters

Tags

Return values

existsPublic()

Parameters

Return values

getCacheKey()

Parameters

Return values

getCacheResponse()

Parameters

Return values

getConfig()

Return values

getHeadObject()

Parameters

Return values

getName()

Return values

getS3Client()

Tags

Return values

getS3Config()

Tags

Return values

getSettings()

Tags

Return values

getStream()

Parameters

Tags

Return values

getString()

Parameters

Tags

Return values

getTransformFolderPrefix()

Tags

Return values

getType()

Return values

FilesBackendS3 extends FilesBackend
in package

Application