Documentation

Attachment
in package

SMF

implements ArrayAccess uses ArrayAccessHelper

This class represents a file attachment.

Also provides methods to handle the uploading and creation of attachments as well as the auto-management of the attachment directories.

Interfaces

ArrayAccess

Constants

APPROVED_ANY = -1
APPROVED_FALSE = 0
APPROVED_TRUE = 1
TYPE_ANY = -1
TYPE_AVATAR = 1
TYPE_STANDARD = 0
TYPE_THUMB = 3

Properties

$approved : bool
$board : int
$downloads : int
$embedded_thumb : bool
$etag : string
$exists : bool
$file_hash : string
$fileext : string
$filename : string
$folder : int
$formatted_size : string
$height : int
$href : string
$id : int
$is_image : bool
$link : string
$loaded : array<string|int, mixed>
$loadedByMember : array<string|int, mixed>
$loadedByMsg : array<string|int, mixed>
$member : int
$mime_type : string
$msg : int
$mtime : int
$name : string
$path : string
$size : int
$source : string
$thumb : int
$thumb_height : int
$thumb_width : int
$topic : int
$type : int
$width : int
$prop_aliases : array<string|int, mixed>

Methods

__construct() : mixed: Constructor.
__set() : void: Sets custom properties.
approve() : bool: Approve an attachment, or maybe even more - no permission check!
assign() : bool: Assigns the given attachments to the given message ID.
automanageBySpace() : bool|null: Called when a directory space limit is reached.
automanageCheckDirectory() : bool|null: Check if the current directory is still valid or not.
automanageCreateDirectory() : bool: Creates a directory
check() : bool: Performs various checks on an uploaded file.
create() : bool: Create an attachment, with the given array of parameters.
createHash() : string: Creates a hash string for a file or string.
getAttachMsgInfo() : self|array<string|int, mixed>: Gets all needed message data associated with an attach ID
getFilePath() : string: Gets the expected path to an attachment file on disk.
load() : array<string|int, mixed>: Loads existing attachments by ID number.
loadAttachmentContext() : array<string|int, mixed>: This loads an attachment's contextual data including, most importantly, its size if it is an image.
loadByMember() : array<string|int, mixed>: Loads existing attachments by member ID.
loadByMsg() : array<string|int, mixed>: Loads existing attachments by message ID.
offsetExists() : bool: Checks whether a property has been set when object is accessed as an array.
offsetGet() : mixed: Gets properties when object is accessed as an array.
offsetSet() : void: Sets properties when object is accessed as an array.
offsetUnset() : void: Unsets properties when object is accessed as an array.
parseAttachBBC() : array<string|int, mixed>|string: Gets an attach ID and tries to load all its info.
prepareByMsg() : void: prepare the Attachment api for all messages
process() : void: Moves an attachment to the proper directory and set the relevant data into $_SESSION['temp_attachments']
remove() : array<string|int, int>|null: Removes attachments or avatars based on a given query condition.
setFileProperties() : void: Sets $this->exists, $this->mtime, $this->size, and $this->etag.
getDirectoryTreeElements() : array<string|int, mixed>|bool: Split a path into a list of all directories and subdirectories
initDir() : string|bool: Return the first part of a path (i.e. c:\ or / + the first directory).
isPathAllowed() : bool: Check if open_basedir restrictions are in effect.
queryData() : Generator<string|int, array<string|int, mixed>>: Generator that runs queries about attachment data and yields the result rows.
setPath() : void: Sets $this->path to the full path to the attachment file on disk.

APPROVED_ANY


    public
        mixed
    APPROVED_ANY
    = -1

APPROVED_FALSE


    public
        mixed
    APPROVED_FALSE
    = 0

APPROVED_TRUE


    public
        mixed
    APPROVED_TRUE
    = 1

TYPE_ANY


    public
        mixed
    TYPE_ANY
    = -1

TYPE_AVATAR


    public
        mixed
    TYPE_AVATAR
    = 1

TYPE_STANDARD


    public
        mixed
    TYPE_STANDARD
    = 0

