devinow/upload

Devinow Framework File Upload Library,Simple and convenient file uploads — secure by default.

4.0.0 2023-08-04 14:46 UTC

Requires

• php: >=8.1.0

MIT

• Devinow

• file
• form
• upload
• validation
• files
• input

README

composer require devinow/upload

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 \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();