letoceiling-coder/media

Laravel Media Manager Package - управление медиа-файлами с поддержкой папок, корзины, фильтрации, Vue компонентов и многоязычности

1.3.1 2025-12-06 18:44 UTC

Requires

• php: ^8.2
• laravel/framework: ^12.0

Requires (Dev)

• phpunit/phpunit: ^11.5

MIT

• LetoCeiling Coder

• media
• upload
• laravel
• file-manager
• media-manager
• folders

README

Пакет для управления медиа-файлами в Laravel с поддержкой папок, корзины, фильтрации, многопользовательского режима, Vue компонентов и многоязычности.

Версия: 1.2.0 | Laravel: >= 12.0 | PHP: >= 8.2

Возможности

• 📁 Управление папками - создание, редактирование, удаление папок с поддержкой иерархии
• 📄 Загрузка файлов - поддержка изображений, видео, документов и других типов файлов
• 🗑️ Корзина - мягкое удаление файлов и папок с возможностью восстановления
• 🔍 Фильтрация и поиск - поиск по имени, фильтрация по типу, расширению, папке
• 👥 Многопользовательский режим - изоляция файлов по пользователям с поддержкой общих папок
• 📊 Пагинация - настраиваемая пагинация для больших списков
• 🔐 Безопасность - защита системных папок, валидация типов файлов
• 🎨 Vue компоненты - готовые Vue 3 компоненты для управления медиа-файлами с drag & drop, превью, редактированием изображений
• 🌍 Многоязычность - поддержка 8 языков (ru, en, fr, it, de, ko, zh, es) для Vue компонентов

Требования

• PHP >= 8.2
• Laravel >= 12.0
• MySQL/MariaDB или PostgreSQL

Установка

Через Composer

composer require letoceiling-coder/media

Публикация конфигурации

php artisan vendor:publish --tag=media-config

Публикация миграций

php artisan vendor:publish --tag=media-migrations

Публикация системных изображений

Системные изображения автоматически копируются при установке пакета. Для ручного копирования используйте:

php artisan media:publish-assets

Или стандартную команду Laravel:

php artisan vendor:publish --tag=media-assets

Публикация Vue компонентов

Пакет включает Vue компоненты для управления медиа-файлами. Для их публикации используйте:

php artisan vendor:publish --tag=media-vue-components

Компоненты будут скопированы в resources/js/vendor/media/, включая:

• Компоненты (components/)
• Утилиты (utils/)
• Composables (composables/)
• Переводы (locales/) - поддержка 8 языков

Важно: После публикации компонентов вам нужно:

1. Установить зависимости: npm install fslightbox-vue vue-advanced-cropper sweetalert2
2. Адаптировать пути импорта под структуру вашего проекта
3. См. подробные инструкции в файле VUE_COMPONENTS.md
4. См. документацию по переводам в файле I18N.md

Для принудительного копирования (перезаписать существующие):

php artisan vendor:publish --tag=media-vue-components --force
php artisan media:publish-assets --force

Запуск миграций

php artisan migrate

Конфигурация

После публикации конфигурации файл будет доступен в config/media.php.

Важно: Если вы получили ошибку Auth guard [api] is not defined, см. раздел Настройка авторизации ниже.

Основные настройки:

Загрузка файлов

'upload' => [
    'max_size' => 10240, // Максимальный размер в KB (10 МБ)
    'allowed_mime_types' => [...], // Разрешенные MIME типы
    'allowed_extensions' => [...], // Разрешенные расширения
    'allow_all_types' => false, // Разрешить все типы файлов
],

Безопасность

'security' => [
    'require_auth' => true, // Требовать авторизацию
    'auth_guard' => 'api', // Guard для авторизации (api, sanctum, web)
    'middleware' => ['api'], // Middleware для роутов
    'allow_delete' => true, // Разрешить удаление
    'allow_edit' => true, // Разрешить редактирование
    'allow_move' => true, // Разрешить перемещение
],

Важно: Если вы получили ошибку Auth guard [api] is not defined, см. раздел Настройка авторизации ниже.

Хранилище

'storage' => [
    'disk' => 'public', // Диск для хранения
    'upload_path' => 'upload', // Путь для загрузки
    'folder_images_path' => 'system', // Путь к системным изображениям
],

Настройка авторизации

Важно: Пакет автоматически определяет доступные guard'ы и использует подходящий. Если вы получили ошибку Auth guard [api] is not defined, выполните одно из следующих действий:

