FileManager Class Reference

Static Public Member Functions
static	cleanFileName ($file_name=null, $shorten_name=false)
static	getIconNameForMimeType ($mime_type=null)
static	getIconForMimeType ( $mime_type=null, $role=Icon::ROLE_CLICKABLE, $attributes=[])
static	getIconForFileRef ($ref, $role=Icon::ROLE_CLICKABLE, array $attributes=[])
static	getDownloadURLForArchivedCourse (ArchivedCourse $archived_course, $protected_archive=false)
static	getDownloadLinkForArchivedCourse (ArchivedCourse $archived_course, $protected_archive=false)
static	getDownloadLinkForTemporaryFile ( $temporary_file_name=null, $download_file_name=null)
static	getDownloadURLForTemporaryFile ( $temporary_file_name=null, $download_file_name=null)
static	checkUploadedFileStatus ($uploaded_file)
static	handleFileUpload (array $uploaded_files, FolderType $folder, $user_id=null)
static	updateFileRef (FileRef $source, User $user, $uploaded_file_data=[], $update_filename=false, $update_other_references=false)
static	editFileRef (FileRef $file_ref, User $user, $name=null, $description=null, $content_terms_of_use_id=null, $url=null)
static	copyFile (FileType $source, FolderType $destination_folder, User $user)
static	moveFile (FileType $source, FolderType $destination_folder, User $user)
static	deleteFileRef (FileRef $file_ref, User $user)
static	createSubFolder (FolderType $destination_folder, User $user, $folder_type_class_name=null, $name=null, $description=null)
static	copyFolder (FolderType $source_folder, FolderType $destination_folder, User $user)
static	moveFolder (FolderType $source_folder, FolderType $destination_folder, User $user)
static	deleteFolder (FolderType $folder, User $user)
static	getFolderTypes ()
static	getAvailableFolderTypes ($range_id_or_object, $user_id)
static	copyFolderContentIntoPath (FolderType $folder, $path=null, $user_id='nobody', $min_perms='nobody', $ignore_perms=false)
static	countFilesInFolder (FolderType $folder, $count_subfolders=true, $owner_id=null, $user_id=null)
static	getFolderFilesRecursive (FolderType $top_folder, $user_id, $check_file_permissions=false)
static	getReadableFolders (FolderType $top_folder, $user_id)
static	getUnreadableFolders (FolderType $top_folder, $user_id)
static	getTypedFolder ($id, $pluginclass=null)
static	fetchURLMetadata ($url, $level=0)
static	getInboxFolder (User $user)
static	getOutboxFolder (User $user)
static	getUploadTypeConfig ($range_id, $user_id=null)
static	loadUploadTypeConfig (string $type, string $status)
static	getFullPath (FolderType $folder, $include_root=true)
static	getFolderURL ($folder)
static	getFolderLink ($folder)
static	fileIsImage (FileType $file)
static	fileIsAudio (FileType $file)
static	fileIsVideo (FileType $file)
static	getRangeIdsForFolders ($user_id=null, $with_personal_file_area=true)
static	getFileIcon ($filename, $role=Icon::ROLE_CLICKABLE)

Detailed Description

The FileManager class contains methods that faciliate the management of files and folders. Furthermore its methods perform necessary additional checks so that files and folders are managed in a correct manner.

It is recommended to use the methods of this class for file and folder management instead of writing own methods.

Member Function Documentation

checkUploadedFileStatus()

static checkUploadedFileStatus (   $uploaded_file )

static

This is a helper method that checks an uploaded file for errors which appeared during upload.

Parameters

array

$uploaded_file

cleanFileName()

static cleanFileName (   $file_name = null,   $shorten_name = false  )

static

Removes special characters from the file name (and by that cleaning the file name) so that the file name which is returned by this method works on every operating system.

Parameters

string	$file_name	The file name that shall be "cleaned".
bool	$shorten_name	True, if the file name shall be shortened to 31 characters. False, if the full length shall be kept (default).

Returns

string The "cleaned" file name.

copyFile()

static copyFile ( FileType  $source, FolderType  $destination_folder, User  $user  )

static

This method handles copying a file to a new folder.

If the user (given by $user) is the owner of the file (by looking at the user_id in the file reference) we can just make a new reference to that file. Else, we must copy the file and its content.

The file name is altered when a file with the identical name exists in the destination folder. In that case, only the name in the FileRef object of the file is altered and the File object's name is unchanged.

Parameters

FileType	$source	The file reference for the file that shall be copied.
FolderType	$destination_folder	The destination folder for the file.
User	$user	The user who wishes to copy the file.

Returns

