Skip to content

[HTTP-cache] Added SSI #11024

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 15, 2019
Merged

[HTTP-cache] Added SSI #11024

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
142 changes: 142 additions & 0 deletions http_cache/ssi.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
.. index::
single: Cache; SSI
single: SSI

.. _server-side-includes:

Working with Server Side Includes
=================================

In a similar way as :doc:`ESI (Edge Side Includes) <esi>`, SSI can be used to
control HTTP caching on fragments of a response. The most important
difference that is SSI is known directly by most web servers like
`Apache <https://httpd.apache.org/docs/current/en/howto/ssi.html>`_,
`Nginx <https://nginx.org/en/docs/http/ngx_http_ssi_module.html>`_ etc.

The SSI instructions are done in HTML comments:

.. code-block:: html

<!DOCTYPE html>
<html>
<body>
<!-- ... some content -->

<!-- Embed the content of another page here -->
<!--#include virtual="http://..." -->

<!-- ... more content -->
</body>
</html>

There is some other `available directives
<https://en.wikipedia.org/wiki/Server_Side_Includes#Directives>`_ but
Symfony manages only the ``#include virtual`` one.

.. caution::

Be careful with SSI, your website may be victim of injections.
Please read this OWASP article first:
https://www.owasp.org/index.php/Server-Side_Includes_(SSI)_Injection.

When the web server reads an SSI directive, it requests the given URI or gives
directly from its cache. It repeats this process until there is no more
SSI directives to handle. Then, it merges all responses into one and sends
it to the client.

.. _using-ssi-in-symfony:

Using SSI in Symfony
~~~~~~~~~~~~~~~~~~~~

First, to use SSI, be sure to enable it in your application configuration:

.. configuration-block::

.. code-block:: yaml

# config/packages/framework.yaml
framework:
# ...
ssi: { enabled: true }

.. code-block:: xml

<!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/symfony"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

<framework:config>
<!-- ... -->
<framework:ssi enabled="true" />
</framework:config>
</container>

.. code-block:: php

// config/packages/framework.php
$container->loadFromExtension('framework', array(
// ...
'ssi' => array('enabled' => true),
));

Suppose you have a page with private content like a Profile page and you want
to cache a static GDPR content block. With SSI, you can add some expiration
on this block and keep the page private::

// src/Controller/ProfileController.php

// ...
class ProfileController extends AbstractController
{
public function index(): Response
{
// by default, responses are private
return $this->render('profile/index.html.twig');
}

public function gdpr(): Response
{
$response = $this->render('profile/gdpr.html.twig');

// sets to public and adds some expiration
$response->setSharedMaxAge(600);

return $response;
}
}

The profile index page has not public caching, but the GDPR block has
10 minutes of expiration. Let's include this block into the main one:

.. code-block:: twig

{# templates/profile/index.html.twig #}

{# you can use a controller reference #}
{{ render_ssi(controller('App\Controller\ProfileController::gdpr')) }}

{# ... or a URL #}
{{ render_ssi(url('profile_gdpr')) }}

The ``render_ssi`` twig helper will generate something like:

.. code-block:: html

<!--#include virtual="/_fragment?_hash=abcdef1234&_path=_controller=App\Controller\ProfileController::gdpr" -->

``render_esi`` ensures that SSI directive are generated only if the request
has the header requirement like ``Surrogate-Capability: device="SSI/1.0"``
(normally given by the web server).
Otherwise it will embed directly the sub-response.

.. note::

For more information about Symfony cache fragments, take a tour on
the :ref:`ESI documentation <http_cache-fragments>`.