File operations such as creating, moving or deleting content-associated files and directories are handled by the \Tfish\FileHandler class (TfFileHandler in Tuskfish v1). For security reasons the file handler methods do not give a free rein. Sensitive operations are generally restricted to the uploads directory (AKA "data_file" path) and the class won't let you work outside of that. appendToFile() (appendFile() in Tuskfish v1) is the exception, it does not have a path restriction. Therefore it must be used carefully.

Directory restrictions are tested internally by the private _dataFilePath() method. This takes the relative file path supplied as a parameter in public methods, prepends the data_file path to it and then checks that the realpath() matches expectations. If a directory traversal is detected, or the path proves to lie outside the uploads directory, then the operation will be cancelled and an error thrown.

In other cases where specific file operations are required other methods exist in other classes (for example \Tfish\Cache->flush()), but again these are generally locked to specific directories. If you have need for additional file manipulation methods you will need to write them, but I encourage you to lock them down to the minimum scope required.

Uploading a file

Call uploadFile( string $filename, string $fieldname ) providing the name of a file that has been uploaded via a form to the $_FILES directory, and the content object property it should be associated with (either 'image' or 'media'), which is the subdirectory that it will be moved to. Returns the filename on success and false on failure.

Appending to a file

Call appendToFile( string $path, string $contents). Do not set the $path using untrusted data sources such as user input.

Downloading a file

Media attachments (file downloads associated with content objects) are served by yoursite.com/enclosure (in Tuskfish v1, enclosure.php), which basically streams the file as a forced download. Call streamFileToBrowser( int $id, string filename = '' ), passing the ID of the content object the file is associated with and the filename, if you would like to rename it.

As the streaming is accomplished via headers you cannot output anything ahead of it, otherwise you will get a "headers already sent" error.

Deleting a file

Call deleteFile( string $path ) to remove an individual file in the uploads directory. The $path should be specified relative to the uploads directory.

Clearing a directory

Call clearDirectory( string $path ) to delete the contents of a specific directory within the uploads directory. The path should be specified relative to the uploads directory, and will not function outside of it. This method is not recursive, so you need to call it on each subdirectory you want to clear.

Deleting a directory

Call deleteDirectory( string $path ) to remove a directory within the uploads directory. It will not operate outside of uploads. This method is recursive and will destroy subdirectories.

File type restrictions on uploads

The types of files that can be uploaded via the image and media properties are restricted (whitelisted) by \Tfish\Traits\Mimetypes, which provides a general method for returning all mimetypes permitted in Tuskfish listMimetypes() and more restrictive methods, listAudioMimetypes(), listImageMimetypes() and listVideoMimetypes(). Currently the lists cover common document formats, image, audio and video formats favoured by the web, plus archives.

You can easily add additional mimetypes by editing the above whitelists, and a similar list found in vendor/tuskfish/contentForm.js, which is used to validate the data entry/edit forms. For dangerous types (executables and code), it is best that they be packed in an archive, rather than be added to the whitelist.

Note that Tuskfish will not force you to upload a media file. You can publish audio or video content, for example, without including an audio or video media file - you may have a valid reason for doing that, such as pre-publishing a story that you will update with the file later.

Tuskfish will display a warning if you attach the wrong type of media file (eg. a video file to an audio object) or change the content type to something that is incompatible with an existing media file. The file will not be deleted, in case you made a mistake. However, it will not be displayed on the public side of your site - you will need to change the content type to match the media type, or vice versa.