symfony · weaverryan · Dec 3, 2013 · Dec 2, 2013 · Dec 2, 2013 · stof
diff --git a/components/expression_language/caching.rst b/components/expression_language/caching.rst
@@ -0,0 +1,70 @@
+.. index::
+    single: Caching; ExpressionLanguage
+
+Caching Expressions Using ParserCaches
+======================================
+
+The ExpressionLanguage component already provides a
+:method:`Symfony\\Component\\ExpresionLanguage\\ExpressionLanguage::compile`
+method to be able to cache the expressions in plain PHP. But internally, the
+component also caches the parsed expressions, so duplicated expressions can be
+compiled/evaluated quicker.
+
+The Workflow
+------------
+
+Both ``evaluate`` and ``compile`` needs to do some things before it can
+provide the return values. For ``evaluate``, this overhead is even bigger.
+
+Both methods need to tokenize and parse the expression. This is done by the 
+:method:`Symfony\\Component\\ExpressionLanguage\\ExpressionLanguage::parse`
+method. It'll return a :class:`Symfony\\Component\\ExpressionLanguage\\ParsedExpression`.
+Now, the ``compile`` method just returns the string conversion of this object.
+The ``evaluate`` method needs to loop through the "nodes" (pieces of an
+expression saved in the ``ParsedExpression``) and evaluate them on the fly.
+
+To save time, the ``ExpressionLanguage`` caches the ``ParsedExpression``, so
+it can skip the tokenize and parse steps with duplicate expressions.
+The caching is done by a
+:class:`Symfony\\Component\\ExpressionLanguage\\ParserCache\\ParserCacheInterface`
+instance (by default, it uses an
+:class:`Symfony\\Component\\ExpressionLanguage\\ParserCache\\ArrayParserCache`).
+You can customize this by creating a custom ``ParserCache`` and injecting this
+in the object using the constructor::
+
+    use Symfony\Component\ExpressionLanguage\ExpressionLanguage;
+    use Acme\ExpressionLanguage\ParserCache\MyDatabaseParserCache;
+
+    $cache = new MyDatabaseParserCache(...);
+    $language = new ExpressionLanguage($cache);
+
+.. note::
+
+    The `DoctrineBridge`_ has a ParserCache implementation using the
+    `doctrine cache library`_, which gives you caching for all sorts of cache
+    strategies, like Apc, Filesystem and Apc.
+
+Using Parsed and Serialized Expressions
+---------------------------------------
+
+Both ``evaluate`` and ``compile`` can handle ``ParsedExpression`` and
+``SerializedParsedExpression``::
+
+    use Symfony\Component\ExpressionLanguage\ParsedExpression;
+    // ...
+
+    $expression = new ParsedExpression($language->parse('1 + 4'));
+
+    echo $language->evaluate($expression); // prints 5
+
+.. code-block:: php
+
+    use Symfony\Component\ExpressionLanguage\SerializedParsedExpression;
+    // ...
+
+    $expression = new SerializedParsedExpression(serialize($language->parse('1 + 4')));
+
+    echo $language->evaluate($expression); // prints 5
+
+.. _DoctrineBridge: https://github.com/symfony/DoctrineBridge
+.. _`doctrine cache library`: http://docs.doctrine-project.org/projects/doctrine-common/en/latest/reference/caching.html
diff --git a/components/expression_language/index.rst b/components/expression_language/index.rst
@@ -7,3 +7,4 @@ Expression Language
     introduction
     syntax
     extending
+    caching
diff --git a/components/expression_language/introduction.rst b/components/expression_language/introduction.rst
@@ -109,4 +109,10 @@ PHP type (including objects)::
 This will print "Honeycrisp". For more information, see the :doc:`/components/expression_language/syntax`
 entry, especially :ref:`component-expression-objects` and :ref:`component-expression-arrays`.
 
+Caching
+-------
+
+The component provides some different caching strategies, read more about them
+in :doc:`/components/expression_language/caching`.
+
 .. _Packagist: https://packagist.org/packages/symfony/expression-language
diff --git a/components/map.rst.inc b/components/map.rst.inc
@@ -62,6 +62,7 @@
   * :doc:`/components/expression_language/introduction`
   * :doc:`/components/expression_language/syntax`
   * :doc:`/components/expression_language/extending`
+  * :doc:`/components/expression_language/caching`
 
 * **Filesystem**
-Original file line number
+Diff line change
@@ Expand Up / @@ -7,3 +7,4 @@ Expression Language @@
         introduction
         syntax
         extending
+        caching