File class - Documentation for SproutCMS

Info Page:

Page options:

class File

Methods for working with files, including images

File: /sprout/Helpers/File.php
Namespace: Sprout\Helpers

Functions

Name	Visibility	Description
absUrl	public (static)	Returns the public URL for a given file, including domain.
backend	private (static)	Return the backend library to use for many file operations
base64Thumb	public (static)	Generates a cropped, base-64 encoded thumbnail of an image
calculateResizeRam	public (static)	Will we have enough RAM to do the resizes?
checkFileContentsExtension	public (static)	Checks file contents match the extension
cleanupLocalCopy	public (static)	Remove a local copy of a file
createDefaultSizes	public (static)	Create default image sizes as per the config parameter 'file.image_transformations'
createLocalCopy	public (static)	Create a copy of the file in a temporary directory.
createSize	public (static)	Create a resized version of the specified file at a given size.
delete	public (static)	Delete a file
deleteCache	public (static)	Delete cached versions of a file
download	public (static)	Prompts a user to download a file, and terminates the script
exists	public (static)	Returns TRUE if the file exists, and FALSE if it does not
filenameMakeSane	public (static)	Make a filename sane - strip lots of characters which create problems
findUsage	public (static)	Searches the whole database to find all records in all columns
getDetails	public (static)	Gets the details of a file using its id.
getExt	public (static)	Gets the (final) extension from a file name, in lowercase
getNoext	public (static)	For a given file, returns the name without an ext
getResizeFilename	public (static)	For a given file, returns the filename to use to retrieve a resized version of the file
getString	public (static)	Returns file content as a string. Basically the same as file_get_contents
getType	public (static)	Determines the file type from a file name by examining its extension
glob	public (static)	Returns all files which match the specified mask.
humanSize	public (static)	Converts a file size, in bytes, into a human readable form (with trailing kb, mb, etc)
imageSize	public (static)	Returns the size of an image, or false on failure.
lookupReplacementName	public (static)	Checks the database for an updated name for a file.
lookupReplacementUrl	public (static)	Checks the database for an updated URL path for a file.
mimetype	public (static)	Return the mimetype for a given filename.
mimetypeExtended	public (static)	Get the content-type of a file using magic mime.
moveUpload	public (static)	Moves an uploaded file into the repository.
mtime	public (static)	Returns the modified time, in unix timestamp format, of the specified file
parseSizeString	public (static)	Parse the size string used in file/resize and some helpers.
postUploadProcessing	public (static)	Do post-processing after a file upload
putExisting	public (static)	Saves file content from an existing file
putStream	public (static)	Saves file content from a stream. Basically just fopen/stream_copy_to_stream/fclose
putString	public (static)	Saves file content as a string. Basically the same as file_put_contents
readfile	public (static)	This is the equivalent of the php readfile function
relUrl	public (static)	Returns the relative public URL for a given file.
replaceSet	public (static)	Replaces a set of files to be stored in a single field; this acts as a backend for Fb::chunkedUpload
resizeUrl	public (static)	Returns the relative URL for a dynamically resized image.
size	public (static)	Returns the size, in bytes, of the specified file
sizeUrl	public (static)	Gets the relative URL for a fixed or dynamically resized image
touch	public (static)	Sets access and modification time of file
url	public (static)	Returns the public URL for a given file. Does not include domain.

public absUrl

string File::absUrl ( string $filename );

Returns the public URL for a given file, including domain.

private backend

FilesBackend File::backend ( );

Return the backend library to use for many file operations

public base64Thumb

false|array File::base64Thumb ( string $file_path , int $width , int $height );

Generates a cropped, base-64 encoded thumbnail of an image

public calculateResizeRam

void File::calculateResizeRam ( array $dimensions );

Will we have enough RAM to do the resizes?

public checkFileContentsExtension

boolean|null File::checkFileContentsExtension ( string $filename , string $ext );

Checks file contents match the extension

public cleanupLocalCopy

unknown File::cleanupLocalCopy ( string $temp_filename );

Remove a local copy of a file
Call this once you're done with the local copy

public createDefaultSizes

void File::createDefaultSizes ( string $filename [, string $specific_size ] );

Create default image sizes as per the config parameter 'file.image_transformations'

The transformed files get saved onto the server.
If any of the transformations in a transform-group fails,
the whole group will fail and the file will not be saved.

public createLocalCopy

string File::createLocalCopy ( string $filename );

Create a copy of the file in a temporary directory.
Don't forget to File::destroy_local_copy($temp_filename) when you're done!

public createSize

bool File::createSize ( string $filename , string $size [, string $force_ext ] );

Create a resized version of the specified file at a given size.

The size is specified the same as the file/resize method (rXXXxYYY or cXXXxYYY)
The output filename will be basename.size.ext

The files can be used with `size_url` or `get_resize_filename` on the front-end.

public delete

bool File::delete ( string $filename );

Delete a file
If the file is an image, any resized variants (e.g. 'small', 'medium' etc.) are deleted too

public deleteCache

void File::deleteCache ( string $filename );

Delete cached versions of a file

public download

void File::download ( string $filename [, string $download_name ] );

