About twzFileStore v1.0.2

twzFileStore is a very simple web-based "file manager"-like application, restricted to a single directory (and any subdirectories) on your web server. It requires PHP5 or later.

Using twzFileStore you can upload and download files, delete files, add and remove sub-folders, search for files by filename and browse files in sub-folders. Any of these features can be disabled if required, potentially on a per-user basis.

Using twzFileStore you can NOT view file contents online, edit, rename, move or compress files, or rename folders.

Quick start

You don't need much to get started:

download twzFileStore from http://tweezy.net.au/twzFileStore.html
edit example.php to specify your store location folder
upload the required files: example.php, twzFileStore.class.php, twzFileStore.css, template.html
ensure the store location folder exists on your server
point your browser at example.php

Quick start
Class methods
Options
Examples

Class methods

__construct ( $Title, $StorePath, $TemplateFile='', $LogFile=false, $LogLevel=3 )

When the twzFileStore class is instantiated, you must supply a page title and the path to an existing, writable directory. The other parameters are optional.

$Title

title for html page generated

$StorePath

path to top level of file store. This directory can be anywhere on the server; it does not need to be web accessible.

$TemplateFile

name or pathname of the page template file. If empty or not specified, 'template.html' is assumed. The template should include placeholders: ##_PAGE_TITLE_## and ##_CONTENT_##

$LogFile

see 'LogFile' option below

$LogLevel

see 'LogLevel' option below

setOption ( $OptionName, $Value )

Use setOption() to set one of the FileStore options. For a list of possible options, see the Options section.

$OptionName

One of the option names listed in Options; case insensitive

$Value

Value of the specified option

Example usage:

$fs->setOption('TopName', 'TOP_LEVEL');
$fs->setOption('AllowSearch', true);

setOptions ( $OptionsArray )

setOptions() allows you to set multiple options in one call, rather than calling setOption() separately for each option.

$OptionsArray

an associative array of options to set.

Example usage:

$Options = array(
    'ShowFilesize'   => false,
    'ShowSubFolders' => true,
    'FileExtensions' => 'doc,xls,txt,pdf,jpg,png',
    'AllowSearch'    => true,
    'AllowAddFolder' => true
    );

$fs->setOptions($Options);

show ( $Echo=true )

show() is the most important method - it show the list of files in the store, and handles all the user actions according to the options you have set.

$Echo

if false, the html output will be returned as a string, not echoed to the browser

getLog ( )

This method is used by the developer for debugging purposes. twzFileStore generates various messages as it performs tasks; getLog() gives you a way to retrieve the list of messages as an array.

$LogInfo = $fs->getLog();
    
if($LogInfo)
    {
    echo '<ul>';
    foreach($LogInfo as $ThisInfo) { echo '<li>'.$ThisInfo.'</li>'; }
    echo '</ul>';
    }

The LogFile option (see below) is generally more useful than using getLog(). In particular, a record of file downloads can be made in the LogFile, but will not be available from getLog().

Quick start
Class methods
Options
Examples

Options

The various twzFileStore options determine what actions the user is permitted to perform, and generally how the application behaves. Options can be set individually with setOption(), or multiple options can be set at once with setOptions(). Each valid option is explained below. Option names are not case sensitive.

User permissions

AllowAddFolder (bool): whether users are allowed to create and remove sub-folders (default is false)
AllowDelete (bool): whether users are allowed to delete files (default is true)
AllowDownload (bool): whether users are allowed to download files (default is true)
AllowSearch (bool): Whether users are allowed to search for files by name (default is false); If files are in multiple folders, the search is always fully recursive. The user can choose whether to search from the top level down, or from the current SubFolder down.
AllowUpload (bool): whether users are allowed to upload/add new files (default is true)

Display options

ShowFileSize (bool)

specifies whether the size of each file is shown in the list of filenames (default is true)

ShowFileTmst (bool|string)

specifies whether each file's last-modified date is shown in the list of filenames. With the default value (false), no date/time will be shown. If true, date/time will be shown similar to '2013-08-21 16:32:17'. If a string, the date/time will be shown according to this as a date format string - see PHP date() function. The default string (when this parameter is true) is 'Y-m-d H:i:s'

ShowFolderTree (bool)

determines how folders are displayed (if ShowSubfolders is true). The default (false) will show only those folders above and below the current sub-folder. If true, all folders and sub-folders will be shown at all times. While the latter is often easier to use, it can become difficult if there are many sub-folders to show.

ShowSubfolders (bool)

whether the user can browse sub-folders (default is false)

TopName (string)

the name shown for the top-level folder (default is 'top')

DisplayOrder (string)

twzFileStore displays several items on each page, depending on the Options currently set. The items are:

