Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/czim/file-handling
File Handling Helper
https://github.com/czim/file-handling
file-handling paperclip storage upload
Last synced: 5 days ago
JSON representation
File Handling Helper
- Host: GitHub
- URL: https://github.com/czim/file-handling
- Owner: czim
- License: mit
- Created: 2017-07-24T20:28:22.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-09-16T10:03:49.000Z (3 months ago)
- Last Synced: 2024-12-01T16:43:09.515Z (21 days ago)
- Topics: file-handling, paperclip, storage, upload
- Language: PHP
- Size: 317 KB
- Stars: 14
- Watchers: 2
- Forks: 9
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Security: SECURITY.md
Awesome Lists containing this project
README
[![Latest Version on Packagist][ico-version]][link-packagist]
[![Software License][ico-license]](LICENSE.md)
[](https://travis-ci.org/czim/file-handling)
[](https://coveralls.io/github/czim/file-handling?branch=master)
# File Handling and Storage Helper
Handles uploads, manipulations and (external) storage
## Changelog
[View the changelog](CHANGELOG.md).
## Usage
This package is framework-independent.
Here's an example of how to set up variant processing in general:
```php
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
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
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](https://github.com/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:
```bash
sudo apt-get install jpegoptim optipng pngquant gifsicle
sudo npm install -g svgo
```
Installation example for MacOS, using [Homebrew](https://brew.sh):
```bash
brew install jpegoptim optipng pngquant svgo gifsicle
```
#### Video Strategies
Included strategies for video manipulation:
- `VideoScreenshotStrategy`: Extracts a video frame for a preview.
(Requires `ffmpeg`/`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 by `seconds`).
`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](SECURITY.md) 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](CONTRIBUTING.md) for details.
## Credits
- [All Contributors][link-contributors]
## License
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
[ico-version]: https://img.shields.io/packagist/v/czim/file-handling.svg?style=flat-square
[ico-license]: https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square
[ico-downloads]: https://img.shields.io/packagist/dt/czim/file-handling.svg?style=flat-square
[link-packagist]: https://packagist.org/packages/czim/file-handling
[link-downloads]: https://packagist.org/packages/czim/file-handling
[link-author]: https://github.com/czim
[link-contributors]: ../../contributors