Prompts a user to download a file, and terminates the script
Sets all the right headers and stuff, doesn't set caching/expires/etc headers though.

public exists

bool File::exists ( string $filename );

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

public filenameMakeSane

string File::filenameMakeSane ( string $filename );

Make a filename sane - strip lots of characters which create problems

public findUsage

unknown File::findUsage ( string $filename );

Searches the whole database to find all records in all columns
which contain a given filename.

The search looks in VARCHAR columns with more than 200 chars (exact match)
and in TEXT columns (contains match)

Return value is an array of matches, in the format:
  [0] => table
  [1] => record id
  [2] => record name, if available

public getDetails

array File::getDetails ( int $id );

Gets the details of a file using its id.

Uses a prepared statement for speed when doing repeated queries.

N.B. If the file entry doesn't exist, a reference to 'missing.png' is returned

public getExt

string File::getExt ( string $filename );

Gets the (final) extension from a file name, in lowercase

public getNoext

string File::getNoext ( string $original );

For a given file, returns the name without an ext

public getResizeFilename

string File::getResizeFilename ( string $original , string $size_name [, string $force_ext ] );

For a given file, returns the filename to use to retrieve a resized version of the file

public getString

string File::getString ( string $filename );

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

public getType

int File::getType ( string $filename );

Determines the file type from a file name by examining its extension

public glob

unknown File::glob ( string $mask );

Returns all files which match the specified mask.
I have a feeling this returns other sizes (e.g. .small) as well - which may not be ideal.

public humanSize

string File::humanSize ( int $size );

Converts a file size, in bytes, into a human readable form (with trailing kb, mb, etc)

public imageSize

array File::imageSize ( string $filename );

Returns the size of an image, or false on failure.

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

public lookupReplacementName

string File::lookupReplacementName ( string $filename );

Checks the database for an updated name for a file.

This only works for full-sized images, e.g. 123_example.jpg, not 123_example.small.jpg

public lookupReplacementUrl

string File::lookupReplacementUrl ( string $filename );

Checks the database for an updated URL path for a file.
I.e. a file which has been replaced by the admin 'replace file' tool.

public mimetype

string File::mimetype ( string $filename );

Return the mimetype for a given filename.

Only uses the extension - doesn't actually check the file
If you need deep checking, take a look at File::checkFileContentsExtension
If the extension is unrecognised, returns 'application/octet-stream'.

public mimetypeExtended

null|string File::mimetypeExtended ( string $path );

Get the content-type of a file using magic mime.

This is _NOT_ limited to the whitelist of mime types described in the
Constants. Use this with care.

Note mime_content_type() inspects file contents and can't always
determine css/js files correctly, this is a hack fix for that.

https://stackoverflow.com/a/17736797/7694753

public moveUpload

bool File::moveUpload ( string $src , string $filename );

Moves an uploaded file into the repository.
Returns TRUE on success, FALSE on failure.

public mtime

int File::mtime ( string $filename );

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

public parseSizeString

array File::parseSizeString ( Size $str );

Parse the size string used in file/resize and some helpers.

Syntax: [crm]{number}x{number}(-[lcr][tcb])(~{number})
        Type  Width    Height    Crop X Y     Quality

Returns an array.
  [0] type, either 'r', 'c' or 'm'
      r = resize, up or down, try to fill the area requested
      c = crop, resulting file will always be the width and height requested
      m = resize down only
  [1] width
  [2] height
  [3] x position, 'left', 'center' or 'right'
  [4] y position, 'top', 'center' or 'bottom'
  [5] jpeg quality, 0 = worst, 100 = best

Returns an empty array on error (so you can use list() safely)

public postUploadProcessing

void File::postUploadProcessing ( string $filename , int $file_id , int $file_type );

Do post-processing after a file upload

public putExisting

bool File::putExisting ( string $filename , string $existing );

Saves file content from an existing file

public putStream

bool File::putStream ( string $filename , resource $stream );

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

public putString

bool File::putString ( string $filename , string $content );

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

public readfile

unknown File::readfile ( string $filename );

This is the equivalent of the php readfile function

public relUrl

string File::relUrl ( string $filename );

Returns the relative public URL for a given file.
Doesn't contain ROOT/ or domain. Use for content areas.

public replaceSet

array File::replaceSet ( string $session_key , string $field_name , array $exts , string $prefix );

Replaces a set of files to be stored in a single field; this acts as a backend for Fb::chunkedUpload

Files are saved as '{prefix}{num}.{ext}', with 'num' starting at 1

public resizeUrl

string File::resizeUrl ( int $id , string $size );

Returns the relative URL for a dynamically resized image.

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

public size

int File::size ( string $filename );

Returns the size, in bytes, of the specified file

public sizeUrl

string File::sizeUrl ( int $id , string $size_name [, string $force_ext [, bool $create_if_missing ]] );

Gets the relative URL for a fixed or dynamically resized image

public touch

bool File::touch ( mixed $filename );

Sets access and modification time of file

public url

string File::url ( string $filename );

Returns the public URL for a given file. Does not include domain.

SproutCMS

Search documentation