Skip to content
This repository was archived by the owner on Sep 16, 2021. It is now read-only.

block: classes checked + added sonata prepended config #282

Merged
merged 5 commits into from
Oct 5, 2013
Merged

block: classes checked + added sonata prepended config #282

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2523a22
block: classes checked + added sonata prepended config
Oct 1, 2013
bf9aeae
continue block bundle doc cleanup
dbu Oct 1, 2013
2d5f989
cleanup cache doc and fix feedback
dbu Oct 2, 2013
995113b
improve after feedback
dbu Oct 2, 2013
cc75b37
Merge remote-tracking branch 'origin/master' into block-bundle
dbu Oct 2, 2013
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
158 changes: 87 additions & 71 deletions bundles/block/cache.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,11 @@
Cache
=====

.. include:: ../_outdate-caution.rst.inc
The Symfony2 CMF BlockBundle integrates with the `SonataCacheBundle`_ to
provide several caching solutions. Have a look at the available adapters in the
`SonataCacheBundle`_ to see all options.

The BlockBundle integrates with the `SonataCacheBundle`_ to provide several
caching solutions. Have a look at the available adapters in the
SonataCacheBundle to see all options.

The BlockBundle additionally provides its own adapters for:
The Symfony2 CMF BlockBundle additionally provides its own adapters for:

* `ESI`_
* `SSI`_
Expand Down Expand Up @@ -58,7 +56,8 @@ CmfBlockBundle and the SonataBlockBundle:
<!-- ... -->

<import resource="@SymfonyCmfBlockBundle/Resources/config/routing/cache.xml"
prefix="/" />
prefix="/"
/>
</routes>

.. code-block:: php
Expand All @@ -74,70 +73,82 @@ CmfBlockBundle and the SonataBlockBundle:
3. *SonataBlockBundle* - Use the ``sonata_block`` key to configure the cache
adapter for each block service:

.. configuration-block::
.. configuration-block::

.. code-block:: yaml
.. code-block:: yaml

# app/config/config.yml
sonata_block:
# ...
blocks:
acme_main.block.news:
# use the service id of the cache adapter
cache: cmf.block.cache.js_async
blocks_by_class:
# cache only the RssBlock and not all action blocks
Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\RssBlock:
# app/config/config.yml
sonata_block:
# ...
blocks:
symfony_cmf.block.action:
# use the service id of the cache adapter
cache: cmf.block.cache.js_async
blocks_by_class:
# cache only the RssBlock and not all action blocks
Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\RssBlock:
cache: cmf.block.cache.js_async

.. code-block:: xml
.. code-block:: xml

<!-- app/config/config.xml -->
<?xml version="1.0" charset="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services">
<!-- app/config/config.xml -->
<?xml version="1.0" charset="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services">

<config xmlns="http://sonata-project.org/schema/dic/block">
<!-- use the service id of the cache adapter -->
<blocks id="symfony_cmf.block.action"
<block
id="symfony_cmf.block.action"
cache="symfony_cmf.block.cache.js_async"
/>
<block-by-class
class="Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\RssBlock"
cache="symfony_cmf.block.cache.js_async"
/>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@wouterj i hope i got this right? the Configuration class is here: https://github.com/sonata-project/SonataBlockBundle/blob/master/DependencyInjection/Configuration.php#L66

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

correct!

</config>
</container>

.. code-block:: php

// app/config/config.php
$container->loadFromExtension('sonata_block', array(
'blocks' => array(
'symfony_cmf.block.action' => array(
// use the service id of the cache adapter
'cache' => 'symfony_cmf.block.cache.js_async',
),
),
));
.. code-block:: php

// app/config/config.php
$container->loadFromExtension('sonata_block', array(
'blocks' => array(
'symfony_cmf.block.action' => array(
// use the service id of the cache adapter
'cache' => 'symfony_cmf.block.cache.js_async',
),
),
'blocks_by_class' => array(
'Symfony\Cmf\Bundle\BlockBundle\Doctrine\Phpcr\RssBlock' => array(
'cache' => 'symfony_cmf.block.cache.js_async',
),
),
),
));

Workflow
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

while i think it makes sense that we document the whole configuration in this doc, this cache flow doc probably should better be in sonata block doc. and it would really profit from a diagram.

if we agree, i will create an issue to transfer that at some point.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#284

--------

The following happens when a block is rendered using cache:
When a block having a cache configured is rendered, the following process
is triggered:

