2017 © Pedro Peláez
 

library fileupload

File uploading library capable of handling large/chunked/multiple file uploads

image

gargron/fileupload

File uploading library capable of handling large/chunked/multiple file uploads

  • Saturday, March 31, 2018
  • by Gargron
  • Repository
  • 28 Watchers
  • 315 Stars
  • 81,962 Installations
  • PHP
  • 9 Dependents
  • 1 Suggesters
  • 61 Forks
  • 2 Open issues
  • 21 Versions
  • 10 % Grown

The README.md

FileUpload

Build Status, (*1)

PHP FileUpload library that supports chunked uploads. Adopted from the procedural script included with [jQuery-File-Upload][1], designed to work with that JavaScript plugin, with normal forms, and to be embeddable into any application/architecture., (*2)

Installing

This package is available via Composer:, (*3)

{
  "require": {
    "gargron/fileupload": "~1.4.0"
  }
}

Requirements

  • Ensure that the PHP extension "php_fileinfo" is enabled;, (*4)

  • Your php.ini must have the next directive:, (*5)

file_uploads = On, (*6)

Status

The unit test suite covers simple uploads and the library "works on my machine", as it were. You are welcome to contribute., (*7)

You can grep the source code for TODO to find things you could help finishing., (*8)

Usage

// Simple validation (max file size 2MB and only two allowed mime types)
$validator = new FileUpload\Validator\Simple('2M', ['image/png', 'image/jpg']);

// Simple path resolver, where uploads will be put
$pathresolver = new FileUpload\PathResolver\Simple('/my/uploads/dir');

// The machine's filesystem
$filesystem = new FileUpload\FileSystem\Simple();

// FileUploader itself
$fileupload = new FileUpload\FileUpload($_FILES['files'], $_SERVER);

// Adding it all together. Note that you can use multiple validators or none at all
$fileupload->setPathResolver($pathresolver);
$fileupload->setFileSystem($filesystem);
$fileupload->addValidator($validator);

// Doing the deed
list($files, $headers) = $fileupload->processAll();

// Outputting it, for example like this
foreach($headers as $header => $value) {
    header($header . ': ' . $value);
}

echo json_encode(['files' => $files]);

foreach($files as $file){
    //Remeber to check if the upload was completed
    if ($file->completed) {
        echo $file->getRealPath();

        // Call any method on an SplFileInfo instance
        var_dump($file->isFile());
    }
}

Alternative usage via factory

$factory = new FileUploadFactory(
    new PathResolver\Simple('/my/uploads/dir'), 
    new FileSystem\Simple(), 
    [
        new FileUpload\Validator\MimeTypeValidator(['image/png', 'image/jpg']),
        new FileUpload\Validator\SizeValidator('3M', '1M') 
        // etc
    ]
);

$instance = $factory->create($_FILES['files'], $_SERVER);

Validators

There are currently 4 validators shipped with FileUpload:, (*9)

  • Simple, (*10)

    // Simple validation (max file size 2MB and only two allowed mime types)
    $validator = new FileUpload\Validator\Simple('2M', ['image/png', 'image/jpg']);
    
    
  • MimeTypeValidator, (*11)

    $mimeTypeValidator = new FileUpload\Validator\MimeTypeValidator(['image/png', 'image/jpg']);
    
  • SizeValidator, (*12)

    // The 1st parameter is the maximum size while the 2nd is the minimum size
    $sizeValidator = new FileUpload\Validator\SizeValidator('3M', '1M');
    
  • DimensionValidator, (*13)

    $config = [
      'width' => 400,
      'height' => 500
    ]; 
    // Can also contain 'min_width', 'max_width', 'min_height' and 'max_height'
    
    $dimensionValidator = new FileUpload\Validator\DimensionValidator($config);
    

Remember to register new validator(s) by $fileuploadInstance->addValidator($validator);, (*14)

If you want you can use the common human readable format for filesizes like '1M', '1G', just pass the string as the first argument., (*15)

$validator = new FileUpload\Validator\Simple('10M', ['image/png', 'image/jpg']);

Here is a listing of the possible values (B => B; KB => K; MB => M; GB => G). These values are binary convention so basing on 1024., (*16)

FileNameGenerator

With the FileNameGenerator you have the possibility to change the filename the uploaded files will be saved as., (*17)

$fileupload = new FileUpload\FileUpload($_FILES['files'], $_SERVER);
$filenamegenerator = new FileUpload\FileNameGenerator\Simple();
$fileupload->setFileNameGenerator($filenamegenerator);
  • Custom
$customGenerator = new FileUpload\FileNameGenerator\Custom($provider);
//$provider can be a string (in which case it is returned as is)
//It can also be a callable or a closure which receives arguments in the other of $source_name, $type, $tmp_name, $index, $content_range, FileUpload $upload
  • MD5
