Inheritance diagram for BxDolStorage:

Public Member Functions
	genToken ($iFileId)

	changeStorageEngine ($sEngine)

	isAvailable ()

	isInstalled ()

	getErrorCode ()

	getErrorString ()

	getMaxUploadFileSize ($iProfileId)

	storeFile ($sMethod, $aMethodParams, $sName=false, $isPrivate=true, $iProfileId=0, $iContentId=0)

	convertMultipleFilesArray ($aFiles)

	storeFileFromForm ($aFile, $isPrivate=true, $iProfileId=0, $iContentId=0)

	storeFileFromXhr ($sName, $isPrivate=true, $iProfileId=0, $iContentId=0)

	storeFileFromPath ($sPath, $isPrivate=true, $iProfileId=0, $iContentId=0)

	storeFileFromUrl ($sUrl, $isPrivate=true, $iProfileId=0, $iContentId=0)

	storeFileFromStorage ($aParams, $isPrivate=true, $iProfileId=0, $iContentId=0)

	deleteFile ($iFileId, $iProfileId=0)

	queueFilesForDeletion ($mixedFileId)

	queueFilesForDeletionFromGhosts ($iProfileId, $iContentId=false)

	queueFilesForDeletionFromObject ()

	download ($aFile, $sToken=false, $bForceDownloadDialog='auto')

	setFilePrivate ($iFileId, $isPrivate=true)

	getFileUrlByRemoteId ($sRemoteId)

	getFileUrlById ($iFileId)

	getFile ($iFileId)

	getGhost ($iFileId)

	isFilePrivate ($iFileId)

	afterUploadCleanup ($mixedFileIds, $iProfileId, $iContentId=false)

	getGhosts ($iProfileId, $iContentId=false, $isCheckAllAccountProfiles=false, $isAdmin=false)

	reorderGhosts ($iProfileId, $iContentId, $aGhosts)

	updateGhostsContentId ($mixedFileIds, $iProfileId, $iContentId, $isAdmin=false)

	getFiles ($iProfileId)

	getFilesAll ($iStart=0, $iPerPage=1000)

	getRestrictionsTextExtensions ($iProfileId)

	getAllowedExtensions ()

	getRestrictionsTextFileSize ($iProfileId)

	getRestrictionsTextArray ($iProfileId)

	reloadMimeTypesFromFile ($sFile)

	getFileExt ($sFileName)

	getFileTitle ($sFileName)

	getMimeTypeByFileName ($sFileName)

	getIconNameByFileName ($sFileName)

	getFontIconNameByFileName ($sFileName)

Static Public Member Functions
static	getObjectInstance ($sObject)

static	pruning ()

static	pruneDeletions ()

static	isQueuedFilesForDeletion ($sPrefix)

Protected Member Functions
	__construct ($aObject)

Detailed Description

See also

BxDolStorage::pruneDeletions This class unify storage. As the result there are many advantages:

files can be stored as on localhost as on remote storage, for example Amazon s3
all files are in one place and separated from other files, so the data can be organised more easily, for example moved to dedicated disk if there is not enough storage
simplicity of usage, there are hight level classes to handle all necessary operations, including upload and security
quotas settings, so you always control how much space you are going to use
persistent storage; uploaded, but not saved files appear upon page reload or future submission of the same form

Usage.

Step 1: Add record to 'sys_objects_storage' table, like you doing this for Comments or Voting objects:

