Интеграция 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 рабочий день.