Author: Tobias Schlitt Date: 2006-01-24 23:07:27 +0100 (Tue, 24 Jan 2006) New Revision: 2022
Log: - Adding Cache tutorial. # Please review! Added: packages/Cache/trunk/docs/tutorial.txt packages/Cache/trunk/docs/tutorial_autoload.php packages/Cache/trunk/docs/tutorial_example_01.php packages/Cache/trunk/docs/tutorial_example_02.php packages/Cache/trunk/docs/tutorial_example_03.php Added: packages/Cache/trunk/docs/tutorial.txt =================================================================== --- packages/Cache/trunk/docs/tutorial.txt 2006-01-24 16:12:05 UTC (rev 2021) +++ packages/Cache/trunk/docs/tutorial.txt 2006-01-24 22:07:27 UTC (rev 2022) @@ -0,0 +1,156 @@ +eZ components - Cache +~~~~~~~~~~~~~~~~~~~~~ + +.. contents:: Table of Contents + +Introduction +============ + +The Cache package provides a collection of lightweight classes to cache +different kinds of data. Beside that, it provides a manager class, which takes +care of instantiating and reusing caches. + +Class overview +============== + +This section gives you an overview on all classes, that are intended to be +used directly. + +ezcCacheManager + This is the manager, which will take care of your caches, if you like. It is + useful to use the manager, if your application needs to cache different data + for different purposes. It allows you to configure all needed caches in a + central place and to retrieve them from the ezcCacheManager, when needed. The + cache manager will store only the configurations and first and only + instantiate the cache object itself, when you request it for use. + +ezcCacheStorage + This is the base class for all cache storages (the cache classes themselves). + All cache classes inherit from this base class. + +ezcCacheStorageFilePlain + Cache objects of this class are capable to store plain text data on the file + system. It utilizes the file_get_contents() and file_put_contents functions + of PHP. + +ezcCacheStorageFileArray + In contrast to ezcCacheStorageFilePlain, objects of this class can store + array structures beside plain text data and will keep PHP data types intact. + The ezcCacheStorageFileArray class generates PHP code, which will be stored + on the file system and simply be required again for restoring the data. + +ezcCacheStorageFileEvalArray + Objects of this storage class follow a similar approach that + ezcCacheStorageFileArray does and is also capable of storing array + structures. The major difference between both classes is, that + ezcCacheStorageFileEvalArray will use PHPs eval() method to restore the + cached data, instead of requiring the stored source. This has the effect, + that the stored data will not be cached again in PHP accelerators like APC_ + (which maybe desirable, if you store large amounts of data at once, to not + pollute your APC cache). + +.. _APC: http://pecl.php.net/package/APC + +Installation +============ + +This tutorial assumes that you have set-up an eZ components environment. For +information on how to do this, please refer to the ComponentsIntroduction_. + +.. _ComponentsIntroduction: http://ez.no/community/articles/an_introduction_to_ez_components + + +Usage +===== + +A simple example +---------------- + +This example shows how to create and use a simple cache with the +ezcCacheManager: + +.. include:: tutorial_example_01.php + :literal: + +In the options for the cache to create, the time-to-life is defined. If left +out, the cache has a lifetime of 24 hrs. In this place, a lifetime of 30 +seconds is defined. On line 9 the cache configuration is stored in the cache +manager. The cache created will be named "simple" and will reside in the directory +/tmp/cache/plain (Note: This directory must exists and must be writable to +the user running the code, else you will get an ezcBaseFileNotFoundException or +an ezcBaseFilePermissionException!). To store the data, the storage class +ezcConsoleStorageFilePlain will be used and as defined before, the stored data +will expire after 30 seconds. + +Line 11 defines a unique ID for the data to cache. After that (line 13), the +cache storage object is retrieved from the ezcCacheManager (the object itself +is created right now, since we access it for the first time). Line 15 shows how +to check for cached data: The method ezcCacheStorage::restore() will return +bool false, if no valid cache data is found. + +In case the cache storage did not find valid data, the data will be generated +and stored in the cache afterwards (lines 17 and 18). The last line shows the +data, so you can follow how it's cached for 30 seconds, by simple running the +example multiple times in a short time frame. + +Using multiple caches +--------------------- + +The following example shows how the cache manager deals with multiple caches: + +.. include:: tutorial_example_02.php + :literal: + +In the lines 12 and 13 you see how 2 caches are created. Each cache must reside +in it's own location and must have a different name. We use 2 different options +for the lifetime of the caches to show how they act independently later. + +Since the first cache reuses the location already used in example 1, the unique +ID has changed. Lines 15 to 25 are almost identical to the code from example 1, +except that the program will sleep for 2 seconds, when it generated new data for +the plain cache, to show different generation times in the 2 caches. + +On line 30 the second cache is retrieved, which is capable of storing arrays. +Therefore, we store the data from the plain cache here and additionally +generate some more data, all stored in an array. Running this example multiple +times will give you different results now after some time, since the second cache +has a longer lifetime and will therefore hold it's data longer than the first one. + +Complex caching +--------------- + +As the next example shows, ezcCacheStorage classes are capable of more advanced +features. This example uses attributes to identify cached data, additionally to their +unique ID: + +.. include:: tutorial_example_03.php + :literal: + +After the creation of an array cache, some sample data is created (lines +11-16). Each data is keyed by it's unique ID, which is associated to an array. +This array will be used as the content and the attributes together later on. Attributes +describe cached data in further detail. We will see, what to do with attributes of +cached data later on, too. + +In line 20 a foreach loop starts, which stores all example data in the cache. After +that (line 36) the method ezcCacheStorageiFile::countDataItems() is used to let +the storage object count it's data items. The first parameter here would be an +ID. When this is set, the method should always return 1 or 0, because only 1 +data item per ID may exist. Instead, the data items with a specific attribute +are counted. The attributes to match are supplied as the second parameter. The first +method call will return 3 (line 28), since we have 3 cache items which have the attribute +"section" set to "articles". The second call (line 32) should return 2, because +2 data items have the attribute "language" set to the value "de". + +On line 36, the storage object is told to delete all cache items, which have +the attribute "language" set to "de". Therefore the next to calls to +ezcCacheStorageiFile::countDataItems() will return 2 and 0. + + + +.. + Local Variables: + mode: rst + fill-column: 79 + End: + vim: et syn=rst tw=79 Property changes on: packages/Cache/trunk/docs/tutorial.txt ___________________________________________________________________ Name: svn:eol-style + native Added: packages/Cache/trunk/docs/tutorial_autoload.php =================================================================== --- packages/Cache/trunk/docs/tutorial_autoload.php 2006-01-24 16:12:05 UTC (rev 2021) +++ packages/Cache/trunk/docs/tutorial_autoload.php 2006-01-24 22:07:27 UTC (rev 2022) @@ -0,0 +1,17 @@ +<?php + +require_once 'Base/trunk/src/base.php'; + +/** + * Autoload ezc classes + * + * @param string $class_name + */ +function __autoload( $class_name ) +{ + if ( ezcBase::autoload( $class_name ) ) + { + return; + } +} +?> Property changes on: packages/Cache/trunk/docs/tutorial_autoload.php ___________________________________________________________________ Name: svn:eol-style + native Added: packages/Cache/trunk/docs/tutorial_example_01.php =================================================================== --- packages/Cache/trunk/docs/tutorial_example_01.php 2006-01-24 16:12:05 UTC (rev 2021) +++ packages/Cache/trunk/docs/tutorial_example_01.php 2006-01-24 22:07:27 UTC (rev 2022) @@ -0,0 +1,23 @@ +<?php + +require_once 'tutorial_autoload.php'; + +$options = array( + 'ttl' => 30, +); + +ezcCacheManager::createCache( 'simple', '/tmp/cache/plain', 'ezcCacheStorageFilePlain', $options ); + +$myId = 'unique_id_1'; + +$cache = ezcCacheManager::getCache( 'simple' ); + +if ( ( $data = $cache->restore( $myId ) ) === false ) +{ + $data = "Plain cache stored on " . date( 'Y-m-d, H:i:s' ); + $cache->store( $myId, $data ); +} + +var_dump( $data ); + +?> Property changes on: packages/Cache/trunk/docs/tutorial_example_01.php ___________________________________________________________________ Name: svn:eol-style + native Added: packages/Cache/trunk/docs/tutorial_example_02.php =================================================================== --- packages/Cache/trunk/docs/tutorial_example_02.php 2006-01-24 16:12:05 UTC (rev 2021) +++ packages/Cache/trunk/docs/tutorial_example_02.php 2006-01-24 22:07:27 UTC (rev 2022) @@ -0,0 +1,46 @@ +<?php + +require_once 'tutorial_autoload.php'; + +$optionsPlain = array( + 'ttl' => 30, +); +$optionsArray = array( + 'ttl' => 45, +); + +ezcCacheManager::createCache( 'plain', '/tmp/cache/plain', 'ezcCacheStorageFilePlain', $optionsPlain ); +ezcCacheManager::createCache( 'array', '/tmp/cache/array', 'ezcCacheStorageFileArray', $optionsArray ); + +$myId = 'unique_id_2'; + +$cache = ezcCacheManager::getCache( 'plain' ); + +if ( ( $plainData = $cache->restore( $myId ) ) === false ) +{ + $plainData = "Plain cache stored on " . date( 'Y-m-d, H:m:s'); + $cache->store( $myId, $plainData ); + + sleep( 2 ); +} + +echo "Plain cache data:\n"; +var_dump( $plainData ); + +$cache = ezcCacheManager::getCache( 'array' ); + +if ( ( $arrayData = $cache->restore( $myId ) ) === false ) +{ + $arrayData = array( + $plainData, + "Array cache stored on " . date( 'Y-m-d, H:m:s'), + true, + 23 + ); + $cache->store( $myId, $arrayData ); +} + +echo "Array cache data:\n"; +var_dump( $arrayData ); + +?> Property changes on: packages/Cache/trunk/docs/tutorial_example_02.php ___________________________________________________________________ Name: svn:eol-style + native Added: packages/Cache/trunk/docs/tutorial_example_03.php =================================================================== --- packages/Cache/trunk/docs/tutorial_example_03.php 2006-01-24 16:12:05 UTC (rev 2021) +++ packages/Cache/trunk/docs/tutorial_example_03.php 2006-01-24 22:07:27 UTC (rev 2022) @@ -0,0 +1,46 @@ +<?php + +require_once 'tutorial_autoload.php'; + +$options = array( + 'ttl' => 30, +); + +ezcCacheManager::createCache( 'array', '/tmp/cache/array', 'ezcCacheStorageFileArray', $options ); + +$exampleData = array( + 'unique_id_3_a' => array( 'language' => 'en', 'section' => 'articles' ), + 'unique_id_3_b' => array( 'language' => 'de', 'section' => 'articles' ), + 'unique_id_3_c' => array( 'language' => 'no', 'section' => 'articles' ), + 'unique_id_3_d' => array( 'language' => 'de', 'section' => 'tutorials' ), +); + +$cache = ezcCacheManager::getCache( 'array' ); + +foreach ( $exampleData as $myId => $exampleDataArr ) +{ + if ( ( $data = $cache->restore( $myId, $exampleDataArr ) ) === false ) + { + $cache->store( $myId, $exampleDataArr, $exampleDataArr ); + } +} + +echo "Data items with tag <section> set to <articles>: " . + $cache->countDataItems( null, array( 'section' => 'articles' ) ) . + "\n"; + +echo "Data items with tag <language> set to <de>: " . + $cache->countDataItems( null, array( 'language' => 'de' ) ) . + "\n\n"; + +$cache->delete( null, array( 'language' => 'de' ) ); + +echo "Data items with tag <section> set to <articles>: " . + $cache->countDataItems( null, array( 'section' => 'articles' ) ) . + "\n"; + +echo "Data items with tag <language> set to <de>: " . + $cache->countDataItems( null, array( 'language' => 'de' ) ) . + "\n\n"; + +?> Property changes on: packages/Cache/trunk/docs/tutorial_example_03.php ___________________________________________________________________ Name: svn:eol-style + native -- svn-components mailing list [email protected] http://lists.ez.no/mailman/listinfo/svn-components