object - your storage object name, usually it is in the following format - vendor prefix, underscore, module prefix; for example for BoonEx Forum module it can be bx_forum.
engine - storage engine, for now the following engines are supported:
1. Local - local storage, by default files are stored in /storage/ subfolder
2. S3 - Amazon S3 storage, files are stored on Amazon S3 storage, you need to point AWS Access Key, AWS Secret Key and AWS Bucket in the settings
params - custom storage engine params as php serialized string, supported params:
1. fields - list of additional fields to add to database as key(field name) and value(func or serialized service call to get the value)
token_life - life of the security token in seconds for private files
cache_control - control browser cache, allow browser to store files in browser's cache for this number of seconds, to disable browser cache, or let browser to decide on its own set it to 0(zero)
levels - store files in subfolders, generated from filename; it is useful when there is limit of number of files/folders per directory; for example if level is 2 and file name is abc.jpg then the file will be stored in a/b/abc.jpg folder, set to to 0(zero) to disable this feature
table_files - table where file info is stored, please refer to step 2 for more details
ext_mode - file extensions restriction mode:
1. allow-deny - allow only file types in ext_allow field and deny all other file types, ext_deny field is ignored.
2. deny-allow - allow all files except the ones specified in ext_deny field, ext_allow field is ignored.
ext_allow - allowed file extensions, comma separated, it is in effect when ext_mode is allow-deny; example - jpg,gif,png
ext_deny - denied file extensions, comma separated, it is in effect when ext_mode is deny-allow; example - exe,com,bat
quota_size - storage engine quota in bytes, the summary of all uploaded files can not be bigger than this number
current_size - current storage engine usage, the sum of all uploaded file sizes
quota_number - max number of files allowed in this storage engine
current_number - current number of files in this storage engine
max_file_size - max file size for this storage engine, please note that other server settings are used if they are less than this setting option
ts - unix timestamp of the last file upload

Step 2: Create table for files.

CREATE TABLE `my_sample_files` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `profile_id` int(10) unsigned NOT NULL,
  `remote_id` varchar(255) NOT NULL,
  `path` varchar(255) NOT NULL,
  `file_name` varchar(255) NOT NULL,
  `mime_type` varchar(128) NOT NULL,
  `ext` varchar(32) NOT NULL,
  `size` int(11) NOT NULL,
  `added` int(11) NOT NULL,
  `modified` int(11) NOT NULL,
  `private` int(11) NOT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `remote_id` (`remote_id`)
);

You need to enter this table name in 'table_files' field in 'sys_objects_storage' table, mentioned in step 1. The files will be added to this table automatically, all you need is to save 'id' from this table, so you can refer to the file by the 'id'. It is not recommended to change this table, it is better to create another table which will be connected with this one by file 'id'.

Step 3: Handling upload.

Sample HTML form:

<form enctype="multipart/form-data" method="POST" action="store_file.php">
    Choose a file to upload:
    <input name="file" type="file" />
    <br />
    <input type="submit" name="add" value="Upload File" />
</form>

Add server code in sample store_file.php file:

require_once('./inc/header.inc.php');
require_once(BX_DIRECTORY_PATH_INC . "design.inc.php");
BxDolStorage::pruning(); // pruning is needed to clear expired security tokens, you can call it on cron when your server is not busy
$oStorage = BxDolStorage::getObjectInstance('my_module'); // create storage object instance, 'my_module' is value of 'object' field in 'sys_objects_storage' table
if (isset($_POST['add'])) { // if form is submitted
        $iId = $oStorage->storeFileFromForm($_FILES['file'], true, 0); // store file from submitted HTML form, 'file' is input name with field, true means store file as private, 0 is profile id
        if ($iId) { // storeFileFromForm returns file id, not false value means operation is successful.
            // save $iId somewhere, so you can refer to the file after
            $iCount = $oStorage->afterUploadCleanup($iId, $iProfileId); // since we saved $iId, we remove it from the orphans list, so it will not appear on the form next time (persistent storage)
            echo "uploaded file id: " . $iId . "(deleted orphans:" . $iCount . ")";
        } else {
            // something went wrong - print the error
            echo "error uploading file: " . $oStorage->getErrorString()
        }
}

Please refer to the functions definition for more additional description of functions params.

Step 4: Displaying the file.

Use the following code to retrieve saved file. Remember you saved filed id somewhere in the previous step. Lets assume that the uploaded file is image, then we can show it using the following code:

require_once('./inc/header.inc.php');
require_once(BX_DIRECTORY_PATH_INC . "design.inc.php");
$oStorage = BxDolStorage::getObjectInstance('my_module');
$iId = 1234; // since you've saved it somewhere in the previous step, you can retrieve it here
echo "Uploaded image: <img src="' . $oStorage->getFileUrlById($iId) . '" />;";

It will show the file, regardless if it is private or public. You need to control it by yourself who will view the file. The difference in viewing private files is that link to the file is expiring after N seconds, you control this period using 'token_life' field in 'sys_objects_storage' table.

Constructor & Destructor Documentation

◆ __construct()

BxDolStorage::__construct ( $aObject )

protected

constructor

Member Function Documentation

◆ afterUploadCleanup()

