Depending on the complexity of the image script (for example if it is doing several DB lookups) this could significantly improve performance.
The rationale behind this is of course performance, and the observation that very few graphs are really real-time, i.e. needs to be updated absolutely every time the graphing script is called.
DEFINE("USE_CACHE",true);
DEFINE("READ_CACHE",true)The first of these, USE_CACHE, is the master-switch which must be set to true to enable the caching system. The second switch READ_CACHE very seldom needs to be changed.
This second switch basically tells whether or not JpGraph should ever look in the cache. Setting this to false and the master-switch to true would then always generate an new updated image file in the cache and this new image would be send back to the browser. The main use for this (admittedly) strange setting is if you like to have the side effect of the script that a fresh image is always stored in the cache directory.
Once you have enabled the cache you must also make sure that a valid cache directory is setup. The cache directory is specified with the define
DEFINE("CACHE_DIR","/tmp/jpgraph_cache/");You can of course change the default directory to whatever directory you fancy. But, you must remember one important thing. The cache directory must be writable for the user running Apache/PHP .
These parameters are supplied in the initial Graph() method call which should be among the first in your script. Instead of manually specifying a file name to be used you could often use the special name "auto". If the filename is specified as "auto" the cashed image will then be named the same as the image script but with the correct extension depending on what image format have been chosen.
If you don't specify a file name no caching will be used no matter the settings of USE_CACHE (without a file name it is impossible!)
The following call to Graph() shows a typical use of the cache.
$graph = new Graph(300,200,"auto",60)
The above code will use the automatic filename and a make the cache valid for 60 minutes.
So, how does this all work now?
The first time you call your script (no cached image) everything will be as usual, the script will run and you will in the end send back the image to the browser. However if you have the caching enabled JpGraph will automatically have stored a copy of the generated image in the cache directory.
The next time you call the script the first thing that happens in the initial Graph() is that it will go and check in the cache directory if the named image exists there. If this is the case it will also checks that the image isn't too old (as compared to the specified timeout value). If the image is valid then the image will be streamed straight back from the image file to the browser and the script will end it's execution.
Hence, if the image is found in the cache no code lines after the initial Graph() call will be executed
The design decision behind this is that your image script code never has to include anything special to make full use of the cache. It will just automatically work.
The performance benefits even for simple CSIM images is around 50% if the cache can be used and can of course be several 1000% if construction of the image requires DB calls and other complex operations which can be avoided.
Before reading further you should have an understanding on how the CSIM works by reading the section "Using Client side image maps".
Please remember that when using CSIM you must end your script with a call to Graph::StrokeCSIM() method insetad of the Graph::Stroke() used for non-csim.
To use the cache with CSIM you have to call the Graph::CheckCSIMCache(). As with the caching for non-CSIM you have to supply a name to be used for the cached version as well as an optional timeout value. The default timeout value if nothing else is specified is 60 minutes.
The name argument requires some more explanations. You must specify a relative name here. For example "myimage" or perhaps "firstpage/image3". Depending on your installation of JpGraph this will now end up in the directory specified in the CSIMCACHE_DIR define. This must also be a directory accessible by the normal web server. By default a directory called "csimcache" will be created in the same directory as the image script itself.
This has the drawback that the directory from where the script is executed must be writable by the process running PHP. Best practice for this is to keep the number of writable directory for PHP down to a minimum and re-use the same directory as is used for the standard cache. This however, require that your system administrator setup that cache directory so that it also accessible by the HTTP server from the htdocs root.
The CheckCSIMCache() method checks the cache for an existing cached version and if found it returns it and halts execution of the script. So, this call should be the first call after the creation of the Graph() and before any heavy work is done to create the image so that you can minimize the execution of the script in the case a match is found.
So, the general structure of a script that uses CSIM and the cache
is
$graph = new Graph(400,300);
// Check cache, 10 min timeout
$graph->CheckCSIMCache("image1",10);
// !! If cached version exists, execution halts here !!
//
// ... Construct the image with heavy DB calls etc, etc
//
$graph->StrokeCSIM();Please note that you do not need to pass any argument to the final call to StrokeCSIM() as you do when not using the cache.