Behavior configuration optionsΒΆ
This is a list of all the available configuration options which can be passed in under each field in your behavior configuration.
pathMethod
: The method to use for file paths. This is appended to thepath
option below- Default: (string)
primaryKey
- Options:
flat
: Does not create a path for each record. Files are moved to the value of the ‘path’ option.primaryKey
: Path based upon the record’s primaryKey is generated. Persists across a record update.random
: Random path is generated for each file upload in the formnn/nn/nn
wherenn
are random numbers. Does not persist across a record update.randomCombined
: Random path - with model id - is generated for each file upload in the formID/nn/nn/nn
whereID
is the current model’s ID andnn
are random numbers. Does not persist across a record update.
- Default: (string)
path
: A path relative to therootDir
. Should end in{DS}
- Default: (string)
'{ROOT}webroot{DS}files{DS}{model}{DS}{field}{DS}'
- Tokens:
- {ROOT}: Replaced by a
rootDir
option - {DS}: Replaced by a
DIRECTORY_SEPARATOR
- {model}: Replaced by the Model Alias.
- {field}: Replaced by the field name.
- {primaryKey}: Replaced by the record primary key, when available. If used on a new record being created, will have undefined behavior.
- {size}: Replaced by a zero-length string (the empty string) when used for the regular file upload path. Only available for resized thumbnails.
- {geometry}: Replaced by a zero-length string (the empty string) when used for the regular file upload path. Only available for resized thumbnails.
- {ROOT}: Replaced by a
- Default: (string)
fields
: An array of fields to use when uploading files- Default: (array)
array('dir' => 'dir', 'type' => 'type', 'size' => 'size')
- Options:
- dir: Field to use for storing the directory
- type: Field to use for storing the filetype
- size: Field to use for storing the filesize
- Default: (array)
rootDir
: Root directory for moving images. Auto-prepended topath
andthumbnailPath
where necessary- Default (string)
ROOT . DS . APP_DIR . DS
- Default (string)
mimetypes
: Array of mimetypes to use for validation- Default: (array) empty
extensions
: Array of extensions to use for validation- Default: (array) empty
maxSize
: Max filesize in bytes for validation- Default: (int)
2097152
- Default: (int)
minSize
: Minimum filesize in bytes for validation- Default: (int)
8
- Default: (int)
maxHeight
: Maximum image height for validation- Default: (int)
0
- Default: (int)
minHeight
: Minimum image height for validation- Default: (int)
0
- Default: (int)
maxWidth
: Maximum image width for validation- Default: (int)
0
- Default: (int)
minWidth
: Minimum image width for validation- Default: (int)
0
- Default: (int)
deleteOnUpdate
: Whether to delete files when uploading new versions (potentially dangerous due to naming conflicts)- Default: (boolean)
false
- Default: (boolean)
thumbnails
: Whether to create thumbnails or not- Default: (boolean)
true
- Default: (boolean)
thumbnailMethod
: The method to use for resizing thumbnails- Default: (string)
imagick
- Options:
- imagick: Uses the PHP
imagick
extension to generate thumbnails - php: Uses the built-in PHP methods (
GD
extension) to generate thumbnails. Does not support BMP images.
- imagick: Uses the PHP
- Default: (string)
thumbnailName
: Naming style for a thumbnail- Default:
NULL
- Note: The tokens
{size}
,{geometry}
and{filename}
are valid for naming and will be auto-replaced with the actual terms. - Note: As well, the extension of the file will be automatically added.
- Note: When left unspecified, will be set to
{size}_{filename}
or{filename}_{size}
depending upon the value ofthumbnailPrefixStyle
- Default:
thumbnailPath
: A path relative to therootDir
where thumbnails will be saved. Should end in{DS}
. If not set, thumbnails will be saved atpath
.- Default:
NULL
- Tokens:
- {ROOT}: Replaced by a
rootDir
option - {DS}: Replaced by a
DIRECTORY_SEPARATOR
- {model}: Replaced by the Model Alias
- {field}: Replaced by the field name
- {size}: Replaced by the size key specified by a given
thumbnailSize
- {geometry}: Replaced by the geometry value specified by a given
thumbnailSize
- {ROOT}: Replaced by a
- Default:
thumbnailPrefixStyle
: Whether to prefix or suffix the style onto thumbnails- Default: (boolean)
true
prefix the thumbnail - Note that this overrides
thumbnailName
whenthumbnailName
is not specified in your config
- Default: (boolean)
thumbnailQuality
: Quality of thumbnails that will be generated, on a scale of 0-100. Not supported gif images when using GD for image manipulation.- Default: (int)
75
- Default: (int)
thumbnailSizes
: Array of thumbnail sizes, with the size-name mapping to a geometry- Default: (array) empty
thumbnailType
: Override the type of the generated thumbnail- Default: (mixed)
false
orpng
when the upload is a Media file - Options:
- Any valid image type
- Default: (mixed)
mediaThumbnailType
: Override the type of the generated thumbnail for a non-image media (pdfs
). OverridesthumbnailType
- Default: (mixed)
png
- Options:
- Any valid image type
- Default: (mixed)
saveDir
: Can be used to turn off saving the directory- Default: (boolean)
true
- Note: Because of the way in which the directory is saved, if you
are using a
pathMethod
other than flat and you setsaveDir
to false, you may end up in situations where the file is in a location that you cannot predict. This is more of an issue for apathMethod
ofrandom
andrandomCombined
thanprimaryKey
, but keep this in mind when fiddling with this option
- Default: (boolean)
deleteFolderOnDelete
: Delete folder related to current record on record delete- Default: (boolean)
false
- Note: Because of the way in which the directory is saved, if you
are using a
pathMethod
of flat, turning this setting on will delete all your images. As such, setting this to true can be potentially dangerous.
- Default: (boolean)
keepFilesOnDelete
: Keep all files when uploading/deleting a record.- Default: (boolean)
false
- Note: This does not override
deleteFolderOnDelete
. If you set that setting to true, your images may still be deleted. This is so that existing uploads are not deleted - unless overwritten.
- Default: (boolean)
mode
: The UNIX permissions to set on the created upload directories.- Default: (integer)
0777
- Default: (integer)
handleUploadedFileCallback
: If set to a method name available on your model, this model method will handle the movement of the original file on disk. Can be used in conjunction withthumbnailMethod
to store your files in alternative locations, such as S3.- Default:
NULL
- Available arguments:
string $field
: Field being manipulatedstring $filename
: The filename of the uploaded filestring $destination
: The configured destination of the moved file
- Default:
nameCallback
: A callback that can be used to rename a file. Currently only handles original file naming.- Default:
NULL
- Available arguments:
string $field
: Field being manipulatedstring $currentName
array $data
array options
:isThumbnail
- a boolean field that is on when we are trying to infer a thumbnail pathrootDir
- root directory to replace{ROOT}
geometry
size
thumbnailType
thumbnailName
thumbnailMethod
mediaThumbnailType
dir
field namesaveType
- create, update, delete
- Return: String - returns the new name for the file
- Default: