Визначення домінантного кольору зображень та підтримка HEIC у Laravel 13.24

Laravel 13.24 розширює можливості Image API: тепер фреймворк вміє визначати домінантний колір зображень та підтримує формат HEIC на вході й виході. Також додано метод modelKeys() для Eloquent query builder, нове правило валідації array_keys та виправлено проблему з продуктивністю валідації масивів, яка могла «підвішувати» запити. Команда Laravel випустила версію v13.24.0 4 серпня 2026 року.

• Метод dominantColor() для зображень, а також підтримка dominant фону для методів contain() та rotate().
• Підтримка AVIF та HEIC на вході, метод toHeic() для збереження, а також підтримка обох форматів у правилі валідації image.
• Метод modelKeys() у конструкторі запитів Eloquent.
• Нове правило валідації array_keys із плейсхолдером :unexpected.
• Оптимізація валідації за масками (наприклад, foo.*.bar), яка раніше сповільнювала роботу з великими масивами.

# Що нового

# Визначення домінантного кольору в Image API

Вбудований Image API тепер дозволяє дізнатися середній колір зображення. Метод dominantColor() зменшує картинку до одного пікселя та повертає його значення у вигляді hex-рядка:

use Illuminate\Support\Facades\Image;
 
$color = Image::fromPath(storage_path('app/photo.jpg'))->dominantColor(); // "#8a6f4c"

Цей колір зручно використовувати як фон-плейсхолдер під час завантаження фото або для тонування карток товарів. Результат кешується для кожного екземпляра зображення. Якщо в пайплайні є незавершені трансформації, вони виконаються перед визначенням кольору, тому ви отримаєте колір фінального зображення, а не оригіналу.

Цю ж логіку можна використовувати для заповнення фону. Параметр dominant у методах contain() або rotate() автоматично підбере колір для порожніх зон (letterbox) або кутів при обертанні:

Image::fromUpload($request->file('photo'))
    ->contain(1200, 800, background: 'dominant')
    ->store('photos');

# Підтримка AVIF та HEIC

Раніше Image API дозволяв створювати AVIF через toAvif(), але не приймав такі файли на вході. Формати HEIC та HEIF ігнорувалися в обох напрямках, хоча Intervention Image підтримує їхні енкодери. Оскільки iPhone за замовчуванням робить фото в HEIC, розробникам доводилося конвертувати їх перед обробкою у фреймворку.

Тепер AVIF, HEIC та HEIF підтримуються на вході. Додано методи toHeic() та optimize('heic'), а всі три формати розпізнаються правилом валідації image:

Image::fromPath(storage_path('app/photo.heic'))
    ->usingImagick()
    ->cover(1200, 800)
    ->toAvif()
    ->quality(80)
    ->store('photos');

Формат heif автоматично нормалізується до HEIC, тому файли зберігаються з розширенням .heic. Для роботи з цим форматом потрібна збірка Imagick із підтримкою відповідного кодека.

# modelKeys() у Eloquent Query Builder

Метод modelKeys() давно був доступний для Eloquent-колекцій, але щоб отримати список ID безпосередньо з бази, доводилося прописувати назву ключа вручну через pluck('id'). Тепер конструктор запитів має власний метод:

$ids = Post::query()->where('published', true)->modelKeys(); // [1, 2, 3]

Він автоматично підтягує назву первинного ключа з моделі, тому правильно працює навіть із кастомними $primaryKey або у складних запитах із join.

# Правило валідації array_keys

Стандартне Rule::array(['sort', 'direction']) відхиляє масиви з неочікуваними ключами, але видає загальну помилку: «Поле має бути масивом». Нове правило array_keys фокусується саме на ключах:

$request->validate([
    'options' => Rule::arrayKeys(['sort', 'direction']),
]);
 
// Або рядком
$request->validate([
    'options' => 'array_keys:sort,direction',
]);

Якщо передати ['sort' => 'name', 'colour' => 'red'], валідатор видасть чітку помилку: «Поле options може містити лише наступні ключі: sort, direction». Це правило обмежує список дозволених ключів, але не робить їх обов'язковими (для цього є required_array_keys).

Для кастомних повідомлень доступний плейсхолдер :unexpected, що показує, які саме ключі викликали помилку.

# Оптимізація валідації масивів

Розробники виправили проблему квадратичної складності при обробці правил на кшталт foo.*.bar. Раніше метод explodeWildcardRules() копіював увесь набір правил для кожного елемента масиву, що призводило до величезних затримок на великих обсягах даних.

Результати тестування (17 правил під однією маскою):

При 8 000 елементів валідація тривала майже півтори хвилини, хоча розмір даних був невеликим (близько 1.1 МБ). Тепер цей процес займає менше секунди.

# Виправлення Arr::forget()

Було виправлено помилку в Arr::forget(), через яку при використанні «крапкової нотації» (dotted keys) метод міг видалити не той елемент. Це виправлення також покращило роботу Arr::except(), Collection::except() та data_forget().

$array = ['users' => ['name' => 'Joe', 'id' => 1], 'id' => 99];
Arr::forget($array, ['users.name', 'id']);
// Раніше: залишався users.name, видалявся users.id
// Тепер: працює коректно

# Інші покращення

• Значно пришвидшено обробку помилок 404 для кешованих маршрутів — час пошуку при 2 000 маршрутах скоротився з 71 мс до 2.5 мс.
• Виправлено баг з аксесорами: раніше, якщо атрибут був у $appends, він міг повертати null замість значення.
• Str::replace() та Str::remove() тепер коректно працюють із багатобайтовими символами (UTF-8) у регістронезалежному режимі.
• Покращено роботу ShouldBeUniqueUntilProcessing для черг: тепер коректно відстежується власник блокування кешу.
• Більшість Artisan-команд переведено на синтаксис $signature, що спрощує їх підтримку та тестування.

Нотатки щодо оновлення

Для більшості застосунків оновлення пройде непомітно. Зверніть увагу, якщо ви розширювали внутрішні компоненти: explodeWildcardRules() більше не викликає mergeRulesForAttribute(). Також Container::getAlias() тепер викидає LogicException у разі виявлення циклічних аліасів замість вичерпання пам'яті. Для підтримки HEIC переконайтеся, що ваш Imagick скомпільовано з відповідним кодеком.

Посилання

• Офіційний changelog
• Порівняння v13.23.0...v13.24.0