This manual covers version 1.15 of JpGraph. A 2D graph plotting library for PHP 4.2 and above.

Even though the library is known to work with version of PHP prior to 4.2 the library is not tested nor is it recommended to run with any older versions of PHP.

2.2 Software License

JpGraph 1.x is released under a dual license QPL 1.0 (Qt-License) for non-commercial (including educational) use of the library and the JpGraph Professional License for commercial use.

This is a truly OO graph library which makes it easy to both draw a "quick and dirty" graph with a minimum of code and quite complex graphs which requires a very fine grain of control. The library tries to assign sensible default values for most parameters hence making the learning curve quite flat since for most of the time very few commands is required to draw graphs with a pleasing esthetic look.

Some highlights of available features are

Flexible scales, supports text-lin, text-log, lin-lin, lin-log, log-lin and log-log and integer scales.
Supports both PNG, GIF and JPG graphic formats. Note that the available formats are dependent on the specific PHP installation where the library is used.
Supports caching of generated graphs to lessen burden of a HTTP server.
Supports batch mode to only generate images to a file
Supports client side image maps which makes it easy to produce drill down images.
Intelligent auto-scaling which gravitates towards esthetic values, i.e. multiples of 2:s and 5:s
Fully supports manual scaling, with fine grain control of position of ticks.
Supports background images with different formatting options
Supports color and brightness adjustments of images directly in PHP.
User specified grace for auto-scaling
Supports up to two different y-scale, it is possible to have different left and right y-scale and add plots to both
Supports, line-plots, filled line-plots, accumulated line-plots, bar plots, accumulated bar plots, grouped bar plots, error plots, line error plots, scatter plots, gantt-charts, radar plots, 2D and 3D pie charts.
Supports unlimited number of plots in each graph, makes it easy to compose complex graph which consists of several plot types
User specified position of axis
Supports color gradient fill in seven styles
Designed as a flexible OO framework which makes it easy to add new types of plots
Supports automatic legend generation
Supports both vertical and horizontal grids
Supports anti-aliasing of lines
Supports background images as well as unlimited number of icons in the graph
Supports rotation of linear graphs
More then 400 named colors
Designed modularly - you don't have to include code which isn't used
...and many many more features

In addition to these high level features the library has been designed to be orthogonal and very coherent in its' naming convention. For example, to specify color each object (i.e. axis, grids, texts, titles etc) within the graph implements the method SetColor() with the same signature.

2.4 Getting the latest version

The latest version of jpgraph can always be found on http://www.aditus.nu/jpgraph/

The current version as of this writing is 1.15

Note. I keep a strait-forward version scheme to avoid the version number inflation. This means

1.x -> 1.x.1, Bug fix release for version 1.x
1.x -> 1.(x+1), Added functionality. Mostly keeping backwards compatibility unless a very good reason not to. All SC breaks will be well announced in release notes and might be small things like a misspelled method name compared to the proper English spelling.
1.x -> 2.0, Substantially new functionality which might break backward compatibility

2.5 Planned future addition

All the following features, which have not been marked as tentatively, will be added. The time frame for these versions are:

Version 2.0, (Q4 2004) Adapted for PHP 5

For the latest update on planned future version see the web-site for JpGraph at http://www.aditus.nu/jpgraph/

2.6 Known bugs and omissions

Background images does not work as expected for rotated graphs

2.7 Acknowledgments

The idea for writing this library grew out of my own needs for a high quality graph drawing library for PHP4. Before reinventing the wheel I searched the net to see if there where anything already available that would meet my needs. When searching I found three other PHP graph plotting libraries:

"chart 0.3" http://quimby.gnus.org/circus/chart/chart-0.3.tar.gz, by Lars Magne Ingebrigtsen
"ykcee.php", http://ykcee.sourceforge.net
"phplot.php", http://www.phplot.com

All these libraries implements some fine graphic features but unfortunately none of those completely fulfilled our needs either for available functionality (for example none of these supported both two Y-scales, auto-scaling, and logarithmic scales), or general flexibility, I especially needed the option of two Y-scales, which none of the above packages supported. My own preference for design was closest to "chart 0.3" so I started by fixing some small bugs in that package and adding some new features. However I soon realized that to add all the features and flexibility I wanted to "chart 0.3" it would require a complete rewrite since the original design wasn't flexible enough, especially adding a second Y-scale would require a more flexible OO architecture. Since at the time I was also interested in giving PHP a try to see how well it would support a fully object oriented design so I started designing this library. The library is completely written from scratch but I have taken some ideas, especially the caching feature from "chart 0.3" and implemented this. I'm therefore thankful for those ideas. Any bugs and faults within the code are completely my own.

2.8 A note on Implementing an OO library in PHP4

In terms of OO support PHP is still at loss to Java, Eiffel or C++ but since it always been my view that OO design is more a state of mind then of implementation details it is still possible to arrive with a decent OO design even in PHP. One of the big obstacles is probably the very different assigning semantics used by PHP as compared to other OO languages since it is always copies of the object that is passed around by default and not references. This took some time for me personally to get used to (giving my own background in OO design in Java, Eiffel and C++). There is also a bug (present in all versions <=4.04pl1) that makes it impossible to use a reference to the '$this' pointer in the constructor. This has an easy workaround by adding an extra method, say Init(), which is called immediately after the constructor and may safely use a reference to '$this' pointer. As an example of JpGraph's OO features this is, to my knowledge, the only piece of PHP code to fully implement the Observer pattern.

2.9 Reporting bugs and suggesting improvements

Bug reports and suggestions are always welcome. We only ask you to make sure that you read the requirements and the FAQ before submitting bugs and making sure you have an up to date version of PHP4, the necessary graphic libraries etc. We will unfortunately not be able to answer standard OO or PHP4 questions. Neither do we have the time to give PHP/GD/TTF/Apache installation support. Please see the corresponding documentation and relevant FAQ. We simply don't have the bandwidth to help with these kinds of installations.

Please note that this library will not work with versions prior to PHP 4.1

Bug reports and suggestions should be sent to jpgraph@aditus.nu

Contents Previous Next

2 Introduction

2.1 Version