gravitypdf/upload

Handle file uploads with extensible validation and storage strategies

3.0.1 2022-12-11 23:50 UTC

Requires

• php: ^7.3 || ~8.0.0 || ~8.1.0 || ~8.2.0
• ext-fileinfo: *

Requires (Dev)

• php-parallel-lint/php-parallel-lint: ^1.3
• phpstan/phpstan: ^1.8
• squizlabs/php_codesniffer: *
• yoast/phpunit-polyfills: ^1.0

Replaces

• codeguy/upload: 1.3.2

MIT

• Josh Lockhart
• Gravity PDF

• file
• upload
• validation

README

This component simplifies file validation and uploading.

Why was this library forked?

• Original library was abandoned (untouched since 2018)
• Adjusted namespace from \Upload to \GravityPdf\Upload
• Bumped minimum PHP version to 7.3+
• Sanitized filename and extension, and add UTF-8 filename support
• Strict type checking
• Added FileSystem::getDirectory() and FileInfo::setNameWithExtension() methods
• Included unreleased code from upstream repo
• PSR-12 Code Formatting
• Automated tools: PHPUnit, PHPStan, PHPCS, and PHP Syntax Checker

TODO: PSR-7 and PSR-17 support (help wanted)

Installation

composer require gravitypdf/upload

Usage

Assume a file is uploaded with this HTML form:

<form method="POST" enctype="multipart/form-data">
    <input type="file" name="foo" value=""/>
    <input type="submit" value="Upload File"/>
</form>

When the HTML form is submitted, the server-side PHP code can validate and upload the file like this:

$storage = new \GravityPdf\Upload\Storage\FileSystem('/path/to/directory');
// To override existing files when uploading, pass `true` as the second parameter
// $storage = new \GravityPdf\Upload\Storage\FileSystem('/path/to/directory', true);
$file = new \GravityPdf\Upload\File('foo', $storage);

// Validate file upload
// MimeType List => http://www.iana.org/assignments/media-types/media-types.xhtml
$file->addValidations([
    // Ensure file is of type "image/png"
    new \GravityPdf\Upload\Validation\Mimetype('image/png'),
    new \GravityPdf\Upload\Validation\Extension('png'),

    //You can also add multi mimetype validation or extensions
    //new \GravityPdf\Upload\Validation\Mimetype(['image/png', 'image/gif'])
    //new \GravityPdf\Upload\Validation\Extension(['png', 'gif']),

    // Ensure file is no larger than 5M (use "B", "K", M", or "G")
    new \GravityPdf\Upload\Validation\Size('5M'),
]);

// Access data about the file
// If upload accepts multiple files an array will be returned for each of these
$data = [
    'name' => $file->getNameWithExtension(),
    'extension' => $file->getExtension(),
    'mime' => $file->getMimetype(),
    'size' => $file->getSize(),
    'md5' => $file->getMd5(),
    'dimensions' => $file->getDimensions(),
];

// If you have an upload field that accepts multiple files you can access each file's info individually
$firstFileName = $file[0]->getNameWithExtension();
if(isset($file[1])) {
    $secondFileName = $file[1]->getNameWithExtension();
}

// or loop over all files for this key
foreach($file as $i => $upload) {
    $name = $upload->getNameWithExtension();
    $upload->setName('file-'.$i);
}

// Try to upload file(s)
try {
    // Success!
    $file->upload();
} catch (\Exception $e) {
    // Validation errors
    $errors = $file->getErrors();
    if(count($errors) === 0) {
        // Failed for another reason, like the file already exists
        $error = $e->getMessage();
    }
}

Authors

• Josh Lockhart
• Gravity PDF

License

MIT Public License