czim / file-handling
File Handling Helper
Installs: 520 123
Dependents: 1
Suggesters: 0
Security: 1
Stars: 14
Watchers: 2
Forks: 9
Open Issues: 3
Requires
- php: >=7.1.0
- ext-curl: *
- imagine/imagine: ^1.2
- myclabs/php-enum: ^1.4
- psr/container: ^1.0|^2.0
- symfony/http-foundation: ^3.0|^4.0|^5.0|^6.0|^7.0
Requires (Dev)
- illuminate/contracts: *
- mikey179/vfsstream: ^1.6
- mockery/mockery: 0.9.*|^1.0
- php-coveralls/php-coveralls: ^2.1
- php-ffmpeg/php-ffmpeg: ^0.9.5|^1.0.0
- phpunit/phpunit: ^7.0|^8.0|^9.0
Suggests
- league/flysystem-aws-s3-v3: Required for AWS S3 file storage
- php-ffmpeg/php-ffmpeg: Required for video conversion and thumbnail generation
- spatie/image-optimizer: Required to use the image optimizer variant strategy
This package is auto-updated.
Last update: 2024-10-16 10:06:01 UTC
README
File Handling and Storage Helper
Handles uploads, manipulations and (external) storage
Changelog
Usage
This package is framework-independent.
Here's an example of how to set up variant processing in general:
<?php // Set up a storage implementation (for your framework of choice), and a PSR-11 container implementation. /** @var \Czim\FileHandling\Contracts\Storage\StorageInterface $storage */ /** @var \Psr\Container\ContainerInterface $container */ $sourcePath = 'storage/input-file-name.jpg'; // Source File $helper = new \Czim\FileHandling\Support\Content\MimeTypeHelper; $interpreter = new \Czim\FileHandling\Support\Content\UploadedContentInterpreter; $downloader = new \Czim\FileHandling\Support\Download\UrlDownloader($helper); $validator = new \Czim\FileHandling\Support\Download\UriValidator(); $factory = new \Czim\FileHandling\Storage\File\StorableFileFactory( $helper, $interpreter, $downloader, $validator ); $file = $factory->makeFromLocalPath($sourcePath); // Handler $strategyFactory = new \Czim\FileHandling\Variant\VariantStrategyFactory($container); $strategyFactory->setConfig([ 'aliases' => [ 'resize' => \Czim\FileHandling\Variant\Strategies\ImageResizeStrategy::class, 'autoOrient' => \Czim\FileHandling\Variant\Strategies\ImageAutoOrientStrategy::class, ], ]); $processor = new \Czim\FileHandling\Variant\VariantProcessor($factory, $strategyFactory); $handler = new \Czim\FileHandling\Handler\FileHandler($storage, $processor); $handler->process($file, new Target($file->path()), [ 'variants' => [ 'tiny' => [ 'autoOrient' => [], 'resize' => [ 'dimensions' => '30x30', ], ], 'orient' => [ 'autoOrient' => [ 'quiet' => false, ], ], ], ]);
For Laravel, you could use the following framework specific storage implementation:
<?php // Storage $storage = new \Czim\FileHandling\Storage\Laravel\LaravelStorage( \Storage::disk('testing'), true, url('testing') ); // If you're using a Laravel version that does not have a PSR-11 compliant container yet: $container = new \Czim\FileHandling\Support\Container\LaravelContainerDecorator(app()); app()->bind(\Imagine\Image\ImagineInterface::class, \Imagine\Gd\Imagine::class);
It is recommended of course to use the dependency container / IoC solution of your framework to simplify the above approach.
Custom Container
If you don't have a feasible PSR-11 container available, you can use a very simple implementation provided with this package.
<?php $container = new \Czim\FileHandling\Support\Container\SimpleContainer; $container->registerInstance( \Czim\FileHandling\Variant\Strategies\ImageResizeStrategy::class, new \Czim\FileHandling\Variant\Strategies\ImageResizeStrategy( new \Czim\FileHandling\Support\Image\Resizer( new \Imagine\Gd\Imagine ) ) ); $container->registerInstance( \Czim\FileHandling\Variant\Strategies\ImageAutoOrientStrategy::class, new \Czim\FileHandling\Variant\Strategies\ImageAutoOrientStrategy( new \Czim\FileHandling\Support\Image\OrientationFixer(new \Imagine\Gd\Imagine) ) );
Storage
Files can be stored using customizable storage implementations.
A very simple adapter/decorator for the Laravel storage is provided.
For any other framework/setup you will (for now) have to write your own implementation of the \Czim\FileHandling\Contracts\Storage\StorageInterface
.
Variants
When a file is processed, variants can be created automatically and stored along with the original.
These can be resizes, crops or recolors of the original image. This package is set up to allow you to easily create your own strategies for making variants.
A single variant is defined by one or more strategy steps, making it possible to combine effects and re-use strategies.
Variants can be re-created from the original.
Note that it this package is designed to easily create and add in custom variant strategies. Consider the source code for the strategies listed below examples to get you started.
Image Strategies
Included strategies for image manipulation:
-
ImageAutoOrientStrategy
: Re-orients rotated or flipped images. -
ImageResizeStrategy
: Resizes (and crops) images.
(Uses Stapler's options & approach to resizes.) -
ImageWatermarkStrategy
: Pastes a watermark onto an image.
In any corner or the center.
Options:
position
(string):top-left
,top-right
,center
,bottom-left
,bottom-right
.
watermark
(string): full path to the watermark image.
The watermark should be a PNG (transparent) image for best results. -
ImageOptimizationStrategy
Optimizes images to decreate their file size.This strategy requires installation of spatie/image-optimizer.
In order for it to work, you'll need to install a few image optimizers as well:
jpegoptim
optipng
pngquant
svgo
gifsicle
Installation example for Ubuntu:
sudo apt-get install jpegoptim optipng pngquant gifsicle sudo npm install -g svgo
Installation example for MacOS, using Homebrew:
brew install jpegoptim optipng pngquant svgo gifsicle
Video Strategies
Included strategies for video manipulation:
VideoScreenshotStrategy
: Extracts a video frame for a preview.
(Requiresffmpeg
/ffprobe
).
Options:
seconds
(int): the second of video runtime to take the shot at.
percentage
(int): the percentage of video runtime to take the shot at (overruled byseconds
).ffmpeg
(string): path to ffmpeg binary (if not/usr/bin/ffmpeg
).ffprobe
(string): path to ffprobe binary (if not/usr/bin/ffprobe
).
Variant Gotcha
When using the resize strategy while working with potentially EXIF-rotated images, keep in mind that portrait/landscape width/height only resizes may run into trouble unless they are auto-oriented first.
For this reason, it is recommended to precede the ImageResizeStrategy
by the ImageAutoOrientStrategy
.
In general, it is always a good idea to consider the order in which strategies are applied.
You may also opt to combine multiple strategies into one strategy class, if efficiency is important. You may use this approach to prevent opening/saving the same file more than once.
Handling URI content
In previous versions, this package automatically retrieved content from raw string content with URIs to local or remote files. This has now been disabled by default to minimize security risks.
For more information on this change, see SECURITY for more information.
Configuration
Configuration of file handling is set by injecting an associative array with a tree structure into the FileHandler.
Contributing
Please see CONTRIBUTING for details.
Credits
License
The MIT License (MIT). Please see License File for more information.