Download the PHP package oleg-chulakov-studio/yii2-filestorage without Composer
On this page you can find all versions of the php package oleg-chulakov-studio/yii2-filestorage. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download oleg-chulakov-studio/yii2-filestorage
More information about oleg-chulakov-studio/yii2-filestorage
Files in oleg-chulakov-studio/yii2-filestorage
Package yii2-filestorage
Short Description Upload and storage files.
License BSD-3-Clause
Informations about the package yii2-filestorage
FileStorage - загрузка и хранение файлов
Компонент позволяющий загружать и хранить файлы, генерировать thumbnails
изображений.
Возможности компонента:
resize
изображения- конвертирование в разные расширения
- наложение водяных меток
- генерирование изображений:
thumbnails
,cover
,contain
,widen
,heighten
от оригинального файла с различными настройками
На данной странице описано базовое использование и базовые настройки данного компонента. Остальное можно прочитать в следующих разделах:
- Слушатели
- Генерация изображений
- Генерация файлового пути
Установка
Чтобы установить компонент, нужно в composer.json
добавить следующие строки:
Или набрать команду:
Настройка
1) Выполнить миграции
Чтобы выполнить миграции нужно вызвать следующую комманду из корня приложения:
При выполнении миграции будет создана таблица file
со следующим содержимым:
, где
group_code
- код группыobject_id
- ID прикрепленного объектаobject_type
- Тип прикрепленного объектаori_name
- оригинальное название файлаori_extension
- оригинальное расширение файлаsys_file
- системное название файлаmime
- mime тип файлаsize
- размер файлаcreated_at
- дата создания файлаupdated_at
- дата обновления файла
2) Подключение компонента хранилища
В config/main.php
нужно настроить компоненты:
3) Подключение поведения модели
Система сохранения работает с помощью поведений, они ответственны за доставку файла модели. Данные поведения прикрепляются к моделям, в дальнейшем обрабатывают файл и прикрепляют файл в указанный атрибут модели.
Имеется два загрузочных поведения:
FileUploadBehavior
- поведение рассчитано на загрузку одного файлаFilesUploadBehavior
- поведение рассчитано на загрузку нескольких файлов.
Подключение поведения:
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
корректно настроенную параметрическую модель или свою реализацию параметрической модели.
Настройка слушателей
7) Пример реализации контроллера с загрузкой файла
В примере реализации контроллера с загрузкой файла можно увидеть метод использования функционала поведения. В результате чего будет получен и сохранен загружаемый файл.
8) Валидация обновляемого файла
Когда используется общая форма для добавления и редактирования данных для обхода валидации обязательности загрузки файла при редактировании, можно воспользоваться встроенным файловым валидатором, который воспринимает наличие наличие ранее загруженного файла и игнорирует обязательность ранее загруженного файла.
Подключение валидатора:
Изначально strict
, строгая проверка по типу объектов (UploadedInterface
- у загружаемого
и BaseFile
- у ранее загруженного), отключена, но ее можно легко включить добавив
в правила подключенного валидатора 'strict' => true
.
9) Миграции с загрузкой файлов
При разработке проектов порой приходится создавать новые миграции с таблицами
к которым должен быть прикреплен файл. Помимо того, что нужно создать саму таблицу
для удобства загружают сразу исходные изображения, то есть нужно осуществить
загрузку файла прямиком через миграцию. Для решения данной задачи нами был
разработан класс Migration
. Для использования нужно от него отнаследоваться.
Непосредственно в миграции появляется дополнительная функция $this->upload();
,
данная функция позволяет указать исходный путь к файлу и передать параметры
вроде группы, идентификатора объекта и типа объекта.
10) Расширение таблицы файла
Если в таблицу к файлу необходимо добавить дополнительные поля, такие как комментарий к каждому файлу, можно смело расширять исходную таблицу и внедрять в нее необходимые поля. Но в силу того, что компонент по умолчанию работает с базовым файлом и знает о модели только те данные, что он может получить из самого файла, то для реализации сохранения расширенных полей можно воспользоваться событием, которое сработает до или после сохранения модели в базу данных и, если это необходимо, указать собственный класс модели файла.
Все остальные примеры можно посмотреть в папке с примерами.
Тестирование
Реализовано базовое unit
тестирование.
Чтобы запустить тесты, нужно выполнить данную команду в корне компонента filestorage
:
Реализованы следующие тесты:
ObserverTest
- тестирование работоспособности событийной системы, а именно слушателя и наблюдателяUploadedFileTest
- тестирование репозитория базовой загрузкиRemoteUploadedFileTest
- тестирование репозитория удаленной загрузкиImageManagerTest
- тестирование менеджера работы с изображениямиThumbManagerTest
- тестирование менеджера для генерирования thumbnailImageContainer
- тестирование сервиса для работы с изображениямиPathServiceTest
- тестирование сервиса для работы с путямиUsageTest
- тестирование полной цепочки действий, от начала загрузки до обработки файлов
Также, во время тестирования происходит работа с тестовой базой данных, она
находится в /data/database/test.db
.