FileType|string[] The copied FileType object on success or an array with error messages on failure.

copyFolder()

static copyFolder ( FolderType  $source_folder, FolderType  $destination_folder, User  $user  )

static

This method handles copying folders, including copying the subfolders and files recursively.

Parameters

FolderType	$source_folder	The folder that shall be copied.
FolderType	$destination_folder	The destination folder.
User	$user	The user who wishes to copy the folder.

Returns

FolderType|string[] The copy of the source_folder FolderType object on success or an array with error messages on failure.

copyFolderContentIntoPath()

static copyFolderContentIntoPath ( FolderType  $folder,   $path = null,   $user_id = 'nobody',   $min_perms = 'nobody',   $ignore_perms = false  )

static

Copies the content of a folder (files and subfolders) into a given path in the operating system's file system.

Parameters

FolderType	$folder	The folder whose content shall be copied.
string	$path	The path in the operating system's file system where the content shall be copied into.
string	$user_id	The user who wishes to copy the content.
string	$min_perms	If set, the selection of subfolders and files is limited to those which are visible for users having the minimum permissions.
bool	$ignore_perms	If set to true, files are copied without checking the minimum permissions or the permissions of the user given by user_id.

Returns

bool True on success, false on error.

countFilesInFolder()

static countFilesInFolder ( FolderType  $folder,   $count_subfolders = true,   $owner_id = null,   $user_id = null  )

static

Counts the number of files inside a folder and its subfolders. The search result can be limited to the files belonging to one user and/or to the files which are readable for one user.

Parameters

FolderType	$folder	The folder whose files shall be counted.
bool	$count_subfolders	True, if files subfolders shall also be counted, too (default). False otherwise.
string	$owner_id	Optional user-ID to count only files of one user specified by the ID.
string	$user_id	Optional user-ID to count only files the user (specified by this user-ID) can read.

Returns

int The amount of files inside the folder (and its subfolders).

createSubFolder()

static createSubFolder ( FolderType  $destination_folder, User  $user,   $folder_type_class_name = null,   $name = null,   $description = null  )

static

Handles the sub folder creation routine.

Parameters

FolderType	$destination_folder	The folder where the subfolder shall be linked.
User	$user	The user who wishes to create the subfolder.
string	$folder_type_class_name	The FolderType class name for the new folder
string	$name	The name for the new folder
string	$description	The description of the new folder

Returns

FolderType|string[] Either the FolderType object of the new folder or an Array with error messages.

deleteFileRef()

static deleteFileRef ( FileRef  $file_ref, User  $user  )

static

This method handles deletign a file reference.

Parameters

FileRef	$file_ref	The file reference that shall be deleted
User	$user	The user who wishes to delete the file reference.

Returns

FileRef|string[] The FileRef object that was deleted from the database on success or an array with error messages on failure.

deleteFolder()

static deleteFolder ( FolderType  $folder, User  $user  )

static

This method helps with deleting a folder.

Parameters

FolderType	$folder	The folder that shall be deleted.
User	$user	The user who wishes to delete the folder.

Returns

FolderType|string[] The deleted folder's FolderType object on success or an array with error messages on failure.

editFileRef()

static editFileRef ( FileRef  $file_ref, User  $user,   $name = null,   $description = null,   $content_terms_of_use_id = null,   $url = null  )

static

This method handles editing file reference attributes.

Checks that have to be made during the editing of a file reference are placed in this method so that a controller can simply call this method to change attributes of a file reference.

At least one of the three parameters name, description and content_terms_of_use_id must be set. Otherwise this method will do nothing.

Parameters

FileRef	$file_ref	The file reference that shall be edited.
User	$user	The user who wishes to edit the file reference.
string | null	$name	The new name for the file reference
string | null	$description	The new description for the file reference.
string | null	$content_terms_of_use_id	The ID of the new ContentTermsOfUse object.
string | null	$url	The new URL for the file to link to. This is only regarded if the file_ref points to an URL instead of a file stored by Stud.IP.

Returns

FileRef|string[] The edited FileRef object on success, string array with error messages on failure.

fetchURLMetadata()

static fetchURLMetadata (   $url,   $level = 0  )

static

Retrieves additional data for an URL by looking at the HTTP header.

Parameters

string	$url	The URL from which additional data shall be fetched.
int	$level	The amount of redirects that have already been walked through. The $level parameter is only useful when this method calls itself recursively.

Returns

array An array with additional data retrieved from the HTTP header.

fileIsAudio()

static fileIsAudio ( FileType  $file )

static

Returns true if the mime-type of that FileType object starts with audio/

Parameters

FileType

$file

The file

Returns

