Upload extends Component uses File
Upload component
Simplifies the file upload and storage for files added to the filesystem
Requires the Input Component
Table of Contents
Properties
| $components | |
| $helpers | |
| $models | |
| $allowed_file_extensions | |
| $allowed_mime_types | |
| $allowed_paths | |
| $data | |
| $errors | |
| $files | |
| $max_file_size | |
| $upload_path | |
| $uploaded_files |
Methods
| __construct() | Initialize the Upload |
| addAllowedPath() | Adds a new path to the whitelist of allowed paths |
| appendCount() | Returns a suggested file name with a number appended at the end so that it is unique in the upload path |
| createUploadPath() | Recursively creates the upload path if it does not already exists. Also sets permissions to the given set when the directory is created |
| errors() | Returns all errors set |
| getAllowedPaths() | Returns an array of all allowed paths |
| getUploadData() | Fetches the upload data |
| md5() | Returns a suggested file name that uses an MD5 hash of the existing file name while preserving the file extension. |
| removeAllowedPath() | Removes an existing path from the whitelist of allowed paths |
| setAllowedFileExtensions() | Sets the allowed extensions |
| setAllowedMimeTypes() | Sets the allowed MIME types |
| setAllowedPaths() | Sets an array of paths, as the whitelist of allowed paths |
| setFiles() | Sets the array of files to be considered for handling. This class automatically defaults the set of arrays to the global FILES array |
| setMaxFileSize() | Sets the maximum file size in bytes. The server may have its own setting for maximum file sizes, so ensure that this value does not exceede the server's allowed maximum size |
| setUploadPath() | Sets the upload path. The upload path will be verified when files are written. If the upload path is invalid file uploads will result in errors |
| writeFile() | Writes one or more files to the file system. Because of the nature of writing files to the disk, if any file fails execution will continue. |
| writeFiles() | Writes multiple files to the file system. Because of the nature of writing files to the disk, if any file fails execution will continue. |
| write() | Writes a file to the file system from the given set files |
Properties
$components
protected
mixed
$components
$helpers
protected
mixed
$helpers
$models
protected
mixed
$models
$allowed_file_extensions
private
array<string|int, mixed>
$allowed_file_extensions
An array of allowed file extensions
$allowed_mime_types
private
array<string|int, mixed>
$allowed_mime_types
An array of allowed MIME types
$allowed_paths
private
array<string|int, mixed>
$allowed_paths
= [CACHEDIR]
A list of directories that are allowed for reading and writing
$data
private
array<string|int, mixed>
$data
= []
An array of data about the upload
$errors
private
array<string|int, mixed>
$errors
= []
An array of errors to be set
$files
private
array<string|int, mixed>
$files
= []
An array of files from the global FILES variable
$max_file_size
private
int
$max_file_size
= 0
The maximum file size allowed, 0 for unlimited
$upload_path
private
string
$upload_path
The full path to the upload directory, where files should be written
$uploaded_files
private
bool
$uploaded_files
= \true
True if the files given have been uploaded, false if they were created instead
Methods
__construct()
Initialize the Upload
public
__construct() : mixed
addAllowedPath()
Adds a new path to the whitelist of allowed paths
public
addAllowedPath(mixed $path) : mixed
Parameters
- $path : mixed
appendCount()
Returns a suggested file name with a number appended at the end so that it is unique in the upload path
public
appendCount(string $file_name) : string
Parameters
- $file_name : string
-
The name of the file to append a count to
Return values
string —The suggested file name
createUploadPath()
Recursively creates the upload path if it does not already exists. Also sets permissions to the given set when the directory is created
public
createUploadPath(string $path[, int $permissions = 0755 ]) : mixed
Parameters
- $path : string
-
The directory path to create
- $permissions : int = 0755
-
The permission value in octets
errors()
Returns all errors set
public
errors() : array<string|int, mixed>
Return values
array<string|int, mixed> —An array of errors set in Input
getAllowedPaths()
Returns an array of all allowed paths
public
getAllowedPaths() : array<string|int, mixed>
Return values
array<string|int, mixed>getUploadData()
Fetches the upload data
public
getUploadData() : array<string|int, mixed>
Return values
array<string|int, mixed> —An array of upload data for each of the uploaded files including:
- orig_name The original name of the uploaded file
- file_name The new file name
- file_path The path where the file was written
- full_path The full path to the file that was written
- file_size The size of the file that was written (in bytes)
md5()
Returns a suggested file name that uses an MD5 hash of the existing file name while preserving the file extension.
public
md5(mixed $file_name) : string
For example my_file.txt becomes 3715ac9af3d0d8cb0970e08494034357.txt, that is md5(my_file.txt) with .txt appended.
Parameters
- $file_name : mixed
Return values
string —$file_name The suggested file name
removeAllowedPath()
Removes an existing path from the whitelist of allowed paths
public
removeAllowedPath(mixed $path) : mixed
Parameters
- $path : mixed
setAllowedFileExtensions()
Sets the allowed extensions
public
setAllowedFileExtensions([array<string|int, mixed> $types = null ]) : mixed
Parameters
- $types : array<string|int, mixed> = null
-
An array of file extensions to allow, set to null to allow all file extensions
setAllowedMimeTypes()
Sets the allowed MIME types
public
setAllowedMimeTypes([array<string|int, mixed> $types = null ]) : mixed
Parameters
- $types : array<string|int, mixed> = null
-
An array of MIME types to allow, set to null to allow all MIME types
setAllowedPaths()
Sets an array of paths, as the whitelist of allowed paths
public
setAllowedPaths(array<string|int, mixed> $paths) : mixed
Parameters
- $paths : array<string|int, mixed>
setFiles()
Sets the array of files to be considered for handling. This class automatically defaults the set of arrays to the global FILES array
public
setFiles(array<string|int, mixed> $files[, bool $uploaded_files = true ]) : mixed
Parameters
- $files : array<string|int, mixed>
-
An array of files from the global FILES array to set. The format of this array must match that the global FILES array exactly
- $uploaded_files : bool = true
-
If true the file was uploaded, false if the file was created and not uploaded
setMaxFileSize()
Sets the maximum file size in bytes. The server may have its own setting for maximum file sizes, so ensure that this value does not exceede the server's allowed maximum size
public
setMaxFileSize([int $bytes = 0 ]) : mixed
Parameters
- $bytes : int = 0
-
The maximum file size in bytes. Set to 0 to use no maximum file size.
setUploadPath()
Sets the upload path. The upload path will be verified when files are written. If the upload path is invalid file uploads will result in errors
public
setUploadPath(string $path[, bool $create = false ]) : mixed
Parameters
- $path : string
-
The server path to where files are to be written
- $create : bool = false
-
Unused argument (optional)
writeFile()
Writes one or more files to the file system. Because of the nature of writing files to the disk, if any file fails execution will continue.
public
writeFile(string $file[, bool $overwrite = true ][, string $file_name = null ][, callable $rename_callback = null ][, int $permissions = 0644 ]) : mixed
Any failed files will be reported by Upload::errors()
Parameters
- $file : string
-
A field name to search the global file variable for
- $overwrite : bool = true
-
Whether or not to overwrite the file if it already exists
- $file_name : string = null
-
The name of the file to use instead of the uploaded file's name, null to use uploaded file's name
- $rename_callback : callable = null
-
A callback to execute used to rename the file
- $permissions : int = 0644
-
The permission value in octets, null to default to user permissions
writeFiles()
Writes multiple files to the file system. Because of the nature of writing files to the disk, if any file fails execution will continue.
public
writeFiles(array<string|int, mixed> $files[, bool $overwrite = true ][, array<string|int, mixed> $file_names = null ][, callable $rename_callback = null ][, int $permissions = 0644 ]) : mixed
Any failed files will be reported by Upload::errors()
Parameters
- $files : array<string|int, mixed>
-
An array of file field names to search the global file variable for
- $overwrite : bool = true
-
Whether or not to overwrite the file if it already exists
- $file_names : array<string|int, mixed> = null
-
The names of the files to use instead of the uploaded file's name, null to use uploaded file's name
- $rename_callback : callable = null
-
A callback to execute used to rename the file
- $permissions : int = 0644
-
The permission value in octets, null to default to user permissions
write()
Writes a file to the file system from the given set files
private
write(array<string|int, mixed> $file[, string $key = null ][, string $index = null ][, bool $overwrite = true ][, string $file_name = null ][, callable $rename_callback = null ][, int $permissions = 0644 ]) : bool
Parameters
- $file : array<string|int, mixed>
-
An array of file information
- $key : string = null
-
The index in the $file array to fetch from
- $index : string = null
-
The index in the $file array to fetch from (if a multi-upload file array)
- $overwrite : bool = true
-
Whether or not to overwrite the file if it already exists
- $file_name : string = null
-
The name of the file to use instead of the uploaded file's name, null to use uploaded file's name
- $rename_callback : callable = null
-
A callback to execute used to rename the file
- $permissions : int = 0644
-
The permission value in octets, null to default to user permissions
Return values
bool —True if the file was written, false otherwise