files (#files found + file list + total size)
delfiles (button to delete files)
newfile (browse + upload buttons)
newfolder (folder name box + button to create a new folder)
folders (clickable list of folders)
delfolder (button to delete current folder - only appears if folder is empty)

Most of the time the default order works well, but can be changed if you wish. DisplayOrder is a comma-separated list of one or more of the above keywords, indicating the required display order.

Example: $fs->setOption('DisplayOrder', 'folders,newfolder');

Any missing items will be appended in their default order; any unrecognised items will be ignored.

System options

AppendDateTime (bool|string): whether the current date/time should be automatically appended to uploaded files. If true (default), the date/time will be appended in the format _yyyymmdd_hhmm for example the file myWork.doc may be saved as myWork_20130815_0920.doc If false, nothing will be appended to filenames. If a string, the date/time will be appended according to this string as a date format. The default string (when this parameter is true) is '_Ymd_Hi'. For date format characters, see PHP date() function.
ExcludeFolder (string|array): If files are stored in multiple folders, this setting specifies any sub-folders that should NOT be included or searchable. (default is empty)
FileExtensions (string): Restricts the file types to be listed by twzFileStore. If FileExtensions is empty (default), all found files will be listed; otherwise it should be a comma- or pipe-separated list of file extensions.
Example: $fs->setOption('FileExtensions', 'pdf,doc,jpg');; This will cause twzFileStore to only display files whose name ends with .pdf or .doc or .jpg.; If this option is set, users won't be able to search by file extension - only by basename of the file. For example with the above setting, if a user searches for "pdf" they will not find all pdf files (but they might find files named "MyPDF.pdf" or "not-a-pdf-file.doc".). Note that any type of file can be uploaded, but files will not be visible unless their extension is included in the FileExtensions string (or the FileExtensions string is empty).
LogFile (false|string): twzFileStore generates various messages as it performs tasks. You can choose to send some or all of these messages to a log file as a permanent record if required. The default for this option is false, meaning that no log file will be generated. If you set it to a string, this must be a pathname to a writable file.; TIP: If you want a new log file generated each month, you could name the file based on the current year and month,; for example: $fs->setOption('LogFile', '../logs/fileStore_'.date('Y-m').'.log');; In this example, messages generated during November 2013 would be written to a file named fileStore_2013-11.log; You can choose which messages are written to the log file with the LogLevel option (see below).
LogLevel (int): If you have specified a LogFile (see above), the LogLevel will determine which kinds of messages are logged.; There are three possible values for LogLevel: 1 logs error messages, 2 logs warnings and 3 logs user actions. Higher levels include all lower levels, so setting LogLevel to 3 will log all errors, warnings and user actions. (default is 3)
SearchMin (int): The minimum number of characters required for search (default 2). If a user attempts to search for fewer characters, the search will not be performed.
UseJsWarning (bool): If true (default), the user will be asked for confirmation before any files are deleted. If false, the selected files will be deleted without warning.

Quick start
Class methods
Options
Examples

Examples - case studies

Quick backup

twzFileStore was originally written for an author who wanted a quick and easy way to backup their novel in progress, by uploading it to their web server.

Using the default settings, they can upload files to a specific folder (directory) on the server. When each file is uploaded, the current date/time is automatically appended to the filename - this allows them to store multiple versions of the same document. They can also download or delete previously uploaded files.

Once the top directory (_filebackups) is created, this is all the code that's required:

<?php
require 'twzFileStore.class.php';
$fs = new twzFileStore('Backup files', '../../_filebackups/');
$fs->show();
?>

Read only

Our second implementation was quite different - the site already had many files stored in multiple directories and subdirectories. Users are able to find and download files, but not add or delete files, create new folders or browse the folders.

<?php
require 'twzFileStore.class.php';

$Options = array(
    'AppendDateTime' => false, 
    'ShowFileTmst'   => true, 
    'ShowSubFolders' => false,
    'AllowDelete'    => false,
    'AllowUpload'    => false,
    'AllowSearch'    => true,
    'AllowAddFolder' => false,
    'FileExtensions' => 'pdf,swf',
    'ExcludeFolder'  => 'homepage,images,resource,abc/images'
    );

$fs = new twzFileStore('Current PDF/SWF files', 'assets/files/');
$fs->setOptions($Options);
$fs->show();
?>

In the above example we only show files with .pdf or .swf extension, and several specific sub-folders are excluded.

CMS

Although twzFileStore was designed as a standalone application, you can probably get it to work with a Content Management System backend (or front end I guess, if you want). We have successfully used it in a MODx Evolution module.

twzFileStore uses two URL query parameters (dir and dl), but will not interfere with any other parameters if they are present. In the unlikely event that your CMS also uses one of these parameters, you can change the names that twzFileStore uses by changing the DOWNLOAD_PARAM and FOLDER_PARAM constants at the top of the class file.