bool True if it is an audio file else false

fileIsImage()

static fileIsImage ( FileType  $file )

static

Returns true if the mime-type of that FileType object starts with image/

Parameters

FileType

$file

The file

Returns

bool True if it is an image else false

fileIsVideo()

static fileIsVideo ( FileType  $file )

static

Returns true if the mime-type of that FileType object starts with video/

Parameters

FileType

$file

The file

Returns

bool True if it is an video file else false

getAvailableFolderTypes()

static getAvailableFolderTypes (   $range_id_or_object,   $user_id  )

static

returns the available folder types, for given context and user

Parameters

string | SimpleORMap	$range_id_or_object
string	$user_id

Returns

array with strings representing the class names of available folder types.

getDownloadLinkForArchivedCourse()

static getDownloadLinkForArchivedCourse ( ArchivedCourse  $archived_course,   $protected_archive = false  )

static

Builds a download link for the file archive of an archived course.

Parameters

ArchivedCourse	$archived_course	An archived course whose file archive is requested.
bool	$protected_archive	True, if the protected file archive is requested. False, if the "readable for everyone" file archive is requested (default).

Returns

string The download link for the file or an empty string on failure.

getDownloadLinkForTemporaryFile()

static getDownloadLinkForTemporaryFile (   $temporary_file_name = null,   $download_file_name = null  )

static

Builds a download link for temporary files.

getDownloadURLForArchivedCourse()

static getDownloadURLForArchivedCourse ( ArchivedCourse  $archived_course,   $protected_archive = false  )

static

Builds a download URL for the file archive of an archived course.

Parameters

ArchivedCourse	$archived_course	An archived course whose file archive is requested.
bool	$protected_archive	True, if the protected file archive is requested. False, if the "readable for everyone" file archive is requested (default).

Returns

string The download link for the file or an empty string on failure.

getDownloadURLForTemporaryFile()

static getDownloadURLForTemporaryFile (   $temporary_file_name = null,   $download_file_name = null  )

static

Builds a download URL for temporary files.

getFileIcon()

static getFileIcon (   $filename,   $role = Icon::ROLE_CLICKABLE  )

static

getFolderFilesRecursive()

static getFolderFilesRecursive ( FolderType  $top_folder,   $user_id,   $check_file_permissions = false  )

static

Creates a list of files and subfolders of a folder.

Parameters

FolderType	$top_folder	The folder whose content shall be retrieved.
string	$user_id	The ID of the user who wishes to get all files and subfolders of a folder.
bool	$check_file_permissions	Set to true, if file permissions shall be checked. Defaults to false.

Returns

mixed[] A mixed array with FolderType and FileType objects.

getFolderLink()

static getFolderLink (   $folder )

static

Create link to a folder

Parameters

FolderType | Folder

$folder

the folder

Returns

string link to the folder's range

getFolderTypes()

static getFolderTypes ( )

static

returns the available folder types, There are several types of folders in Stud.IP. This method returns all available folder types.

Returns

array with strings representing the class names of available folder types.

getFolderURL()

static getFolderURL (   $folder )

static

Create URL to a folder

Parameters

FolderType | Folder

$folder

the folder

Returns

string URL to the folder's range

getFullPath()

static getFullPath ( FolderType  $folder,   $include_root = true  )

static

Create URL to a folder

Parameters

FolderType	$folder	the folder
bool	$include_root

Returns

array array of FolderType

getIconForFileRef()

static getIconForFileRef (   $ref,   $role = Icon::ROLE_CLICKABLE, array  $attributes = []  )

static

Returns the icon for a given file ref.

Parameters

FileRef | stdClass	$ref	The file ref whose icon is requested.
string	$role	The requested role
array	$attributes	Optional additional attributes

Returns

Icon The icon for the file ref.

getIconForMimeType()

static getIconForMimeType (   $mime_type = null,   $role = Icon::ROLE_CLICKABLE,   $attributes = []  )

static

Returns the icon for a given mime type.

Parameters

string	$mime_type	The mime type whose icon is requested.
string	$role	The requested role
array	$attributes	Optional additional attributes

Returns

Icon The icon for the mime type.

getIconNameForMimeType()

static getIconNameForMimeType (   $mime_type = null )

static

Returns the icon name for a given mime type.

Parameters

string

$mime_type

The mime type whose icon is requested.

Returns

string The icon name for the mime type.

getInboxFolder()

static getInboxFolder ( User  $user )

static

Returns an INBOX folder for the given user.

Parameters

User

$user

The user whose inbox folder is requested.

Returns

FolderType|null Returns the inbox folder on success, null on failure.

getOutboxFolder()

