Інтеграція Cloudinary для управління медіафайлами сайту

Інтеграція Cloudinary для управління медіафайлами веб-сайту

Cloudinary — облачний сервіс для зберігання, трансформації й доставки зображень і відео. Основна цінність — не просто CDN, а динамічні трансформації через URL: зміна розміру, формату, якості, обрізка, накладення водяних знаків прямо у параметрах запиту. Ніяких заготованих превью, одне зображення — всі потрібні розміри.

Підключення і конфігурація

Реєстрація на cloudinary.com, у дашборді — Cloud Name, API Key, API Secret.

composer require cloudinary-labs/cloudinary-laravel

CLOUDINARY_URL=cloudinary://API_KEY:API_SECRET@CLOUD_NAME

// config/cloudinary.php публікується через artisan vendor:publish

Завантаження файлів

use CloudinaryLabs\CloudinaryLaravel\Facades\Cloudinary;

// Завантаження зі збереженням public_id
$result = Cloudinary::upload($request->file('image')->getRealPath(), [
    'folder'    => 'products',
    'public_id' => 'product-' . $product->id,
    'overwrite' => true,
    'tags'      => ['product', 'catalog'],
]);

$publicId  = $result->getPublicId();   // products/product-123
$secureUrl = $result->getSecureUrl();  // https://res.cloudinary.com/...

У базі достатньо зберігати public_id — URL генерується динамічно при кожному зверненні. Зберігати URL не потрібно: він зміниться при смені домену або параметрів трансформації.

Динамічні трансформації через URL

Все управління зображенням — в URL:

https://res.cloudinary.com/CLOUD_NAME/image/upload/
  w_800,h_600,c_fill,g_auto,f_auto,q_auto/
  products/product-123

Параметри:

• w_800,h_600 — ширина й висота
• c_fill — режим обрізки (fill, fit, scale, crop, thumb та ін.)
• g_auto — автоматичний вибір фокуса (AI-визначення головного об'єкту)
• f_auto — автоматичний формат (WebP для Chrome, AVIF де підтримується, JPEG для решти)
• q_auto — автоматична якість (Cloudinary підбирає оптимальну)

На PHP зручніше генерувати URL через SDK:

use Cloudinary\Cloudinary;
use Cloudinary\Transformation\Resize;
use Cloudinary\Transformation\Quality;
use Cloudinary\Transformation\Format;

$cloudinary = new Cloudinary();

$url = $cloudinary->image($publicId)
    ->resize(Resize::fill()->width(800)->height(600)->gravity('auto'))
    ->quality(Quality::auto())
    ->format(Format::auto())
    ->toUrl();

Адаптивні зображення

Для різних екранів генеруємо кілька розмірів:

function cloudinaryResponsive(string $publicId, array $widths = [400, 800, 1200]): string
{
    $cloudinary = new Cloudinary();
    $srcset = [];

    foreach ($widths as $w) {
        $url = $cloudinary->image($publicId)
            ->resize(Resize::scale()->width($w))
            ->format(Format::auto())
            ->quality(Quality::auto())
            ->toUrl();
        $srcset[] = "{$url} {$w}w";
    }

    return implode(', ', $srcset);
}

<img
  src="https://res.cloudinary.com/CLOUD/image/upload/w_800,f_auto,q_auto/products/123"
  srcset="{{ cloudinaryResponsive('products/product-123') }}"
  sizes="(max-width: 600px) 400px, (max-width: 1200px) 800px, 1200px"
  alt="..."
  loading="lazy"
>

Відео: автоматична оптимізація

$videoUrl = $cloudinary->video($publicId)
    ->resize(Resize::scale()->width(1280))
    ->quality(Quality::auto())
    ->format(Format::auto()) // mp4/webm за підтримкою браузера
    ->toUrl();

Для потокового відео Cloudinary генерує адаптивний бітрейт (ABR) при наявності відповідного плану.

Підписані URL для приватних файлів

Якщо файли не повинні бути публічно доступні:

$signedUrl = $cloudinary->image($publicId)
    ->signUrl(true)
    ->resize(Resize::scale()->width(800))
    ->toUrl();

Підписаний URL містить HMAC-підпис і може мати час життя — через параметр expires_at при генерації.

Видалення й управління ресурсами

// Видалення одного файлу
Cloudinary::destroy('products/product-123');

// Видалення за тегом (наприклад, всі зображення видаленого товара)
$cloudinary->adminApi()->deleteResourcesByTag('product-123');

Гуки завантаження: автоматична обробка

Cloudinary підтримує Incoming Transformations — трансформації, застосовані автоматично при завантаженні. Наприклад, автоматичне видалення фону для каталожних фото:

Cloudinary::upload($path, [
    'eager' => [
        ['effect' => 'background_removal', 'format' => 'png'],
        ['width' => 800, 'height' => 800, 'crop' => 'fill', 'format' => 'webp'],
    ],
    'eager_async' => true,
]);

Після завантаження Cloudinary асинхронно застосовує трансформації й може сповістити вебхуком про готовність.

Терміни й що входить

Базове підключення SDK, завантаження файлів, генерація динамічних URL: 2–4 години. Повний кейс з адаптивними зображеннями, автоформатом, управлінням через медіатеку й видаленням при видаленні контенту з CMS — 1 робочий день.