BxDolStorage::afterUploadCleanup	(	$mixedFileIds,
		$iProfileId,
		$iContentId = `false`
	)

Call this function after saving/associate just uploaded file id, so file is not orphaned/ghost. Ghost files appear on download form automaticaly during next upload, for example if file was uploaded but was not submitted for some reason. This mechanism ensure that the file is not lost.

Parameters

$mixedFileIds	array of file ids or just one file id
$iProfileId	profile id
return	number of deleted ghost files

◆ changeStorageEngine()

BxDolStorage::changeStorageEngine ( $sEngine )

Change storage engine. It's possible to change it when there is no files in storage engine.

Parameters

$sEngine new storage engine

Returns: true on success or false on error

◆ convertMultipleFilesArray()

BxDolStorage::convertMultipleFilesArray ( $aFiles )

convert default multiple files array into more logical one

◆ deleteFile()

BxDolStorage::deleteFile	(	$iFileId,
		$iProfileId = `0`
	)

Delete file by file id.

◆ download()

BxDolStorage::download	(	$aFile,
		$sToken = `false`,
		$bForceDownloadDialog = `'auto'`
	)

Download file.

Parameters

array	$aFile	downloading file info.
boolean	$bForceDownloadDialog	if downloading to a local file system first is required and/or send the outout as attachment rather than inline.

◆ genToken()

BxDolStorage::genToken ( $iFileId )

Get file token for private files.

Parameters

$iFileId file

Returns: file token string

◆ getAllowedExtensions()

BxDolStorage::getAllowedExtensions ( )

Returns: list of allowed extensions, if ext_mode = 'allow-deny', returns false otherwise.

◆ getErrorCode()

BxDolStorage::getErrorCode ( )

Get error code from the last occured error

Returns: error code

◆ getErrorString()

BxDolStorage::getErrorString ( )

Get error string from the last occured error

Returns: error string

◆ getFile()

BxDolStorage::getFile ( $iFileId )

Get file info array by file id.

Parameters

$iFileId file id

Returns: array

◆ getFileExt()

BxDolStorage::getFileExt ( $sFileName )

Get file extension by file name.

Parameters

$sFileName file name

Returns: file extention string

◆ getFiles()

BxDolStorage::getFiles ( $iProfileId )

Get files list for particular user.

Parameters

$iProfileId profile id

Returns: array of arrays

◆ getFilesAll()

BxDolStorage::getFilesAll	(	$iStart = `0`,
		$iPerPage = `1000`
	)

Get all files in the storage

◆ getFileTitle()

BxDolStorage::getFileTitle ( $sFileName )

Get file title by file name, actually file title is file name without extension.

Parameters

$sFileName file name

Returns: file title string

◆ getFileUrlById()

BxDolStorage::getFileUrlById ( $iFileId )

Get file url.

Parameters

$iFileId file id

Returns: file url or false on error

◆ getFileUrlByRemoteId()

BxDolStorage::getFileUrlByRemoteId ( $sRemoteId )

Get file url.

Parameters

$sRemoteId file remote id

Returns: file url or false on error

◆ getFontIconNameByFileName()

BxDolStorage::getFontIconNameByFileName ( $sFileName )

Get file font icon by file name. Actually just a class name of icon is returnted.

Parameters

$sFileName file name

Returns: file icon string

◆ getGhost()

BxDolStorage::getGhost ( $iFileId )

Get ghost file info array by file id.

Parameters

$iFileId file id

Returns: array

◆ getGhosts()

BxDolStorage::getGhosts	(	$iProfileId,
		$iContentId = `false`,
		$isCheckAllAccountProfiles = `false`,
		$isAdmin = `false`
	)

Get ghost/orphaned files for particular user.

Parameters

$iProfileId	profile id
$iContentId	content id, or false to not consider content id at all
$isCheckAllAccountProfiles	get all files associated with all account profiles
$isAdmin	if true, then don't check files ownership, it makes sense when $iContentId is provided, so it will return all files assiciated with content

Returns: array of arrays

◆ getIconNameByFileName()

BxDolStorage::getIconNameByFileName ( $sFileName )

Get file icon by file name. File icon is just icon filename without patch or URL. File icons must be located in images/icons directory in your template subfolder.

Parameters

$sFileName file name

Returns: file icon string

