Laravel Head — це новий офіційний пакет від команди Laravel, представлений Тейлором Отвеллом на конференції Laracon US 2026. Він пропонує зручний fluent API для керування вмістом тегу <head>: заголовками, метаописами, канонічними URL, тегами Open Graph, директивами robots, структурованими даними JSON-LD та підказками ресурсів. Пакет сумісний із застосунками на Blade, Livewire та Inertia.
Основні можливості пакета:
- П’ятирівнева система пріоритетів — дані за замовчуванням, метадані груп маршрутів, конкретних маршрутів, рантайму та помилок об’єднуються поочередно.
- Метадані на рівні маршрутів — метод
withHead()для маршрутів, груп, ресурсів та синглтонів зберігає дані у вигляді масивів і не заважає кешуванню маршрутів. - Open Graph та картки X (Twitter) — методи
og(),ogImage(),ogVideo()таogAudio(). Теги Twitter автоматично генеруються на основі заголовка, опису та зображення. - Схеми JSON-LD — конструктори для
article,product,offer,breadcrumbs,faqта інших типів, а також можливість реєстрації власних схем. - Продуктивність та індексація — підтримка
preload(),prefetch(),preconnect(),dnsPrefetch(),paginate(),alternates()таfeed(). - Браузерні метадані — колірні теми з підтримкою media queries, фавіконки, Apple touch icons та метод
pwa()для прогресивних вебзастосунків. - Метадані сторінок помилок — налаштування заголовків, описів та інструкцій для robots залежно від HTTP-статусу в одному service provider.
# П’ятирівнева обробка метаданих
Метадані сторінки формуються з п’яти шарів, від найнижчого до найвищого пріоритету. Вищі шари точково замінюють значення нижчих: наприклад, заголовок, встановлений у контролері, замінить заголовок маршруту, але залишить його опис незмінним.
Глобальні налаштування для всього сайту задаються у 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');
});Суфікс, вказаний у налаштуваннях за замовчуванням, автоматично додається до заголовків на вищих рівнях. Так, 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.',
);Метод працює для груп на будь-якому рівні вкладеності, а також для ресурсів та синглтонів:
Route::withHead(robots: 'noindex, nofollow')
->prefix('admin')
->name('admin.')
->group(function () {
Route::get('/dashboard', DashboardController::class)
->name('dashboard')
->withHead(title: 'Dashboard');
});Технічно withHead() записує дані через стандартний API метаданих маршрутів Laravel, тому сумісність із кешуванням зберігається. Аргументи обмежені вбудованими властивостями для підтримки статичного аналізу, а кастомні розширення передаються через масив extensions.
Динамічні дані, що залежать від контексту запиту, встановлюються через facade у рантаймі:
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).
# Open Graph, картки X та схеми
Загальні title та description документа автоматично заповнюють og:title та og:description, якщо ті не вказані окремо. Якщо в налаштуваннях за замовчуванням зареєстровано тип картки Twitter, відповідні теги сформуються на основі тих самих даних:
use Laravel\Head\Enums\TwitterCard;
Head::defaults(fn (HeadBuilder $head) => $head->twitter(
card: TwitterCard::SummaryWithLargeImage,
));Для роботи зі структурованими даними використовується окремий facade 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)
)
);Breadcrumbs та FAQ підтримують масове додавання елементів. Невідомі методи створюють універсальний об’єкт схеми, а для складних випадків можна реєструвати власні класи з атрибутом #[SchemaType]. Помилки у JSON-LD викликають виняток під час розробки та записуються в лог у продакшені.
# Робота з Blade, Livewire та Inertia
У Blade та Livewire для виводу тегів використовується директива @head у макеті:
<head>
<meta charset="utf-8">
@head
</head>Оскільки директива рендериться синхронно, метадані мають бути визначені до виводу макета. У Livewire кожен візит через wire:navigate автоматично отримує оновлений head для нового маршруту.
Найбільше інтегрована Inertia. Пакет передає метадані як масив рядків у проп head для кожної сторінки:
{
"props": {
"head": [
"<title data-inertia=\"title\">Dashboard - Laravel</title>",
"<meta data-inertia=\"description\" name=\"description\" content=\"Your application overview.\">"
]
}
}В Inertia 3.5+ з’явилася опція serverHead, яку слід активувати у createInertiaApp(). Це дозволяє пошуковим роботам бачити метатеги без виконання JavaScript, а Inertia автоматично синхронізує їх при навігації. Клієнтський компонент <Head> у такому разі більше не потрібен.
Глобальні теги, що не змінюються (viewport, фавіконки тощо), можна винести в Head::inertiaGlobals() — вони рендеритимуться без атрибутів відстеження Inertia і не будуть оновлюватися після першого завантаження.
# Встановлення
Laravel Head потребує PHP 8.3 та Laravel 13.17 або новіше. Встановлюється через Composer:
composer require laravel/headПісля встановлення достатньо налаштувати дефолтні значення у service provider та додати @head до layout. Якщо потрібні сирі дані замість готової розмітки, використовуйте Head::toArray().
Детальніша інформація доступна в документації та в репозиторії на GitHub.
