PHPackages                             parabellumkoval/backpack-images - 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. [Image & Media](/categories/media)
4. /
5. parabellumkoval/backpack-images

ActiveLibrary[Image & Media](/categories/media)

parabellumkoval/backpack-images
===============================

Reusable image uploader and Backpack helpers for Laravel 12.

063PHP

Since Dec 17Pushed 4mo agoCompare

[ Source](https://github.com/parabellumKoval/backpack-images)[ Packagist](https://packagist.org/packages/parabellumkoval/backpack-images)[ RSS](/packages/parabellumkoval-backpack-images/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

parabellumkoval/backpack-images
===============================

[](#parabellumkovalbackpack-images)

Пакет предоставляет единый сервис загрузки изображений и вспомогательные инструменты для Laravel Backpack 4.1. Он поддерживает несколько провайдеров хранения (локальный диск, BunnyCDN и любые кастомные) и позволяет легко подключать repeatable-поля и колонки для CRUD.

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

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

1. Подключите пакет через `composer.json` проекта (в репозитории уже добавлен путь `packages/*`).
2. Зарегистрируйте сервис-провайдер, если не используете автоматическое обнаружение:

```
// bootstrap/providers.php
return [
    // ...
    ParabellumKoval\BackpackImages\BackpackImagesServiceProvider::class,
];
```

3. Опубликуйте конфигурацию (опционально):

```
php artisan vendor:publish --tag=backpack-images-config
```

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

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

Файл `config/backpack-images.php` содержит:

- `default_provider` — имя провайдера по умолчанию (`local`, `bunny` и т.д.);
- `default_folder` — базовая папка для хранения изображений;
- `preserve_original_name` и `generate_unique_name` — стратегия именования файлов;
- `providers` — список провайдеров. Каждый провайдер указывает класс драйвера и необходимые параметры.

Пример для BunnyCDN и локального диска уже настроен. Вы можете добавить свои провайдеры, реализовав интерфейс `ParabellumKoval\BackpackImages\Contracts\ImageStorageProvider` или расширив `ConfigurableImageProvider`.

Использование в моделях
-----------------------

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

Подключите трейт `HasImages` к Eloquent-модели:

```
use Illuminate\Database\Eloquent\Model;
use ParabellumKoval\BackpackImages\Traits\HasImages;

class Article extends Model
{
    use HasImages;

    // Опционально переопределите настройки
    public static function imageProviderName(): string
    {
        return 'bunny';
    }

    public static function imageStorageFolder(): string
    {
        return 'articles';
    }

    public static function imageFieldPrefix(): string
    {
        return config('services.cdn.articles_url');
    }
}
```

Трейт автоматически приводит поле `images` к массиву и предоставляет набор вспомогательных методов:

- `getAllImages()` — массив всех элементов (alt/title/size/src);
- `getFirstImage()` и `getFirstImageUrl()` — первая картинка и её URL;
- `getImagesLimited($limit)` — несколько первых изображений;
- `getImagePaths()` / `getImageUrls()` — пути или полные ссылки;
- `getImageSourcesForApi($limit = null)` — массив, готовый для API.

Загрузка из URL:

```
$stored = $article->uploadImageFromUrl('https://example.com/image.jpg');
$article->images = array_merge($article->getAllImages(), [[
    'src' => $stored->path,
    'alt' => '...',
    'title' => '...',
    'size' => 'cover',
]]);
$article->save();
```

### Несколько коллекций изображений

[](#несколько-коллекций-изображений)

Одной модели можно назначить несколько независимых "коллекций" изображений. Для этого переопределите метод `imageCollections()` и добавьте дополнительные ключи — каждый ключ соответствует отдельному атрибуту и наследует дефолтные настройки:

```
use ParabellumKoval\BackpackImages\Traits\HasImages;

class Review extends Model
{
    use HasImages;

    public static function imageCollections(): array
    {
        return array_replace_recursive(
            static::defaultImageCollections(),
            [
                'video_poster' => [
                    'folder' => 'reviews/video-posters',
                    'label' => 'Постер видео',
                    'field' => [
                        'label' => 'Постер видео',
                        'tab' => null,
                        'max_rows' => 1,
                        'fields' => [
                            [
                                'label' => 'Постер',
                                'aspect_ratio' => 16 / 9,
                            ],
                        ],
                    ],
                    'column' => [
                        'label' => 'Постер видео',
                    ],
                ],
            ]
        );
    }
}
```

После этого в CRUD можно добавить поле/колонку с именем коллекции:

```
$this->addImagesField(['name' => 'video_poster']);
$this->addImagesColumn(['name' => 'video_poster']);
```

Все вспомогательные методы (`getAllImages`, `getFirstImage`, `getImagePaths` и др.) принимают необязательный параметр атрибута:

```
$poster = $review->getFirstImage('video_poster');
$posterUrl = $review->getFirstImageForApi('video_poster');
```

Компоненты для Backpack CRUD
----------------------------

[](#компоненты-для-backpack-crud)

Для контроллеров Backpack предусмотрен трейт `HasImagesCrudComponents`:

```
use Backpack\CRUD\app\Http\Controllers\CrudController;
use ParabellumKoval\BackpackImages\Traits\HasImagesCrudComponents;

class ArticleCrudController extends CrudController
{
    use HasImagesCrudComponents;

    protected function setupCreateOperation(): void
    {
        $this->addImagesField(); // можно передать overrides
    }

    protected function setupListOperation(): void
    {
        $this->addImagesColumn(['label' => 'Preview']);
    }
}
```

Метод `addImagesField()` создаёт repeatable-поле из примера (image/alt/title/size), а `addImagesColumn()` отображает миниатюры первых изображений в списке. Оба метода принимают массив `overrides`, позволяющий переопределить любую часть конфигурации Backpack.

Работа с провайдерами
---------------------

[](#работа-с-провайдерами)

Сервис `ImageUploader` управляет провайдерами через реестр. Вы можете получить провайдер вручную:

```
use ParabellumKoval\BackpackImages\Services\ImageUploader;

$uploader = app(ImageUploader::class);
$provider = $uploader->getProvider('local');
$url = $provider->getUrl('articles/sample.jpg');
```

### Добавление собственного провайдера

[](#добавление-собственного-провайдера)

1. Реализуйте интерфейс `ImageStorageProvider` или `ConfigurableImageProvider`.
2. Добавьте конфигурацию в `backpack-images.providers` с ключом `driver` и необходимыми параметрами.

API фасад
---------

[](#api-фасад)

Фасад `ImageUploader` остаётся доступным (совместимо со старым кодом):

```
use ImageUploader;

$result = ImageUploader::uploadMany($urls, 'products', 'bunny');
```

Методы возвращают массивы вида `['url' => ..., 'path' => ..., 'filename' => ..., 'extension' => ...]` для обратной совместимости.

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

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

MIT

###  Health Score

20

—

LowBetter than 14% of packages

Maintenance50

Moderate activity, may be stable

Popularity10

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity12

Early-stage or recently created project

 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.

### Community

Maintainers

![](https://www.gravatar.com/avatar/1a9edb05ebf647a1976e4dbf92497c0186607984165f62b97b6498a01e9141ab?d=identicon)[parabellumKoval](/maintainers/parabellumKoval)

---

Top Contributors

[![parabellumKoval](https://avatars.githubusercontent.com/u/27732309?v=4)](https://github.com/parabellumKoval "parabellumKoval (13 commits)")

### Embed Badge

![Health badge](/badges/parabellumkoval-backpack-images/health.svg)

```
[![Health](https://phpackages.com/badges/parabellumkoval-backpack-images/health.svg)](https://phpackages.com/packages/parabellumkoval-backpack-images)
```

###  Alternatives

[milon/barcode

Barcode generator like Qr Code, PDF417, C39, C39+, C39E, C39E+, C93, S25, S25+, I25, I25+, C128, C128A, C128B, C128C, 2-Digits UPC-Based Extention, 5-Digits UPC-Based Extention, EAN 8, EAN 13, UPC-A, UPC-E, MSI (Variation of Plessey code)

1.5k13.3M39](/packages/milon-barcode)[bkwld/croppa

Image thumbnail creation through specially formatted URLs for Laravel

510496.0k23](/packages/bkwld-croppa)[char0n/ffmpeg-php

PHP wrapper for FFmpeg application

495225.1k1](/packages/char0n-ffmpeg-php)[goat1000/svggraph

Generates SVG graphs

132849.6k3](/packages/goat1000-svggraph)[cohensive/embed

Media Embed (for Laravel or as a standalone).

120370.4k](/packages/cohensive-embed)[netresearch/rte-ckeditor-image

Image support in CKEditor for the TYPO3 ecosystem - by Netresearch

63991.3k4](/packages/netresearch-rte-ckeditor-image)

PHPackages © 2026

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