Вариант 1: Настройте guard 'api' в config/auth.php

// config/auth.php
'guards' => [
    'api' => [
        'driver' => 'sanctum', // или 'token', 'passport'
        'provider' => 'users',
    ],
],

Вариант 2: Измените guard в config/media.php

// config/media.php
'security' => [
    'require_auth' => true,
    'auth_guard' => 'sanctum', // или 'web'
    'middleware' => ['api'], // или ['web']
],

Вариант 3: Отключите авторизацию (только для тестирования)

// config/media.php
'security' => [
    'require_auth' => false,
],

Пакет автоматически попробует использовать guard'ы в следующем порядке:

1. Указанный в auth_guard (по умолчанию api)
2. sanctum (если доступен)
3. web (если доступен)
4. Стандартный auth middleware (если ни один guard не найден)

Подробные инструкции см. в CONFIGURATION.md

Использование

API Endpoints

Папки

• GET /api/folders - Список папок
• POST /api/folders - Создать папку
• GET /api/folders/{id} - Информация о папке
• PUT /api/folders/{id} - Обновить папку
• DELETE /api/folders/{id} - Удалить папку
• POST /api/folders/{id}/restore - Восстановить папку
• GET /api/folders/tree/all - Дерево папок
• POST /api/folders/update-positions - Обновить позиции

Медиа-файлы

• GET /api/media - Список файлов
• POST /api/media - Загрузить файл
• GET /api/media/{id} - Информация о файле
• PUT /api/media/{id} - Обновить файл
• DELETE /api/media/{id} - Удалить файл
• POST /api/media/{id}/restore - Восстановить файл
• DELETE /api/media/trash/empty - Очистить корзину

Примеры использования

Загрузка файла

use LetoCeilingCoder\Media\Models\Media;
use LetoCeilingCoder\Media\Models\Folder;

// Загрузка через API
POST /api/media
Content-Type: multipart/form-data

file: [файл]
folder_id: 1 (опционально)

Работа с моделями

use LetoCeilingCoder\Media\Models\Media;
use LetoCeilingCoder\Media\Models\Folder;

// Получить все файлы пользователя
$files = Media::all();

// Получить файлы в папке
$files = Media::inFolder(1)->get();

// Получить папки пользователя
$folders = Folder::whereNull('parent_id')->get();

// Создать папку
$folder = Folder::create([
    'name' => 'Новая папка',
    'parent_id' => null,
]);

// Получить корзину
$trashFolder = Folder::getTrashFolder();

Фильтрация

use LetoCeilingCoder\Media\Filters\FolderFilter;

// Фильтрация папок
$filter = app()->make(FolderFilter::class, [
    'queryParams' => ['user_id' => 1, 'name' => 'Test']
]);
$folders = Folder::filter($filter)->get();

Ресурсы

use LetoCeilingCoder\Media\Resources\MediaResource;
use LetoCeilingCoder\Media\Resources\FolderResource;

// Преобразование в JSON
return new MediaResource($media);
return FolderResource::collection($folders);

Структура базы данных

Таблица folders

• id - ID папки
• name - Название папки
• slug - URL-слаг
• src - Иконка папки
• parent_id - ID родительской папки
• position - Позиция для сортировки
• protected - Защищенная папка
• is_trash - Является ли корзиной
• user_id - ID пользователя
• created_at, updated_at, deleted_at

Таблица media

• id - ID файла
• name - Имя файла
• original_name - Оригинальное имя
• extension - Расширение
• disk - Диск хранения
• width, height - Размеры (для изображений)
• type - Тип файла (photo, video, document)
• size - Размер в байтах
• folder_id - ID папки
• original_folder_id - ID оригинальной папки (для корзины)
• user_id - ID пользователя
• metadata - Дополнительные данные (JSON)
• temporary - Временный файл
• created_at, updated_at, deleted_at

Многопользовательский режим

Пакет автоматически фильтрует файлы и папки по пользователю через глобальный scope UserScope.

Обход фильтрации

// Получить все файлы (для администратора)
$allFiles = Media::allUsers()->get();

// Получить файлы конкретного пользователя
$userFiles = Media::forUser($userId)->get();

// Получить без учета пользователя
$files = Media::withoutUserScope()->get();

Системные папки

Системные папки (с user_id = NULL) доступны всем пользователям. Корзина также общая для всех.

Безопасность

