PHP-FileUpload
Simple and convenient file uploads — secure by default
Requirements
- PHP 5.6.0+
Installation
-
Include the library via Composer [?]:
$ composer require delight-im/file-upload -
Include the Composer autoloader:
require __DIR__ . '/vendor/autoload.php';
-
Set up your HTML form for the file upload, e.g.:
<form action="" method="post" enctype="multipart/form-data"> <input type="hidden" name="MAX_FILE_SIZE" value="1048576"> <input type="file" name="my-input-name"> <button type="submit">Upload</button> </form>
The two attributes
method="post"andenctype="multipart/form-data"on the<form>element are mandatory. Likewise, there must be at least one<input type="file">element with a propernameattribute. Finally, some way to submit the form, e.g. the<button type="submit">element, is required. The hidden input namedMAX_FILE_SIZEis an optional hint for the client.
Usage
File uploads
$upload = new \Delight\FileUpload\FileUpload();
$upload->withTargetDirectory('/my-app/users/' . $userId . '/avatars');
$upload->from('my-input-name');
try {
$uploadedFile = $upload->save();
// success
// $uploadedFile->getFilenameWithExtension()
// $uploadedFile->getFilename()
// $uploadedFile->getExtension()
// $uploadedFile->getDirectory()
// $uploadedFile->getPath()
// $uploadedFile->getCanonicalPath()
}
catch (\Delight\FileUpload\Throwable\InputNotFoundException $e) {
// input not found
}
catch (\Delight\FileUpload\Throwable\InvalidFilenameException $e) {
// invalid filename
}
catch (\Delight\FileUpload\Throwable\InvalidExtensionException $e) {
// invalid extension
}
catch (\Delight\FileUpload\Throwable\FileTooLargeException $e) {
// file too large
}
catch (\Delight\FileUpload\Throwable\UploadCancelledException $e) {
// upload cancelled
}Limiting the maximum permitted file size
$upload->withMaximumSizeInBytes(4194304);
// or
$upload->withMaximumSizeInKilobytes(4096);
// or
$upload->withMaximumSizeInMegabytes(4);Reading the maximum permitted file size
// e.g. int(4194304)
$upload->getMaximumSizeInBytes();
// or
// e.g. int(4096)
$upload->getMaximumSizeInKilobytes();
// or
// e.g. int(4)
$upload->getMaximumSizeInMegabytes();Restricting the allowed file types or extensions
$upload->withAllowedExtensions([ 'jpeg', 'jpg', 'png', 'gif' ]);Note: By default, a set of filename extensions is used that is relatively safe for PHP applications and common on the web. This may be sufficient for some use cases.
Reading the allowed file types or extensions
// e.g. array(4) { [0]=> string(4) "jpeg" [1]=> string(3) "jpg" [2]=> string(3) "png" [3]=> string(3) "gif" }
$upload->getAllowedExtensionsAsArray();
// or
// e.g. string(16) "jpeg,jpg,png,gif"
$upload->getAllowedExtensionsAsMachineString();
// or
// e.g. string(19) "JPEG, JPG, PNG, GIF"
$upload->getAllowedExtensionsAsHumanString();
// or
// e.g. string(21) "JPEG, JPG, PNG or GIF"
$upload->getAllowedExtensionsAsHumanString(' or ');Reading the target directory
// e.g. string(24) "/my-app/users/42/avatars"
$upload->getTargetDirectory();Defining the target filename
$upload->withTargetFilename('my-picture');Note: By default, a random filename will be used, which is sufficient (and desired) in many cases.
Reading the target filename
// e.g. string(10) "my-picture"
$upload->getTargetFilename();Reading the name of the input field
// e.g. string(13) "my-input-name"
$upload->getSourceInputName();Base64 uploads
$upload = new \Delight\FileUpload\Base64Upload();
$upload->withTargetDirectory('/my-app/users/' . $userId . '/avatars');
$upload->withData($_POST['my-base64']);
try {
$uploadedFile = $upload->save();
// success
// $uploadedFile->getFilenameWithExtension()
// $uploadedFile->getFilename()
// $uploadedFile->getExtension()
// $uploadedFile->getDirectory()
// $uploadedFile->getPath()
// $uploadedFile->getCanonicalPath()
}
catch (\Delight\FileUpload\Throwable\InputNotFoundException $e) {
// input not found
}
catch (\Delight\FileUpload\Throwable\InvalidFilenameException $e) {
// invalid filename
}
catch (\Delight\FileUpload\Throwable\InvalidExtensionException $e) {
// invalid extension
}
catch (\Delight\FileUpload\Throwable\FileTooLargeException $e) {
// file too large
}
catch (\Delight\FileUpload\Throwable\UploadCancelledException $e) {
// upload cancelled
}Limiting the maximum permitted file size
$upload->withMaximumSizeInBytes(4194304);
// or
$upload->withMaximumSizeInKilobytes(4096);
// or
$upload->withMaximumSizeInMegabytes(4);Reading the maximum permitted file size
// e.g. int(4194304)
$upload->getMaximumSizeInBytes();
// or
// e.g. int(4096)
$upload->getMaximumSizeInKilobytes();
// or
// e.g. int(4)
$upload->getMaximumSizeInMegabytes();Defining the filename extension
$upload->withFilenameExtension('png');Note: This defines the filename extension of the file to be uploaded, which is a property of the FileUpload instance. It does not change the extension of any file already uploaded, which would be represented in a File instance. By default, the filename extension bin for arbitrary (binary) data will be used, which may be sufficient in some cases.
Reading the filename extension
// e.g. string(3) "png"
$upload->getFilenameExtension();Note: This retrieves the filename extension of the file to be uploaded, which is a property of the FileUpload instance. It does not read the extension of any file already uploaded, which would be represented in a File instance.
Reading the target directory
// e.g. string(24) "/my-app/users/42/avatars"
$upload->getTargetDirectory();Defining the target filename
$upload->withTargetFilename('my-picture');Note: By default, a random filename will be used, which is sufficient (and desired) in many cases.
Reading the target filename
// e.g. string(10) "my-picture"
$upload->getTargetFilename();Reading the Base64 data
// e.g. string(20) "SGVsbG8sIFdvcmxkIQ=="
$upload->getData();Data URI uploads
$upload = new \Delight\FileUpload\DataUriUpload();
$upload->withTargetDirectory('/my-app/users/' . $userId . '/avatars');
$upload->withUri($_POST['my-data-uri']);
try {
$uploadedFile = $upload->save();
// success
// $uploadedFile->getFilenameWithExtension()
// $uploadedFile->getFilename()
// $uploadedFile->getExtension()
// $uploadedFile->getDirectory()
// $uploadedFile->getPath()
// $uploadedFile->getCanonicalPath()
}
catch (\Delight\FileUpload\Throwable\InputNotFoundException $e) {
// input not found
}
catch (\Delight\FileUpload\Throwable\InvalidFilenameException $e) {
// invalid filename
}
catch (\Delight\FileUpload\Throwable\InvalidExtensionException $e) {
// invalid extension
}
catch (\Delight\FileUpload\Throwable\FileTooLargeException $e) {
// file too large
}
catch (\Delight\FileUpload\Throwable\UploadCancelledException $e) {
// upload cancelled
}Limiting the maximum permitted file size
$upload->withMaximumSizeInBytes(4194304);
// or
$upload->withMaximumSizeInKilobytes(4096);
// or
$upload->withMaximumSizeInMegabytes(4);Reading the maximum permitted file size
// e.g. int(4194304)
$upload->getMaximumSizeInBytes();
// or
// e.g. int(4096)
$upload->getMaximumSizeInKilobytes();
// or
// e.g. int(4)
$upload->getMaximumSizeInMegabytes();Restricting the allowed MIME types and extensions
$upload->withAllowedMimeTypesAndExtensions([
'image/jpeg' => 'jpg',
'image/png' => 'png',
'image/gif' => 'gif'
]);Note: By default, a set of MIME types is used that is relatively safe for PHP applications and common on the web. This may be sufficient for some use cases.
Reading the allowed MIME types and extensions
// e.g. array(3) { [0]=> string(10) "image/jpeg" [1]=> string(9) "image/png" [2]=> string(9) "image/gif" }
$upload->getAllowedMimeTypesAsArray();
// or
// e.g. string(30) "image/jpeg,image/png,image/gif"
$upload->getAllowedMimeTypesAsMachineString();
// or
// e.g. string(32) "image/jpeg, image/png, image/gif"
$upload->getAllowedMimeTypesAsHumanString();
// or
// e.g. string(34) "image/jpeg, image/png or image/gif"
$upload->getAllowedMimeTypesAsHumanString(' or ');
// or
// e.g. array(3) { [0]=> string(3) "jpg" [1]=> string(3) "png" [2]=> string(3) "gif" }
$upload->getAllowedExtensionsAsArray();
// or
// e.g. string(11) "jpg,png,gif"
$upload->getAllowedExtensionsAsMachineString();
// or
// e.g. string(13) "JPG, PNG, GIF"
$upload->getAllowedExtensionsAsHumanString();
// or
// e.g. string(15) "JPG, PNG or GIF"
$upload->getAllowedExtensionsAsHumanString(' or ');Reading the target directory
// e.g. string(24) "/my-app/users/42/avatars"
$upload->getTargetDirectory();Defining the target filename
$upload->withTargetFilename('my-picture');Note: By default, a random filename will be used, which is sufficient (and desired) in many cases.
Reading the target filename
// e.g. string(10) "my-picture"
$upload->getTargetFilename();Reading the data URI
// e.g. string(43) "data:text/plain;base64,SGVsbG8sIFdvcmxkIQ=="
$upload->getUri();Contributing
All contributions are welcome! If you wish to contribute, please create an issue first so that your feature, problem or question can be discussed.
License
This project is licensed under the terms of the MIT License.