delight-im/file-upload

Simple and convenient file uploads — secure by default

PHP-FileUpload

Simple and convenient file uploads — secure by default, _(*1)

Requirements

• PHP 5.6.0+

Installation

1. Include the library via Composer [?]:, _(*2)

   $ composer require delight-im/file-upload
   

2. Include the Composer autoloader:, _(*3)

   require __DIR__ . '/vendor/autoload.php';
   

3. Set up your HTML form for the file upload, e.g.:, _(*4)

   <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" and enctype="multipart/form-data" on the <form> element are mandatory. Likewise, there must be at least one <input type="file"> element with a proper name attribute. Finally, some way to submit the form, e.g. the <button type="submit"> element, is required. The hidden input named MAX_FILE_SIZE is an optional hint for the client., _(*5)

Usage

• File uploads
  • Limiting the maximum permitted file size
  • Reading the maximum permitted file size
  • Restricting the allowed file types or extensions
  • Reading the allowed file types or extensions
  • Reading the target directory
  • Defining the target filename
  • Reading the target filename
  • Reading the name of the input field
• Base64 uploads
  • Limiting the maximum permitted file size
  • Reading the maximum permitted file size
  • Defining the filename extension
  • Reading the filename extension
  • Reading the target directory
  • Defining the target filename
  • Reading the target filename
  • Reading the Base64 data
• Data URI uploads
  • Limiting the maximum permitted file size
  • Reading the maximum permitted file size
  • Restricting the allowed MIME types and extensions
  • Reading the allowed MIME types and extensions
  • Reading the target directory
  • Defining the target filename
  • Reading the target filename
  • Reading the data URI

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., _(*6)

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., _(*7)

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., _(*8)

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., _(*9)

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., _(*10)

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., _(*11)

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., _(*12)

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., _(*13)

License

This project is licensed under the terms of the MIT License., _(*14)