README

Компонент позволяющий загружать и хранить файлы, генерировать thumbnails изображений.

Возможности компонента:

resize изображения
конвертирование в разные расширения
наложение водяных меток
генерирование изображений: thumbnails, cover, contain, widen, heighten от оригинального файла с различными настройками

На данной странице описано базовое использование и базовые настройки данного компонента. Остальное можно прочитать в следующих разделах:

Установка

Чтобы установить компонент, нужно в 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);
    }
}

Все остальные примеры можно посмотреть в папке с примерами.

Тестирование

Реализовано базовое unit тестирование.

Чтобы запустить тесты, нужно выполнить данную команду в корне компонента filestorage:

../bin/phpunit

Реализованы следующие тесты:

ObserverTest - тестирование работоспособности событийной системы, а именно слушателя и наблюдателя
UploadedFileTest - тестирование репозитория базовой загрузки
RemoteUploadedFileTest - тестирование репозитория удаленной загрузки
ImageManagerTest - тестирование менеджера работы с изображениями
ThumbManagerTest - тестирование менеджера для генерирования thumbnail
ImageContainer - тестирование сервиса для работы с изображениями
PathServiceTest - тестирование сервиса для работы с путями
UsageTest - тестирование полной цепочки действий, от начала загрузки до обработки файлов

Также, во время тестирования происходит работа с тестовой базой данных, она находится в /data/database/test.db.

oleg-chulakov-studio / yii2-filestorage

Maintainers

Details

README

Установка

Настройка

Тестирование