PHPackages besnovatyj/yii2-cms-upload - 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. besnovatyj/yii2-cms-upload ActiveYii2-extension[File & Storage](/categories/file-storage) besnovatyj/yii2-cms-upload ========================== Функционал загрузок для Yii2 CMS v1.0.2(2w ago)011↓66.7%3MITPHPPHP >=8.4 Since Jul 6Pushed 1mo agoCompare [ Source](https://github.com/besnovatyj/yii2-cms-upload)[ Packagist](https://packagist.org/packages/besnovatyj/yii2-cms-upload)[ RSS](/packages/besnovatyj-yii2-cms-upload/feed)WikiDiscussions master Synced 1w ago READMEChangelog (1)Dependencies (4)Versions (4)Used By (3) Upload Component — Система загрузки файлов ========================================== [](#upload-component--система-загрузки-файлов) Обзор ----- [](#обзор) Переработанная система загрузки файлов и изображений для Yii2 ActiveRecord. Один behavior для файлов и изображений. Чёткое разделение ответственностей. Структура --------- [](#структура) ``` upload/ ├── UploadBehavior.php — единый behavior, lifecycle-хуки модели ├── PathResolver.php — резолвинг шаблонов путей ├── NameGenerator.php — генерация и санитизация имён файлов ├── ThumbnailProfile.php — value object профиля превью ├── ThumbnailMode.php — enum режимов превью (crop/resize) ├── ThumbnailGenerator.php — генерация превью изображений ├── FileUploadException.php — исключение загрузки ├── UrlDownloader.php — скачивание файлов по URL ├── DownloadResult.php — value object результата скачивания └── Storage/ ├── StorageInterface.php — контракт хранилища ├── StorageException.php — исключение хранилища └── LocalStorage.php — локальная файловая система ``` Интеграция в проект ------------------- [](#интеграция-в-проект) ### 1. Регистрация компонента хранилища [](#1-регистрация-компонента-хранилища) Через DIC, смотри `\Besnovatyj\Upload\Bootstrap` ### 2. Обновление модели Profile [](#2-обновление-модели-profile) Было: ``` use common\components\upload\behaviors\ImageUploadBehavior; public function behaviors(): array { return [ [ 'class' => ImageUploadBehavior::class, 'attribute' => 'photo', 'filePath' => '@static/origin/users/[[attribute_user_id]]/[[id]].[[extension]]', 'fileUrl' => '@staticHostName/origin/users/[[attribute_user_id]]/[[id]].[[extension]]', 'thumbPath' => '@static/cache/users/[[attribute_user_id]]/[[profile]]_[[id]].[[extension]]', 'thumbUrl' => '@staticHostName/cache/users/[[attribute_user_id]]/[[profile]]_[[id]].[[extension]]', 'thumbs' => [ 'admin' => ['width' => 100, 'height' => 70], 'thumb' => ['width' => 370, 'height' => 370], ], ], ...parent::behaviors(), ]; } ``` Стало: ``` use Besnovatyj\Upload\heap\UploadBehavior; use Besnovatyj\Upload\heap\ThumbnailProfile; public function behaviors(): array { return [ 'photoUpload' => [ 'class' => UploadBehavior::class, 'attribute' => 'photo', 'pathTemplate' => 'origin/users/{attr.user_id}/{pk}.{extension}', 'thumbnails' => [ new ThumbnailProfile('admin', width: 100, height: 70), new ThumbnailProfile('thumb', width: 370, height: 370), ], 'thumbPathTemplate' => 'cache/users/{attr.user_id}/{profile}_{pk}.{extension}', ], ...parent::behaviors(), ]; } ``` ### 3. Обновление view-файлов и сервисов [](#3-обновление-view-файлов-и-сервисов) Методы получения URL: ``` // Было: $model->getImageFileUrl('photo'); $model->getThumbFileUrl('photo', 'admin'); $model->getUploadedFileUrl('photo'); $model->getUploadedFilePath('photo'); // Стало: $model->getUploadUrl('photo'); $model->getThumbUrl('photo', 'admin'); $model->getUploadPath('photo'); $model->getThumbPath('photo', 'admin'); ``` Все методы поддерживают fallback URL: ``` $model->getUploadUrl('photo', '/images/no-photo.png'); $model->getThumbUrl('photo', 'admin', '/images/no-photo-sm.png'); ``` ### 4. Удаление старых файлов [](#4-удаление-старых-файлов) После миграции удалить: - `app/common/components/upload/behaviors/FileUploadBehavior.php` - `app/common/components/upload/behaviors/ImageUploadBehavior.php` - `app/common/components/upload/behaviors/FileUploadException.php` - `app/common/components/upload/behaviors/TODO.MD` - `app/common/components/upload/behaviors/` (директория) - `app/common/components/upload/UploadFromUrl.php` - `app/common/components/upload/UploadFileFromUrl.php` ### 5. Поиск всех использований в проекте [](#5-поиск-всех-использований-в-проекте) Найти и обновить все файлы, ссылающиеся на старые классы: ``` grep -r "common\\\\components\\\\upload\\\\behaviors" app/ --include="*.php" grep -r "ImageUploadBehavior\|FileUploadBehavior" app/ --include="*.php" grep -r "getImageFileUrl\|getThumbFileUrl\|getUploadedFileUrl\|getUploadedFilePath" app/ --include="*.php" ``` --- Шаблоны путей ------------- [](#шаблоны-путей) Пути — относительные, без Yii-алиасов. Хранилище само добавляет `basePath` и `baseUrl`. ### Плейсхолдеры [](#плейсхолдеры) ПлейсхолдерОписаниеПример значения`{pk}`Primary key модели`42``{model}`Имя класса (lcfirst)`profile``{attribute}`Имя атрибута`photo``{extension}`Расширение файла`jpg``{filename}`Имя без расширения`my-photo``{basename}`Полное имя файла`my-photo.jpg``{profile}`Профиль превью`admin``{attr.xxx}`Значение атрибута модели`{attr.user_id}` → `5``{md5.xxx}`MD5 от атрибута модели`{md5.email}` → `ab12...`### Примеры [](#примеры) ``` // Файл документа 'pathTemplate' => 'documents/{attr.user_id}/{pk}.{extension}' // → documents/5/42.pdf // Изображение с превью 'pathTemplate' => 'origin/gallery/{attr.gallery_id}/{pk}.{extension}' 'thumbPathTemplate' => 'cache/gallery/{attr.gallery_id}/{profile}_{pk}.{extension}' // → origin/gallery/10/42.jpg // → cache/gallery/10/admin_42.jpg ``` --- Примеры конфигураций -------------------- [](#примеры-конфигураций) ### Простая загрузка файла (без превью) [](#простая-загрузка-файла-без-превью) ``` [ 'class' => UploadBehavior::class, 'attribute' => 'document', 'pathTemplate' => 'documents/{attr.user_id}/{pk}.{extension}', ] ``` ### Изображение с превью [](#изображение-с-превью) ``` use Besnovatyj\Upload\heap\ThumbnailProfile; use Besnovatyj\Upload\heap\ThumbnailMode; [ 'class' => UploadBehavior::class, 'attribute' => 'photo', 'pathTemplate' => 'origin/users/{attr.user_id}/{pk}.{extension}', 'generateName' => true, // уникальные имена 'thumbnails' => [ new ThumbnailProfile('small', width: 100, height: 100, mode: ThumbnailMode::Crop), new ThumbnailProfile('medium', width: 400, height: 300), new ThumbnailProfile('large', width: 800, height: 600, quality: 90), ], 'thumbPathTemplate' => 'cache/users/{attr.user_id}/{profile}_{pk}.{extension}', ] ``` ### Превью в webp/avif (параметр `format`) [](#превью-в-webpavif-параметр-format) Формат превью задаётся per-профильно и не зависит от формата оригинала: ``` 'thumbnails' => [ // формат оригинала (как раньше) new ThumbnailProfile('admin', width: 100, height: 70), // современный формат отдачи: энкодер + {extension} в пути превью станут webp new ThumbnailProfile('thumb', width: 370, height: 370, format: 'webp'), new ThumbnailProfile('hero', width: 1600, height: 900, format: 'avif', quality: 60), ], ``` Принципы: - **Оригинал не перекодируется** — `format` касается только превью (оригинал остаётся источником для регенерации и скачивания). - `format` определяет энкодер imagine/Imagick и подставляется в `{extension}` шаблона `thumbPathTemplate` — `getThumbUrl()` автоматически вернёт URL с новым расширением (`cache/users/5/thumb_1.webp`). - Поддерживаемые значения зависят от сборки Imagick: проверить — `php -r "print_r(Imagick::queryFormats('WEBP')); print_r(Imagick::queryFormats('AVIF'));"`. - `null` (дефолт) — прежнее поведение: формат оригинала. - Рекомендация: `webp` — безопасный дефолт для превью (поддержка браузерами ~98%); `avif` — точечно для тяжёлых изображений (энкодинг заметно дороже, поддержка ~95%). ### Кастомная генерация имени [](#кастомная-генерация-имени) ``` [ 'class' => UploadBehavior::class, 'attribute' => 'avatar', 'pathTemplate' => 'avatars/{pk}.{extension}', 'generateName' => fn(\yii\web\UploadedFile $file) => 'avatar_' . time(), 'deleteOnEmpty' => true, // удалять файл если атрибут очищен ] ``` ### Загрузка файла по URL [](#загрузка-файла-по-url) ``` use Besnovatyj\Upload\heap\UrlDownloader; $downloader = new UrlDownloader(timeout: 60); $result = $downloader->download( url: 'https://example.com/photo.jpg', allowedExtensions: ['jpg', 'png', 'webp'], maxSize: 5 * 1024 * 1024, // 5 MB ); // Использование результата в модели $model->photo = /* создать UploadedFile из $result->tempPath */; $model->save(); $result->cleanup(); // удалить временный файл ``` --- Разница со старой системой -------------------------- [](#разница-со-старой-системой) АспектБылоСталоКлассы behavior2 (наследование)1 (final, без наследования)Файловые операцииРазбросаны по behavior-амИзолированы в `LocalStorage`Резолвинг путей30-строчный regex callback`PathResolver` с `strtr()`Конфигурация превьюСырые массивы`ThumbnailProfile` (typed VO)Формат превьюТолько формат оригиналаPer-профильный `format` (webp/avif/…)Режим превьюМагическая строка `'thumbsType'``ThumbnailMode` enumДрайвер изображенийХардкод IMAGICK каждый вызовНастраивается в конструктореОбработка ошибок превьюНет (crash)try/catch на каждый профильСкачивание по URL2 дублирующихся класса1 класс `UrlDownloader`Пути в модели`@static/...`, `@staticHostName/...`Относительные, storage добавляет базуКонфиг в моделиfilePath + fileUrl + thumbPath + thumbUrlpathTemplate + thumbPathTemplate ### Health Score 43 — FairBetter than 89% of packages Maintenance93 Actively maintained with recent releases Popularity7 Limited adoption so far Community14 Small or concentrated contributor base Maturity53 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% 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 ~14 days Total 3 Last Release 19d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/4dab004c4cab25d241bbf453f63cb48e6226d00bd84f50315e735c257c4a1b40?d=identicon)[besnovatyj](/maintainers/besnovatyj) --- Top Contributors [![besnovatyj](https://avatars.githubusercontent.com/u/1440158?v=4)](https://github.com/besnovatyj "besnovatyj (5 commits)") --- Tags cmsuploadyii2Behavior ### Embed Badge ![Health badge](/badges/besnovatyj-yii2-cms-upload/health.svg) ``` [![Health](https://phpackages.com/badges/besnovatyj-yii2-cms-upload/health.svg)](https://phpackages.com/packages/besnovatyj-yii2-cms-upload) ``` ### Alternatives [craftcms/cms Craft CMS 3.6k3.7M3.4k](/packages/craftcms-cms)[skeeks/cms SkeekS CMS — control panel and tools based on php framework Yii2 13926.0k66](/packages/skeeks-cms)[mohorev/yii2-upload-behavior Upload behavior for Yii 2 128280.1k9](/packages/mohorev-yii2-upload-behavior)[demi/image Yii2 behavior for upload image to model 2115.4k](/packages/demi-image)[sjaakp/yii2-illustrated-behavior ActiveRecord Behavior with associated Widget for Yii2. 423.2k](/packages/sjaakp-yii2-illustrated-behavior)[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)