TYPE_THUMB


    public
        mixed
    TYPE_THUMB
    = 3

$approved


    public
        bool
    $approved
     = true

Whether this attachment has been approved.

$board


    public
        int
    $board
     = 0

ID number of the board that this attachment's message is in.

$downloads


    public
        int
    $downloads
     = 0

How many times this attachment has been downloaded.

$embedded_thumb


    public
        bool
    $embedded_thumb
     = false

Whether this attachment is an image with an embedded thumbnail.

$etag


    public
        string
    $etag
     = ''

The attachment's entity tag.

$exists


    public
        bool
    $exists
     = false

Whether the attachment's file exists.

$file_hash


    public
        string
    $file_hash
     = ''

The unique hash for this attachment.

$fileext


    public
        string
    $fileext
     = ''

The file extension of this attachment.

$filename


    public
        string
    $filename
     = ''

The name of this attachment.

$folder


    public
        int
    $folder
     = 1

ID number of the folder that this attachment's file is stored in.

$formatted_size


    public
        string
    $formatted_size
     = ''

Human-friendly representation of the file size.

$height


    public
        int
    $height
     = 0

The image height of this attachment.

$href


    public
        string
    $href
     = ''

Download URL for this attachment.

$id


    public
        int
    $id

This attachment's ID number.

$is_image


    public
        bool
    $is_image
     = false

Whether this attachment is an image.

$link


    public
        string
    $link
     = ''

HTML link to download this attachment.

$loaded


    public
    static    array<string|int, mixed>
    $loaded
     = []

All loaded instances of this class.

$loadedByMember


    public
    static    array<string|int, mixed>
    $loadedByMember
     = []

Loaded instances of this class, grouped by member.

$loadedByMsg


    public
    static    array<string|int, mixed>
    $loadedByMsg
     = []

Loaded instances of this class, grouped by message.

$member


    public
        int
    $member
     = 0

ID number of the member that this attachment is an avatar for.

$mime_type


    public
        string
    $mime_type
     = ''

The MIME type of this attachment.

$msg


    public
        int
    $msg
     = 0

ID number of the message that this attachment is attached to.

$mtime


    public
        int
    $mtime
     = 0

Last modification time of the attachment's file.

$name


    public
        string
    $name
     = ''

Version of $this->filename with escaped HTML special characters.

$path


    public
        string
    $path
     = ''

Path to the attachment file on disk.

$size


    public
        int
    $size
     = 0

The file size of this attachment.

$source


    public
        string
    $source
     = ''

Indicates whether the data was loaded by SMF's native attachments system or by an alternative system.

$thumb


    public
        int
    $thumb
     = 0

ID number of this attachment's thumbnail.

$thumb_height


    public
        int
    $thumb_height
     = 0

Height of the thumbnail image, if applicable.

$thumb_width


    public
        int
    $thumb_width
     = 0

Width of the thumbnail image, if applicable.

$topic


    public
        int
    $topic
     = 0

ID number of the topic that this attachment's message is in.

$type


    public
        int
    $type
     = 0

The type of this attachment.

$width


    public
        int
    $width
     = 0

The image width of this attachment.

$prop_aliases


    protected
        array<string|int, mixed>
    $prop_aliases
     = ['id_attach' => 'id', 'attachID' => 'id', 'id_thumb' => 'thumb', 'id_msg' => 'msg', 'id_member' => 'member', 'id_folder' => 'folder', 'id_topic' => 'topic', 'id_board' => 'board', 'attachment_type' => 'type', 'attachment_approved' => 'approved', 'is_approved' => 'approved', 'filesize' => 'size', 'byte_size' => 'size', 'filePath' => 'path']

Alternate names for some object properties.

__construct()

Constructor.


    public
                    __construct([int $id = 0 ][, array<string|int, mixed> $props = [] ]) : mixed

Parameters

$id : int = 0: The ID number of the attachment.
$props : array<string|int, mixed> = []: Properties to set for this attachment.

__set()

Sets custom properties.


    public
                    __set(string $prop, mixed $value) : void