• Валидация типов файлов при загрузке
• Защита системных папок от удаления
• Защита корзины от прямого добавления файлов
• Авторизация через middleware (настраивается)

Лицензия

MIT

Автор

LetoCeiling Coder

Документация

• QUICK_START.md - Быстрый старт
• INSTALLATION.md - Подробная инструкция по установке
• VUE_COMPONENTS.md - Документация по Vue компонентам
• I18N.md - Документация по переводам (i18n)
• CONFIGURATION.md - Настройка пакета
• UPDATE.md - Инструкции по обновлению
• CHANGELOG.md - История изменений

Поддержка

GitHub: https://github.com/letoceiling-coder/media

Vue компоненты

Пакет включает готовые Vue 3 компоненты для управления медиа-файлами:

• Media.vue - Полнофункциональный медиа-менеджер с:

  • Drag & Drop загрузкой файлов
  • Превью изображений и видео
  • Режимом выбора файлов
  • Поиском и фильтрацией
  • Пагинацией
  • Управлением папками
  • Работой с корзиной

• ImageEditor.vue - Редактор изображений с:

  • Обрезкой изображений
  • Поворотом и отражением
  • Изменением размера
  • Настройкой качества
  • Экспортом в разные форматы

Подробные инструкции по использованию см. в VUE_COMPONENTS.md

История изменений (Changelog)

Версия 1.2.2 (Текущая версия)

Исправлено

• 🔧 Исправлена проблема с обрезкой изображения в ImageEditor
  • Теперь обрезанное изображение правильно сохраняется
  • Улучшено извлечение canvas из результата cropper
• 🔧 Исправлена проблема с сохранением folder_id при обновлении файла
  • Файл теперь сохраняется в той же папке, где был изначально
  • folder_id не теряется при редактировании и сохранении изображения

Версия 1.2.1

Исправлено

• 🔧 Исправлена проблема с потерей folder_id при обновлении файла через ImageEditor
• 🔧 Исправлена проблема с обновлением файла при обрезании изображения
  • Улучшено удаление старого файла
  • Добавлено версионирование URL для предотвращения кэширования

Версия 1.2.0

Добавлено

• 🌍 Многоязычная поддержка (i18n) для Vue компонентов
  • Поддержка 8 языков: русский, английский, французский, итальянский, немецкий, корейский, китайский, испанский
  • Composable useI18n для работы с переводами
  • Автоматическое определение языка из браузера или localStorage
  • Совместимость с vue-i18n (опционально)
  • Документация I18N.md с примерами использования

Изменено

• Обновлена документация VUE_COMPONENTS.md с информацией о i18n
• Обновлен README.md с упоминанием многоязычной поддержки
• Обновлен INSTALLATION.md с информацией о переводах

Версия 1.1.1

Исправлено

• 🔧 Исправлена ошибка "Auth guard [api] is not defined"
  • Добавлена автоматическая проверка существования guard
  • Fallback на sanctum, web или стандартный auth middleware
  • Гибкая настройка через config/media.php

Добавлено

• 📝 Файл CONFIGURATION.md с подробными инструкциями по настройке авторизации
• 📝 Обновлена документация с решениями проблем авторизации

Версия 1.1.0

Добавлено

• ✨ Vue 3 компоненты для управления медиа-файлами
  • Media.vue - полнофункциональный медиа-менеджер
  • ImageEditor.vue - редактор изображений с обрезкой и редактированием
• ✨ Утилиты для работы с API (resources/js/utils/api.js)
• ✨ Composable для работы с токеном авторизации (resources/js/composables/useAuthToken.js)
• ✨ Публикация Vue компонентов через vendor:publish --tag=media-vue-components
• 📝 Документация по использованию Vue компонентов (VUE_COMPONENTS.md)

Изменено

• Улучшена автоматическая публикация системных изображений
• Обновлена документация с информацией о Vue компонентах
• Обновлено описание пакета в composer.json

Версия 1.0.0

Добавлено

• Управление папками (создание, редактирование, удаление, иерархия)
• Загрузка и управление медиа-файлами
• Корзина с возможностью восстановления
• Многопользовательский режим с изоляцией файлов
• Фильтрация и поиск файлов и папок
• Пагинация для больших списков
• Защита системных папок
• Валидация типов файлов
• API endpoints для работы с папками и файлами
• Автоматическая публикация системных изображений
• Команда media:publish-assets для публикации изображений

Подробный список изменений см. в CHANGELOG.md