You are currently reading the 1.2 documentation. Switch to 2.0 

Query Cache & Result Cache

Introduction

Doctrine provides means for caching the results of the DQL parsing process, as well as the end results of DQL queries (the data). These two caching mechanisms can greatly increase performance. Consider the standard workflow of DQL query execution:

  1. Init new DQL query
  2. Parse DQL query
  3. Build database specific SQL query
  4. Execute the SQL query
  5. Build the result set
  6. Return the result set

Now these phases can be very time consuming, especially phase 4 which sends the query to your database server. When Doctrine query cache is being used only the following phases occur:

  1. Init new DQL query
  2. Execute the SQL query (grabbed from the cache)
  3. Build the result set
  4. Return the result set

If a DQL query has a valid cache entry the cached SQL query is used, otherwise the phases 2-3 are executed normally and the result of these steps is then stored in the cache. The query cache has no disadvantages, since you always get a fresh query result.

You should always use query cache in a production environment. That said, you can easily use it during development, too. Whenever you change a DQL query and execute it the first time Doctrine sees that it has been modified and will therefore create a new cache entry, so you don't even need to invalidate the cache.

It's worth noting that the effectiveness of the query cache greatly relies on the usage of prepared statements (which are used by Doctrine by default anyway). You should not directly embed dynamic query parts and always use placeholders instead.

When using a result cache things get even better. Then your query process looks as follows (assuming a valid cache entry is found):

  1. Init new DQL query
  2. Return the result set

As you can see, the result cache implies the query cache shown previously. You should always consider using a result cache if the data returned by the query does not need to be up-to-date at any time.

Query Cache

Using the Query Cache

You can set a connection or manager level query cache driver by using the Doctrine_Core::ATTR_QUERY_CACHE attribute. Setting a connection level cache driver means that all queries executed with this connection use the specified cache driver whereas setting a manager level cache driver means that all connections (unless overridden at connection level) will use the given cache driver.

Setting a manager level query cache driver:

// bootstrap.php

// ...
$manager->setAttribute(Doctrine_Core::ATTR_QUERY_CACHE, $cacheDriver);

The value of $cacheDriver above could be any of the drivers we instantiated in the previous section of this chapter.

Setting a connection level cache driver:

// bootstrap.php

// ...
$conn->setAttribute(Doctrine_Core::ATTR_QUERY_CACHE, $cacheDriver);

Fine Tuning

In the previous chapter we used global caching attributes. These attributes can be overriden at the query level. You can override the cache driver by calling useQueryCache() and pass it an instance of a valid Doctrine cache driver. This rarely makes sense for the query cache but is possible:

$q = Doctrine_Query::create()
    ->useQueryCache(new Doctrine_Cache_Apc());

Result Cache

Using the Result Cache

You can set a connection or manager level result cache driver by using Doctrine_Core::ATTR_RESULT_CACHE. Setting a connection level cache driver means that all queries executed with this connection use the specified cache driver whereas setting a manager level cache driver means that all connections (unless overridden at connection level) will use the given cache driver.

Setting a manager level cache driver:

// bootstrap.php

// ...
$manager->setAttribute(Doctrine_Core::ATTR_RESULT_CACHE, $cacheDriver);

Setting a connection level cache driver:

// bootstrap.php

// ...
$conn->setAttribute(Doctrine_Core::ATTR_RESULT_CACHE, $cacheDriver);

Usually the cache entries are valid for only some time. You can set global value for how long the cache entries should be considered valid by using Doctrine_Core::ATTR_RESULT_CACHE_LIFESPAN.

Set the lifespan as one hour (60 seconds * 60 minutes = 1 hour = 3600 secs):

// bootstrap.php

// ...
$manager->setAttribute(Doctrine_Core::ATTR_RESULT_CACHE_LIFESPAN, 3600);

Now as we have set a cache driver for use we can make a DQL query use it by calling the useResultCache() method:

Fetch blog post titles and the number of comments:

$q = Doctrine_Query::create()
    ->select('b.title, COUNT(c.id) count')
    ->from('BlogPost b')
    ->leftJoin('b.Comments c')
    ->limit(10)
    ->useResultCache(true);

$blogPosts = $q->execute();

Fine Tuning

In the previous chapter we used global caching attributes. These attributes can be overriden at the query level. You can override the cache driver by calling useCache() and pass it an instance of a valid Doctrine cache driver.

$q = Doctrine_Query::create()
    ->useResultCache(new Doctrine_Cache_Apc());

Also you can override the lifespan attribute by calling setResultCacheLifeSpan():

$q = Doctrine_Query::create()
    ->setResultCacheLifeSpan(60 * 30);

Questions and Feedback

If you find a problem with the documentation or have a suggestion, please register and open a ticket.

If you need support or have a technical question, you can post to the user mailing-list.