# Doctrine View Cache Plugin

This is a plugin which includes a Doctrine behavior for your models. It 
implements integration with the symfony caching and routing layers. Below you 
will find a list of the main features of this behavior:

# Installation

## SVN

Currently their is no package so you will need to checkout the plugin using SVN 
into your plugins directory.

    $ svn co http://svn.symfony-project.com/plugins/sfDoctrineViewCachePlugin/trunk plugins/sfDoctrineViewCachePlugin

>**TIP**
>**SVN EXTERNALS**
>
>You can of course use externals if your project is already in SVN. This is highly recommended.

## Enable

Now you need to enable the plugin in your `config/ProjectConfiguration.class.php`:

    [php]
    public function setup()
    {
      $this->enablePlugins(array('sfDoctrineViewCachePlugin'));
    }


# Versions

This has only been tested with symfony 1.2 but it should work the same for 1.0 and 1.1.

# Features

Below you will find a list of the main features of this behavior:

* Ability to control whether cache is cleared on insert/update/delete
* Clear cache globally
* Specify array of items to remove from cache the using `sfViewCacheManager::remove()` method or the `sfToolKit::clearGlob()` method.
* The most convenient feature is the integration with the routing layer so it is aware of what routes are bound to Doctrine objects so it can know what items to clear from the cache.

The Doctrine View Cache Plugin integrates with the symfony view
cache so that you can specify items to clear when records are inserted, updated 
or deleted. It even integrates with the symfony routing system
and will automatically detect what namespaces to clear in the cache based on the
objects you have mapped to URLs.

Below you will find some example syntaxes:

>**NOTE**
>When you add the `sfViewCache` behavior with the `actAs` option you will need 
>rebuild your models and clear your cache before the behavior will begin to
>work.
>
>     $ ./symfony doctrine:build-model
>     $ ./symfony cc

## Globally Clear Cache

Sometimes it may just be easiest to clear the entire cache when a model is 
changed. You can do this with the global option:

    [yml]
    BlogPost:
      actAs:
        sfViewCache:
          global: true
      columns:
        title: string(255)
        body: clob

## Clearing Items

You can clear items from the cache the normal way just as you would with the 
`sfViewCacheManager::remove` or `sfToolKit::clearGlob` methods in your project
code.

### View Cache Manager

You can use the `sfViewCacheManager` to remove items from your cache just like
you would in your project code like the following:

    [php]
    $cacheManager = $this->getContext()->getViewCacheManager();
    $cacheManager->remove('blog/view?slug='.$blogPost->slug);

Here is a similar example where we add that cache clearing functionality to our
model:

    [yml]
    BlogPost:
      actAs:
        sfViewCache:
          items:
            blog_index: blog/index
            blog_post_view: blog/view?slug=:slug
            blog_latest: blog/latest
      columns:
        title: string(255)
        body: clob

-

> **NOTE**
> In order to clear the cache using the `sfViewCacheManager` the `sfConfig` setting `sf_cache` must be set to true and it can only clear cache items for the application the behavior is invoked from.

### Manual

You can use the `manual` option to specify the behavior to simply use 
`sfToolKit::clearGlob` to find the cache for the pattern you specify. Just like 
the example above you can use the `:field_name` syntax to replace variables in the path from the object that invokes the behavior.

    [yml]
    BlogPost:
      actAs:
        sfViewCache:
          items:
            blog_index: blog/index
            blog_post_view:
              manual: true
              path: blog/:slug
            blog_latest:
              manual: true
              path: blog/latest
      columns:
        title: string(255)
        body: clob

### Clear Routes

Want Doctrine to try and find all the cache items that are 
related to the model with the behavior is attached to? Simply enable the 
`clear_routes` option for a certain application and it will parse the routes and 
find the modules and actions bound to the model.

    [yml]
    BlogPost:
      actAs:
        sfViewCache:
          clear_routes: frontend
      columns:
        title: string(255)
        body: clob

Here are three example routes that would be matched and cleared:

    [yml]
    blog:
      url:   /blog
      param: { module: blog, action: index }
      class: sfDoctrineRoute
      options: { model: BlogPost, type: list, method: retrieveBlogIndex }

    latest_blog:
      url:   /blog/latest
      param: { module: blog, action: latest }
      class: sfDoctrineRoute
      options: { model: BlogPost, type: list, method: retrieveLatest }

    blog_post:
      url:   /blog/:slug
      param: { module: blog, action: view  }
      class: sfDoctrineRoute
      options: { model: BlogPost, type: object }

### Insert, Update, Delete?

Want to control whether the the behavior is triggered on insert, update and deleted? You can use the `on_insert`, `on_update` and `on_delete` and options:

    [yml]
    BlogPost:
      actAs:
        sfViewCache:
          global: true
          on_insert: true
          on_delete: false
          on_update: false
      columns:
        title: string(255)
        body: clob