9.3. Using the cache in your script
Prev Chapter 9. Using the JpGraph cache system Next

9.3. Using the cache in your script

The principle of the library cache is as follows when it is enabled.

  1. The first time the graph script is called everything will be as usual, the script will run and in the end the script sends back the image to the browser. However if the caching is enabled JpGraph will automatically have stored a copy of the generated image in the cache directory.

  2. When the graph script is executed the next time it checks to see if an image corresponding to this graph script has already been generated and is available in the cache directory.

  3. If the image is available in the cache directory the library check to see how old the image is. If the images is older than a specified limit than it assumes that the image is out dated and runs the graph script as usual and makes sure the newly generated image is stored in the cache directory. Hence replacing the outdated image.

  4. If the image in the cache directory was current (i.e. not too old) it is read and send back to the clients (e.g. Web-browser) without the rest of the graph script being executed.

From the above description there are a couple of parameters that should be specified, the name to use when the image is stored and the timeout value when the image is considered too old, i.e. how long was it since the image was generated.

The first parameter, the filename, can be either manually specified or the library can create a filename based on the name of the graph script.

Both these parameters are specified in the initial Graph() call where a new graph instance is created. A basic example of this is shown in Example 9.1.

Example 9.1. Using an automatic cache filename and a 60min timeout of the cached images.

1
2
3
4
5
6
7
8
9

<?php
// ... includes
 
$graph = new Graph($width, $height, 'auto', 60);
 
// ... rest of the graph script
 
$graph->Stroke();
?>


The code in Example 9.1. will use an automatic filename for the cached image and a make the image valid for 60 minutes. This means that if the script is called again, within 60minutes, it will return the image just after the initial Graph() call and not execute any more lines of code in the script.

For basic usage this is all that is necessary, enable the cache in the settings and supply a filename and a timeout value. The rest of the logic is handled by the library.

Tip

If you want the timeout value to be "forever" then you can specify a "0" as the timeout value (or leave the parameter blank). To regenerate the image you will have to manually remove the image files from the cache. This removal could for example be handled by a nightly cron-job.

There is however one caveat which must be understood when using the above construction. The image/graph store in the cached file will be returned to the browser as a side effect of the initial $graph = new Graph(). This also means that:

No lines after the initial Graph() call will be executed in the image script in case the image exists in the cache directory.

This is the expected behaviour since this means that no unnecessary code will be executed in the graph script in case the image has been found in the image cache.

However, for the case where some more control of exactly how a cached image is sent back it is necessary to add some complexity by doing things less automatically. This gives greater control but also is slightly more complex and is described in the next section.

9.3.1. Manually controlling the cached image

Note

These utility functions were added in v3.0.5 of the library. It is still possible to do this in previous versions but then some more code is needed to duplicate what these methods does. If this feature is wanted then it is strongly advised to upgrade to this or later version.

There are two parts to doing this manually.

  1. Check if the cached image exists in the cache and is valid (i.e. not too old)

  2. Stream the cached image file back to the browser in that case

If the cached image is not valid then we just need to construct the graph as usual and it will be stored in the cache automatically.

The following code example shows how this is done in principle in a graph script where we use automatic naming i.e. the cached file name will get a name based on the script name. This is done with the library utility function GenImgName() which constructs a suitable image name from the script name and with a proper image compression format (i.e png, jpg or gif).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

<?php
$width = ...;
$height = ...;
$cachefilename = GenImgName();
$graph = new Graph($width,$height);
 
// Check if the cache file exists and is valid
$valid = $graph->cache->IsValid($cachefilename);
 
if( $valid ) {
    // The cached file is valid and we can now do any necessary
    // processing and then send it back to the client
    doSomeProcessingIfNecessary();
 
    $graph->cache->StreamImgFile($graph->img,$cachefilename);
 
} else {
    
    // The cache file is not valid or does not exists so we
    // must construct the graph as normal
 
    // Tell the graph that we want to cache this image
    $timeout = ...;
    $graph->SetupCache($cachefilename,$timeout);
 
    // The remainder of a normal graph script
 
    ...
 
    // .. and send back the image as usual (this will also store
    // a copy of the image in the cache directory)
    $graph->Stroke();
}

Prev Up Next
9.2. Permission settings for the cache files Home 9.4. Using the cache with Client Side Image Maps (CSIM)