static getOutboxFolder ( User  $user )

static

Returns a FolderType object for the outbox folder of the given user.

Parameters

User

$user

The user whose outbox folder is requested.

Returns

FolderType|null Returns the inbox folder on success, null on failure.

getRangeIdsForFolders()

static getRangeIdsForFolders (   $user_id = null,   $with_personal_file_area = true  )

static

Retrieves the range-IDs for all courses and institutes a user has access to.

Parameters

string	$user_id	The ID of the user.
bool	$with_personal_file_area	Whether to include the user-ID of the user in the list of range-IDs (true) or not (false). Defaults to false.

Returns

string[] An array with all retrieved range-IDs of the user.

getReadableFolders()

static getReadableFolders ( FolderType  $top_folder,   $user_id  )

static

Creates a list of readable subfolders of a folder.

Parameters

FolderType	$top_folder
string	$user_id

Returns

FolderType[] assoc array ID => FolderType

getTypedFolder()

static getTypedFolder (   $id,   $pluginclass = null  )

static

Returns a FolderType instance for a given folder-ID. This method can also get FolderType instances which are defined in a file system plugin.

Parameters

string	$id	The ID of a Folder object.
null	$pluginclass	The name of a Plugin's main class.

Returns

FolderType|null A FolderType object if it can be retrieved using the Folder-ID (and by option the plugin class name) or null in case no FolderType object can be created.

getUnreadableFolders()

static getUnreadableFolders ( FolderType  $top_folder,   $user_id  )

static

Creates a list of unreadable subfolders of a folder.

Parameters

FolderType	$top_folder
string	$user_id

Returns

FolderType[] assoc array ID => FolderType

getUploadTypeConfig()

static getUploadTypeConfig (   $range_id,   $user_id = null  )

static

returns config array for upload types and sizes for a given range id

Parameters

string	$range_id	id of Course Institute User
string | null	$user_id	Optional user id

Returns

array

handleFileUpload()

static handleFileUpload ( array  $uploaded_files, FolderType  $folder,   $user_id = null  )

static

Handles uploading one or more files

Parameters

array	$uploaded_files	A two-dimensional array with file data for all uploaded files. The array has the following structure in the second dimension: [ 'name': The name of the file 'error': An integer telling if there were errors. 0, if no errors occured. 'type': The uploaded file's mime type. 'tmp_name': Name of the temporary file that was created right after the upload. 'size': Size of the uploaded file in bytes. ]
FolderType	$folder	the folder where the files are inserted
string	$user_id	the ID of the user who wants to upload files

Returns

array Array with the created file objects and error strings

loadUploadTypeConfig()

static loadUploadTypeConfig ( string  $type, string  $status  )

static

Loads the upload type configuration for a specific type and status.

Parameters

string	$type
string	$status

Returns

array{type: string, file_types: array, file_size: int}

moveFile()

static moveFile ( FileType  $source, FolderType  $destination_folder, User  $user  )

static

This method handles moving a file to a new folder.

Parameters

FileType	$source	The file reference for the file that shall be moved.
FolderType	$destination_folder	The destination folder.
User	$user	The user who wishes to move the file.

Returns

FileRef|string[] $source FileRef object on success, Array with error messages on failure.

moveFolder()

static moveFolder ( FolderType  $source_folder, FolderType  $destination_folder, User  $user  )

static

This method handles moving folders, including subfolders and files.

Parameters

FolderType	$source_folder	The folder that shall be moved.
FolderType	$destination_folder	The destination folder.
User	$user	The user who wishes to move the folder.

Returns

FolderType|string[] The moved folder's FolderType object on success or an array with error messages on failure.

updateFileRef()

static updateFileRef ( FileRef  $source, User  $user,   $uploaded_file_data = [],   $update_filename = false,   $update_other_references = false  )

static

This method handles updating the File a FileRef is pointing to.

The parameters $source, $user and $uploaded_file_data are required for this method to work.

Parameters

FileRef	$source	The file reference pointing to a file that shall be updated.
User	$user	The user who wishes to update the file.
array	$uploaded_file_data	The data of the uploaded new version of the file that is going to be updated.
bool	$update_filename	True, if the file name of the File and the FileRef shall be set to the name of the uploaded new version of the file. False otherwise.
bool	$update_other_references	If other FileRefs pointing to the File that is going to be updated shall be updated too, set this to True. In case only the FileRef $source and its file shall be updated, set this to False. In the latter case the File will be copied and the copy gets updated.

Returns

FileRef|string[] On success the updated $source FileRef is returned. On failure an array with error messages is returned.

---

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

• lib/filesystem/FileManager.php