> ## Documentation Index > Fetch the complete documentation index at: https://kawax.biz/llms.txt > Use this file to discover all available pages before exploring further. # Laravel Head — pacchetto per gestire il del documento > Introduzione a laravel/head. Il pacchetto ufficiale Laravel che gestisce con un'API fluida title, meta, Open Graph, canonical URL, robots, performance hints e dati strutturati per Blade, Livewire e Inertia. Rilascio del 28 luglio 2026. ## Introduzione [laravel/head](https://github.com/laravel/head) è il pacchetto ufficiale Laravel che gestisce con un'API fluida il `` del documento della tua applicazione. Supporta title, meta tag, Open Graph, canonical URL, direttive robots, performance hints e dati strutturati; funziona con Blade, Livewire e Inertia. La v0.1.0 è stata rilasciata il 28 luglio 2026. ```bash theme={null} composer require laravel/head ``` ## Ordine di risoluzione I dati di head della pagina vengono risolti secondo cinque livelli, dal più basso al più alto in priorità. 1. Default della pagina 2. Metadati del gruppo di route 3. Metadati della route 4. Metadati a runtime 5. Metadati delle pagine di errore I livelli superiori sovrascrivono i livelli inferiori campo per campo. Ad esempio, il title impostato a runtime sostituisce il title della route ma non ne sostituisce la description. ```mermaid theme={null} graph TD A["Default della pagina"] --> B["Metadati del
gruppo di route"] B --> C["Metadati della route"] C --> D["Metadati a runtime"] D --> E["Metadati delle
pagine di errore"] E --> F["Output finale
<head>"] ``` ## Registrazione dei default I default a livello di sito si registrano in un service provider. ```php theme={null} use Laravel\Head\Facades\Head; use Laravel\Head\HeadBuilder; use Laravel\Head\Enums\OgType; Head::defaults(function (HeadBuilder $head) { $head ->title('Acme', suffix: ' - Acme') ->description('Build something great.') ->canonical() ->og(siteName: 'Acme', type: OgType::Website) ->searchableByRobots() ->preconnect('https://fonts.example.com'); }); ``` Il livello dei default è quello con priorità più bassa. Finché nessun livello superiore imposta il title verrà usato `Acme` così com'è; se un livello superiore imposta il title, verrà applicato il suffisso ereditato (`Head::title('About')` diventa `About - Acme`). ## Metadati della route Le pagine statiche possono associare i metadati direttamente alla definizione della route. ```php theme={null} Route::view('/contact', 'contact') ->name('contact') ->withHead( title: 'Contact Us', description: 'Get in touch.', ); ``` Puoi applicare metadati comuni a un intero gruppo. ```php theme={null} Route::withHead(robots: 'noindex, nofollow') ->prefix('admin') ->name('admin.') ->group(function () { Route::get('/dashboard', DashboardController::class) ->name('dashboard') ->withHead(title: 'Dashboard'); }); ``` `withHead()` salva un array semplice attraverso l'API standard dei metadati di route di Laravel (sotto la chiave `head` di `->metadata()`), quindi mantiene la compatibilità con le route in cache. ## Metadati a runtime Per valori noti solo alla richiesta — come il titolo di un post — impostali a runtime con la facade `Head`. ```php theme={null} use App\Models\Post; use Laravel\Head\Facades\Head; public function show(Post $post) { Head::title($post->title) ->description($post->description); return view('posts.show', ['post' => $post]); } ``` I metadati condizionali si esprimono in modo fluido con `when()` / `unless()`. ```php theme={null} Head::title($post->title) ->when($post->isDraft(), fn ($head) => $head->hiddenFromRobots()); ``` ## Pagine di errore Puoi registrare metadati per singolo status code. ```php theme={null} use Laravel\Head\ErrorPages; use Laravel\Head\Facades\Head; Head::errors(function (ErrorPages $errors) { $errors->defaults(robots: 'noindex, follow'); $errors->status(404, title: 'Page Not Found', description: 'The page you are looking for could not be found.', ); }); ``` Quando viene renderizzato uno degli status di errore registrati, questi metadati hanno la precedenza su qualunque altro livello. ## Open Graph e Twitter Card Con `og()` imposti le proprietà Open Graph e con metodi come `ogImage()` aggiungi immagini, video o audio. ```php theme={null} use Laravel\Head\Enums\ImageType; use Laravel\Head\Enums\OgType; Head::og(type: OgType::Article, title: $post->title) ->ogImage($post->hero_image_url) ->ogImage( $post->gallery_image_url, alt: $post->gallery_image_alt, width: 1200, height: 630, type: ImageType::Jpeg, ); ``` `title` e `description` del documento popolano automaticamente `og:title` / `og:description` se non impostati. Le Twitter Card, una volta registrate nei default, si renderizzano automaticamente usando gli stessi title, description e immagini di Open Graph. ```php theme={null} use Laravel\Head\Enums\TwitterCard; use Laravel\Head\Facades\Head; use Laravel\Head\HeadBuilder; Head::defaults(fn (HeadBuilder $head) => $head->twitter( card: TwitterCard::SummaryWithLargeImage, )); ``` Puoi anche sovrascrivere esplicitamente i valori Twitter sulla singola pagina. ```php theme={null} Head::twitter(title: $post->social_title) ->twitterImage($post->social_image_url, alt: $post->title); ``` ## PWA, performance e icone L'helper `pwa()` imposta in blocco i tag `` necessari per un'app web installabile. ```php theme={null} Head::pwa( name: 'Acme', manifest: '/site.webmanifest', themeColor: '#0f172a', appleTouchIcon: '/apple-touch-icon.png', appleWebAppStatusBarStyle: 'black', ); ``` ## Theme color Il theme color può essere impostato a livello globale, di route o a runtime. Con l'enum `Media` puoi specificare theme color per media specifici. ```php theme={null} use Laravel\Head\Enums\Media; Head::themeColor('#ffffff', media: Media::Light) ->themeColor('#111827', media: Media::Dark); ``` `Media` include anche `Portrait` e `Landscape`. ## Metadati e icone dell'app Laravel Head include helper per i comuni metadati di browser e app. ```php theme={null} use Laravel\Head\Enums\ImageType; use Laravel\Head\Enums\Media; Head::applicationName('Acme') ->colorScheme('light dark') ->referrer('strict-origin-when-cross-origin') ->viewport('width=device-width, initial-scale=1') ->appleWebAppTitle('Acme') ->webAppCapable() ->appleWebAppStatusBarStyle('black') ->favicon('/favicon.svg', type: ImageType::Svg) ->icon('/favicon-32x32.png', type: ImageType::Png, sizes: '32x32') ->appleTouchIcon('/apple-touch-icon.png', sizes: '180x180') ->appleTouchStartupImage('/launch.png', media: Media::Portrait) ->maskIcon('/safari-pinned-tab.svg', color: '#111827') ->manifest('/site.webmanifest'); ``` `favicon()` è un alias di `icon()` e accetta gli stessi argomenti `type`, `sizes` e `media`. ## Performance e discoverability Laravel Head può renderizzare anche performance hints, link di paginazione, alternative di locale e tag per la scoperta dei feed. ```php theme={null} Head::preload(asset('fonts/inter.woff2'), as: 'font', crossorigin: true) ->prefetch(asset('images/next.webp')) ->preconnect('https://cdn.example.com') ->dnsPrefetch('https://analytics.example.com') ->paginate($posts) ->alternates([ 'en' => 'https://example.com/en/about', 'fr' => 'https://example.com/fr/about', 'x-default' => 'https://example.com/about', ]) ->feed('/feed', title: 'Acme RSS') ->feed('/feed.atom', type: 'atom', title: 'Acme Atom'); ``` `preloadAsset()` / `prefetchAsset()` risolvono l'URL con l'helper `asset()` e rilevano automaticamente l'attributo `as` dall'estensione. ```php theme={null} Head::preloadAsset('fonts/inter.woff2') ->prefetchAsset('images/next.webp'); ``` ```html theme={null} ``` ## Tag personalizzati I tag senza un metodo dedicato si aggiungono con `meta()` / `link()`. ```php theme={null} Head::meta('format-detection', 'telephone=no') ->meta('article:author', $post->author->name) ->link('search', '/opensearch.xml', [ 'type' => 'application/opensearchdescription+xml', 'title' => 'Acme Search', ]); ``` `meta()` usa `name=` per i normali meta tag, ma per le chiavi che di norma usano `property=` (Open Graph `og:`, metadati di articolo `article:`) passa automaticamente all'attributo corretto. ```php theme={null} Head::meta('description', 'About Acme') ->meta('og:title', 'About Acme'); ``` ```html theme={null} ``` ## Dati strutturati (JSON-LD) Lo schema builder integrato copre i principali tipi JSON-LD. ```php theme={null} 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) ) ); ``` I metodi factory integrati sono `article`, `blogPosting`, `product`, `offer`, `brand`, `breadcrumbs`, `faq`, `organization`, `person`, `webPage` e `webSite`. I factory sconosciuti ricadono su un oggetto schema generico, così puoi rappresentare anche tipi schema.org personalizzati. Gli elementi di una breadcrumb possono essere aggiunti uno per volta o in blocco. La posizione viene assegnata in automatico in base all'ordine. ```php theme={null} Head::schema( Schema::breadcrumbs()->items([ 'Home' => route('home'), 'Shop' => route('shop.index'), 'Shoes' => route('shop.category', 'shoes'), ]) ); ``` Le domande delle FAQ seguono lo stesso pattern. Con `question()` aggiungi una domanda alla volta, con `questions()` più insieme. ```php theme={null} Head::schema( Schema::faq()->questions([ 'What is Laravel Head?' => 'A fluent API for managing the document head.', 'Is it free?' => 'Yes, it is open source.', ]) ); ``` I tipi di schema personalizzati vanno registrati esplicitamente. ```php theme={null} use DateTimeInterface; use Laravel\Head\Facades\Schema; use Laravel\Head\Schema\SchemaObject; use Laravel\Head\SchemaType; #[SchemaType('JobPosting')] class JobPosting extends SchemaObject { public function title(string $title): static { return $this->set('title', $title); } public function datePosted(DateTimeInterface|string $date): static { return $this->date('datePosted', $date); } } Schema::register(JobPosting::class); ``` ## Conclusioni `laravel/head` è un pacchetto che ti permette di gestire in modo centralizzato i metadati necessari a SEO e condivisione sui social, attraversando Blade, Livewire e Inertia. La struttura a cinque livelli (default, gruppo di route, route, runtime, pagine di errore) preserva la coerenza dell'intero sito e allo stesso tempo lascia flessibilità di personalizzazione pagina per pagina. Codice sorgente e novità più recenti. ## Related topics - [PHP FFI](/it/advanced/ffi.md) - [Gestire la compatibilità tra versioni dei pacchetti](/it/advanced/package-versioning.md) - [Personalizzare il rate limiting](/it/advanced/rate-limiting.md) - [Protezione CSRF](/it/csrf.md) - [Response](/it/responses.md)