Docs for page file.php

## /file.php

Description

This script implements the Phorum file storage API.

A "Phorum file" is a file which is used from within Phorum as a personal user file (which can be uploaded through the user's control center) or as a message attachment.

By default, the contents of a Phorum file are stored in the Phorum database, but this API does support modules that change this behavior (e.g. by storing file contents on a filesystem instead).

- copyright: 2010, Phorum Development Team
- license: Phorum

Constants
PHORUM_FLAG_FORCE_DOWNLOAD = 8 (line 65)

Function call flag, which tells phorum_api_file_retrieve() to force a download by the browser by sending an application/octet-stream Content-Type header. This flag will only have effect if the PHORUM_FLAG_SEND flag is set as well.

PHORUM_FLAG_GET = 1 (line 45)

Function call flag, which tells phorum_api_file_retrieve() that the retrieved Phorum file data has to be returned to the caller.

PHORUM_FLAG_IGNORE_PERMS = 4 (line 57)

Function call flag, which tells the function to skip any permission checks.

PHORUM_FLAG_SEND = 2 (line 51)

Function call flag, which tells phorum_api_file_retrieve() that the retrieved Phorum file can be sent to the browser directly.

Functions
phorum_api_file_check_delete_access (line 975)

Check if the active user has permission to delete a file.

- return: TRUE if the user has rights to delete the file, FALSE otherwise.
- example: Delete a file.

boolean phorum_api_file_check_delete_access (integer $file_id)

- integer $file_id: The file_id of the file for which to check the delete access.

phorum_api_file_check_read_access (line 591)

Check if a file exists and if the active user has permission to read it.

The function will return either an array containing descriptive data for the file or FALSE, in case access was not granted.

Note that the file_data field is not available in the return array. That data can be retrieved by the phorum_api_file_retrieve() function.

- return:

  On error, this function will return FALSE. The functions phorum_api_strerror() and phorum_api_errno() can be used to retrieve information about the error which occurred.

  On success, it returns an array containing descriptive data for the file. The following fields are available in this array:

  - file_id: The file_id for the requested file.
  - filename: The name of the file.
  - filesize: The size of the file in bytes.
  - add_datetime: Epoch timestamp describing at what time the file was stored.
  - message_id: The message to which a message is linked (in case it is a message attachment).
  - user_id: The user to which a message is linked (in case it is a private user file).
  - link: A value describing to what type of entity the file is linked. One of PHORUM_LINK_USER, PHORUM_LINK_MESSAGE, PHORUM_LINK_EDITOR and PHORUM_LINK_TEMPFILE.

mixed phorum_api_file_check_read_access (integer $file_id, [integer $flags = 0])

- integer $file_id: The file_id of the file for which to check read access.
- integer $flags: If the PHORUM_FLAG_IGNORE_PERMS flag is used, then permission checks are fully bypassed. In this case, the function will only check if the file exists or not.

phorum_api_file_check_write_access (line 168)

Check if the active user has permissions to store a personal file or a message attachment.

Note that the checks for message attachments aren't all checks that are done by Phorum. The attachment posting script does run some additional checks on the message level (e.g. to see if the maximum cumulative attachment size is not exceeded).

- return: If access is allowed, then TRUE will be returned. If access is denied, then FALSE will be returned. The functions phorum_api_strerror() and phorum_api_errno() can be used to retrieve information about the error which occurred.
- example: Store a personal file.

array phorum_api_file_check_write_access (array $file)

- array $file: This is an array, containing information about the file that will be uploaded. The array should contain at least the "link" field. That field will be used to handle checking for personal uploaded files in the control center (PHORUM_LINK_USER) or message attachments (PHORUM_LINK_MESSAGE). Next to that, interesting file fields to pass to this function are "filesize" (to check maximum size) and "filename" (to check allowed file type extensions). A "user_id" field can either be provided or the user_id of the active Phorum user will be used.

phorum_api_file_delete (line 1072)

Delete a Phorum file.

- example: Delete a file.

void phorum_api_file_delete (mixed $file)

- mixed $file: This is either an array containing at least the field "file_id" or a numerical file_id value.

phorum_api_file_exists (line 1324)

Check if a Phorum file exists.

(this is a simple wrapper function around the phorum_api_file_check_read_access() function)

- return: TRUE in case the file exists or FALSE if it doesn't.

bool phorum_api_file_exists (integer $file_id)

- integer $file_id: The file_id of the Phorum file to check.

phorum_api_file_get (line 1377)

Retrieve and return a Phorum file.

(this is a simple wrapper function around the phorum_api_file_retrieve() function)

- return: See the return value for the phorum_api_file_retrieve() function.

mixed phorum_api_file_get (mixed $file, [integer $flags = 0])

- mixed $file: This is either an array containing at least the fields "file_id" and "filename" or a numerical file_id value. Note that you can use the return value of the function phorum_api_file_check_read_access() as input for this function.
- integer $flags: If the PHORUM_FLAG_IGNORE_PERMS flag is used, then permission checks are fully bypassed.

phorum_api_file_get_mimetype (line 121)

Lookup the MIME type for a given filename.

This will use an internal lookup list of known file extensions to find the correct content type for a filename. If no content type is known, then "application/octet-stream" will be used as the MIME type (causing the browser to download the file, instead of opening it).

- return: The MIME type for the given filename.

string phorum_api_file_get_mimetype (string $filename)

- string $filename: The filename for which to lookup the MIME type.

phorum_api_file_list (line 1124)

Retrieve a list of files.

- return: An array of files, indexed by file_id. The array elements are arrays containing the fields: file_id, filename, filesize and add_datetime.

array phorum_api_file_list ([string $link_type = NULL], [integer $user_id = NULL], [integer $message_id = NULL])

- string $link_type: The type of link to retrieve from the database. Normally this is one of the Phorum built-in link types, but it can also be a custom link type (e.g. if a module uses the file storage on its own). This parameter can be NULL to retrieve any link type.
- integer $user_id: The user_id to retrieve files for or NULL to retrieve files for any user_id.
- integer $message_id: The message_id to retrieve files for or NULL to retrieve files for any message_id.

phorum_api_file_purge_stale (line 1150)

This function is used for purging stale files from the Phorum system.

- return: An array of stale Phorum files, indexed by file_id. Every item in this array is an array on its own, containing the fields:
  - file_id: the file id of the stale file
  - filename: the name of the stale file
  - filesize: the size of the file in bytes
  - add_datetime: the time (epoch) at which the file was added
  - reason: the reason why it's a stale file
  This array will be returned, regardless of the $do_purge parameter.

array phorum_api_file_purge_stale (boolean $do_purge)

- boolean $do_purge: If this parameter is set to a false value (the default), then no actual purging will take place. The function will only return an array of stale files. If the parameter is set to a true value, then the stale files will be purged for real.

phorum_api_file_retrieve (line 749)

Retrieve a Phorum file.

This function can handle Phorum file retrieval in multiple ways: either return the file to the caller or send it directly to the user's browser (based on the $flags parameter). Sending it directly to the browser allows for the implementation of modules that don't have to buffer the full file data before sending it (a.k.a. streaming, which provides the advantage of using less memory for sending files).

- return:

  On error, this function will return FALSE. The functions phorum_api_strerror() and phorum_api_errno() can be used to retrieve information about the error which occurred.

  If the PHORUM_FLAG_SEND flag is used, then the function will return NULL.

  If the PHORUM_FLAG_GET flag is used, then the function will return a file description array, containing the fields "file_id", "username", "file_data", "mime_type". If the $file parameter was an array, then all fields from that array will be included as well.

mixed phorum_api_file_retrieve (mixed $file, [integer $flags = PHORUM_FLAG_GET])

- mixed $file: This is either an array containing at least the fields "file_id" and "filename" or a numerical file_id value. Note that you can use the return value of the function phorum_api_file_check_read_access() as input for this function.
- integer $flags: These are flags which influence aspects of the function call. It is a bitflag value, so you can OR multiple flags together. Available flags for this function are: PHORUM_FLAG_IGNORE_PERMS, PHORUM_FLAG_GET, PHORUM_FLAG_SEND and PHORUM_FLAG_FORCE_DOWNLOAD. The SEND flag has precedence over the GET flag.

phorum_api_file_safe_to_view (line 1228)

Check if the file is safe to view in the browser.

This will emulate MIME-sniffing as done by browsers to see if the file could be interpreted as an HTML file by the browser.

- return: TRUE if the browser might qualify the file as HTML code, FALSE otherwise.

boolean phorum_api_file_safe_to_view (array $file)

- array $file: An array, containing information for the file. This array has to contain at least the file_data field.

phorum_api_file_send (line 1351)

Send a file to the browser.

(this is a simple wrapper function around the phorum_api_file_retrieve() function)

void phorum_api_file_send (mixed $file, [integer $flags = 0])

- mixed $file: This is either an array containing at least the fields "file_id" and "filename" or a numerical file_id value. Note that you can use the return value of the function phorum_api_file_check_read_access() as input for this function.
- integer $flags: If the PHORUM_FLAG_IGNORE_PERMS flag is used, then permission checks are fully bypassed. If PHORUM_FLAG_FORCE_DOWNLOAD is used, then a download by the browser is forced (instead of opening the file in an appliction that the browser finds appropriate for the file type).

phorum_api_file_store (line 356)

Store or update a file.

- return:

  On error, this function will return FALSE. The functions phorum_api_strerror() and phorum_api_errno() can be used to retrieve information about the error which occurred.

  On success, an array containing the data for the stored file will be returned. If the function is called with no "file_id" in the $file argument (when a new file is stored), then the new "file_id" and "add_datetime" fields will be included in the return variable as well.

- example: Store a personal file.

mixed phorum_api_file_store (array $file)

- array $file:

  An array, containing information for the file. This array has to contain the following fields:

  - filename: The name of the file.
  - file_data: The file data.
  - filesize: The size of the file data in bytes.
  - link: A value describing to what type of entity the file is linked. The following values are available:
    - PHORUM_LINK_USER
    - PHORUM_LINK_MESSAGE
    - PHORUM_LINK_EDITOR
    - PHORUM_LINK_TEMPFILE
  - user_id: The user to link a file to. If none is provided, then
  - message_id: The message to link a file to or 0 if it's no message attachment.

  Additionally, the "file_id" field can be set. If it is set, then the existing file will be updated. If it is not set, a new file will be created.

Documentation generated on Fri, 24 Aug 2012 01:45:39 -0500 by phpDocumentor 1.4.3