trait FileUploadReceiver mixin FormField (View source)

Provides operations for reading and writing uploaded files to/from {File} dataobject instances.

Allows writing to a parent record with the following relation types:

  • has_one
  • has_many
  • many_many Additionally supports writing directly to the File table not attached to any parent record.

Note that this trait expects to be applied to a {\SilverStripe\Forms\FormField} class

Traits

Represents a form field which has an Upload() instance and can upload to a folder

Properties

protected Upload $upload

Upload object (needed for validation and actually moving the temporary file created by PHP).

from  UploadReceiver
protected string $folderName

Partial filesystem path relative to /assets directory.

from  UploadReceiver
public bool $relationAutoSetting

Flag to automatically determine and save a has_one-relationship on the saved record (e.g. a "Player" has_one "PlayerImage" would trigger saving the ID of newly created file into "PlayerImageID" on the record).

protected DataObject $record

Parent data record. Will be inferred from parent form or controller if blank.

protected SS_List $items

Items loaded into this field. May be a RelationList, or any other SS_List

Methods

protected
constructUploadReceiver()

Bootstrap Uploadable field

public
getUpload()

Retrieves the Upload handler

public
$this
setUpload(Upload $upload)

Sets the upload handler

public
$this
setAllowedExtensions(array $rules)

Limit allowed file extensions. Empty by default, allowing all extensions.

public
$this
setAllowedFileCategories(string $category)

Limit allowed file extensions by specifying categories of file types.

public
array
getAllowedExtensions()

Returns list of extensions allowed by this field, or an empty array if there is no restriction

public
getValidator()

Get custom validator for this field

public
$this
setValidator(Upload_Validator $validator)

Set custom validator for this field

public
$this
setFolderName(string $folderName)

Sets the upload folder name

public
string
getFolderName()

Gets the upload folder name

protected
constructFileUploadReceiver()

No description

public
$this
setRecord(DataObject $record)

Force a record to be used as "Parent" for uploaded Files (eg a Page with a has_one to File)

public
DataObject
getRecord()

Get the record to use as "Parent" for uploaded Files (eg a Page with a has_one to File) If none is set, it will use Form->getRecord() or Form->Controller()->data()

public
$this
setValue(array $value, array|DataObject|SS_List $record = null)

Loads the related record values into this field. This can be uploaded in one of three ways:

public
$this
setItems(SS_List $items)

Sets the items assigned to this field as an SS_List of File objects.

public
getItems()

Retrieves the current list of files

public
array
getItemIDs()

Retrieves the list of selected file IDs

public
Value()

No description

public
$this
saveInto(DataObjectInterface $record)

No description

protected
saveTemporaryFile(array $tmpFile, string $error = null)

Loads the temporary file data into a File object

public
string
getRelationAutosetClass(string $default = File::class)

Gets the foreign class that needs to be created, or 'File' as default if there is no relationship, or it cannot be determined.

public
$this
setRelationAutoSetting(bool $auto)

Set if relation can be automatically assigned to the underlying dataobject

public
bool
getRelationAutoSetting()

Check if relation can be automatically assigned to the underlying dataobject

protected
array
extractUploadedFileData(array $postVars)

Given an array of post variables, extract all temporary file data into an array

Details

protected constructUploadReceiver()

Bootstrap Uploadable field

Upload getUpload()

Retrieves the Upload handler

Return Value

Upload

$this setUpload(Upload $upload)

Sets the upload handler

Parameters

Upload $upload

Return Value

$this

Self reference

$this setAllowedExtensions(array $rules)

Limit allowed file extensions. Empty by default, allowing all extensions.

To allow files without an extension, use an empty string. See File::$allowed_extensions to get a good standard set of extensions that are typically not harmful in a webserver context. See setAllowedMaxFileSize() to limit file size by extension.

Parameters

array $rules

List of extensions

Return Value

$this

$this setAllowedFileCategories(string $category)

Limit allowed file extensions by specifying categories of file types.

These may be 'image', 'image/supported', 'audio', 'video', 'archive', 'flash', or 'document' See File::$allowed_extensions for details of allowed extensions for each of these categories

Parameters

string $category

Category name

Return Value

$this

array getAllowedExtensions()

Returns list of extensions allowed by this field, or an empty array if there is no restriction

Return Value

array

Upload_Validator getValidator()

Get custom validator for this field

Return Value

Upload_Validator

$this setValidator(Upload_Validator $validator)

Set custom validator for this field

Parameters

Upload_Validator $validator

Return Value

$this

$this setFolderName(string $folderName)

Sets the upload folder name

Parameters

string $folderName

Return Value

$this

string getFolderName()

Gets the upload folder name

Return Value

string

protected constructFileUploadReceiver()

No description

$this setRecord(DataObject $record)

Force a record to be used as "Parent" for uploaded Files (eg a Page with a has_one to File)

Parameters

DataObject $record

Return Value

$this

DataObject getRecord()

Get the record to use as "Parent" for uploaded Files (eg a Page with a has_one to File) If none is set, it will use Form->getRecord() or Form->Controller()->data()

Return Value

DataObject

$this setValue(array $value, array|DataObject|SS_List $record = null)

Loads the related record values into this field. This can be uploaded in one of three ways:

  • By passing in a list of file IDs in the $value parameter (an array with a single key 'Files', with the value being the actual array of IDs).
    • By passing in an explicit list of File objects in the $record parameter, and leaving $value blank.
    • By passing in a dataobject in the $record parameter, from which file objects will be extracting using the field name as the relation field.

Each of these methods will update both the items (list of File objects) and the field value (list of file ID values).

Parameters

array $value

Array of submitted form data, if submitting from a form

array|DataObject|SS_List $record

Full source record, either as a DataObject, SS_List of items, or an array of submitted form data

Return Value

$this

Self reference

Exceptions

ValidationException

$this setItems(SS_List $items)

Sets the items assigned to this field as an SS_List of File objects.

Calling setItems will also update the value of this field, as well as updating the internal list of File items.

Parameters

SS_List $items

Return Value

$this

self reference

SS_List|File[] getItems()

Retrieves the current list of files

Return Value

SS_List|File[]

array getItemIDs()

Retrieves the list of selected file IDs

Return Value

array

Value()

No description

$this saveInto(DataObjectInterface $record)

No description

Parameters

DataObjectInterface $record

Return Value

$this

protected AssetContainer saveTemporaryFile(array $tmpFile, string $error = null)

Loads the temporary file data into a File object

Parameters

array $tmpFile

Temporary file data

string $error

Error message

Return Value

AssetContainer

File object, or null if error

string getRelationAutosetClass(string $default = File::class)

Gets the foreign class that needs to be created, or 'File' as default if there is no relationship, or it cannot be determined.

Parameters

string $default

Default value to return if no value could be calculated

Return Value

string

Foreign class name.

$this setRelationAutoSetting(bool $auto)

Set if relation can be automatically assigned to the underlying dataobject

Parameters

bool $auto

Return Value

$this

bool getRelationAutoSetting()

Check if relation can be automatically assigned to the underlying dataobject

Return Value

bool

protected array extractUploadedFileData(array $postVars)

Given an array of post variables, extract all temporary file data into an array

Parameters

array $postVars

Array of posted form data

Return Value

array

List of temporary file data