No Matches
BxDolStorage Class Reference
Inheritance diagram for BxDolStorage:
BxDolFactory iBxDolFactoryObject BxDolStorageLocal BxDolStorageS3 BxDolStorageS3v4 BxDolStorageS3v4alt

Public Member Functions

 genToken ($iFileId)
 changeStorageEngine ($sEngine)
 isAvailable ()
 isInstalled ()
 getObject ()
 getObjectData ()
 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)
 insertGhost ($iFileId, $iProfileId, $iContentId=0)
 onBeforeFileDelete ($aFileInfo, $iProfileId)
 onFileDeleted ($aFileInfo, $iProfileId, $aGhost=false)
 queueFiles ($aFiles)

Static Public Member Functions

static getObjectInstance ($sObject)
static pruning ()
static pruneDeletions ()
static isQueuedFilesForDeletion ($sPrefix)

Protected Member Functions

 __construct ($aObject)
 determineIcon ($aIcons, $sExt, $sMimeType)
 onBeforeFileAdd ($aFileInfo)
 onFileAdded ($aFileInfo)
 setErrorCode ($i)
 genRandName ($isCheckForUniq=true)
 genPath ($s, $iLevels)
 genRemoteNamePath ($sPath, $sLocalId, $sExt)
 isValidExt ($sExt)
 isAllowedExt ($sExt)
 isDeniedExt ($sExt)
 isAllowedDeniedExt ($sExt, $sExtMode)
 getFileDuration ($sFilePath, $sMimeType, $sExt, $oStorage)
 getFileDimensions ($sFilePath, $sMimeType, $sExt, $oStorage)

Protected Attributes

 $_aMimeTypesViewable = ['audio/', 'image/', 'video/']

Detailed Description

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


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` (
`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,
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" />

Add server code in sample store_file.php file:

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()
static pruning()
Definition BxDolStorage.php:250
static getObjectInstance($sObject)
Definition BxDolStorage.php:216

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(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)


Reimplemented in BxDolStorageLocal, and BxDolStorageS3.

Member Function Documentation

◆ afterUploadCleanup()

BxDolStorage::afterUploadCleanup ( $mixedFileIds,
$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.

$mixedFileIdsarray of file ids or just one file id
$iProfileIdprofile id
returnnumber 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.

$sEnginenew storage engine
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.

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

Reimplemented in BxDolStorageLocal, and BxDolStorageS3.

◆ genToken()

BxDolStorage::genToken ( $iFileId)

Get file token for private files.

file token string

◆ getAllowedExtensions()

BxDolStorage::getAllowedExtensions ( )
list of allowed extensions, if ext_mode = 'allow-deny', returns false otherwise.

◆ getErrorCode()

BxDolStorage::getErrorCode ( )

Get error code from the last occured error

error code

◆ getErrorString()

BxDolStorage::getErrorString ( )

Get error string from the last occured error

error string

◆ getFile()

BxDolStorage::getFile ( $iFileId)

Get file info array by file id.

$iFileIdfile id

◆ getFileExt()

BxDolStorage::getFileExt ( $sFileName)

Get file extension by file name.

$sFileNamefile name
file extention string

◆ getFiles()

BxDolStorage::getFiles ( $iProfileId)

Get files list for particular user.

$iProfileIdprofile id
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.

$sFileNamefile name
file title string

◆ getFileUrlById()

BxDolStorage::getFileUrlById ( $iFileId)

Get file url.

$iFileIdfile id
file url or false on error

Reimplemented in BxDolStorageLocal, BxDolStorageS3, and BxDolStorageS3v4alt.

◆ getFileUrlByRemoteId()

BxDolStorage::getFileUrlByRemoteId ( $sRemoteId)

Get file url.

$sRemoteIdfile remote id
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.

$sFileNamefile name
file icon string

◆ getGhost()

BxDolStorage::getGhost ( $iFileId)

Get ghost file info array by file id.

$iFileIdfile id

◆ getGhosts()

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

Get ghost/orphaned files for particular user.

$iProfileIdprofile id
$iContentIdcontent id, or false to not consider content id at all
$isCheckAllAccountProfilesget all files associated with all account profiles
$isAdminif true, then don't check files ownership, it makes sense when $iContentId is provided, so it will return all files assiciated with content
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.

$sFileNamefile name
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

$iProfileIdprofile id to check quota for
quota size in bytes

◆ getMimeTypeByFileName()

BxDolStorage::getMimeTypeByFileName ( $sFileName)

Get file mime/type by file name.

$sFileNamefile name
file mime type string

◆ getObjectInstance()

static BxDolStorage::getObjectInstance ( $sObject)

Get storage object instance by object name

$sObjectobject name
object instance or false on error

Implements iBxDolFactoryObject.

◆ getRestrictionsTextArray()

BxDolStorage::getRestrictionsTextArray ( $iProfileId)

Get readable representation of all restrictions.

$iProfileIdprofile id
array of strings

◆ getRestrictionsTextExtensions()

BxDolStorage::getRestrictionsTextExtensions ( $iProfileId)

Get readable representation of restrictions by file extentions.

$iProfileIdprofile id

◆ getRestrictionsTextFileSize()

BxDolStorage::getRestrictionsTextFileSize ( $iProfileId)

Get readable representation of restrictions by file size.

$iProfileIdprofile id

◆ isAvailable()

BxDolStorage::isAvailable ( )

Is storage engine available?


◆ isFilePrivate()

BxDolStorage::isFilePrivate ( $iFileId)

check if file is private or public

$iFileIdfile id

◆ isInstalled()

BxDolStorage::isInstalled ( )

Are required php modules installed for this storage engine ?


◆ isQueuedFilesForDeletion()

static BxDolStorage::isQueuedFilesForDeletion ( $sPrefix)

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

$sPrefix- usually module name
number of files pending for deletion which were found by prefix

◆ pruneDeletions()

static BxDolStorage::pruneDeletions ( )

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
number of deleted records

◆ pruning()

static BxDolStorage::pruning ( )

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

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).

$mixedFileIdfile id or array of file ids.
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

$iProfileIdprofile id associated with files
$iContentIdcontent id associated with files, or false if to check by profile id only
number of queued files

◆ queueFilesForDeletionFromObject()

BxDolStorage::queueFilesForDeletionFromObject ( )

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

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.

$sFilefile to read mime types from
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,
$aGhosts )

Reorder ghost/orphaned files for particular content/user.

$iProfileIdprofile id
$iContentIdcontent id, or false to not consider content id at all
$aGhostsan ordered list of ghost/orphaned files' IDs.
boolean result of operation

◆ setFilePrivate()

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

Set file private or public.

Reimplemented in BxDolStorageS3, and BxDolStorageS3v4alt.

◆ storeFile()

BxDolStorage::storeFile ( $sMethod,
$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

$sMethodupload method, like regular Form upload, upload from URL, etc
$aMethodParamsupload method params
$sNamefile name with extention
$isPrivateprivate or public file
$iProfileIdprofile id of the upload action performer
$iContentIdcontent id to associate with ghost file
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

$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,
$isAdmin = false )

Update ghosts' content id.

$mixedFileIdsarray of file ids or just one file id
$iProfileIdprofile id
$iContentIdcontent id
$isAdminif true, then don't check files ownership
true on success or false otherwise

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