Laravel Head - це новий офіційний пакет від команди розробників Laravel з відкритим кодом, продемонстрований на сцені під час основної доповіді Тейлора Отвелла на Laracon US 2026. Пакет надає зручний fluent API для всього, що потрапляє в елемент <head> вашого документа: заголовки, мета-описи, канонічні URL, теги Open Graph, директиви для роботів, структуровані дані JSON-LD та підказки щодо ресурсів. Метадані розв'язуються для кожного запиту окремо і працюють з Blade, Livewire та Inertia додатками.
Основні можливості пакету
Пакет охоплює широкий спектр функціональності:
- П'ятирівнева пріоритетність - дефолтні налаштування сторінки, метадані групи маршрутів, метадані маршруту, runtime метадані та метадані помилок об'єднуються поле за полем
- Метадані на рівні маршрутів - метод
withHead() для маршрутів, груп, ресурсів та singleton'ів, який зберігає прості масиви і залишається сумісним з кешованими маршрутами
- Open Graph та картки X - методи
og(), ogImage(), ogVideo() та ogAudio(), з Twitter-тегами, що автоматично генеруються з тих самих заголовків, описів та зображень
- JSON-LD схеми - білдери для
article, blogPosting, product, offer, brand, breadcrumbs, faq, organization, person, webPage та webSite, плюс можливість реєстрації власних типів
- Продуктивність та виявлення -
preload(), prefetch(), preconnect(), dnsPrefetch(), paginate(), alternates() та feed()
- Метадані браузера та додатків - кольори теми з медіа-запитами, favicon'и, іконки Apple touch та метод
pwa() для встановлюваних веб-додатків
- Метадані сторінок помилок - заголовок, опис та значення robots для кожного статусу, які реєструються один раз у service provider
П'ятирівнева система розв'язання метаданих
Метадані сторінки формуються з п'яти рівнів, упорядкованих від найнижчого до найвищого пріоритету: дефолтні налаштування сторінки, метадані групи маршрутів, метадані маршруту, runtime метадані та метадані помилок. Вищі рівні замінюють нижчі поле за полем, тому runtime заголовок замінює заголовок маршруту, не торкаючись опису маршруту.
Дефолтні налаштування для всього сайту реєструються в service provider:
use Laravel\Head\Enums\OgType;
use Laravel\Head\Facades\Head;
use Laravel\Head\HeadBuilder;
Head::defaults(function (HeadBuilder $head) {
$head
->title('Laravel', suffix: ' - Laravel')
->description('Build something great.')
->canonical()
->og(siteName: 'Laravel', type: OgType::Website)
->searchableByRobots()
->preconnect('https://fonts.example.com');
});
Суфікс, зареєстрований у defaults, переноситься на вищі рівні, тому Head::title('About') відрендериться як About - Laravel. Передайте exact: true, коли заголовок повинен ігнорувати успадкований префікс або суфікс. Виклик canonical() без аргументів використовує URL поточного запиту і нормалізує його до https, що можна вимкнути через forceHttps: false.
Директиви robots приймають сирий рядок, випадки enum RobotsRule або список, що змішує обидва варіанти. Скорочення searchableByRobots() та hiddenFromRobots() рендерять all та none відповідно.
Метадані безпосередньо на маршрутах
Для сторінок, метадані яких відомі заздалегідь, withHead() прикріплює їх безпосередньо до визначення маршруту:
Route::view('/contact', 'contact')
->name('contact')
->withHead(
title: 'Contact Us',
description: 'Get in touch.',
);
Метод працює на групах у будь-якій позиції в ланцюжку, а також на resource та singleton маршрутах:
Route::withHead(robots: 'noindex, nofollow')
->prefix('admin')
->name('admin.')
->group(function () {
Route::get('/dashboard', DashboardController::class)
->name('dashboard')
->withHead(title: 'Dashboard');
});
Під капотом withHead() записує прості масиви через нативний API метаданих маршрутів Laravel - еквівалент виклику metadata() з атрибутами, вкладеними під ключем head - тому кешування маршрутів як і раніше працює. Іменовані аргументи навмисно обмежені вбудованими властивостями пакету, щоб статичний аналіз виявляв друкарські помилки; все, що реєструється власним білдером тегів, передається через масив extensions.
Runtime метадані
Все, що невідомо до моменту надходження запиту, встановлюється під час виконання через фасад:
public function show(Post $post)
{
Head::title($post->title)
->description($post->description)
->when($post->isDraft(), fn ($head) => $head->hiddenFromRobots());
return view('posts.show', ['post' => $post]);
}
Поля з одним значенням приймають останній виклик. Поля, що повторюються, зберігають кілька записів, але повторне використання того самого ключа оновлює попередній - для ogImage() URL є ключем, тому виклик двічі з однаковим URL об'єднує атрибути замість створення двох тегів.
Open Graph, картки X та схеми
title та description документа автоматично заповнюють відсутні og:title та og:description. Зареєструйте тип картки Twitter у ваших defaults, і теги картки будуть отримані з тих самих значень:
use Laravel\Head\Enums\TwitterCard;
Head::defaults(fn (HeadBuilder $head) => $head->twitter(
card: TwitterCard::SummaryWithLargeImage,
));
Встановлення заголовка, опису та ogImage() на сторінці створює обидва набори тегів, з twitter() та twitterImage() доступними, коли сторінці потрібен інший соціальний контент.
Структуровані дані використовують окремий фасад Schema з білдерами, що вкладаються:
use Laravel\Head\Enums\OfferAvailability;
use Laravel\Head\Facades\Schema;
Head::schema(
Schema::product()
->name($product->name)
->offers(
Schema::offer()
->price($product->price)
->currency('USD')
->availability(OfferAvailability::InStock)
)
);
Хлібні крихти та FAQ приймають масиви оптом - Schema::breadcrumbs()->items([...]) призначає позиції в заданому порядку. Невідомі фабричні методи створюють загальний об'єкт схеми, і ви можете зареєструвати типізований клас з атрибутом #[SchemaType] для будь-чого, для чого потрібні першокласні методи. Недійсний JSON-LD викидає виняток поза production і логує попередження в production.
Рендеринг у Blade, Livewire та Inertia
Blade та Livewire обидва рендерять розв'язані теги за допомогою директиви @head у макеті:
<head>
<meta charset="utf-8">
@head
</head>
Директива рендериться синхронно, тому метадані повинні бути визначені до рендерингу макета. Livewire не потребує додаткової конфігурації - резолвер має область запиту, тому кожне відвідування wire:navigate отримує документ, чий head відображає маршрут призначення.
Inertia отримує найбільше функціональності. Коли Inertia встановлено, пакет ділиться розв'язаним head як масивом відрендерених рядків елементів під пропсом head на кожному об'єкті сторінки:
{
"props": {
"head": [
"<title data-inertia=\"title\">Dashboard - Laravel</title>",
"<meta data-inertia=\"description\" name=\"description\" content=\"Your application overview.\">"
]
}
}
Ви вмикаєте опцію serverHead Inertia - доступну в Inertia 3.5 і пізніше - всюди, де ви викликаєте createInertiaApp(), включаючи вашу точку входу SSR, якщо вона у вас є. Кожен елемент несе стабільний ключ data-inertia, який Inertia приймає і підтримує синхронізованим між відвідуваннями, миттєвими відвідуваннями та навігацією вперед/назад. Оскільки @head поміщає теги у початкову HTML-відповідь, краулери та боти попереднього перегляду посилань читають їх без запуску JavaScript, і клієнтський компонент <Head> не потрібен.
Теги, які ніколи не змінюються протягом сесії - viewport, колірна схема, favicon'и, маніфест - можна зареєструвати окремо за допомогою Head::inertiaGlobals(). Вони виключаються з пропса head, рендеряться без атрибутів володіння і ніколи не оновлюються після першої відповіді.
Якщо ви додаєте це до існуючого додатка Inertia, видаліть колбеки заголовків з app.tsx та ssr.tsx і перенесіть все, що зараз знаходиться в компоненті <Head> Inertia, щоб вони ніколи не керували одним і тим самим елементом.
Встановлення та використання
Laravel Head вимагає PHP 8.3 та Laravel 13.17 або новіше, і встановлюється через Composer:
composer require laravel/head
Далі зареєструйте defaults у service provider і додайте @head до вашого макета. Додатки, які хочуть отримати розв'язані метадані як дані, а не розмітку, можуть викликати Head::toArray(), який повертає заголовки, значення Open Graph, схеми JSON-LD та решту як структурований масив.
Повна документація доступна в офіційних документах Laravel, а вихідний код знаходиться в репозиторії laravel/head на GitHub.
