1 This is the NEWS file for PHPlot, with release documentation.
2 The project web site is http://sourceforge.net/projects/phplot/
3 The project home page is http://phplot.sourceforge.net/
4 Refer the the ChangeLog file for detailed source changes.
5 -----------------------------------------------------------------------------
7 2010-10-03 Release 5.2.0
11 This is the current stable release of PHPlot. This release includes some
12 bug fixes and new features, described below, and a reimplementation of
13 internal processing of colors.
15 The PHPlot reference manual has been updated to match this release.
16 Horizontal plots are now documented in the manual, and the interim
17 documentation in the source release (HorizontalBars.txt) has been removed.
18 The manual is available in HTML format as a separate download from
19 Sourceforge. The manual is also available for on-line viewing from the
20 project home page. Starting with this release, the manual is also
21 available in PDF format from the project home page.
24 Cautions, Important Notes, and Compatibility Issues:
26 Due to changes in color allocation (see bug #3049726 below), image files
27 produced with PHPlot-5.2.0 will differ when compared byte-for-byte with
28 those created by earlier releases, even when the images are identical (as
29 they nearly always are).
31 If you are creating a horizontal plot with any negative X values, and not
32 setting the Y axis position, your plot will change (see bug #3074402 below)
33 because PHPlot no longer leaves the Y axis on the left for horizontal plots.
35 Some internal methods that used to have 'public' visibility are now protected.
36 This will generally prevent you from using them. The list of changed functions
37 can be found in the release ChangeLog. Avoid using any internal methods.
39 If you are making a stackedbar plot with any negative values, PHPlot-5.1.3
40 and earlier took the absolute value of each data value (which was not
41 documented), but PHPlot-5.2.0 does not. See Feature Request #3073679 below.
43 If your plot fills the 256 available color map slots in a palette image,
44 your image may look different with PHPlot-5.2.0 due to changes in color
45 allocation order. This was seen on two of the tests in the PHPlot test
46 suite. These tests tiled a JPEG image into the plot area or image
47 background. Being a truecolor image, the JPEG had a huge number of colors,
48 which filled all available slots in the color map. Additional colors for
49 plot elements had to be approximated, and different colors resulted with
50 PHPlot-5.2.0 versus previous releases. To avoid this problem, either use a
51 truecolor PHPlot object (PHPlot_truecolor constructor), or reduce the
52 number of colors in the background image and convert it to PNG or GIF.
54 This release contains significant changes to PHPlot internals. In particular,
55 variables and functions related to element colors and color handling have
56 changed. Refer to the PHPlot release ChangeLog for more details. Remember,
57 if you rely on accessing any member variable, or on using any non-public
58 function or any function not documented in the reference section of the manual,
59 your code is at risk of breaking with each new release.
62 New features in 5.2.0:
64 #3077554 "Finer control over plot element colors" (partial):
65 The X, Y, and main titles can now have different colors. See the PHPlot
66 Reference Manual entries for SetXTitleColor and SetYTitleColor.
68 #3073679 "Stacked bar plots with negative values":
69 A stacked bar plot can now include negative values, and stacks of negative
70 values will be drawn downwards (or leftwards). See the PHPlot Reference
71 Manual under "Plot Type: stackedbars" for details.
76 #3045131 "SetTransparentColor problems":
77 Setting a transparent color now works whether before or after setting
78 the background color (for example), and also now works with a data color.
80 #3049726 "Optimize color allocation"
81 PHPlot now defers allocating colors until drawing time, and tries to allocate
82 only the colors which are actually needed. For palette images, this results
83 in use of fewer color slots and slightly smaller image files.
85 #3074402 "Fix Y axis default for horizontal plots":
86 When horizontal plots were introduced, an asymmetry with the X and Y axis
87 position defaults was known but left. This behavior was later determined
88 to be unhelpful. So now the Y axis on horizontal plots will default to X=0,
89 or the X value closest to zero within the plot area range. This is the same
90 behavior as for the X axis in vertical plots.
92 #3056991 "Internal methods should be 'protected'":
93 More of the internal PHPlot functions were changed to 'protected' visibility,
94 as the test suite was fixed to not call them directly.
96 #3057000 "Review 'deprecated' methods":
97 One broken deprecated method (SetColor) was removed and one changed.
98 Note that deprecated methods are not documented and not tested.
100 -----------------------------------------------------------------------------
102 2010-08-30 Release 5.1.3
106 This is the current stable release of PHPlot. Additional horizontal plot
107 types and features have been added, however horizontal plots are still
108 considered 'experimental'. A new callback has been added which allows
109 greater control over the data colors. An improved method for accessing
110 TrueType Font (TTF) files means that on many systems TTF text can be used
111 without specifying font paths.
114 Cautions and Important Notes:
116 Since the previous PHPlot release, PHP-5.3.3 and PHP-5.2.14 have been
117 released, and these include a fix for the TrueType Font (TTF) rendering
118 problem. Use of these releases is now recommended.
120 There has been extensive cleanup of the PHPlot code. If you have a
121 customized version of PHPlot, you may find it difficult to update.
123 The "additional data support" script phplot_data.php has been removed from
124 this release. The script has not been developed or tested in a long time,
125 and was found to have numerous problems. The script can still be found in
128 The changes in this release (horizontal plots, custom data color callback,
129 and TrueType Font handling) should not result in any compatibility issues.
132 New features in 5.1.3:
134 #3049703 "Additional horizontal plots and features":
135 + Implemented data values labels in horizontal bar charts.
136 Use: SetXDataLabelPos('plotin').
137 + Add horizontal stacked bar charts, with data value labels.
138 + Add horizontal thinbarline plots.
139 Horizontal plots are still considered 'experimental', and documentation is
140 in the HorizontalBars.txt text file rather than the PHPlot Reference Manual.
142 #3034164 "Extended control of data colors":
143 New callback 'data_color' can be used to customize selection of the color
144 of each bar, line segment, point marker, etc. This is documented in the
145 PHPlot Reference Manual section "Custom Data Color Selection", with new
146 examples in the Examples chapter.
151 #3051906 "Better choice for default TT font":
152 Rather than always using the unlikely 'benjamingothic.ttf' as its default
153 TrueType font name, PHPlot now has a short list of sans-serif fonts, and
154 tries to find one that works if a default TT font is needed. On many
155 systems, this will provide a high-quality default font without help.
157 #3051832 "Let PHP/GD find the font file":
158 Instead of using file existence to validate a TT font file, PHPlot now
159 just tries to use the font. This allows PHP/GD to use its own rules to
160 try to find the font, without needing a pathname. This works on Windows
161 and at least some Linux systems.
163 #3048267 "phplot_data add-on is still broken"
164 Not fixed. phplot_data.php has been removed from the release.
166 -----------------------------------------------------------------------------
168 2010-06-29 Release 5.1.2
172 This is the current stable release of PHPlot. Truecolor image support is no
173 longer considered 'experimental', and is now documented in the reference
174 manual. There is a new experimental feature for horizontal bar charts. This
175 release also contains a bug fix and new feature.
178 Cautions and Important Notes:
180 The advisory against using PHP-5.3.2 or PHP-5.2.13 with PHPlot if you use
181 TrueType fonts (TTF) continues. See the item below for PHPlot-5.1.1. The
182 good news is that this has been fixed by the PHP Team and will be in the
185 Compatibility of data type and plot type are now checked completely. If
186 you used an incorrect data type with certain plot types, your script may no
187 longer work until you fix the data type. Specifically, the area, squared,
188 and thinbarline plot types failed to check the data type they received, and
189 treated anything other than 'data-data' as 'text-data'. If you have a
190 squared plot with data type 'data-data-error', for example (which is not
191 supposed to work), it did produce a plot, but will now result in an error.
193 The addition of horizontal bar charts should not impact any existing plot,
194 with one small exception. The function SetYDataLabelPos() used to accept
195 some additional, undocumented options (plotleft, plotright, both, yaxis)
196 and pass these through to SetYTickLabelPos() "for compatibility". It no
197 longer does so, as some of those are now used for horizontal bar chart
198 labels. To position Y tick labels, use only SetYTickLabelPos().
201 New features in 5.1.2:
203 #3002606 "Add to plot and image border options":
204 SetPlotBorderType() now accepts 'right', 'top', and 'bottom', as well
205 as an array of options. So you can now control exactly which of the 4
206 border sides will be drawn.
207 SetImageBorderType() now accepts 'solid' as a choice. This will use the
208 actual color set with SetImageBorderColor(), rather than the darker
209 shade as type 'plain' does (which may have been a bug).
210 SetImageBorderWidth() is a new function that sets the width of the image
211 border. The defaults are the same as the fixed values used before: 1
212 pixel for plain, 2 pixels for raised. The image border width is now
213 accounted for in margin calculations, if it is greater than 2 (to make
214 sure existing plots will not change).
216 #2885930 "Horizontal Bars":
217 Horizontal bar charts are implemented, as an experimental feature.
218 'Experimental' means they are not yet documented in the reference manual,
219 and subject to change or removal.
220 Refer to the text file HorizontalBars.txt for details.
222 #2947679 (follow-up) "Support for alpha blending/Truecolor":
223 Truecolor support is now documented in the Reference Manual. The interim
224 documentation file Truecolor.txt has been removed. Alpha channel
225 specification now works with both constructors and both image types. This
226 fixes an issue if the base constructor was used with a truecolor background
227 image. (In PHPlot-5.1.1, the result would be a truecolor image, but the
228 alpha channel features were not available.)
233 #3010116 "Bad rendering of title in multi-plot image when using TTF":
234 Make sure the main title is drawn only once, to avoid bad rendering of
235 TTF titles with multiple plots due to anti-aliasing.
237 -----------------------------------------------------------------------------
239 2010-04-04 Release 5.1.1
243 This is the current stable release of PHPlot. This release adds truecolor
244 image support as an experimental feature, fixes a number of bugs and adds
247 The PHPlot reference manual has been updated to match this release. The
248 manual is available as a separate download from Sourceforge. The manual is
249 also available for on-line viewing from the project home page.
251 See the ChangeLog file in the release for more about changes and bug fixes.
254 Cautions and Important Notes:
256 Avoid using PHP-5.3.2 or PHP-5.2.13 with PHPlot if you use TrueType fonts
257 (TTF). Some new bugs were introduced in those releases that adversely
258 affects accurate positioning and rendering of TrueType font text.
261 New features in 5.1.1:
263 #2947679 "Support for alpha blending/Truecolor":
264 PHPlot can now produce truecolor images, with alpha blending of colors and
265 other effects. This is considered an experimental feature, meaning it is
266 not yet documented in the PHPlot Reference Manual, and subject to change.
267 Refer to the text file Truecolor.txt included in the PHPlot release for
268 information on using truecolor.
269 Two drawing changes were made to improve plot appearance with Truecolor:
270 + Filled dots (in points & linepoints plots) are now drawn better. This
271 also makes them look rounder with regular (non-Truecolor) plots.
272 + Area plots have the areas filled without overlapping each area down to
273 the Y axis. This was needed to fix problems with alpha blending, and
274 should have no effect on non-Truecolor plots.
276 #2973995 "Add y-Data to Stackedbars":
277 You can now have Y Data Labels with 'stackedbars' plots. These label the Y
278 values (incremental and total) for each bar. Refer to the reference manual
279 page for SetYDataLabelPos().
284 #2976735 "Improvements and fixes for 'area' plots":
285 Moving X axis works; handle Y<0 better; new 'stackedarea' plot type is a
286 variation on 'area' with the data represented differently.
288 #2974639 "Stacked bars plot breaks with X axis != 0":
291 #2963757 "point_counts undefined error in 5.1.0":
292 Fixed an error introduced in PHPlot-5.1.0 when point size and shape arrays
293 were set to the same size.
295 #2938219 "Bars go in wrong direction":
296 For bar charts with all Y<0, bars will still be drawn down even if Y=0 is
299 -----------------------------------------------------------------------------
301 2009-12-24 Release 5.1.0
305 This is the current stable release of PHPlot. This release fixes a number of
306 bugs and adds some new features. Some of the changes in this release can
307 alter the appearance of plots, so be sure to review the information in this
308 NEWS file and test this release with your application.
310 The PHPlot reference manual has been updated to match this release. The
311 manual is available as a separate download from Sourceforge. The manual is
312 also available for on-line viewing from the project home page.
314 See the ChangeLog file in the release for more about changes and bug fixes.
317 New features in 5.1.0:
319 + A new "contrib" directory has been added for useful add-ons.
320 This currently contains:
321 * prune_labels : Control data label density on X axis.
322 * color_range : Define a gradient map for data colors.
324 + Feature Request 2899921 "Allow different format for data and tick labels"
325 Text angle and format can now be controlled separately for data labels.
327 + Locale loading override
328 New variable locale_override stops PHPlot from getting locale from system.
330 + Translating Coordinates
331 New function GetDeviceXY() to translate world to device coordinates.
333 + New drawing callback
334 New callback 'draw_all', called after all drawing is done.
335 The manual now contains an example of using this new callback and
336 the new GetDeviceXY() function to annotate a plot.
341 #2914403 "Pie + X/Y titles: Undefined property error"
342 X/Y titles are now properly ignored for pie charts.
344 #2908256 "Error: array_sum() should be an array" (drupal)
345 #2916864 "Should at least print legend on pie charts with empty data"
346 Pie charts with invalid data (no Y values > 0) now make an empty plot.
348 #2906436 "Fixes for X Tick Labels vs X Data Labels"
349 Smarter determination of whether to do Tick labels, Data labels, or both.
351 #2900914 "Problem with display of 0 on Y axis"
352 Fixed rounding error that could produce something like Y=8.12345E-16.
354 #2886365 "PHP 5 patch" (Declare all functions and variables in PHP5 style)
355 Most internal PHPlot member functions now have "protected" visibility.
357 #2839547 "SetImageBorderType('none')
358 You can use SetImageBorderType('none') to turn the image border back off.
360 #1795972 "Fix default point shapes"
361 We now have 20 (vs 10) point shapes, with 10 (vs 1) used by default.
363 #1795971 "Fix default data colors"
364 We now have 16 (vs 8) default data colors, no duplicates, all visible.
367 Visible Changes and Possible Incompatibilities:
369 + PHP5 visibility changes (Bug #2886365)
370 Details: Most internal PHPlot member functions now have visibility
371 'protected', rather than all being public. All member variables are
374 Reason for the change: Use the recommended PHP5 syntax, better OO style.
376 Compatibility: If you were calling a PHPlot internal function that got
377 changed to 'protected', this will break. Please report this.
380 + Fix default point shapes (Bug 1795972)
381 Details: We now have 20 (vs 10) point shapes available, and by default we
382 have 10 (vs 1) different shapes in use. The default size is now 6 pixels
383 for all point shapes.
385 Reason for the changes: Using different shapes helps distinguish the data
386 sets. The existing 10 defined shapes were not enough, since some of them
387 are not centered over the points, too small, or otherwise hard to see.
388 The code to synchronize the point shape and size arrays was broken, and
389 some dubious code to adjust sizes to even numbers needed to be fixed.
391 Compatibility (1): If you have a points or linepoints plot with more than
392 one dataset, and you did not use SetPointShapes() to configure the
393 shapes, them your plot will change from using a diamond for all data
394 sets to using different shapes for up to 10 data sets.
396 Compatibility (2): Fixing the point size/point shape array size bug may
397 slightly change the size of some shapes, but it now works the way it
398 was documented and supposed to work.
400 + Fix default data colors (Bug 1795971)
401 Details: Defined a new set of 16 default data colors. The colors are
402 different and contrast well against the default white background.
403 The first 4 colors were not changed.
405 Reason for the change: The default 8 data colors included two instances
406 of orange, and one color which was invisible on a white background.
408 Compatibility: Colors will change on any plot with more than 4 data sets
409 where you did not use SetDataColors() to set your own data colors.
411 + Re-used old function SetXDataLabelAngle()
412 Details: SetXDataLabelAngle() now does something different.
414 Reason for the change: This name was needed for a new function, to set the
415 angle for the X Data Labels. The old use of this function was not
416 documented, and marked "deprecated" in the code since around 2003-12-07.
418 Compatibility: If you are still using SetXDataLabelAngle() to set both Tick
419 and Data label angles, you need to use SetXLabelAngle() instead.
421 + Separate controls for tick and data labels (Feature Request 2899921)
422 Details: New functions SetXDataLabelAngle(), SetYDataLabelAngle(),
423 SetXDataLabelType(), and SetYDataLabelType() to allow separate control
424 over the angle and format of data labels, versus tick labels.
426 Reason for the change: Allow Data Labels to use different formatting and
427 angle compared to Tick Labels.
429 Compatibility: The default behavior has been set up such that there should
430 be no compatibility issues. For example:
431 Old behavior: SetXLabelType() sets the type for both tick and data labels.
432 New behavior: SetXLabelType() sets the type for tick labels and the
433 default type for data labels. SetXDataLabelType() sets the type for
434 data labels (overrides SetXLabelType).
436 + X Tick Labels vs X Data Labels (Bug 2906436)
437 Details: Regarding SetXTickLabelPos() and SetXDataLabelPos(): If only one
438 of them is called, the behavior is unchanged (only that label type will
439 be displayed). If both are called: Do exactly what was requested. If
440 neither was called: display only data labels if any data labels are
441 non-empty, else display only tick labels.
443 Reason for the change: 1) Fix the long-standing problem behavior that by
444 default PHPlot overlays tick and data labels below the X axis. 2) Fix
445 order dependency between setting the position of tick and data labels.
446 3) Prepare for future extension of data labels, and allow both tick
447 and data labels to be on if the programmer enables both.
449 Compatibility: There are some cases where your plot will change.
450 (a) Calls neither SetXDataLabelPos() nor SetXTickLabelPos():
451 Old behavior: Both tick and data labels displayed, possibly overlaid.
452 New behavior: If there are any non-blank data labels, then show only
453 the data labels, not the tick labels. Otherwise, show tick labels.
455 (b) Calls both SetXDataLabelPos() and SetXTickLabelPos(), with other than
456 'none' for each position:
457 Old behavior: The latter call was effective; earlier one ignored.
458 New behavior: Independent of order, both calls are effective.
460 -----------------------------------------------------------------------------
462 2009-06-14 Release 5.0.7
466 This is the current stable release of PHPlot. The release adds one new
467 feature, fixes a few bugs, and changes the license under which PHPlot
470 The PHPlot reference manual has been updated to match this release. The
471 manual is available as a separate download from Sourceforge. The manual is
472 also now available for on-line viewing at http://phplot.sourceforge.net
474 See the ChangeLog file for more about changes and bug fixes.
479 PHPlot is now released on the terms of the GNU Lesser General Public
480 License, version 2.1. (Previous versions of PHPlot were released under
481 a dual "PHP/GPL" license.) The licensing change was authorized by the
482 original author and copyright holder of PHPlot.
485 New feature in 5.0.7:
487 + Plot area margins can now be partially specified, using either
488 SetMarginsPixels or SetPlotAreaPixels. In previous releases of
489 PHPlot you had to either specify all 4 margins or none.
490 Credit to adoll for this feature.
493 Visible Changes and Possible Incompatibilities:
495 + Y data range can change:
496 As a result of the bug fixes in this release, automatically-calculated
497 Y data ranges can change. If you have missing Y values in your data,
498 and you let PHPlot calculate the Y data range (that is, you do not
499 call SetPlotAreaWorld with a Ymin value), then the lower limit for Y
500 can change. If you have a plot with data-data-error data type, different
501 error values for different points, and let PHPlot calculate the Y data
502 range, then either Y limit can change.
508 + Fix for bug 2803900: SetRGBArray('large') does not work:
509 Corrected an array name usage problem. You can now select the large
510 color map. Also PHPlot no longer overrides use of the PHP include
511 path when loading the large color map, and now reports an error if the
512 file is needed and not found.
514 + Fix for bug 2791502 "Error plots treat missing Y values as 0":
515 Missing Y values now with with data-data-error plots.
517 + Fix for bug 2792860 "Wrong DataLabelLines with missing Y":
518 Data label lines are now suppressed at missing Y values.
520 + Fix for bug 2786350 "Missing Y data results in bad auto-range":
521 Missing Y values are now ignored when calculating the Y data range.
522 Bug report and analysis by mrten.
524 + Fix for bug 2786354 "Incorrect auto-range for data-data-error":
525 The Y data range is now correctly calculated for data-data-error plots
526 when the error values differ from point to point.
529 -----------------------------------------------------------------------------
531 2009-01-20 Release 5.0.6
535 This is the current stable release of PHPlot. The purpose of this release
536 is to fix additional problems with text spacing and positioning, and
537 introduce some minor new features.
539 The PHPlot reference manual has been updated to match this release. The
540 manual is available as a separate download from Sourceforge. The manual is
541 also now available for on-line viewing at http://phplot.sourceforge.net
544 New features in 5.0.6:
546 + Allow mixing GD and TrueType font text on the same plot
547 You can use the new method functions SetFontGD() and SetFontTTF() to
548 select a font and font type for text element (labels, titles, etc.) For
549 example, you can have TrueType plot titles, and GD-fixed font labels.
550 SetUseTTF() now sets the default text type, TTF or GD. This is fully
553 + Extended label formatting
554 See the reference manual for more information on these.
556 New label formatting types are added: 'printf' (using a user-defined
557 format), and 'custom' (using a callback function).
559 For 'data' type formatting, a prefix and suffix can be added. (PHPlot
560 previously had an undocumented suffix for 'data' type, which still
563 For 'time' formatting, the format can now be specified in the same function
564 call rather than using SetXTimeFormat and SetYTimeFormat.
566 For 'data' formatting, the precision can now be specified in the same
567 function call, rather than using SetPrecisionX and SetPrecisionY.
569 + Better control over line spacing in multi-line labels
571 Line spacing can now be set separately for each text element using an
572 additional argument to SetFont, SetFontGD, and SetFontTTF. The overall
573 SetLineSpacing() value is the default for each text element that does not
574 have a specific line spacing set.
576 PHPlot now interprets the value set for line spacing as the number of
577 pixels only for GD text. For TrueType text, it is a scale factor for the
578 font's built-in line spacing for TrueType text. The equation used is:
579 interline_spacing = line_spacing * font_natural_spacing / 6
580 where line_spacing is either the global value set with SetLineSpacing
581 or a more specific value set with SetFont(), and font_natural_spacing
582 is the amount of space between lines built-in to the TrueType font. The
583 factor 6 should really be 4 (since PHPlot always used 4 as the default
584 line_spacing, this would give the natural font spacing by default). But
585 the text is too widely spaced with this value, and 6 was chosen to be
586 more compatible for typical font sizes.
588 Visible Changes and Possible Incompatibilities:
591 Multi-line TrueType titles and labels will have different inter-line
592 spacing. Since the text size affects the margin and plot area sizes,
593 this results in slightly different sized features on any plot with
594 multi-line TrueType text.
595 Previous versions of PHPlot used a default 4 pixels for inter-line
596 spacing of multi-line TrueType text, regardless of the font size.
597 PHPlot now uses the 'natural' font inter-line spacing, adjusted by a line
598 spacing parameter (per text type, with a global default).
600 The same change can also increase the size of the legend box slightly.
602 + Internal changes were made to the way font information is stored. Anything
603 that directly references PHPlot internals regarding fonts will break. Usage
604 also changed for the internal functions to size and draw text (ProcessText*,
605 SizeText*) due to font data storage changes.
607 + Changes were made to internal class variables used to store label
608 formatting information. Anything relying on these internals may break.
613 #1932571: Data-Data Plot fails with same X values
614 PHPlot will no longer hang if all X values are the same. But this is
615 interim fix to force the X range to 1 to prevent the hang. Eventually,
616 smarter automatic range code will handle this better.
617 Credit to andyl for finding this.
619 #1891636: Misaligned TTF X Labels
620 PHPlot will now correctly line-up TrueType labels along the X axis. There
621 were small but very noticeable errors before, when the text had descenders
622 or lines with all short letters.
625 -----------------------------------------------------------------------------
627 2008-01-13 Released 5.0.5
631 This is the current stable release of PHPlot. The emphasis of this release
632 is to improve text positioning, margin calculation, and error handling.
634 Although this is considered a stable release, it has a large amount
635 of changed code compared to the previous release 5.0.4. Two of the more
636 complex components of PHPlot - text and margin calculations - were mostly
637 re-written in this release. You are advised to carefully test your own
638 applications with PHPlot-5.0.5 to see how your plots look. Refer to the
639 README.txt file included in the release for information on reporting problems.
641 Starting with this release, PHPlot no longer supports PHP4, since the PHP
642 group officially declared end-of-life for PHP4 as of 31 December 2007.
643 PHPlot-5.0.5 was tested only with PHP-5.2.5 and we are unlikely to address
644 any issues using PHPlot with older versions of PHP.
646 The PHPlot reference manual has been updated to match this release. The
647 manual is available as a separate download from Sourceforge. The manual is
648 now also now available for on-line viewing at http://phplot.sourceforge.net
650 The callback feature added in 5.0.4 is now documented in the reference
651 manual. It is still considered experimental and subject to change, however.
655 Visible Changes and Possible Incompatibilities:
657 + Dropped support for PHP4.
659 + Eliminated remaining order-dependent behavior related to margins and
660 text. PHPlot should now do nothing at all, except record parameters, until
661 you draw the graph with DrawGraph. I believe this was always the intended
662 behavior of PHPlot, but over time perhaps various pre-calculations and
663 dependencies crept in. Fixing this simplifies processing and should lead to
664 more consistent behavior.
666 + The rewritten margin calculation code now uses actual sizes of all tick
667 and data labels and tick marks, rather than guesses. Margins collapse to
668 remove unused elements, but a minimum margin (currently fixed at 15 pixels)
669 is applied so the plot edges don't get to close to the image edges. The
670 result is that most graphs with auto-calculated margins will change in
671 appearance. It most cases, the margins get slightly smaller. In other
672 cases, earlier releases mis-calculated the margins, so this release will
673 produce much neater margins.
675 + The X and Y titles are now offset out from the plot area, not in from the
676 image area. For auto-calculated margins this should not make any
677 difference, but if you use SetMarginsPixels or SetPlotAreaPixels to set
678 larger margins, the axis titles will move in closer to the plot with this
681 + Changes were made to PHPlot internals, including removal of some class
682 variables and functions, and addition of new variables and functions.
683 These are documented in the ChangeLog. Relying on any internal variables
684 or functions in an application using PHPlot is unwise. The following
685 internal functions were removed:
686 SetImageArea() DrawDotSeries() DrawLineSeries() CalcXHeights()
687 CalcYWidths() DrawLabels() InitImage() DrawDashedLine()
688 These were marked 'deprecated', were undocumented and unmaintained.
690 This was replaced with SizeText().
692 + Line spacing set with SetLineSpacing() now affects TTF text as well as
693 GD text. Previously, it only affected GD text. The default line spacing
694 happens to be usable for TTF text.
696 + Changes were made to error handling. PHPlot will now trigger a user-level
697 error after producing an error image, instead of exiting. If no error
698 handler has been set, it will exit, as before. But now the error message
699 should also get logged, or written to the standard error stream, depending
700 on the SAPI in use. You can now establish an error handler to catch most
701 PHPlot errors and do some cleanup before exit.
703 + PHPlot no longer accepts some invalid option values (such as a substring
704 of a valid value, or empty strings) passed to functions. If your
705 application aborts in CheckOption with PHPlot-5.0.5 but 'worked' with
706 previous releases, them you were probably using an invalid option value.
712 #945439: x_tick_label_height not set correctly
713 Exact sizes of labels are now used to calculate margins.
715 #1813070: Bad position for multi-line TrueType text
716 Fixed as part of text functions rewrite. Use correct basepoint
717 (lower left of each line) when positioning text lines.
719 #1813071: Wrong title height for multi-line TTF text
720 Fixed as part of text functions rewrite: calculate height of
721 multi-line text correctly. Also now uses the line-spacing setting.
723 #1813474: DrawText alignment arguments wrong
724 Fixed so 'top' and 'bottom' now have the usual meaning: top means
725 align top of text with reference, bottom means align bottom of text.
726 This was switched before. Changed every internal caller to compensate.
728 #1816844: Fix order dependency for setting titles
729 Defer processing of title strings until DrawGraph(),
730 so it doesn't matter if fonts, etc. are set before or after.
732 #1819668: Horiz. align multi-line text: GD vs TTF
733 The text functions were rewritten to draw TTF text line-by-line,
734 like GD text, and correctly align each line.
736 #1823774: Default Font Path and Error Message
737 Error handling has been improved to make sure a message is logged, in
738 addition to the error image, and use error_trigger rather than exit.
740 #1826513: FIXME in DrawLegend: Max label length
741 The actual size needed for legend text is now used.
743 #1827263: Spoiled up pie-chart if $val is close to zero
744 Fixed by skipping over any segment that rounds to 0 degrees of
745 arc. (The GD function uses integer angles only, and 0 degrees
746 means draw a complete circle.)
748 #1836528: Insufficient checking of parameter values
749 Rewrote validator function to reject improper parameter values.
751 #1843012: Make margins, drawing consistent
752 Margin code logic was rewritten and checked for consistency.
754 #1856207: Margin error with 'xaxis'/'yaxis' position
755 Margin space is now allocated for ticks and labels if their position
756 is 'xaxis' or 'yaxis' and the axis is at the plot edge. This is not
757 a perfect fix (the axis could be close but not at the edge).
760 -----------------------------------------------------------------------------
762 2007-10-20 Released 5.0.4
766 This is the latest stable release of PHPlot. We are abandoning the 'rc'
767 version naming style, because we don't consider these last releases
768 'release candidate' versions. As we continue to make changes to PHPlot,
769 we are not converging toward a final "5.0" release, however we do consider
770 these releases stable and complete enough for production use.
772 This release fixes a number of problems and introduces a few new features.
774 The PHPlot reference manual has also been updated to match this release.
775 New material has been added documenting some of the PHPlot internals.
776 The manual is available as a separate download from Sourceforge.
781 Some code cleanup is going in to this release. It is hoped that these
782 changes will not impact any existing scripts using PHPlot, but will make
783 the PHPlot code itself easier to understand and maintain.
785 PHPlot now avoids making changes outside its own class definition. There
786 are no longer any functions defined outside the class, nor any constants.
787 Three constants (MINY MAXY TOTY) were removed, and 2 functions were removed
788 (see Visible Changes below). Also PHPlot no longer sets the PHP error
789 reporting level to E_ALL. Although we highly recommend setting error
790 reporting to E_ALL in your php.ini file or scripts, it is not right for
791 PHPlot to assume that you want it.
794 Visible Changes and Possible Incompatibilities:
796 Arrays containing color and style information are used with several PHPlot
797 functions to control the plot style array. These functions are:
798 SetPointShapes, SetPointSizes, SetLineWidths, SetLineStyles,
799 SetDataColors, SetDataBorderColors, and SetErrorBarColors.
800 The arrays passed to these functions MUST used sequential integer 0-based
801 indexes. This is what the PHP manual calls "Usual integer indices (starting
802 from zero, increasing by one)". This is the type of array you get in PHP by
803 default if you use array() without specifying key values, or use the
804 empty-bracket assignment operator to add values onto an array. In previous
805 versions of PHPlot, some of these functions would also work with
806 string-indexed or non-sequentially-indexed arrays, but this was not clearly
807 defined. Starting with PHPlot-5.0.4, only arrays with "usual integer
808 indices" work, and other array indexes will cause errors.
810 Some internal-use-only functions have had their usage changed or been removed.
811 If you are using functions that are not documented in the PHPlot Function
812 Reference in the manual, your code may have to be changed.
814 As part of the code cleanup, two functions which were defined outside the
815 PHPlot class were removed: array_pad_array(), and array_merge_php4().
816 If your code used these, you need to fix your code.
818 The routines which accept a color name, value, or array now check for a valid
819 color name. If you specify a color name which is not in your current color
820 table, PHPlot will draw an error and exit. Previously, PHP would report an
821 index error, continue, and get a 'headers already sent' message.
826 #1813021: Miss-positioned right-justified vertical GD text.
827 Fixed DrawText() to correctly position 90 degree right-justified text
828 drawn in a fixed GD font. This could be seen with 90 degree Y tick labels.
830 #1790441 Removed destructor/shutdown function, and no longer recommend
831 using reference assignment when creating a PHPlot object. This was
832 interfering with memory usage.
833 Credit to annajilly for analysis.
835 #1779115 SetLegendWorld() failed because of undefined variables. The
836 required order dependency was too hard to meet. This is now fixed.
837 You can now use SetLegendWorld anywhere before DrawGraph.
839 #1726810 (feature request, but actually a bug fix) Ignore empty strings
840 as data labels when doing time or data label formatting. These would
841 previously produce errors or bad formatting. Now you can omit labels
842 as needed even with time and data formatting.
843 Credit to exgerhardr for finding this.
845 #1605555 Y data labels used wrong font and not formatted (bar charts only).
847 #1208054 Localization of number formatting in 'data' format type. PHPlot
848 will attempt to format the numbers in a way appropriate to your locale.
849 You can also force the formatting with the new function SetNumberFormat.
850 Credit to David Hernández Sanz.
852 #937944 X/Y Tick counts: PHPlot could draw one two few Y tick counts, and
853 one too many X tick counts. This is not a perfect fix, and more work is
854 needed here, but this fixes an error case in both X and Y values.
857 New Features in 5.0.4:
859 New function SetLegendStyle allows control of the alignment of text and
860 color boxes within the legend. Also allows removing the color boxes.
861 Based on bug #1208054.
862 Credit to David Hernández Sanz.
864 New function SetNumberFormat. See bug report #1208054 above.
866 Callbacks are added. PHPlot can call back your functions while generating the
867 plot. This is experimental, and documented only in the file "Callbacks".
868 Credit to annajilly for the idea and design.
870 -----------------------------------------------------------------------------
872 2006-11-13 Released 5.0rc3
876 This is an interim release. It has been a long time since the previous
877 release 5.0rc2, and there have been a lot of changes. There are still more
878 changes likely to go in before we have "5.0", but there are enough for now.
880 The PHPlot Reference Manual has also been released, and is available as a
881 separate download from Sourceforge. PHPlot users and developers are
882 strongly encouraged to read the manual.
884 This release does not include the "doc/" and "examples/" directories of
885 previous releases. The Reference Manual contains more complete and
886 up-to-date information and examples, and I am unable to maintain the doc/
887 and examples/ files while also maintaining the Reference Manual. If you
888 need those files, they can be accessed with the Sourceforge web CVS
894 The emphasis for this release is bug fixing, so there are few new features.
896 + You can now suppress lines or points on individual plots in a linepoints
897 graph. This feature was added because I needed a graph with several
898 linepoints lines, but also with a solid line showing an "80% goal".
899 Use SetPointShapes with the value 'none' in the array to suppress the
900 point markers for that plot (and only draw the line).
901 Use SetLineStyles with the value 'none' in the array to suppress the
902 line for that plot (and only draw the point markers).
905 + Bar charts can have data labels above the bar with the value. Turn
906 these on with SetYDataLabelPos('plotin'). This is somewhat experimental,
907 since there isn't a lot of room for labels on top of the bars and you
908 may find the results are not useful.
913 Here are the more significant changes in this release. These are changes
914 which may affect existing scripts and output from PHPlot. See the
915 ChangeLog file for information about all changes and bug fixes.
917 + A bug fix on bar chart bar borders results in black borders around the
918 bars if shading is turned off. The border was previously covered up,
919 but was supposed to be there. If you need borderless, unshaded bars,
920 you need to use SetDataBorderColors to make the borders the same colors
921 as the bars. [Bug # 1096197]
923 + TrueType font pathname handling was fixed. You no longer need to use
924 SetUseTTF(True). You can either use full paths to the font files with
925 SetDefaultTTFont() and SetFont(), or you can call SetTTFPath() to point
926 to a directory of font files, and then use simple font filenames without
927 paths in SetDefaultTTFont() and SetFont().
928 [Bug # 1144644 plus several others]
930 + There have been several fixes regarding automatically calculated ranges
931 and scales. The result is that you may see less extra space and fewer
932 tick marks in some cases.
934 + A fix was made to bar and stackedbar graph bar widths in order to get
935 the X axis labels to properly center. As part of the fix, the bar widths
936 now match between the two graph types. (Before this fix, the bars were
937 narrower in bar graphs compared to the same data plotted as a stacked
938 bar.) As a result, bar graph bars will now be drawn with wider bars, and
939 stackedbar graph bars will be narrower. You can adjust this with the new
940 class variable bar_extra_space. [Bug # 1437912]
942 + Dot shapes and sizes were off by 1 or 2 slots in the array of shapes or
943 sizes. After the fix, you may get different dot shapes or sizes per
944 plot line. [Bug # 1096194]
949 Since its output is visual (graphics), and it has so many interconnected
950 modes and options, PHPlot is difficult to test. But at least we are now
951 trying. I have a collection of PHPlot scripts (currently about 60) and a
952 script to run through them. The script automatically checks that:
953 1) Nothing was written to the standard error stream;
954 2) An image file of size greater than 0 was written;
955 3) Neither the test script nor PHPlot did exit(). This catches cases
956 where PHPlot aborts with DrawError().
958 The automated test is an easy way to check for serious regression, but you
959 really need to inspect the output files to validate PHPlot. This takes a
960 little time, and it is easy to overlook problems.
962 The real issue is test coverage. Just as we can be sure that future
963 PHPlot releases will pass the test collection, we can also be sure that
964 future bug reports will be written against untested cases.
968 2006-11-08 PHPlot on Sourceforge has a new maintainer: lbayuk
972 2004-10-24 Released 5.0rc2