Parameters

$prop : string: The property name.
$value : mixed: The value to set.

approve()

Approve an attachment, or maybe even more - no permission check!


    public
            static        approve(array<string|int, mixed> $attachments) : bool

Parameters

$attachments : array<string|int, mixed>: The IDs of the attachments to approve.

Return values

bool —

Whether the operation was successful.

assign()

Assigns the given attachments to the given message ID.


    public
            static        assign([array<string|int, mixed> $attachIDs = [] ][, int $msgID = 0 ]) : bool

Parameters

$attachIDs : array<string|int, mixed> = []: array of attachment IDs to assign.
$msgID : int = 0: integer the message ID.

Return values

bool —

false on error or missing params.

automanageBySpace()

Called when a directory space limit is reached.


    public
            static        automanageBySpace() : bool|null

Creates a new directory and increments the directory suffix number.

Return values

bool|null —

False on errors, true if successful, nothing if auto-management of attachments is disabled

automanageCheckDirectory()

Check if the current directory is still valid or not.


    public
            static        automanageCheckDirectory() : bool|null

If not creates the new directory

Return values

bool|null —

False if any error occurred

automanageCreateDirectory()

Creates a directory


    public
            static        automanageCreateDirectory(string $updir) : bool

Parameters

$updir : string: The directory to be created

Return values

bool —

False on errors

check()

Performs various checks on an uploaded file.


    public
            static        check(string|int $attachID) : bool

Requires that $_SESSION['temp_attachments'][$attachID] be properly populated.

Parameters

$attachID : string|int: The ID of the attachment. When attached, int, for temp attachments, this is a string.

Return values

bool —

Whether the attachment is OK

create()

Create an attachment, with the given array of parameters.


    public
            static        create(array<string|int, mixed> &$attachmentOptions) : bool

Adds any additional or missing parameters to $attachmentOptions.
Renames the temporary file.
Creates a thumbnail if the file is an image and the option enabled.

Parameters

$attachmentOptions : array<string|int, mixed>: An array of attachment options

Return values

bool —

Whether the attachment was created successfully

createHash()

Creates a hash string for a file or string.


    public
            static        createHash([string $input = '' ]) : string

If $input is the path to a file, returns a hash of the file contents. If $input is an empty string, returns a hash of some random bytes. Otherwise, returns a hash of the input string itself.

Parameters

$input : string = '': The path to the file on disk.

Return values

string —

A hash string.

getAttachMsgInfo()

Gets all needed message data associated with an attach ID


    public
            static        getAttachMsgInfo(string|int $attachID) : self|array<string|int, mixed>

Parameters

$attachID : string|int: The ID of the attachment. When attached, int, for temp attachments, this is a string.

Return values

self|array<string|int, mixed> —

An instance of this class, or an empty array on failure.

getFilePath()

Gets the expected path to an attachment file on disk.


    public
            static        getFilePath(int $id) : string

Parameters

$id : int: The ID number of an attachment.

Return values

string —

The file path, or an empty string on error.

load()

Loads existing attachments by ID number.


    public
            static        load(array<string|int, mixed>|string|int $ids[, int $approval_status = self::APPROVED_ANY ][, int $type = self::TYPE_ANY ][, bool $get_thumbs = true ]) : array<string|int, mixed>

Parameters

$ids : array<string|int, mixed>|string|int: The ID numbers of one or more attachments.
$approval_status : int = self::APPROVED_ANY: One of this class's APPROVED_* constants. Default: self::APPROVED_ANY.
$type : int = self::TYPE_ANY: One of this class's TYPE_* constants. Default: self::TYPE_ANY.
$get_thumbs : bool = true: Whether to get the thumbnail image dimensions. Default: true.

Return values

array<string|int, mixed> —

Instances of this class for the loaded attachments.

loadAttachmentContext()

This loads an attachment's contextual data including, most importantly, its size if it is an image.


    public
            static        loadAttachmentContext(int $id_msg, array<string|int, mixed> $attachments) : array<string|int, mixed>

