..versionadded::3.3

The WebLink component was introduced in Symfony 3.3.

By implementing cutting edge web standards, namely `HTTP/2 Server Push`_ and

W3C's `Resource Hints`_, the WebLink component

brings great opportunities to boost webapp's performance.

Thanks to WebLink, HTTP/2 (**h2**) servers are able to push resources to clients

before they even know that they need them (think to CSS or JavaScript

files, or relations of an API resource). WebLink also enables other very

efficient optimisations that work with HTTP 1:

- telling the browser to fetch or to render another webpage in the

background ;

- init early DNS lookups, TCP handshakes or TLS negotiations

Let's discover how easy it is to use it and the real life benefits you

can expect.

To benefit from HTTP/2 Server Pushes, a HTTP/2 server and a HTTPS connection

are mandatory (even in local).

Both Apache, Nginx and Caddy support these protocols.

Be sure they are properly configured before reading.

Alternatively, you can use the `Docker installer and runtime for

Symfony`_ provided by Kévin Dunglas (community supported).

It includes everything you need to run Symfony

(PHP:doc:`configured properly for Symfony</performance>`, and Composer)

as well as a development reverse proxy (Apache) supporting HTTP/2 Server Push

and HTTPS (most clients only support HTTP/2 over TLS).

Unzip the downloaded archive, open a shell in the resulting directory and run

the following command:

Installation

..code-block::terminal

Open ``https://localhost``, if this nice page appears, you

successfully created your first Symfony 4 project and are browsing it in

HTTP/2!

..image::/_images/components/weblink/symfony4-http2.png

Let's create a very simple homepage using

the `Twig`_ templating engine.

The first step is to install the library itself:

..code-block::terminal

Symfony is smart enough to download Twig, to automatically register it,

and to enable Symfony features requiring the library.

It also generates a base HTML5 layout in the ``templates/`` directory.

Now, download `Boostrap`_, extract the archive and copy the file

``dist/css/bootstrap.min.css`` in the ``public/`` directory of our

Chrome DevTools), encounters the reference to ``bootstrap.min.css`` and

finally sends a new HTTP request, we could take benefit of the HTTP/2

Push feature to directly send both resources to the browser.

Let's do it! Install the WebLink component:

..code-block::terminal

As for Twig, Symfony will automatically download and register this component into our app.

Now, update the template to use the ``preload`` Twig helper that

``bootstrap.min.css`` has started to be received before the browser even requested it!

..note::

Google Chrome provides a nice interface to debug HTTP/2 connections.

Open ``chrome://net-internals/#http2`` to start the tool.

How does it works?

The WebLink component tracks Link HTTP headers to add to the response.

When using the ``preload()`` helper, a ``Link`` header

with a `preload`_

``rel`` attribute is added to the response:

issuing an early separate HTTP request, use the ``nopush`` attribute:

..code-block::html+twig

{# ... #}

<link rel="stylesheet" href="{{ preload('/bootstrap.min.css', {nopush: true}) }}">

{# ... #}

Before using HTTP/2 Push, be sure to read `this great article`_ about

known issues, cache implications and the state of the support in popular

browsers.

In addition to HTTP/2 Push and preloading, the WebLink component also

provide some helpers to send `Resource

Hints <https://www.w3.org/TR/resource-hints/#resource-hints>`__ to

clients, the following helpers are available:

- ``dns_prefetch``: "indicate an origin that will be used to fetch

required resources, and that the user agent should resolve as early

as possible"

- ``preconnect``: "indicate an origin that will be used to fetch

required resources. Initiating an early connection, which includes

the DNS lookup, TCP handshake, and optional TLS negotiation, allows

the user agent to mask the high latency costs of establishing a

connection"

- ``prefetch``: "identify a resource that might be required by the next

navigation, and that the user agent *should* fetch, such that the

user agent can deliver a faster response once the resource is

requested in the future"

- ``prerender``: "identify a resource that might be required by the

next navigation, and that the user agent *should* fetch and

execute, such that the user agent can deliver a faster response once

the resource is requested in the future"

The component can also be used to send HTTP link not related to

performance. For instance, any `link defined in the HTML specification`_:

..code::html+twig

{# ... #}

<link rel="alternate" href="{{ link('/index.jsonld', 'alternate') }}">

<link rel="stylesheet" href="{{ preload('/bootstrap.min.css', {nopush: true}) }}">

{# ... #}

The previous snippet will result in this HTTP header being sent to the

client:

``Link: </index.jsonld>; rel="alternate",</bootstrap.min.css>; rel="preload"; nopush``

You can also add links to the HTTP response directly from a controller

or any service:

..code::php

..code-block::yaml

Last but not least, as all Symfony components, WebLink can be used as a

standalone PHP library:

Alternatively, you can clone the `<https://github.com/symfony/weblink>`_ repository.

..code-block::php

..include::/components/require_autoload.rst.inc

Usage

To see how WebLink is used in the wild, take a look to the `Bolt`_

and `Sulu`_ CMS, they both use WebLink to trigger HTTP/2 pushes.

While we're speaking about interoperability, WebLink can deal with any link implementing

`PSR-13`_.

..seealso::

Thanks to Symfony WebLink, there is no excuses to not to switch to HTTP/2!

Read the:doc:`WebLink documentation</weblink>`_ to learn how

to use the features implemented by this component.

.. _`Web Links`: https://tools.ietf.org/html/rfc5988

.. _`HTTP/2 Server Push`:https://tools.ietf.org/html/rfc7540#section-8.2

.. _`Resource Hints`:https://www.w3.org/TR/resource-hints/

.. _`Twig`:https://twig.symfony.com/

.. _`Docker installer and runtime for Symfony`:https://github.com/dunglas/symfony-docker

.. _`Bootstrap`:https://getbootstrap.com/

.. _`nice integration with of the most popular CSS framework`:https://symfony.com/blog/new-in-symfony-3-4-bootstrap-4-form-theme

.. _`preload`:https://developer.mozilla.org/en-US/docs/Web/HTML/Preloading_content

.. _`the Preload specification`:https://www.w3.org/TR/preload/#server-push-(http/2)

.. _`Cloudflare`:https://blog.cloudflare.com/announcing-support-for-http-2-server-push-2/

.. _`Fastly`:https://docs.fastly.com/guides/performance-tuning/http2-server-push

.. _`Akamai`:https://blogs.akamai.com/2017/03/http2-server-push-the-what-how-and-why.html

.. _`this great article`:https://www.shimmercat.com/en/blog/articles/whats-push/

.. _`link defined in the HTML specification`:https://html.spec.whatwg.org/dev/links.html#linkTypes

.. _`Bolt`:https://bolt.cm/

.. _`Sulu`:https://sulu.io/

.. _`PSR-13`:http://www.php-fig.org/psr/psr-13/