Contents Previous Next

# 2 Introduction

## 2.1 Version

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

Note that this library will not work with versions prior to PHP 4.1 due to extension in the object model that is used in this library.

## 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.

#### 2.2.0.1 Why is it not altogether free?

JpGraph is free software as in free speech but not as in free beer. Every hour I spend working on this library means one less hour spend on my consultancy work needed to pay silly things like rent and food. If you are a large company making use of the library in a commercial context you are both morally and legally bound to get the Professional JpGraph License.

The license fee corresponds to the cost for roughly 35 min of work for a professional IT consultant (average according to IDG for 2002)

The professional version also contains additional features not available in the free version

- Additional plot module for tachometer plots
- Off-line class reference
- PDF version of the documentation

## 2.3 JpGraph Features

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 esthetical 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 autoscaling which gravitates towards esthetical 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 autoscaling
- 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-alising of lines
- Supports rotation of linear graphs
- More then 400 named colors
- Designed modularly - you don't have to include code which isn't used

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.8

Note. I keep a straitforward 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 timeframe for these versions are:

- Version 2.0, (Q1 2004) Adapted for PHP 5

No time frames have been determined for version 2.x and above. If you like these timeframes to move forward either get involved in the development yourself or conside make a donation. Changes, bugfixes and additions are always welcome. For the latest upate 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 Acknowledgements

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:

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

All these libraries implements some fine graphic features but unfortunately none of those completely fulfilled my 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. I 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. I will unfortunately not be able to answer standard OO or PHP4 questions. Neither do I have the time to give PHP/GD/TTF/Apache installation support. Please see the corresponding documentation and relevant FAQ. I simply don't have the bandwith to help with these kinds of installations. Please note that this library will not work with versions prior to PHP4.02. Bug reports and suggestions should be sent to jpgraph@aditus.nu

Contents Previous Next