It requires the view_attachments permission to calculate image size. It attempts to keep the "aspect ratio" of the posted image in line, even if it has to be resized by the max_image_width and max_image_height settings.

Parameters

$id_msg : int: ID of the post to load attachments for
$attachments : array<string|int, mixed>: An array of already loaded attachments. This function no longer depends on having $topic declared, thus, you need to load the actual topic ID for each attachment.

Return values

array<string|int, mixed> —

An array of attachment info

loadByMember()

Loads existing attachments by member ID.


    public
            static        loadByMember(array<string|int, mixed>|int $members[, int $approval_status = self::APPROVED_TRUE ][, bool $get_thumbs = true ]) : array<string|int, mixed>

Parameters

$members : array<string|int, mixed>|int
$approval_status : int = self::APPROVED_TRUE: One of this class's APPROVED_* constants. Default: self::APPROVED_TRUE.
$get_thumbs : bool = true: Whether to get the thumbnail image dimensions. Default: true.

Return values

array<string|int, mixed> —

Instances of this class for the loaded attachments.

loadByMsg()

Loads existing attachments by message ID.


    public
            static        loadByMsg(array<string|int, mixed>|int $msgs[, int $approval_status = self::APPROVED_TRUE ][, int $type = self::TYPE_STANDARD ][, bool $get_thumbs = true ]) : array<string|int, mixed>

Parameters

$msgs : array<string|int, mixed>|int: The ID numbers of one or more messages.
$approval_status : int = self::APPROVED_TRUE: One of this class's APPROVED_* constants. Default: self::APPROVED_TRUE.
$type : int = self::TYPE_STANDARD: One of this class's TYPE_* constants. Default: self::TYPE_STANDARD.
$get_thumbs : bool = true: Whether to get the thumbnail image dimensions. Default: true.

Return values

array<string|int, mixed> —

Instances of this class for the loaded attachments.

offsetExists()

Checks whether a property has been set when object is accessed as an array.


    public
                    offsetExists(mixed $prop) : bool

Parameters

$prop : mixed: The property name.

Return values

bool

offsetGet()

Gets properties when object is accessed as an array.


    public
                &    offsetGet(mixed $prop) : mixed

Parameters

$prop : mixed: The property name.

Return values

mixed —

A reference to the property.

offsetSet()

Sets properties when object is accessed as an array.


    public
                    offsetSet(mixed $prop, mixed $value) : void

Parameters

$prop : mixed: The property name.
$value : mixed: The value to set.

offsetUnset()

Unsets properties when object is accessed as an array.


    public
                    offsetUnset(mixed $prop) : void

Parameters

$prop : mixed: The property name.

parseAttachBBC()

Gets an attach ID and tries to load all its info.


    public
            static        parseAttachBBC([string|int $attachID = 0 ]) : array<string|int, mixed>|string

Parameters

$attachID : string|int = 0: The ID of the attachment. When attached, int, for temp attachments, this is a string.

Return values

array<string|int, mixed>|string —

If successful, it will return an array of loaded data. String, most likely a Lang::$txt key if there was some error.

prepareByMsg()

prepare the Attachment api for all messages


    public
            static        prepareByMsg(array<string|int, int> $msgIDs) : void

Parameters

$msgIDs : array<string|int, int>: the message ID to load info from.

process()

Moves an attachment to the proper directory and set the relevant data into $_SESSION['temp_attachments']


    public
            static        process() : void

remove()

Removes attachments or avatars based on a given query condition.


    public
            static        remove(array<string|int, mixed> $condition[, string $query_type = '' ][, bool $return_affected_messages = false ][, bool $autoThumbRemoval = true ]) : array<string|int, int>|null

Called by several remove avatar/attachment functions in this file. It removes attachments based that match the $condition. It allows query_types 'messages' and 'members', whichever is need by the $condition parameter. It does no permissions check.

Parameters

$condition : array<string|int, mixed>: An array of conditions
$query_type : string = '': The query type. Can be 'messages' or 'members'
$return_affected_messages : bool = false: Whether to return an array with the IDs of affected messages
$autoThumbRemoval : bool = true: Whether to automatically remove any thumbnails associated with the removed files

