PHPackages ochen-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. ochen-studio/yii2-filestorage ActiveYii2-components ochen-studio/yii2-filestorage ============================= Upload and storage files. 1.1.0(yesterday)04↑2900%BSD-3-ClausePHP >=5.6.0 Since Jul 19Compare [ Source](https://github.com/ochen-studio/yii2-filestorage)[ Packagist](https://packagist.org/packages/ochen-studio/yii2-filestorage)[ RSS](/packages/ochen-studio-yii2-filestorage/feed)WikiDiscussions Synced today READMEChangelog (1)Dependencies (2)Versions (2)Used By (0) FileStorage - загрузка и хранение файлов ======================================== [](#filestorage---загрузка-и-хранение-файлов) Компонент позволяющий загружать и хранить файлы, генерировать `thumbnails` изображений. **Возможности компонента:** - `resize` изображения - конвертирование в разные расширения - наложение водяных меток - генерирование изображений: `thumbnails`, `cover`, `contain`, `widen`, `heighten`от оригинального файла с различными настройками На данной странице описано базовое использование и базовые настройки данного компонента. Остальное можно прочитать в следующих разделах: - [Слушатели](docs/listeners.md) - [Генерация изображений](docs/image-generation.md) - [Генерация файлового пути](docs/path-service.md) Установка --------- [](#установка) Чтобы установить компонент, нужно в `composer.json` добавить следующие строки: ``` "require": { "ochen-studio/yii2-filestorage": "~1.0.11" } ``` Или набрать команду: ``` composer require ochen-studio/yii2-filestorage ``` Настройка --------- [](#настройка) **1) Выполнить миграции** Чтобы выполнить миграции нужно вызвать следующую комманду из корня приложения: ``` php yii migrate/up --migrationPath=@vendor/ochen-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' => \ochen\filestorage\FileStorage::class, 'storageBaseUrl' => false, // Базовый url 'storagePath' => '@webroot', // Путь сохранения 'storageDir' => 'uploaded', // Папка с сохраняемыми файлами 'fileMode' => 0755, // Уровень доступа к сохраняемым файлам 'storagePattern' => '{group}/{id}', // Корневой шаблон генерации пути сохранения файлов ], 'imageComponent' => [ 'class' => \ochen\filestorage\ImageComponent::class, 'driver' => 'gd', // Базовые драйвера: gd и imagick ] ``` **3) Подключение поведения модели** Система сохранения работает с помощью поведений, они ответственны за доставку файла модели. Данные поведения прикрепляются к моделям, в дальнейшем обрабатывают файл и прикрепляют файл в указанный атрибут модели. **Имеется два загрузочных поведения:** - `FileUploadBehavior` - поведение рассчитано на загрузку одного файла - `FilesUploadBehavior` - поведение рассчитано на загрузку нескольких файлов. **Подключение поведения:** ``` public function behaviors() { return [ [ 'class' => \ochen\filestorage\behaviors\FileUploadBehavior::class, // Поведение 'attribute' => 'image', // Атрибут модели 'group' => 'photos', // Сохраняемая группа 'type' => 'detail', // Тип файла в группе объектов 'fileStorage' => 'fileStorage', // Компонент хранения файлов 'repository' => \ochen\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' => \ochen\filestorage\behaviors\FileUploadBehavior::class, // подключаемое поведение 'attribute' => 'image', // атрибут, куда будет помещен файл 'group' => 'photos', // группа сохраняемого изображения 'type' => 'detail', // тип сохраняемого изображения в группе 'fileStorage' => 'fileStorage', // компонент хранения 'repository' => \ochen\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' => \ochen\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 35 — LowBetter than 77% of packages Maintenance100 Actively maintained with recent releases Popularity5 Limited adoption so far Community2 Small or concentrated contributor base Maturity28 Early-stage or recently created project 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 Unknown Total 1 Last Release 1d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/dcffe61920f733d1fb64833d8ae28e644b3a310750f5a911986f68749cd2182c?d=identicon)[support@ochen.team](/maintainers/support@ochen.team) ### Embed Badge ![Health badge](/badges/ochen-studio-yii2-filestorage/health.svg) ``` [![Health](https://phpackages.com/badges/ochen-studio-yii2-filestorage/health.svg)](https://phpackages.com/packages/ochen-studio-yii2-filestorage) ``` ### Alternatives [craftcms/cms Craft CMS 3.6k3.6M3.2k](/packages/craftcms-cms)[unopim/unopim UnoPim Laravel PIM 10.5k2.4k](/packages/unopim-unopim)[october/rain October Rain Library 1601.7M87](/packages/october-rain)[code16/sharp Laravel Content Management Framework 79164.7k9](/packages/code16-sharp)[skeeks/cms SkeekS CMS — control panel and tools based on php framework Yii2 13825.8k63](/packages/skeeks-cms)[symfony/ux-cropperjs Cropper.js integration for Symfony 19346.6k3](/packages/symfony-ux-cropperjs) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)