◆ getMaxUploadFileSize()

BxDolStorage::getMaxUploadFileSize ( $iProfileId )

Get max file size allowed for current user, it checks user quota, object quota, site quota and php setting

Parameters

$iProfileId profile id to check quota for

Returns: quota size in bytes

◆ getMimeTypeByFileName()

BxDolStorage::getMimeTypeByFileName ( $sFileName )

Get file mime/type by file name.

Parameters

$sFileName file name

Returns: file mime type string

◆ getObjectInstance()

static BxDolStorage::getObjectInstance ( $sObject )

static

Get storage object instance by object name

Parameters

$sObject object name

Returns: object instance or false on error

Implements iBxDolFactoryObject.

◆ getRestrictionsTextArray()

BxDolStorage::getRestrictionsTextArray ( $iProfileId )

Get readable representation of all restrictions.

Parameters

$iProfileId profile id

Returns: array of strings

◆ getRestrictionsTextExtensions()

BxDolStorage::getRestrictionsTextExtensions ( $iProfileId )

Get readable representation of restrictions by file extentions.

Parameters

$iProfileId profile id

Returns: string

◆ getRestrictionsTextFileSize()

BxDolStorage::getRestrictionsTextFileSize ( $iProfileId )

Get readable representation of restrictions by file size.

Parameters

$iProfileId profile id

Returns: string

◆ isAvailable()

BxDolStorage::isAvailable ( )

Is storage engine available?

Returns: boolean

◆ isFilePrivate()

BxDolStorage::isFilePrivate ( $iFileId )

check if file is private or public

Parameters

$iFileId file id

Returns: boolean

◆ isInstalled()

BxDolStorage::isInstalled ( )

Are required php modules installed for this storage engine ?

Returns: boolean

◆ isQueuedFilesForDeletion()

static BxDolStorage::isQueuedFilesForDeletion ( $sPrefix )

static

Check if module has any files pending for deletion, it is supposed that all module storage object names are prefixed with module name

Parameters

$sPrefix - usually module name

Returns: number of files pending for deletion which were found by prefix

◆ pruneDeletions()

static BxDolStorage::pruneDeletions ( )

static

Delete files queued for deletions It is alutomatically called upin cron execution, usually one time per minute. Max number of deletetion per time is defined in

See also: BX_DOL_STORAGE_QUEUED_DELETIONS_PER_RUN

Returns: number of deleted records

◆ pruning()

static BxDolStorage::pruning ( )

static

Delete old security tokens from database. It is alutomatically called upin cron execution, usually once in a day.

Returns: number of deleted records

◆ queueFilesForDeletion()

BxDolStorage::queueFilesForDeletion ( $mixedFileId )

Queue file(s) for deletion. File(s) will be deleted later upon cron call (usually every minute).

Parameters

$mixedFileId file id or array of file ids.

Returns: number of queued files

◆ queueFilesForDeletionFromGhosts()

BxDolStorage::queueFilesForDeletionFromGhosts	(	$iProfileId,
		$iContentId = `false`
	)

Queue file(s) for deletion by getting neccesary files from ghosts table by profile id and content id

Parameters

$iProfileId	profile id associated with files
$iContentId	content id associated with files, or false if to check by profile id only

Returns: number of queued files

◆ queueFilesForDeletionFromObject()

BxDolStorage::queueFilesForDeletionFromObject ( )

Queue file(s) for deletion of the whole storage object

Returns: number of queued files

◆ reloadMimeTypesFromFile()

BxDolStorage::reloadMimeTypesFromFile ( $sFile )

Reread available mimetypes from particular file. It clears 'sys_storage_mime_types' table and fill it with data form provided file. The format of file is: mime/type space_or_tab extentions_sperated_by_space. Usually the file is mime.types file from apache or /etc/mime.types from unix systems.

Parameters

$sFile file to read mime types from

Returns: false if file was not found or can not be read, string with result on other case - it can contains file markup errors or localized "Success" string if everything went fine.

◆ reorderGhosts()

BxDolStorage::reorderGhosts	(	$iProfileId,
		$iContentId,
		$aGhosts
	)

Reorder ghost/orphaned files for particular content/user.

Parameters

$iProfileId	profile id
$iContentId	content id, or false to not consider content id at all
$aGhosts	an ordered list of ghost/orphaned files' IDs.

