--- title: "Laravel Head: новий офіційний пакет для керування мета-тегами, Open Graph та JSON-LD" url: https://laravelukraine.com/blog/laravel-head-oficiinii-paket-dlia-keruvannia-meta-tegami-open-graph-ta-json-ld date: 2026-08-05 source: https://laravel-news.com/laravel-head-package?utm_medium=feed&utm_source=feedpress.me&utm_campaign=Feed%3A+laravelnews --- # Laravel Head: новий офіційний пакет для керування мета-тегами, Open Graph та JSON-LD Laravel Head - це новий офіційний пакет від команди розробників Laravel з відкритим кодом, продемонстрований на сцені під час основної доповіді Тейлора Отвелла на Laracon US 2026. Пакет надає зручний fluent API для всього, що потрапляє в елемент `` вашого документа: заголовки, мета-описи, канонічні 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: ```php 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()` прикріплює їх безпосередньо до визначення маршруту: ```php Route::view('/contact', 'contact') ->name('contact') ->withHead( title: 'Contact Us', description: 'Get in touch.', ); ``` Метод працює на групах у будь-якій позиції в ланцюжку, а також на resource та singleton маршрутах: ```php 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 метадані Все, що невідомо до моменту надходження запиту, встановлюється під час виконання через фасад: ```php 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, і теги картки будуть отримані з тих самих значень: ```php use Laravel\Head\Enums\TwitterCard; Head::defaults(fn (HeadBuilder $head) => $head->twitter( card: TwitterCard::SummaryWithLargeImage, )); ``` Встановлення заголовка, опису та `ogImage()` на сторінці створює обидва набори тегів, з `twitter()` та `twitterImage()` доступними, коли сторінці потрібен інший соціальний контент. Структуровані дані використовують окремий фасад `Schema` з білдерами, що вкладаються: ```php 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` у макеті: ```blade @head ``` Директива рендериться синхронно, тому метадані повинні бути визначені до рендерингу макета. Livewire не потребує додаткової конфігурації - резолвер має область запиту, тому кожне відвідування `wire:navigate` отримує документ, чий head відображає маршрут призначення. Inertia отримує найбільше функціональності. Коли Inertia встановлено, пакет ділиться розв'язаним head як масивом відрендерених рядків елементів під пропсом `head` на кожному об'єкті сторінки: ```json { "props": { "head": [ "Dashboard - Laravel", "" ] } } ``` Ви вмикаєте опцію `serverHead` Inertia - доступну в Inertia 3.5 і пізніше - всюди, де ви викликаєте `createInertiaApp()`, включаючи вашу точку входу SSR, якщо вона у вас є. Кожен елемент несе стабільний ключ `data-inertia`, який Inertia приймає і підтримує синхронізованим між відвідуваннями, миттєвими відвідуваннями та навігацією вперед/назад. Оскільки `@head` поміщає теги у початкову HTML-відповідь, краулери та боти попереднього перегляду посилань читають їх без запуску JavaScript, і клієнтський компонент `` не потрібен. Теги, які ніколи не змінюються протягом сесії - viewport, колірна схема, favicon'и, маніфест - можна зареєструвати окремо за допомогою `Head::inertiaGlobals()`. Вони виключаються з пропса `head`, рендеряться без атрибутів володіння і ніколи не оновлюються після першої відповіді. Якщо ви додаєте це до існуючого додатка Inertia, видаліть колбеки заголовків з `app.tsx` та `ssr.tsx` і перенесіть все, що зараз знаходиться в компоненті `` Inertia, щоб вони ніколи не керували одним і тим самим елементом. ## Встановлення та використання Laravel Head вимагає PHP 8.3 та Laravel 13.17 або новіше, і встановлюється через Composer: ```bash composer require laravel/head ``` Далі зареєструйте defaults у service provider і додайте `@head` до вашого макета. Додатки, які хочуть отримати розв'язані метадані як дані, а не розмітку, можуть викликати `Head::toArray()`, який повертає заголовки, значення Open Graph, схеми JSON-LD та решту як структурований масив. Повна документація доступна в [офіційних документах Laravel](https://laravel.com/docs/13.x/head), а вихідний код знаходиться в [репозиторії laravel/head на GitHub](https://github.com/laravel/head).