* A document is loaded based on the name
* The document is loaded based on the name;
* If caching is configured, the cache is checked and content is returned if
found
found.

* Cache keys are computed using:

* The cache keys of the block service
* The extraCacheKeys passed from the template
* The cache keys of the block service;
* The extraCacheKeys passed from the template.

* The cache adapter is asked for a cache element
* The cache adapter is asked for a cache element:

* The ESI and SSI adapter add a specific tag and a url to retrieve the
block content
* The Javascript adapter adds javascript and a url to retrieve the block
content
block content;
* The javascript adapter adds javascript and a url to retrieve the block
content.

* If the cache element is not expired and has data it is returned
* If the cache element is not expired and has data it is returned.
* The template is rendered:

* For ESI and SSI the url is called to retrieve the block content
Expand All @@ -150,55 +161,60 @@ The following happens when a block is rendered using cache:
cache is found, have a look at the ``has`` method of the adapters in the
SonataCacheBundle to see how they respond.

If cache is checked and the cache adapter returned that no cache was found,
If the cache is checked and the cache adapter returned that no cache was found,
the workflow proceeds like this:

* Each block document also has a block service, the execute method of it is
called to render the block and return a response
* If the response is cacheable the configured adapter creates a cache element,
it contains
* The block service is asked to render the block
:ref:`as usual <bundle-block-execute>`;
* If the ``Response`` is cacheable, the configured adapter creates a cache
element containing:

* The computed cache keys
* The ttl of the response
* The response
* And additional contextual keys
* The computed cache keys;
* The time to live (TTL) of the response;
* The ``Response``;
* Any additional contextual keys.

* The template is rendered
* The template is rendered.

Cache Keys
----------

The block service has the responsibility to generate the cache keys, the
method ``getCacheKeys`` returns these keys, see :ref:`bundle-block-service`.
It is the responsibility of the :ref:`block service <bundle-block-service>` to generate the cache keys in
the method ``getCacheKeys``.

The block services shipped with the BlockBunde use the ``getCacheKeys`` method
of the ``Sonata\BlockBundle\Block\BaseBlockService``, and return:
The block services shipped with the Symfony CMF BlockBunde use the
``getCacheKeys`` method of the ``Sonata\BlockBundle\Block\BaseBlockService``
which returns:

* ``block_id``
* ``updated_at``

.. note::
.. caution::

If block settings need to be persisted between requests it is advised to
store them in the block document. Alternatively they can be added to the
cache keys. However be very cautious because, depending on the adapter,
the cache keys can be send to the browser and are not secure.
If block settings need to be persisted between requests, it is advised to
store them in the block document. If you add them to the cache keys, you
have to be aware that depending on the adapter, the cache keys can be sent
to the browser and thus are neither hidden nor safe from manipulation by a
client.

Extra Cache Keys
~~~~~~~~~~~~~~~~

The extra cache keys array is used to store metadata along the cache element.
The metadata can be used to invalidate a set of cache elements.
The metadata can be used to invalidate a set of cached elements.

Contextual Keys
~~~~~~~~~~~~~~~

The contextual cache array hold the object class and id used inside the
template. This contextual cache array is then added to the extra cache key.

This feature can be use like this ``$cacheManager->remove(array('objectId' => 'id'))``.
This feature can be use like this::

$cacheManager->remove(array('objectId' => 'id'));

Of course not all cache adapters support this feature, varnish and MongoDB do.
While not all cache adapters support this feature, the Varnish and MongoDB
adapters do.

The BlockBundle also has a cache invalidation listener that calls the
``flush`` method of a cache adapter automatically when a cached block document
Expand Down Expand Up @@ -235,7 +251,7 @@ your Twig template when using cache:
),
)) ?>

When using the Esi, Ssi or Js cache adapters the settings passed here are remembered:
When using the Esi, Ssi or Js cache adapters, the settings passed here are remembered:

.. configuration-block::

Expand Down Expand Up @@ -269,9 +285,9 @@ also the `SonataBlockBundle Advanced usage`_ documentation.

.. caution::

Because, as mentioned above, settings can be added to the url as parameters
avoid exposing sensitive settings from ``sonata_block_render`` and try to
store them in the block document.
Because, as mentioned above, settings can be added to the URL as
parameters, you have to avoid exposing sensitive settings from
``sonata_block_render`` and store them in the block document instead.

Adapters
--------
Expand Down
Loading