PHPackages                             letoceiling-coder/media - 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. letoceiling-coder/media

ActiveLibrary[File & Storage](/categories/file-storage)

letoceiling-coder/media
=======================

Laravel Media Package - Полный функционал для работы с медиа-файлами, папками, загрузкой, управлением

v1.3.8(5mo ago)014MITPHPPHP ^8.2

Since Dec 7Pushed 5mo agoCompare

[ Source](https://github.com/letoceiling-coder/media)[ Packagist](https://packagist.org/packages/letoceiling-coder/media)[ Docs](https://github.com/letoceiling-coder/media)[ RSS](/packages/letoceiling-coder-media/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (3)Versions (22)Used By (0)

Laravel Media Package
=====================

[](#laravel-media-package)

**Версия:** 1.3.6
**Лицензия:** MIT

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

> 🚀 **Новое в версии 1.2.3:** Добавлен редактор изображений с функцией обрезки (crop) - при клике на кнопку редактирования открывается модальное окно! ✨ **Добавлено в версии 1.2.2:** Системные иконки папок для корректного отображения! 🐛 **Исправлено в версии 1.2.1:** Пути к иконкам, ошибка редактирования фото, улучшена обработка альтернативных путей!

Возможности
-----------

[](#возможности)

- ✅ Загрузка файлов (изображения, видео, документы)
- ✅ Управление папками с иерархической структурой
- ✅ Корзина с возможностью восстановления
- ✅ Фильтрация и поиск файлов
- ✅ Пагинация
- ✅ Сортировка
- ✅ Drag & Drop для папок
- ✅ Vue компонент для фронтенда
- ✅ RESTful API
- ✅ Защищенные папки
- ✅ Мультипользовательская поддержка (scope по user\_id)
- ✅ Мягкое удаление
- ✅ Автоматическая генерация превью для изображений

Требования
----------

[](#требования)

- PHP >= 8.2
- Laravel >= 10.0
- MySQL/MariaDB или PostgreSQL

Быстрая установка
-----------------

[](#быстрая-установка)

### Минимальная установка (только API)

[](#минимальная-установка-только-api)

```
composer require letoceiling-coder/media
php artisan migrate
```

**Готово!** Пакет работает автоматически. Подробнее в [QUICK\_START.md](QUICK_START.md)

> ⚠️ **Важно:** Если используете Vue компоненты, обязательно выполните шаги "Полная установка" ниже!

### Полная установка (с Vue компонентами)

[](#полная-установка-с-vue-компонентами)

См. подробную инструкцию: [INSTALLATION\_STEPS.md](INSTALLATION_STEPS.md)

**Кратко:**

1. `composer require letoceiling-coder/media`
2. `php artisan migrate`
3. `php artisan vendor:publish --tag=media-components`
4. `php artisan vendor:publish --tag=media-styles`
5. Подключите `@import './vendor/media.css';` в `resources/css/app.css`
6. `npm install vue@^3.5.0 vue-router@^4.6.0 fslightbox-vue@^3.0.1 sweetalert2@^11.26.3`

Установка
---------

[](#установка)

### 1. Установка через Composer

[](#1-установка-через-composer)

Установите пакет напрямую:

```
composer require letoceiling-coder/media
```

Команда автоматически установит последнюю стабильную версию пакета.

### 2. Автоматическая установка пакета

[](#2-автоматическая-установка-пакета)

После установки через Composer выполните команду автоматической установки:

```
php artisan media:install
```

Эта команда автоматически выполнит все необходимые шаги:

- Публикует миграции в `database/migrations/`
- Публикует конфигурацию в `config/media.php`
- Публикует Vue компоненты в `resources/js/vendor/media/`
- Публикует CSS стили в `resources/css/vendor/media.css`
- Публикует системные иконки в `public/img/system/media/`
- Проверяет подключение CSS стилей
- Проверяет наличие роута для редактирования изображений
- Обнаруживает проблемы с порядком роутов
- Может автоматически исправить порядок роутов (с опцией `--auto-fix-routes`)
- Показывает следующие шаги (миграции, npm установка, роуты)

#### Опции команды `media:install`:

[](#опции-команды-mediainstall)

- `--force` - Перезаписать существующие файлы
- `--no-components` - Не публиковать Vue компоненты
- `--no-styles` - Не публиковать CSS стили
- `--no-assets` - Не публиковать иконки

**Примеры:**

```
# Полная установка
php artisan media:install

# Установка с перезаписью существующих файлов
php artisan media:install --force

# Установка без Vue компонентов (только API)
php artisan media:install --no-components --no-styles --no-assets
```

> **Примечание:** Если пакет не опубликован в Packagist, добавьте репозиторий в `composer.json`:
>
> ```
> {
>     "repositories": [
>         {
>             "type": "vcs",
>             "url": "https://github.com/letoceiling-coder/media.git"
>         }
>     ]
> }
> ```
>
>
>
> Затем установите пакет: `composer require letoceiling-coder/media`

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

[](#3-запуск-миграций)

```
php artisan migrate
```

Пакет автоматически:

- ✅ Определит и подключит нужный middleware (auth:sanctum или auth:api)
- ✅ Создаст директорию `public/upload` при первой загрузке файла
- ✅ Настроит все необходимые роуты

> **Примечание:** Если пакет не опубликован в Packagist, добавьте репозиторий в `composer.json`:
>
> ```
> {
>     "repositories": [
>         {
>             "type": "vcs",
>             "url": "https://github.com/letoceiling-coder/media.git"
>         }
>     ]
> }
> ```
>
>
>
> Затем установите пакет: `composer require letoceiling-coder/media`

### Ручная публикация файлов (если не использовали `media:install`)

[](#ручная-публикация-файлов-если-не-использовали-mediainstall)

Если вы не использовали команду `php artisan media:install`, выполните следующие шаги вручную:

#### Публикация конфигурации (опционально)

[](#публикация-конфигурации-опционально)

Публикация конфигурации нужна только для кастомизации. Пакет работает с настройками по умолчанию:

```
php artisan vendor:publish --provider="LetoceilingCoder\Media\MediaServiceProvider" --tag="media-config"
```

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

[](#публикация-vue-компонентов)

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

Это опубликует:

- `resources/js/vendor/media/components/Media.vue` - полнофункциональный медиа-менеджер
- `resources/js/vendor/media/utils/api.js` - утилиты для API запросов
- `resources/js/vendor/media/composables/useAuthToken.js` - composable для авторизации

### 5. Публикация CSS стилей (обязательно для Vue компонентов)

[](#5-публикация-css-стилей-обязательно-для-vue-компонентов)

**ВАЖНО:** Для корректного визуального отображения компонента необходимо опубликовать CSS стили:

```
php artisan vendor:publish --tag=media-styles
```

Затем подключите стили в вашем главном CSS файле (`resources/css/app.css`):

```
@import './vendor/media.css';
```

Или в `app.js`:

```
import '../css/vendor/media.css'
```

### 6. Установка зависимостей для Vue компонентов

[](#6-установка-зависимостей-для-vue-компонентов)

```
npm install vue@^3.5.0 vue-router@^4.6.0 fslightbox-vue@^3.0.1 sweetalert2@^11.26.3
```

Подробнее о использовании Vue компонентов см. [VUE\_COMPONENTS.md](VUE_COMPONENTS.md)

### 7. Публикация изображений (иконки папок, системные изображения) (опционально)

[](#7-публикация-изображений-иконки-папок-системные-изображения-опционально)

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

Это опубликует иконки папок в `public/img/system/media/` для использования в компоненте.

Автоматические настройки
------------------------

[](#автоматические-настройки)

Пакет работает "из коробки" без дополнительной настройки. Все настройки имеют оптимальные значения по умолчанию.

### Автоматическое определение middleware

[](#автоматическое-определение-middleware)

Пакет автоматически определяет, какой middleware использовать:

- Если установлен Laravel Sanctum → использует `auth:sanctum`
- Если настроен `auth.guards.api` → использует `auth:api`
- Можно переопределить через конфигурацию или `.env`

### Автоматическое создание директорий

[](#автоматическое-создание-директорий)

Директория для загрузки файлов (`public/upload`) создается автоматически при первой загрузке файла или при загрузке ServiceProvider.

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

[](#конфигурация)

Если нужно изменить настройки, можно:

1. **Использовать переменные окружения** (рекомендуется, без публикации конфига):

    ```
    MEDIA_MIDDLEWARE_API=auth:sanctum
    MEDIA_MAX_SIZE=10240
    MEDIA_UPLOAD_PATH=upload
    MEDIA_USER_SCOPING=true
    ```
2. **Опубликовать и редактировать конфигурацию**:

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

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

```
return [
    'upload' => [
        'max_size' => 10240, // Максимальный размер файла в KB (по умолчанию 10 MB)
        'allow_all_types' => false, // Разрешить загрузку всех типов файлов
        'allowed_mime_types' => [
            'image/jpeg',
            'image/png',
            'image/gif',
            'image/webp',
            'image/svg+xml',
            'video/mp4',
            // ...
        ],
        'path' => 'upload', // Путь для загрузки файлов
    ],

    'pagination' => [
        'per_page_default' => 20,
        'per_page_max' => 100,
    ],

    'user_scoping' => true, // Включить фильтрацию по user_id

    'middleware' => [
        // Автоматически определяется, если не указано
        // null = автопределение, 'auth:sanctum' = явно указать
        'api' => env('MEDIA_MIDDLEWARE_API', null),

        // Дополнительные middleware
        'additional' => env('MEDIA_MIDDLEWARE_ADDITIONAL', '')
            ? explode(',', env('MEDIA_MIDDLEWARE_ADDITIONAL', ''))
            : [],
    ],

    'auto_setup' => [
        // Автоматически создавать директорию для загрузки
        'create_upload_directory' => env('MEDIA_AUTO_CREATE_UPLOAD_DIR', true),
    ],
];
```

Также можно настроить через переменные окружения в `.env`:

```
MEDIA_MAX_SIZE=10240
MEDIA_ALLOW_ALL_TYPES=false
MEDIA_UPLOAD_PATH=upload
MEDIA_PER_PAGE_DEFAULT=20
MEDIA_PER_PAGE_MAX=100
MEDIA_USER_SCOPING=true
```

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

[](#использование)

### API Endpoints

[](#api-endpoints)

Пакет автоматически регистрирует следующие роуты:

#### Folders

[](#folders)

- `GET /api/v1/folders` - Список папок
- `POST /api/v1/folders` - Создать папку
- `GET /api/v1/folders/{id}` - Показать папку
- `PUT /api/v1/folders/{id}` - Обновить папку
- `DELETE /api/v1/folders/{id}` - Удалить папку (переместить в корзину)
- `POST /api/v1/folders/{id}/restore` - Восстановить папку из корзины
- `GET /api/v1/folders/tree/all` - Получить дерево всех папок
- `POST /api/v1/folders/update-positions` - Обновить позиции папок

#### Media

[](#media)

- `GET /api/v1/media` - Список файлов
- `POST /api/v1/media` - Загрузить файл
- `GET /api/v1/media/{id}` - Показать файл
- `PUT /api/v1/media/{id}` - Обновить файл (переместить в другую папку или заменить файл)
- `DELETE /api/v1/media/{id}` - Удалить файл (переместить в корзину)
- `POST /api/v1/media/{id}/restore` - Восстановить файл из корзины
- `DELETE /api/v1/media/trash/empty` - Очистить корзину

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

[](#примеры-использования-api)

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

[](#загрузка-файла)

```
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('folder_id', folderId); // опционально

fetch('/api/v1/media', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + token
    },
    body: formData
})
.then(response => response.json())
.then(data => console.log(data));
```

#### Получение списка файлов с фильтрацией

[](#получение-списка-файлов-с-фильтрацией)

```
// Получить файлы из папки
fetch('/api/v1/media?folder_id=1&per_page=20&page=1&sort_by=created_at&sort_order=desc')
    .then(response => response.json())
    .then(data => console.log(data));

// Поиск файлов
fetch('/api/v1/media?search=photo&type=photo')
    .then(response => response.json())
    .then(data => console.log(data));
```

#### Создание папки

[](#создание-папки)

```
fetch('/api/v1/folders', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer ' + token
    },
    body: JSON.stringify({
        name: 'Новая папка',
        parent_id: null // null для корневой папки
    })
})
.then(response => response.json())
.then(data => console.log(data));
```

### Использование моделей в коде

[](#использование-моделей-в-коде)

```
use LetoceilingCoder\Media\Models\Media;
use LetoceilingCoder\Media\Models\Folder;

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

// Получить файлы из конкретной папки
$folder = Folder::find(1);
$files = $folder->files;

// Создать папку
$folder = Folder::create([
    'name' => 'Мои файлы',
    'parent_id' => null
]);

// Загрузить файл (обычно через контроллер)
$media = Media::create([
    'name' => 'filename.jpg',
    'original_name' => 'original.jpg',
    'extension' => 'jpg',
    'type' => 'photo',
    'size' => 1024000,
    'folder_id' => $folder->id,
    // ...
]);
```

### Использование Vue компонента

[](#использование-vue-компонента)

После публикации компонента, импортируйте его в ваше приложение:

```

import Media from '@/vendor/media/Media.vue'

const showMediaManager = ref(true)

const handleFileSelected = (file) => {
    console.log('Выбран файл:', file)
}

```

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

[](#структура-базы-данных)

### Таблица `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`

[](#таблица-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 пользователя
- `telegram_file_id` - ID файла в Telegram (если был загружен оттуда)
- `metadata` - Дополнительные метаданные (JSON)
- `temporary` - Временный ли файл
- `created_at`, `updated_at`, `deleted_at`

Авторизация
-----------

[](#авторизация)

По умолчанию API не защищено middleware авторизации. Для защиты добавьте middleware в контроллеры или через `MediaServiceProvider`:

```
// В MediaServiceProvider::boot()
Route::prefix('api/v1')
    ->middleware(['api', 'auth:sanctum']) // Добавьте middleware
    ->group(function () {
        // роуты...
    });
```

Фильтрация по пользователям
---------------------------

[](#фильтрация-по-пользователям)

Пакет поддерживает автоматическую фильтрацию по `user_id` через scope. Это можно включить/выключить через конфигурацию:

```
'user_scoping' => true // или false для отключения
```

При включенной фильтрации:

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

Для обхода scope используйте:

```
// Получить все файлы без фильтрации по user_id
$allMedia = Media::withoutUserScope()->get();

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

// Получить файлы всех пользователей
$allUsersMedia = Media::allUsers()->get();
```

Расширение
----------

[](#расширение)

### Добавление кастомных фильтров

[](#добавление-кастомных-фильтров)

Создайте свой фильтр:

```
namespace App\Http\Filters;

use LetoceilingCoder\Media\Http\Filters\AbstractFilter;
use Illuminate\Database\Eloquent\Builder;

class MediaFilter extends AbstractFilter
{
    public const TYPE = 'type';

    protected function getCallbacks(): array
    {
        return [
            self::TYPE => [$this, 'type'],
        ];
    }

    public function type(Builder $builder, $value)
    {
        $builder->where('type', $value);
    }
}
```

### Кастомизация моделей

[](#кастомизация-моделей)

Если нужно расширить функциональность моделей, создайте свои модели, наследуя от моделей пакета:

```
namespace App\Models;

use LetoceilingCoder\Media\Models\Media as BaseMedia;

class Media extends BaseMedia
{
    // Ваша кастомизация
}
```

Поддержка
---------

[](#поддержка)

Для вопросов и предложений создайте issue в репозитории:

Лицензия
--------

[](#лицензия)

MIT License

###  Health Score

38

—

LowBetter than 85% of packages

Maintenance71

Regular maintenance activity

Popularity6

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity57

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 ~0 days

Total

21

Last Release

162d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/bba6a99134d905eaed0dcccbc768321a5d14edc29aab6dedc45cac31beb0d36e?d=identicon)[letoceiling-coder](/maintainers/letoceiling-coder)

---

Top Contributors

[![Postads](https://avatars.githubusercontent.com/u/25578332?v=4)](https://github.com/Postads "Postads (61 commits)")

---

Tags

laravelmediauploadfile managerfolder

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/letoceiling-coder-media/health.svg)

```
[![Health](https://phpackages.com/badges/letoceiling-coder-media/health.svg)](https://phpackages.com/packages/letoceiling-coder-media)
```

###  Alternatives

[mwguerra/filemanager

A full-featured file manager package for Laravel and Filament v5 with dual operating modes, drag-and-drop uploads, S3/MinIO support, and comprehensive security features.

718.5k1](/packages/mwguerra-filemanager)[erlandmuchasaj/laravel-file-uploader

A simple package to help you easily upload files to your laravel project.

128.7k](/packages/erlandmuchasaj-laravel-file-uploader)[gaspertrix/laravel-backpack-dropzone-field

Add Dropzone support for Laravel Backpack

172.2k](/packages/gaspertrix-laravel-backpack-dropzone-field)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)