Returns: boolean result of operation

◆ setFilePrivate()

BxDolStorage::setFilePrivate	(	$iFileId,
		$isPrivate = `true`
	)

Set file private or public.

◆ storeFile()

BxDolStorage::storeFile	(	$sMethod,
		$aMethodParams,
		$sName = `false`,
		$isPrivate = `true`,
		$iProfileId = `0`,
		$iContentId = `0`
	)

Store file in the storage area. It is not recommended to use this function directly, use other funtions like: storeFileFromForm, storeFileFromXhr, storeFileFromPath, storeFileFromUrl

Parameters

$sMethod	upload method, like regular Form upload, upload from URL, etc
$aMethodParams	upload method params
$sName	file name with extention
$isPrivate	private or public file
$iProfileId	profile id of the upload action performer
$iContentId	content id to associate with ghost file

Returns: id of added file on success, false on error - to get exact error string call getErrorString()

◆ storeFileFromForm()

BxDolStorage::storeFileFromForm	(	$aFile,
		$isPrivate = `true`,
		$iProfileId = `0`,
		$iContentId = `0`
	)

the same as storeFile, but it tries to do it directly from uploaded file

◆ storeFileFromPath()

BxDolStorage::storeFileFromPath	(	$sPath,
		$isPrivate = `true`,
		$iProfileId = `0`,
		$iContentId = `0`
	)

the same as storeFile, but it tries to do it directly from local file

◆ storeFileFromStorage()

BxDolStorage::storeFileFromStorage	(	$aParams,
		$isPrivate = `true`,
		$iProfileId = `0`,
		$iContentId = `0`
	)

the same as storeFile, but it tries to do it directly from the same or another storage by file id

Parameters

$aParams['id']	- file ID in the storage
$aParams['storage']	- the storage name

◆ storeFileFromUrl()

BxDolStorage::storeFileFromUrl	(	$sUrl,
		$isPrivate = `true`,
		$iProfileId = `0`,
		$iContentId = `0`
	)

the same as storeFileFromPath, but it tries to do it from URL

◆ storeFileFromXhr()

BxDolStorage::storeFileFromXhr	(	$sName,
		$isPrivate = `true`,
		$iProfileId = `0`,
		$iContentId = `0`
	)

the same as storeFile, but it tries to do it directly from HTML5 file upload method

◆ updateGhostsContentId()

BxDolStorage::updateGhostsContentId	(	$mixedFileIds,
		$iProfileId,
		$iContentId,
		$isAdmin = `false`
	)

Update ghosts' content id.

Parameters

$mixedFileIds	array of file ids or just one file id
$iProfileId	profile id
$iContentId	content id
$isAdmin	if true, then don't check files ownership

Returns: true on success or false otherwise

The documentation for this class was generated from the following file:

inc/classes/BxDolStorage.php

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ afterUploadCleanup()

◆ changeStorageEngine()

◆ convertMultipleFilesArray()

◆ deleteFile()

◆ download()

◆ genToken()

◆ getAllowedExtensions()

◆ getErrorCode()

◆ getErrorString()

◆ getFile()

◆ getFileExt()

◆ getFiles()

◆ getFilesAll()

◆ getFileTitle()

◆ getFileUrlById()

◆ getFileUrlByRemoteId()

◆ getFontIconNameByFileName()

◆ getGhost()

◆ getGhosts()

◆ getIconNameByFileName()

◆ getMaxUploadFileSize()

◆ getMimeTypeByFileName()

◆ getObjectInstance()

◆ getRestrictionsTextArray()

◆ getRestrictionsTextExtensions()

◆ getRestrictionsTextFileSize()

◆ isAvailable()

◆ isFilePrivate()

◆ isInstalled()

◆ isQueuedFilesForDeletion()

◆ pruneDeletions()

◆ pruning()

◆ queueFilesForDeletion()

◆ queueFilesForDeletionFromGhosts()

◆ queueFilesForDeletionFromObject()

◆ reloadMimeTypesFromFile()

◆ reorderGhosts()

◆ setFilePrivate()

◆ storeFile()

◆ storeFileFromForm()

◆ storeFileFromPath()

◆ storeFileFromStorage()

◆ storeFileFromUrl()

◆ storeFileFromXhr()

◆ updateGhostsContentId()