devinow / upload
Devinow Framework File Upload Library,Simple and convenient file uploads — secure by default.
Requires
- php: >=8.1.0
README
composer require devinow/upload
Usage
File uploads
$upload = new \Devinow\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 (\Devinow\FileUpload\Throwable\InputNotFoundException $e) { // input not found } catch (\Devinow\FileUpload\Throwable\InvalidFilenameException $e) { // invalid filename } catch (\Devinow\FileUpload\Throwable\InvalidExtensionException $e) { // invalid extension } catch (\Devinow\FileUpload\Throwable\FileTooLargeException $e) { // file too large } catch (\Devinow\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 \Devinow\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 (\Devinow\FileUpload\Throwable\InputNotFoundException $e) { // input not found } catch (\Devinow\FileUpload\Throwable\InvalidFilenameException $e) { // invalid filename } catch (\Devinow\FileUpload\Throwable\InvalidExtensionException $e) { // invalid extension } catch (\Devinow\FileUpload\Throwable\FileTooLargeException $e) { // file too large } catch (\Devinow\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 \Devinow\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 (\Devinow\FileUpload\Throwable\InputNotFoundException $e) { // input not found } catch (\Devinow\FileUpload\Throwable\InvalidFilenameException $e) { // invalid filename } catch (\Devinow\FileUpload\Throwable\InvalidExtensionException $e) { // invalid extension } catch (\Devinow\FileUpload\Throwable\FileTooLargeException $e) { // file too large } catch (\Devinow\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();