24.1.2.1. Installation of Cache-Lite

Download Cache-Lite and extract it in the includes folder of your PHP-Nuke installation.

If your PHP does not include the PEAR library, you will need to download download the base PEAR package too. Extract only the PEAR.php file and put it in the same folder as mainfile.php, i.e. your PHP-Nuke base folder.

Cache-Lite needs the PEAR.php file for its error-handling, so you may not notice that you need it until some error occurs.

If your PHP installation includes PEAR, you don't need to bother installing PEAR.php anywhere - it is already there, at the right place. But if your ISP does not include it, the above PEAR.php will do the trick.

That's all! You are now ready to use Cache-Lite.

24.1.2.2. How to use Cache-Lite

Cache-Lite can easily be used to cache a PHP variable. The easiest application of this is to cache the $content variable of a block that does not change very often - and this is the majority of PHP-Nuke blocks!

To use Cache-Lite in a PHP-Nuke block, open that block in your editor and put the following code (see How to accelerate PHP-Nuke):

// include the Cache-Lite package
require_once("includes/Cache_Lite/Lite.php");
// set some variables
$options = array(
  "cacheDir" => "/tmp/Cache_Lite/",
  "lifeTime" => 900
);
// create a Cache_Lite object
$objCache = new Cache_Lite($options);
// test if there exists a valid cache,
// the <acronym>ID</acronym> will be the basename of the block
$fileid = basename($blockfile,".php");
if ($content = $objCache->get($fileid)) {
// add a message indicating this is cached output
  $content .= "\n[cached with ID=$fileid]";
}
else
{
// do the block's work here...

after the lines

if (eregi("block-XXXXXXX.php",$PHP_SELF)) {
  Header("Location: index.php");
  die();
}

What does the inserted code do?

• It includes Cache-Lite. Note that in this example, Cache_Lite is a symbolic link to the actual directory the Lite.php file is in. I created this symbolic link myself, as I did not want to put a version-specific directory name in my code - I would have to change it each time I would upgrade Cache-Lite, this way I will only need to change the symbolic link to show to the right directory.

• It first sets the path to the cache directory, in this case /tmp/Cache_Lite/. The directory must exist and must be writable and readable by the web server.

• Sets the cache expiration time intervall for the object we are going to cache, in this case to 900 seconds.

• Creates a cache object with the above settings.

• Uses a computed "file id" as a key to identify the cached object (the cached $content variable). I have decided to use the basename of the PHP-Nuke block , i.e. the filename of the block without the ".php" ending, as the key for the $content variable. This way I don't have to change my code each time I insert the above lines in a new block. The $key will be computed automatically and will be the basename of the block file. Since in PHP-Nuke blocks are guaranteed to have distinct names, this is a good choice.

  $blockfile is a variable that is computed by PHP-Nuke in mainfile.php, in function blocks():

  $sql = "SELECT bid, bkey, title, content, url, blockfile, view FROM ".$prefix."_blocks WHERE bposition='$pos' AND active='1' $querylang ORDER BY weight ASC"; $result = $db->sql_query($sql); while($row = $db->sql_fetchrow($result)) { $bid = $row[bid]; $title = $row[title]; $content = $row[content]; $url = $row[url]; $blockfile = $row[blockfile];

  The value of $blockfile is then passed through to the individual block: it is passed to function render_blocks() (in mainfile.php again), which in turn renders the block using the blockfileinc() function.

  What to do if the cache ID is empty

  Looking at the blockfileinc() function in mainfile.php, you can see that it uses the functions themecenterbox(() and themesidebox() for blocks that don't have a filename - and, of course, it does not pass the (empty) blockfile parameter. Thus, if you see that the above code for the block prints an empty cache ID, then you will know that you are using a block without a filename (see empty cache ID and Cache-Lite). The quick solution is to explicitly set the fileid variable to some arbitrary value in you block code. However, you should check to find out why your block does not posess a filename (e.g. it could be an RSS block - we describe these in Section 7.1 and Figure 7-7).

• If a valid cached copy of the object identified by the key exists, it is fetched and fed into the $content variable of the block. I issue an echo to print the cache ID (the key) in this case, just for the start, to give me some idea of how (and if at all) this works. Of course, you can comment the echo later.

• In case the cache misses the object (or expiration time is over), you wil have to compute $content from scratch. Put your normal code here.

Of course, we are not done yet - after we compute $content in our block, we will want to cache it for future use.

Thus, after the end of your computations and before you close the block with "?>", put the following to instruct Cache-Lite to cache your $content:

// ...and save it in the cache for future use
$objCache->save($content, $fileid);
}

This closes the IF-statement we opened with the previous block of lines. It caches the $content variable in our cache object, using as identifier the file ID we derived from the block's filename. You have to put these two blocks of lines in every PHP-Nuke block you plan to cache, but the work is worth it!

The complete code for your cached block should thus look like:

<?php
if (eregi("block-XXXXXXX.php",$PHP_SELF)) {
    Header("Location: index.php");
    die();
}
// include the Cache-Lite package
require_once("includes/Cache_Lite/Lite.php");
// set some variables
$options = array(
  "cacheDir" => "/tmp/Cache_Lite/",
  "lifeTime" => 900
);
// create a Cache_Lite object
$objCache = new Cache_Lite($options);
// test if there exists a valid cache,
// the <acronym>ID</acronym> will be the basename of the block
$fileid = basename($blockfile,".php");
if ($content = $objCache->get($fileid)) {
  // add a message indicating this is cached output
  $content .= "\n[cached with ID=$fileid]";
}
else
{
  // do the whole work here...
-------> Your original code goes here <-------
  // ...and save it in the cache for future use
  $objCache->save($content, $fileid);
}
?>

If something goes wrong and your block is not being cached, check the following (How to accelerate PHP-Nuke):

• Do you have the PEAR.php?

• Where did you install the Lite.php file?

• Did you install it in includes/Cache_Lite/Lite.php, as I suggested?

• Did you enter the right path to Lite.php in the block you are trying to cache?

• Did you follow my example for a cached block above?

• If you did, do you have the right path in the line

  require_once("includes/Cache_Lite/Lite.php");

  of that example?

For a more in-depth tutorial on Cache-Lite, see Caching With PHP Cache_Lite.

You can use both jpcache and Cache-Lite together in a cache strategy that caches the whole page with jpcache when a user is not logged-in, but caches the least changing blocks (probably most of them) with Cache-Lite when he is. Such a strategy allows enough flexibility and room for experimentation and brings a considerable acceleration to your PHP-Nuke, without, on the other hand, requiring any access to the internals of your PHP installation - something that you will need, if you want to try the ultimate approach to caching , which we will present you in Section 24.1.3.