File Handling Helper
Handles uploads, manipulations and (external) storage
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); $factory = new \Czim\FileHandling\Storage\File\StorableFileFactory($helper, $interpreter, $downloader); $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.
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) ) );
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
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.
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.
watermark(string): full path to the watermark image.
The watermark should be a PNG (transparent) image for best results.
ImageOptimizationStrategyOptimizes 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:
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
Included strategies for video manipulation:
VideoScreenshotStrategy: Extracts a video frame for a preview.
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 by
ffmpeg(string): path to ffmpeg binary (if not
ffprobe(string): path to ffprobe binary (if not
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
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.
Configuration of file handling is set by injecting an associative array with a tree structure into the FileHandler.
Please see CONTRIBUTING for details.
The MIT License (MIT). Please see License File for more information.