PHPackages oleg-chulakov-studio/yii2-filestorage - 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. [File & Storage](/categories/file-storage) 4. / 5. oleg-chulakov-studio/yii2-filestorage ActiveYii2-components[File & Storage](/categories/file-storage) oleg-chulakov-studio/yii2-filestorage ===================================== Upload and storage files. 2.0.6(10mo ago)67.5k↓100%4[2 issues](https://github.com/OlegChulakovStudio/yii2-filestorage/issues)1BSD-3-ClausePHPPHP >=8.1.0 Since Apr 10Pushed 10mo ago6 watchersCompare [ Source](https://github.com/OlegChulakovStudio/yii2-filestorage)[ Packagist](https://packagist.org/packages/oleg-chulakov-studio/yii2-filestorage)[ RSS](/packages/oleg-chulakov-studio-yii2-filestorage/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (8)Dependencies (3)Versions (27)Used By (1) FileStorage - загрузка и хранение файлов ======================================== [](#filestorage---загрузка-и-хранение-файлов) Компонент позволяющий загружать и хранить файлы, генерировать `thumbnails` изображений. **Возможности компонента:** - `resize` изображения - конвертирование в разные расширения - наложение водяных меток - генерирование изображений: `thumbnails`, `cover`, `contain`, `widen`, `heighten`от оригинального файла с различными настройками На данной странице описано базовое использование и базовые настройки данного компонента. Остальное можно прочитать в следующих разделах: - [Слушатели](docs/listeners.md) - [Генерация изображений](docs/image-generation.md) - [Генерация файлового пути](docs/path-service.md) Установка --------- [](#установка) Чтобы установить компонент, нужно в `composer.json` добавить следующие строки: ``` "require": { "oleg-chulakov-studio/yii2-filestorage": "~1.0.11" } ``` Или набрать команду: ``` composer require oleg-chulakov-studio/yii2-filestorage ``` Настройка --------- [](#настройка) **1) Выполнить миграции** Для выполнения миграции нужно вызвать следующую команду из корня приложения: ``` php yii migrate/up --migrationPath=@vendor/oleg-chulakov-studio/yii2-filestorage/src/migrations ``` При выполнении миграции будет создана таблица `file` со следующим содержимым: ``` +---------------+------------------+------+-----+---------+----------------+ | Field | Type | Null | Key | Default | Extra | +---------------+------------------+------+-----+---------+----------------+ | id | int(11) | NO | PRI | NULL | auto_increment | | group_code | varchar(16) | NO | MUL | NULL | | | object_id | int(11) | YES | MUL | NULL | | | object_type | varchar(16) | YES | | NULL | | | ori_name | varchar(255) | NO | | NULL | | | ori_extension | varchar(16) | NO | | NULL | | | sys_file | varchar(255) | NO | UNI | NULL | | | mime | varchar(255) | NO | | NULL | | | size | int(11) unsigned | NO | | 0 | | | created_at | int(11) | NO | | NULL | | | updated_at | int(11) | NO | | NULL | | +---------------+------------------+------+-----+---------+----------------+ ``` **, где** - `group_code` - код группы - `object_id` - ID прикрепленного объекта - `object_type` - Тип прикрепленного объекта - `ori_name` - оригинальное название файла - `ori_extension` - оригинальное расширение файла - `sys_file` - системное название файла - `mime` - mime тип файла - `size` - размер файла - `created_at` - дата создания файла - `updated_at` - дата обновления файла **2) Подключение компонента хранилища** В `config/main.php` нужно настроить компоненты: ``` 'fileStorage' => [ 'class' => \chulakov\filestorage\FileStorage::class, 'storageBaseUrl' => false, // Базовый url 'storagePath' => '@webroot', // Путь сохранения 'storageDir' => 'uploaded', // Папка с сохраняемыми файлами 'fileMode' => 0755, // Уровень доступа к сохраняемым файлам 'storagePattern' => '{group}/{id}', // Корневой шаблон генерации пути сохранения файлов ], 'imageComponent' => [ 'class' => \chulakov\filestorage\ImageComponent::class, 'driver' => 'gd', // Базовые драйвера: gd и imagick ] ``` **3) Подключение поведения модели** Система сохранения работает с помощью поведений, они ответственны за доставку файла модели. Данные поведения прикрепляются к моделям, в дальнейшем обрабатывают файл и прикрепляют файл в указанный атрибут модели. **Имеется два загрузочных поведения:** - `FileUploadBehavior` - поведение рассчитано на загрузку одного файла - `FilesUploadBehavior` - поведение рассчитано на загрузку нескольких файлов. **Подключение поведения:** ``` public function behaviors() { return [ [ 'class' => \chulakov\filestorage\behaviors\FileUploadBehavior::class, // Поведение 'attribute' => 'image', // Атрибут модели 'group' => 'photos', // Сохраняемая группа 'type' => 'detail', // Тип файла в группе объектов 'fileStorage' => 'fileStorage', // Компонент хранения файлов 'repository' => \chulakov\filestorage\uploaders\UploadedFile::class, // Репозиторий ], ]; } ``` **4) Подключение репозиториев** К каждому поведению нужно настроить способ получения файла, а именно - настроить репозиторий. Доступные репозитории: - `UploadedFile` - загрузка обычных файлов(через POST запрос) - `RemoteUploadedFile` - загрузка удаленных файлов(через ссылку на файл) - `LocalUploadedFile` - загрузка локального файла (через указание абсолютного пути до файла) **5) Настройка репозиториев** Сам репозиторий основан на шаблоне `Observer`, то есть он имеет слушателя и наблюдателя: - `UploadedFile` - наблюдатель - `ImageManager` - слушатель В конечном итоге, весь компонент работает на событийной модели обработки и сохранения файлов. Реализуется такая цепочка: `получаем файл` -> `срабатывает событие` -> `производится обработка файла` -> `сохранение файла`. **6) Настройка слушателей** Слушатели подписываются на события наблюдателя, после чего каждый слушатель получает информацию о файле в момент сохранения файла. Каждый слушатель может производить над файлом свои действия, в результате чего производится видоизменение файла и различные побочные действия. Все слушатели должны реализовывать `ListenerInterface`, только так они могут подписаться на наблюдателя. **ImageManager** `ImageManager` работает с только изображениями, производит `resize`, накладывает `watermark`, меняет расширение и т.д. Он имеет следующие настройки: - `width` - ширина изображения - `height` - высота изображения - `encode` - расширение изображения - `quality` - качество изображения - `watermark` - путь на водяную метку - `watermarkPosition` - позиция водяной метки - `imageClass` - компонент работы с изображениями **ThumbManager** Все параметры по настройки `ThumbManager` аналогичны `ImageManager`. Каждая настройка применяется над файлом, после сохранения все данные настройки будут отображены на конечном сохраненном файле. Все сохраненные `thumbnail` сохраняются в отдельную папку под названием `thumbs`. Базовой путь до файлов подвержен структуре формирования пути: `'{relay}/{group}/{basename}/{type}_{width}x{height}.{ext}'` **, где:** - `relay` - полный `root` путь до группы - `group` - название сохраняемой группы - `basename` - базовое имя файла - `type` - тип изображения. Есть несколько базовых типов: `thumbs`, `cover`, `contain`, `widen`, `heighten`. - `width` - ширина - `height` - высота - `ext` - расширение файла Чтобы повлиять на алгоритм генерации пути, можно прокинуть в `imageParamsClass`корректно настроенную параметрическую модель или свою реализацию параметрической модели. **Настройка слушателей** ``` public function behaviors() { return [ [ 'class' => \chulakov\filestorage\behaviors\FileUploadBehavior::class, // подключаемое поведение 'attribute' => 'image', // атрибут, куда будет помещен файл 'group' => 'photos', // группа сохраняемого изображения 'type' => 'detail', // тип сохраняемого изображения в группе 'fileStorage' => 'fileStorage', // компонент хранения 'repository' => \chulakov\filestorage\uploaders\UploadedFile::class, // выбранный загрузчик 'repositoryOptions' => [ // опции репозитория 'listeners' => [ // список слушателей [ 'class' => ThumbsManager::class, // Класс слушателя 'width' => 640, // Ширина 'height' => 480, // Высота 'encode' => 'jpg', // Расширение 'quality' => 100, // Качество в процентах 'watermarkPath' => '/path/to/image/watermark.png', // Наложенная водяная метка 'watermarkPosition' => Position::CENTER, // Позиция водяной метки 'imageComponent' => 'imageComponent', // Имя компонента для работы изображениями ], [ 'class' => ImageManager::class, // Класс слушателя 'width' => 640, // Ширина 'height' => 480, // Высота 'encode' => 'jpg', // Расширение 'quality' => 100, // Качество в процентах 'watermarkPath' => '/path/to/image/watermark.png', // Наложенная водяная метка 'watermarkPosition' => Position::CENTER, // Позиция водяной метки 'imageComponent' => 'imageComponent', // Имя компонента для работы изображениями 'accessRole' => 'role_example', // Роль разрешенная для работы с изображениями ] ], ] ], ]; } ``` **7) Пример реализации контроллера с загрузкой файла** В примере реализации контроллера с загрузкой файла можно увидеть метод использования функционала поведения. В результате чего будет получен и сохранен загружаемый файл. ``` /** * Загрузка изображения через ajax запрос */ public function actionIndex() { $form = new FileForm(); // Инициализация формы $request = \Yii::$app->request; if ($request->isPost) { $form->load(\Yii::$app->request->post(), ''); // Загрузка параметров if ($form->validate() && $form->upload()) { // Валидация и загрузка файлов return json_encode(['success' => true]); // Выдача сообщения о успешной загрузки } } throw new NotUploadFileException('Файл не был загружен.'); } ``` **8) Валидация обновляемого файла** Когда используется общая форма для добавления и редактирования данных для обхода валидации обязательности загрузки файла при редактировании, можно воспользоваться встроенным файловым валидатором, который воспринимает наличие ранее загруженного файла и игнорирует обязательность ранее загруженного файла. Подключение валидатора: ``` public function rules() { return [ ['attachFile', FileValidator::class, 'targetAttribute' => 'attachedFile'], // ['attachFile', FileValidator::class, 'targetAttribute' => 'attachedFile', 'strict' => true], ]; } ``` Изначально `strict`, строгая проверка по типу объектов (`UploadedInterface` - у загружаемого и `BaseFile` - у ранее загруженного), отключена, но ее можно легко включить добавив в правила подключенного валидатора `'strict' => true`. **9) Миграции с загрузкой файлов** При разработке проектов порой приходится создавать новые миграции с таблицами к которым должен быть прикреплен файл. Помимо того, что нужно создать саму таблицу для удобства загружают сразу исходные изображения, то есть нужно осуществить загрузку файла прямиком через миграцию. Для решения данной задачи нами был разработан класс `Migration`. Для использования необходимо унаследоваться от этого класса. Непосредственно в миграции появляется дополнительная функция `$this->upload();`, данная функция позволяет указать исходный путь к файлу и передать параметры вроде группы, идентификатора объекта и типа объекта. ``` public function safeUp() { $params = new UploadParams('group'); $params->object_id = 123; $params->object_type = 'logo'; $this->upload('/path/to/file.png', $params); } ``` **10) Расширение таблицы файла** Если в таблицу к файлу необходимо добавить дополнительные поля, такие как комментарий к каждому файлу, можно смело расширять исходную таблицу и внедрять в нее необходимые поля. Но в силу того, что компонент по умолчанию работает с базовым файлом и знает о модели только те данные, что он может получить из самого файла, то для реализации сохранения расширенных полей можно воспользоваться событием, которое сработает до или после сохранения модели в базу данных и, если это необходимо, указать собственный класс модели файла. ``` public function behaviors() { return [ [ 'class' => \chulakov\filestorage\behaviors\FileUploadBehavior::class, 'attribute' => 'image', 'group' => 'photos', 'modelClass' => \common\model\MyFileModel::class, 'repositoryOptions' => [ 'events' => [ SaveModelEvent::BEFORE_MODEL_SAVE => [ [$this, 'fillModel'], ], ], ] ], ]; } public function fillModel(SaveModelEvent $event) { /** @var \common\model\MyFileModel $model **/ $model = $event->model; $model->comment = $this->comment; // или более безопасный способ if ($event->model->hasAttribute('comment')) { $event->model->setAttribute('comment', $this->comment); } } ``` Все остальные примеры можно посмотреть в [папке с примерами](examples). Тестирование ------------ [](#тестирование) Реализовано базовое `unit` тестирование. Чтобы запустить тесты, нужно выполнить данную команду в корне компонента `filestorage`: ``` ../bin/phpunit ``` **Реализованы следующие тесты:** - `ObserverTest` - тестирование работоспособности событийной системы, а именно слушателя и наблюдателя - `UploadedFileTest` - тестирование репозитория базовой загрузки - `RemoteUploadedFileTest` - тестирование репозитория удаленной загрузки - `ImageManagerTest` - тестирование менеджера работы с изображениями - `ThumbManagerTest` - тестирование менеджера для генерирования thumbnail - `ImageContainer` - тестирование сервиса для работы с изображениями - `PathServiceTest` - тестирование сервиса для работы с путями - `UsageTest` - тестирование полной цепочки действий, от начала загрузки до обработки файлов Также, во время тестирования происходит работа с тестовой базой данных, она находится в `/data/database/test.db`. ### Health Score 48 — FairBetter than 94% of packages Maintenance47 Moderate activity, may be stable Popularity27 Limited adoption so far Community21 Small or concentrated contributor base Maturity82 Battle-tested with a long release history Bus Factor1 Top contributor holds 59.5% of commits — single point of failure 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 ~119 days Recently: every ~13 days Total 23 Last Release 326d ago Major Versions 1.2.10 → 2.0.02025-04-25 PHP version history (2 changes)1.0.12PHP >=5.6.0 2.0.0PHP >=8.1.0 ### Community Maintainers ![](https://www.gravatar.com/avatar/a7cb11be37853072fe7ab807b40211e2c135bc04bf5c7c79d9c523dc4022ed2d?d=identicon)[Oleg Chulakov Studio](/maintainers/Oleg%20Chulakov%20Studio) --- Top Contributors [![Tzendos](https://avatars.githubusercontent.com/u/14998789?v=4)](https://github.com/Tzendos "Tzendos (234 commits)")[![ikchulakov](https://avatars.githubusercontent.com/u/32455466?v=4)](https://github.com/ikchulakov "ikchulakov (141 commits)")[![it-donnet](https://avatars.githubusercontent.com/u/92182969?v=4)](https://github.com/it-donnet "it-donnet (7 commits)")[![aleksandr-hlyncev](https://avatars.githubusercontent.com/u/201724266?v=4)](https://github.com/aleksandr-hlyncev "aleksandr-hlyncev (7 commits)")[![rodial](https://avatars.githubusercontent.com/u/17547603?v=4)](https://github.com/rodial "rodial (2 commits)")[![sem-soft](https://avatars.githubusercontent.com/u/6681346?v=4)](https://github.com/sem-soft "sem-soft (1 commits)")[![drag947](https://avatars.githubusercontent.com/u/66410937?v=4)](https://github.com/drag947 "drag947 (1 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/oleg-chulakov-studio-yii2-filestorage/health.svg) ``` [![Health](https://phpackages.com/badges/oleg-chulakov-studio-yii2-filestorage/health.svg)](https://phpackages.com/packages/oleg-chulakov-studio-yii2-filestorage) ``` ### Alternatives [unisharp/laravel-filemanager A file upload/editor intended for use with Laravel 5 to 10 and CKEditor / TinyMCE 2.2k3.3M74](/packages/unisharp-laravel-filemanager)[mihaildev/yii2-elfinder Yii2 ElFinder 169658.8k52](/packages/mihaildev-yii2-elfinder)[farhanshares/laravel-mediaman MediaMan - The most elegant & powerful media management package for Laravel! 293.7k](/packages/farhanshares-laravel-mediaman)[liyunfang/yii2-upload-behavior Upload behavior for Yii 2 161.7k](/packages/liyunfang-yii2-upload-behavior) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)