Return values

array<string|int, int>|null —

Returns an array containing IDs of affected messages if $return_affected_messages is true

setFileProperties()

Sets $this->exists, $this->mtime, $this->size, and $this->etag.


    public
                    setFileProperties() : void

getDirectoryTreeElements()

Split a path into a list of all directories and subdirectories


    protected
            static        getDirectoryTreeElements(string $directory) : array<string|int, mixed>|bool

Parameters

$directory : string: A path

Return values

array<string|int, mixed>|bool —

An array of all the directories and subdirectories or false on failure

initDir()

Return the first part of a path (i.e. c:\ or / + the first directory).


    protected
            static        initDir(array<string|int, mixed> &$tree, int &$count) : string|bool

Used by Attachment::automanageCreateDirectory()

Parameters

$tree : array<string|int, mixed>: An array
$count : int: The number of elements in $tree

Return values

string|bool —

The first part of the path or false on error

isPathAllowed()

Check if open_basedir restrictions are in effect.


    protected
            static        isPathAllowed(string $path) : bool

If so check if the path is allowed.

Parameters

$path : string: The path to check

Return values

bool —

True if the path is allowed, false otherwise.

queryData()

Generator that runs queries about attachment data and yields the result rows.


    protected
            static        queryData(array<string|int, mixed> $selects[, array<string|int, mixed> $params = [] ][, string $from = '{db_prefix}attachments AS a' ][, array<string|int, mixed> $joins = [] ][, array<string|int, mixed> $where = [] ][, array<string|int, mixed> $order = [] ][, int $limit = 0 ]) : Generator<string|int, array<string|int, mixed>>

Parameters

$selects : array<string|int, mixed>: Table columns to select.
$params : array<string|int, mixed> = []: Parameters to substitute into query text.
$from : string = '{db_prefix}attachments AS a': FROM clause. Default: '{db_prefix}attachments AS a'
$joins : array<string|int, mixed> = []: Zero or more complete JOIN clauses. E.g.: 'LEFT JOIN {db_prefix}messages AS m ON (a.id_msg = m.id_msg)'
$where : array<string|int, mixed> = []: Zero or more conditions for the WHERE clause. Conditions will be placed in parentheses and concatenated with AND. If this is left empty, no WHERE clause will be used.
$order : array<string|int, mixed> = []: Zero or more conditions for the ORDER BY clause. If this is left empty, no ORDER BY clause will be used.
$limit : int = 0: Maximum number of results to retrieve. If this is left empty, all results will be retrieved.

Return values

Generator<string|int, array<string|int, mixed>> —

Iterating over the result gives database rows.

setPath()

Sets $this->path to the full path to the attachment file on disk.


    protected
                    setPath() : void

Attachment in package SMF implements ArrayAccess uses ArrayAccessHelper

Table of Contents

Interfaces

Constants

Properties

Methods

Constants

APPROVED_ANY

APPROVED_FALSE

APPROVED_TRUE

TYPE_ANY

TYPE_AVATAR

TYPE_STANDARD

TYPE_THUMB

Properties

$approved

$board

$downloads

$embedded_thumb

$etag

$exists

$file_hash

$fileext

$filename

$folder

$formatted_size

$height

$href

$id

$is_image

$link

$loaded

$loadedByMember

$loadedByMsg

$member

$mime_type

$msg

$mtime

$name

$path

$size

$source

$thumb

$thumb_height

$thumb_width

$topic

$type

$width

$prop_aliases

Methods

__construct()

Parameters

__set()

Parameters

approve()

Parameters

Return values

assign()

Parameters

Return values

automanageBySpace()

Return values

automanageCheckDirectory()

Return values

automanageCreateDirectory()

Parameters

Return values

check()

Parameters

Return values

create()

Parameters

Return values

createHash()

Parameters

Return values

getAttachMsgInfo()

Parameters

Return values

getFilePath()

Attachment
in package

SMF

implements ArrayAccess uses ArrayAccessHelper