PHPackages atk4/filestore - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Framework](/categories/framework) 4. / 5. atk4/filestore ActiveLibrary[Framework](/categories/framework) atk4/filestore ============== Integration between ATK UI Form Upload Field and PHP Flysystem 5.0.0(2y ago)926.0k8[5 issues](https://github.com/atk4/filestore/issues)[1 PRs](https://github.com/atk4/filestore/pulls)1MITPHPPHP >=7.4 <8.4 Since Aug 13Pushed 1y ago8 watchersCompare [ Source](https://github.com/atk4/filestore)[ Packagist](https://packagist.org/packages/atk4/filestore)[ Docs](https://github.com/atk4/filestore)[ RSS](/packages/atk4-filestore/feed)WikiDiscussions develop Synced 3w ago READMEChangelog (5)Dependencies (10)Versions (6)Used By (1) Starting from Version 1.4 of ATK UI, it adds support for File and Image uploads. In it's raw form, developer is responsible for taking care of the file once it's uploaded. In most cases, developer would want to store file either on a local or remote filesystem, but he would need to perform that action himself. **Filestore** is a plugin for ATK Data and ATK UI which offers seamless integration with Flysystem. Introduction ------------ [](#introduction) Attaching files to your database records is super-simple with **Filestore**. The next example can be implemented and added to YOUR php application in just a few lines: [![upload1](docs/images/demo.gif)](docs/images/demo.gif) Since ATK Form submits using AJAX file must be sent to the server as soon as it is selected. File is instantly placed inside **flysystem** (in the demo I'm using Local storage) and record in the database is created containing all the information about the file including if it is an image and if it is - dimensions: [![upload1](docs/images/table.png)](docs/images/table.png) Two random identifiers are generated - one is used for the actual file name (to make sure you don't overwrite existing file) and another one (token) will be used to reference the file. Actually you don't see a token at all, but it's used to keep things secure. Files can be uploaded directly in your CRUD and you can have several file fields: [![upload1](docs/images/crud.png)](docs/images/crud.png) In your main table you only need one `varchar` field to store file token. If you use SQL, you can have instant access to additional fields such as name of original file or more: [![upload1](docs/images/refs.png)](docs/images/refs.png) This is especially valuable if you need to incorporate all these fields on your custom template. Installation and Code ===================== [](#installation-and-code) To install run `composer require atk4\filestore` and you will need to create `filestore_file` table. In the definition of your model, you simply need to declare a new field: ``` $this->addField('file', [\Atk4\Filestore\Field\FileField::class, 'flysystem' => $this->getApp()->filesystem]); ``` This pretty much takes care of everything! For full example see file `demos/basic.php`. Features ======== [](#features) Currently the following features are implemented: - Nice file upload UI and full integration with ATK UI Form. Upload tracking with a progress-bar. - Keep files clean, removing record also removes linked files. Files uploaded but not linked remain in status "draft" you can clean them up periodically - Supports any storage through integration with flysystem. - Very flexible, use different table, map fields differently, use multiple locations, add custom actions and much more. - Files can be scoped under "user\_id" for further security (user won't be able to access images of another user even if he knows a token). Roadmap ======= [](#roadmap) We have the following ideas for the up-coming version. If you would like to help us implement (or sponsor) any of the features below, please contact @romaninsh (): - Ability to specify which extensions and/or file types to accept. - Easy to download file, that was previously uploaded. - Add automatic thumbnail creation. Delete thumbnails together with original image. - Specify custom actions for Upload, Link, Unlink and Delete. - Display icon for file type or preview for image - Add interactive cropping. - Add method to verify file. - Add drag&drop uploading. - Add new View for a big drop-target or use arbitrary view (upload without form). - Add a UI for "file management" - Add support for re-croping thumbnails from originals. - Integrate NoSQL persistence support. - Encrypt file before storing / decrypt when loading. - Add option for "hashing" file into subdirectories. --- OLD README: event, so file upload will take place as soon as the file is selected. There are however some conditions, when file uploaded/deleted and form is not submitted. On successful completion, PHP-side callback is executed to generate **ID**. **Filestore** provides this callback and performs the following actions: - Collect information about the file - original filename, size, mime type etc. - Store information inside "File" model generating ID. - Move file into Flysystem by using a randomized name, recording it also in "File" model. - Respond with File's ID which is then passed back into form' submission handler. Example ------- [](#example) If you have a Model such as `Friend` and you wish to upload friend's photo, Filestore offers a great way to integrate: ``` // in Friend::init(); $this->addField('photo_file_token', [\Atk4\Filestore\Field\FileField::class]); ``` This field will automatically appear on the form as an upload field, but in the database will be storing "token" from the "File" model. You can even define multiple fields like that. By default the local file storage will be used, but you can configure a different location simply by passing into your field: ``` $this->addField('photo_file_token', [ \Atk4\Filestore\Field\FileField::class, // specify if you want to only accept certain types of files or extensions. 'onlyTypes' => ['image/*', 'application/x-pdf'], 'onlyExtensions' => ['img', 'png', 'pdf'], // safer to specify both // where to store 'flysystem' => $flysystem, // you can also define callback if you wish to do something more with the file 'onUpload' => function ($file) { // do something with file }, // this is called when form with the file is submitted 'onAttach' => function ($file) { // $file is a model object }, // when user detaches file from the related entity 'onDetach' => function ($file) { // $file is a model object }, ]) ``` If you open form for the `Friend` which already have a file attached, you will be able to remove the files. However just "removing" files may not mean they will be unassociated, user can still click "Cancel". When form is saved, however, if the file was removed, it will be also deleted from the storage and from `File` table. Image ----- [](#image) Filestore also implements `\Atk4\Filestore\Field\Image` class which offers additional features by extending File to automatically crop and store various thumbnails for an image. ``` $this->addField('picture_id', [ \Atk4\Filestore\Field\Image::class, // no need to specify types, will only accept valid images // where to store 'flysystem' => $flysystem, // you can still define this if you wish to pre-process your file, e.g. add watermark 'onUpload' => function ($file) { // do something with file }, // cropping table 'crop' => [ 'medium' => [200, 300], // width, height 'small' => [50, 50], ], ]) ``` The cropping will maintain aspect ratio of original image, but will make sure that the image is filled. Will use either "imagick" or "gd" for the operation. Arguments are defined like that: - `0 => 200`, width - `1 => height`, height - `'type' => 'jpeg'` optional. Defaults to 'png' In order to store thumbnails, filestore will create additional file(s) inside `File` table. File model ---------- [](#file-model) Filestore comes with a custom Model `Atk4\Filestore\Model\File`, which is designed to store file meta-information. For each uploaded file it stores: - file\_token - generated randomly, used on a form to pass back to submission handler - location - (used to identify file in Flysystem. Generated randomly) - storage - (short info on the storage used) - source\_file\_id (specify ID of the original file. Used for thumbnails or other generated files) - status (defines where is file currently) Several "meta" fields are also defined which describe contents of the file - meta\_filename - meta\_extension - meta\_md5 - meta\_mime\_type - meta\_size - meta\_is\_image - meta\_image\_width - meta\_image\_height ### Methods [](#methods) ``` $file->createFromPath('path/to/file.txt', 'my_file.txt'); ``` Create a `File` entity, save the data to `flysystem` and save the entity. ``` $stream = $file->getStream(); ``` Returns stream of file contents. You can call `$stream->getContents()` to fetch the file content as a string. Roadmap ------- [](#roadmap-1) Some of the possible future features: - Add "temporary" location for files - Allow option to initialize Flysystem details when loading random file through model ### Health Score 43 — FairBetter than 90% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity30 Limited adoption so far Community22 Small or concentrated contributor base Maturity84 Battle-tested with a long release history Bus Factor2 2 contributors hold 50%+ of commits How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~513 days Total 5 Last Release 817d ago Major Versions 0.2.0 → 2.4.02021-07-12 2.4.0 → 3.1.02021-12-29 3.1.0 → 5.0.02024-03-28 PHP version history (4 changes)0.1.0PHP >=5.6.0 2.4.0PHP >=7.2 3.1.0PHP >=7.4 <8.2 5.0.0PHP >=7.4 <8.4 ### Community Maintainers ![](https://www.gravatar.com/avatar/426ad318d07e7685454f7e449a9d0c9f005b83aef0777558d97d854ff9c28a5a?d=identicon)[romaninsh](/maintainers/romaninsh) --- Top Contributors [![romaninsh](https://avatars.githubusercontent.com/u/453929?v=4)](https://github.com/romaninsh "romaninsh (15 commits)")[![mvorisek](https://avatars.githubusercontent.com/u/2228672?v=4)](https://github.com/mvorisek "mvorisek (13 commits)")[![DarkSide666](https://avatars.githubusercontent.com/u/1969119?v=4)](https://github.com/DarkSide666 "DarkSide666 (9 commits)")[![mkrecek234](https://avatars.githubusercontent.com/u/28671486?v=4)](https://github.com/mkrecek234 "mkrecek234 (8 commits)")[![abbadon1334](https://avatars.githubusercontent.com/u/5801824?v=4)](https://github.com/abbadon1334 "abbadon1334 (5 commits)")[![2kodes](https://avatars.githubusercontent.com/u/2084398?v=4)](https://github.com/2kodes "2kodes (1 commits)")[![szepeviktor](https://avatars.githubusercontent.com/u/952007?v=4)](https://github.com/szepeviktor "szepeviktor (1 commits)") --- Tags agileatk4filestorephpuploadFlysystemframeworkimagedataAgileuploadatk4agile uifilestore ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/atk4-filestore/health.svg) ``` [![Health](https://phpackages.com/badges/atk4-filestore/health.svg)](https://phpackages.com/packages/atk4-filestore) ``` ### Alternatives [laravel/framework The Laravel Framework. 34.8k532.1M19.4k](/packages/laravel-framework)[shopware/platform The Shopware e-commerce core 3.4k1.5M3](/packages/shopware-platform)[atk4/login Login and User module for Agile UI 2518.5k5](/packages/atk4-login)[tempest/framework The PHP framework that gets out of your way. 2.2k31.1k12](/packages/tempest-framework)[atk4/mastercrud Multi-level CRUD system component for ATK UI 109.7k](/packages/atk4-mastercrud)[atk4/chart Chart.js for Agile UI 1214.2k](/packages/atk4-chart) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)