$md5Generator = new FileUpload\FileNameGenerator\MD5($allowOverride);
//$allowOverride should be a boolean. A true value would overwrite the file if it exists while a false value would not allow the file to be uploaded since it already exists.
  • Random
$randomGenerator = new FileUpload\FileNameGenerator\Random($length);
//Where $length is the maximum length of the generator random name

  • Simple
$simpleGenerator = new FileUpload\FileNameGenerator\Simple();
//Saves a file by it's original name

  • Slug
$slugGenerator = new FileUpload\FileNameGenerator\Slug();
//This generator slugifies the name of the uploaded file(s)

Remember to register new validator(s) by $fileuploadInstance->setFileNameGenerator($generator);, (*18)

Every call to setFileNameGenerator overrides the currently set $generator, (*19)

Callbacks

Currently implemented events:, (*20)

  • completed
$fileupload->addCallback('completed', function(FileUpload\File $file) {
    // Whoosh!
});
  • beforeValidation
$fileUploader->addCallback('beforeValidation', function (FileUpload\File $file) {
    // About to validate the upload;
});
  • afterValidation
$fileUploader->addCallback('afterValidation', function (FileUpload\File $file) {
    // Yay, we got only valid uploads
});

Extending

The reason why the path resolver, the validators and the file system are abstracted, is so you can write your own, fitting your own needs (and also, for unit testing). The library is shipped with a bunch of "simple" implementations which fit the basic needs. You could write a file system implementation that works with Amazon S3, for example., (*21)

License

Licensed under the MIT license, see LICENSE file., (*22)

The Versions

31/03 2018

dev-master

9999999-dev

File uploading library capable of handling large/chunked/multiple file uploads

  Sources   Download

MIT

The Development Requires

05/08 2017

dev-next

dev-next

File upload and validation library.....

  Sources   Download

MIT

The Requires

  • php ~7.0

 

The Development Requires

upload php7 file upload

19/05 2017

v1.4.5

1.4.5.0

File uploading library capable of handling large/chunked/multiple file uploads

  Sources   Download

MIT

The Development Requires

12/04 2017

v1.4.4

1.4.4.0

File uploading library capable of handling large/chunked/multiple file uploads

  Sources   Download

MIT

The Development Requires

17/03 2017

v1.4.3

1.4.3.0

File uploading library capable of handling large/chunked/multiple file uploads

  Sources   Download

MIT

The Development Requires

16/03 2017

v1.4.2

1.4.2.0

File uploading library capable of handling large/chunked/multiple file uploads

  Sources   Download

MIT

The Development Requires

16/03 2017

dev-hot-fix

dev-hot-fix

File uploading library capable of handling large/chunked/multiple file uploads

  Sources   Download

MIT

The Development Requires

20/02 2017

v1.4.1

1.4.1.0

File uploading library capable of handling large/chunked/multiple file uploads

  Sources   Download

MIT

The Development Requires

24/01 2017

v1.4.0

1.4.0.0

File uploading library capable of handling large/chunked/multiple file uploads

  Sources   Download

MIT

The Development Requires

22/01 2017

v1.3.0

1.3.0.0

File uploading library capable of handling large/chunked/multiple file uploads

  Sources   Download

MIT

The Development Requires

05/12 2016

v1.2.1

1.2.1.0

File uploading library capable of handling large/chunked/multiple file uploads

  Sources   Download

MIT

The Development Requires

02/12 2016

v1.2.0

1.2.0.0

File uploading library capable of handling large/chunked/multiple file uploads

  Sources   Download

MIT

The Development Requires

01/12 2016

dev-revert-31-master

dev-revert-31-master

File uploading library capable of handling large/chunked/multiple file uploads

  Sources   Download

MIT

The Development Requires

30/08 2016

v1.1.2

1.1.2.0

File uploading library capable of handling large/chunked/multiple file uploads

  Sources   Download

MIT

The Development Requires

13/02 2016

v1.1.1

1.1.1.0

File uploading library capable of handling large/chunked/multiple file uploads

  Sources   Download

MIT

The Development Requires

14/12 2014

v1.1.0

1.1.0.0

File uploading library capable of handling large/chunked/multiple file uploads

  Sources   Download

MIT

The Development Requires

20/02 2014

dev-development

dev-development

File uploading library capable of handling large/chunked/multiple file uploads

  Sources   Download

MIT

The Development Requires

20/02 2014

v1.0.2

1.0.2.0

File uploading library capable of handling large/chunked/multiple file uploads

  Sources   Download

MIT

The Development Requires

29/09 2013

v1.0.1

1.0.1.0

File uploading library capable of handling large/chunked/multiple file uploads

  Sources   Download

MIT

The Development Requires

19/09 2013

v1.0.0

1.0.0.0

File uploading library capable of handling large/chunked/multiple file uploads

  Sources   Download

MIT

The Development Requires

25/08 2013

v0.1

0.1.0.0

File uploading library capable of handling large/chunked/multiple file uploads

  Sources   Download

MIT

The Development Requires