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.

090PHP

Since Dec 17Pushed 6mo 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 today

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

19

—

LowBetter than 9% of packages

Maintenance46

Moderate activity, may be stable

Popularity10

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity13

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://avatars.githubusercontent.com/u/27732309?v=4)[Андрей](/maintainers/parabellumKoval)[@parabellumKoval](https://github.com/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

[goat1000/svggraph

Generates SVG graphs

135911.1k3](/packages/goat1000-svggraph)[gravatarphp/gravatar

Gravatar URL builder which is most commonly called as a Gravatar library

16653.6k2](/packages/gravatarphp-gravatar)

PHPackages © 2026

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