{"id":22125714,"url":"https://github.com/czim/file-handling","last_synced_at":"2026-02-26T07:20:55.408Z","repository":{"id":40643767,"uuid":"98232124","full_name":"czim/file-handling","owner":"czim","description":"File Handling Helper","archived":false,"fork":false,"pushed_at":"2024-09-16T10:03:49.000Z","size":325,"stargazers_count":14,"open_issues_count":3,"forks_count":9,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-13T12:49:10.349Z","etag":null,"topics":["file-handling","paperclip","storage","upload"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/czim.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-07-24T20:28:22.000Z","updated_at":"2024-09-16T10:01:23.000Z","dependencies_parsed_at":"2024-09-16T11:40:57.266Z","dependency_job_id":null,"html_url":"https://github.com/czim/file-handling","commit_stats":{"total_commits":190,"total_committers":13,"mean_commits":"14.615384615384615","dds":0.4368421052631579,"last_synced_commit":"f6e2ab8e52908e58779d76fdf103e13c52caf223"},"previous_names":[],"tags_count":41,"template":false,"template_full_name":null,"purl":"pkg:github/czim/file-handling","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/czim%2Ffile-handling","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/czim%2Ffile-handling/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/czim%2Ffile-handling/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/czim%2Ffile-handling/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/czim","download_url":"https://codeload.github.com/czim/file-handling/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/czim%2Ffile-handling/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259831457,"owners_count":22918513,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["file-handling","paperclip","storage","upload"],"created_at":"2024-12-01T16:37:18.058Z","updated_at":"2026-02-26T07:20:50.373Z","avatar_url":"https://github.com/czim.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Latest Version on Packagist][ico-version]][link-packagist]\n[![Software License][ico-license]](LICENSE.md)\n[![Build Status](https://travis-ci.org/czim/file-handling.svg?branch=master)](https://travis-ci.org/czim/file-handling)\n[![Coverage Status](https://coveralls.io/repos/github/czim/file-handling/badge.svg?branch=master)](https://coveralls.io/github/czim/file-handling?branch=master)\n\n\n# File Handling and Storage Helper\n\nHandles uploads, manipulations and (external) storage\n\n\n## Changelog\n\n[View the changelog](CHANGELOG.md).\n\n\n## Usage\n\nThis package is framework-independent.\n\nHere's an example of how to set up variant processing in general:\n\n```php\n\u003c?php\n    // Set up a storage implementation (for your framework of choice), and a PSR-11 container implementation.\n    /** @var \\Czim\\FileHandling\\Contracts\\Storage\\StorageInterface $storage */\n    /** @var \\Psr\\Container\\ContainerInterface $container */\n    \n    $sourcePath = 'storage/input-file-name.jpg';\n    \n\n    // Source File\n    $helper      = new \\Czim\\FileHandling\\Support\\Content\\MimeTypeHelper;\n    $interpreter = new \\Czim\\FileHandling\\Support\\Content\\UploadedContentInterpreter;\n    $downloader  = new \\Czim\\FileHandling\\Support\\Download\\UrlDownloader($helper);\n    $validator   = new \\Czim\\FileHandling\\Support\\Download\\UriValidator();\n    $factory     = new \\Czim\\FileHandling\\Storage\\File\\StorableFileFactory(\n        $helper,\n        $interpreter,\n        $downloader,\n        $validator\n    );\n\n    $file = $factory-\u003emakeFromLocalPath($sourcePath);\n\n    // Handler\n    $strategyFactory = new \\Czim\\FileHandling\\Variant\\VariantStrategyFactory($container);\n    $strategyFactory-\u003esetConfig([\n        'aliases' =\u003e [\n            'resize'     =\u003e \\Czim\\FileHandling\\Variant\\Strategies\\ImageResizeStrategy::class,\n            'autoOrient' =\u003e \\Czim\\FileHandling\\Variant\\Strategies\\ImageAutoOrientStrategy::class,\n        ],\n    ]);\n\n    $processor = new \\Czim\\FileHandling\\Variant\\VariantProcessor($factory, $strategyFactory);\n\n    $handler = new \\Czim\\FileHandling\\Handler\\FileHandler($storage, $processor);\n    \n    $handler-\u003eprocess($file, new Target($file-\u003epath()), [\n        'variants' =\u003e [\n            'tiny' =\u003e [\n                'autoOrient' =\u003e [],\n                'resize' =\u003e [\n                    'dimensions' =\u003e '30x30',\n                ],\n            ],\n            'orient' =\u003e [\n                'autoOrient' =\u003e [\n                    'quiet' =\u003e false,\n                ],\n            ],\n        ],\n    ]);\n``` \n\nFor Laravel, you could use the following framework specific storage implementation:\n\n```php\n\u003c?php\n    // Storage\n    $storage = new \\Czim\\FileHandling\\Storage\\Laravel\\LaravelStorage(\n        \\Storage::disk('testing'),\n        true,\n        url('testing')\n    );\n   \n    // If you're using a Laravel version that does not have a PSR-11 compliant container yet:\n    $container = new \\Czim\\FileHandling\\Support\\Container\\LaravelContainerDecorator(app());\n    \n    app()-\u003ebind(\\Imagine\\Image\\ImagineInterface::class, \\Imagine\\Gd\\Imagine::class);\n```\n\nIt is recommended of course to use the dependency container / IoC solution of your framework to simplify the above approach.\n\n\n### Custom Container \n\nIf you don't have a feasible PSR-11 container available, you can use a very simple implementation provided with this package.\n\n```php\n\u003c?php\n    $container = new \\Czim\\FileHandling\\Support\\Container\\SimpleContainer;\n    \n    $container-\u003eregisterInstance(\n        \\Czim\\FileHandling\\Variant\\Strategies\\ImageResizeStrategy::class,\n        new \\Czim\\FileHandling\\Variant\\Strategies\\ImageResizeStrategy(\n            new \\Czim\\FileHandling\\Support\\Image\\Resizer(\n                new \\Imagine\\Gd\\Imagine\n            )\n        )\n    );\n    $container-\u003eregisterInstance(\n        \\Czim\\FileHandling\\Variant\\Strategies\\ImageAutoOrientStrategy::class,\n        new \\Czim\\FileHandling\\Variant\\Strategies\\ImageAutoOrientStrategy(\n                new \\Czim\\FileHandling\\Support\\Image\\OrientationFixer(new \\Imagine\\Gd\\Imagine)\n            )\n    );\n```\n\n\n### Storage\n\nFiles can be stored using customizable storage implementations.\n\nA very simple adapter/decorator for the Laravel storage is provided.\nFor any other framework/setup you will (for now) have to write your own implementation of the `\\Czim\\FileHandling\\Contracts\\Storage\\StorageInterface`.  \n\n\n### Variants\n\nWhen a file is processed, variants can be created automatically and stored along with the original.\n\nThese can be resizes, crops or recolors of the original image.\nThis package is set up to allow you to easily create your own strategies for making variants.\n\nA single variant is defined by one or more strategy steps, making it possible to combine effects and re-use strategies.\n\nVariants can be re-created from the original.\n\n\nNote 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.\n\n\n#### Image Strategies\n\nIncluded strategies for image manipulation:\n\n- `ImageAutoOrientStrategy`: Re-orients rotated or flipped images.\n\n- `ImageResizeStrategy`: Resizes (and crops) images.  \n    (Uses Stapler's options \u0026 approach to resizes.)\n\n- `ImageWatermarkStrategy`: Pastes a watermark onto an image.  \n    In any corner or the center.  \n    Options:  \n    `position` (string): `top-left`, `top-right`, `center`, `bottom-left`, `bottom-right`.  \n    `watermark` (string): full path to the watermark image.  \n    The watermark should be a PNG (transparent) image for best results. \n\n- `ImageOptimizationStrategy` Optimizes images to decreate their file size.\n\n    This strategy requires installation of [spatie/image-optimizer](https://github.com/spatie/image-optimizer).\n    \n    In order for it to work, you'll need to install a few image optimizers as well:\n    - `jpegoptim`\n    - `optipng`\n    - `pngquant`\n    - `svgo`\n    - `gifsicle`\n   \n    Installation example for Ubuntu:\n\n    ```bash\n    sudo apt-get install jpegoptim optipng pngquant gifsicle\n    sudo npm install -g svgo\n    ```\n\n    Installation example for MacOS, using [Homebrew](https://brew.sh):\n\n    ```bash\n    brew install jpegoptim optipng pngquant svgo gifsicle\n    ```\n\n\n\n#### Video Strategies\n\nIncluded strategies for video manipulation:\n\n- `VideoScreenshotStrategy`: Extracts a video frame for a preview.  \n    (Requires `ffmpeg`/`ffprobe`).  \n    Options:  \n    `seconds` (int): the second of video runtime to take the shot at.  \n    `percentage` (int): the percentage of video runtime to take the shot at (overruled by `seconds`).\n    `ffmpeg` (string): path to ffmpeg binary (if not `/usr/bin/ffmpeg`).\n    `ffprobe` (string): path to ffprobe binary (if not `/usr/bin/ffprobe`).  \n\n \n### Variant Gotcha\n\nWhen 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.\n\nFor this reason, it is recommended to precede the `ImageResizeStrategy` by the `ImageAutoOrientStrategy`.\n\nIn general, it is always a good idea to consider the order in which strategies are applied.\n\nYou 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.\n\n### Handling URI content \n\nIn previous versions, this package automatically retrieved content from raw string content with URIs to local or remote files.\nThis has now been disabled by default to minimize security risks.\n\nFor more information on this change, see [SECURITY](SECURITY.md) for more information.\n \n## Configuration\n\nConfiguration of file handling is set by injecting an associative array with a tree structure into the FileHandler.\n\n\n## Contributing\n\nPlease see [CONTRIBUTING](CONTRIBUTING.md) for details.\n\n\n## Credits\n\n- [All Contributors][link-contributors]\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n\n[ico-version]: https://img.shields.io/packagist/v/czim/file-handling.svg?style=flat-square\n[ico-license]: https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square\n[ico-downloads]: https://img.shields.io/packagist/dt/czim/file-handling.svg?style=flat-square\n\n[link-packagist]: https://packagist.org/packages/czim/file-handling\n[link-downloads]: https://packagist.org/packages/czim/file-handling\n[link-author]: https://github.com/czim\n[link-contributors]: ../../contributors\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fczim%2Ffile-handling","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fczim%2Ffile-handling","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fczim%2Ffile-handling/lists"}