Deprecated/0.11.0/CachingExecutionFilter
Warning! This page has the following tags:
- This page is deprecated as of Agavi 0.11.0.
- This page exists for reference purposes only.
The CachingExecutionFilter?
Since 0.11, Agavi ships with an alternative ExecutionFilter that can cache the output generated by Actions. All aspects of the caching can be controlled using a configuration file.
Enabling The Filter
To turn on the caching support, change the execution_filter line in contexts.ini to:
execution_filter = "CachingExecutionFilter"
If your application uses configuration files from previous Agavi versions there are two more things to do:
- Add CachingExecutionFilter? either to webapp/config/autoload.ini or webapp/config/compile.conf, which ever you prefer
autoload.ini style: CachingExecutionFilter = "%AG_APP_DIR%/filter/CachingExecutionFilter.class.php"
compile.conf style:%AG_APP_DIR%/filter/CachingExecutionFilter.class.php
- Define a handler for modules/*/config/caching.ini in webapp/config/config_handlers.ini
[modules/*/config/caching.ini]
class = "ReturnArrayConfigHandler"
A First Look At Configuration
Use a file called caching.ini, which must sit in a module's config directory, to control all aspects of the caching.
For every Action you want to cache, you have to begin a new section. The section name is the name of the Action. If you're using Sub-Actions, use the dot-notation that you'd also use in the URL to dispatch a request. Example:
[Products.View]
Next, we have to turn on caching for this action and define some groups. Think of groups as folders in the file system. They are a very important feature, because they allow you to control caches if you set them up in an intelligent manner. We'll talk about this later. First, some code:
[Products.View] enabled = true groups.0.name = "Products" groups.1.source = "request.parameter" groups.1.name = "id" views.whitelist.0 = "Success"
This will enable caching for Products/ViewMachineAction if the Action returns "Success" (i.e. View::SUCCESS) as it's View. This way, evil people can't fill your server's hard drive by calling the action repeatedly with reandom, non-existant product IDs (assuming you return View::ERROR in that case, which you really should!).
A Closer Look At Groups
Groups get directly translated into filesystem paths (okay, the identifiers are base64_encode()d). Since the file system is a tree structure, you might already have guessed that this makes clearing multiple caches at once a pice of cake. Or not? Anyways, we'll continue with an example.
So your website is bilingual, you have an English, an Italian and a... uhm... yeah, what about German? version. And each product has an English, an Italian and a German description. Let's assume your language is defined in the constant LANG (no, I'm not joking, I'm actually doing this; it is set in config.php based on what Apache gives me via $_ENV):
groups.0.name = "Products" groups.1.source = "request.parameter" groups.1.name = "id" groups.2.name = LANG
You may have noticed two things:
- This crazy guy is using the source declaration whenever he seems to feel like it.
- Can't he for the sake of god be consistent with his use of quotation marks.
I'll tell ya a secret. The default source is string. And if you don't put a string into quotation marks, it gets treated as a constant. Cool, eh? Yes.
It's time to show why we're doing this anyway. Let's say in your backend's Products.Edit Action (or whatever it is), you'd do something along the lines of:
CachingExecutionFilter::clearCache(array('Products', $productId));
to clear the cache for this product when the product is edited. And w0000t''' all language versions are cleared, too, and the cache automatically gets re-generated the next time someone accesses the product! Isn't that wonderful?
Also, it is important to note that the filter automatically appends a default group to the end of the list. The group name is the name of the action. This way, you could have a slot which uses the same Products/<id>/<language> structure, and this cache, too, would be removed when you clear it with the code in the example above.
