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 2011-01-15 Release 5.3.1
11 This is the current stable release of PHPlot. This release focuses on
12 providing better support and documentation for creating multiple plots on a
15 The PHPlot reference manual has been updated to match this release. Some
16 new material has been added, including a new section on multiple plots per
17 image, and a new example of overlay plots.
22 #3143586 "Multiple plots per image - fixes & docs":
23 The reference manual now contains a section on multiple plots, and a
24 new example. A bug was fixed with SetLegendWorld and multiple plots.
25 Image border will now be drawn at most once. It is now possible to
26 restore the default 'automatic' behavior for axis positioning. Other
27 functions were changed to make arguments optional, so when called with
28 no arguments they reset to the default. The reference manual has been
29 updated with these changes too.
31 #3147397 "Data colors missing with multiple plots":
32 The fix for bug #3049726 "Optimize color allocation" caused a problem
33 with multiple plots. This has been fixed. PHPlot will no longer truncate
34 the data color table at each plot. It will still only allocate data colors
35 as needed, but all of the pre-set or configured data colors will be
36 available for each plot.
39 -----------------------------------------------------------------------------
41 2010-12-04 Release 5.3.0
45 This is the current stable release of PHPlot. This release includes new
46 plot types and some new features.
48 The PHPlot reference manual has been updated to match this release. Some of
49 the sections have been moved, there are new examples for the new plot types,
50 and a new section on tunable parameters has been added.
53 New features in 5.3.0:
55 #3093483 "Investing support chart types":
56 Added 3 new plot types: Basic OHLC (Open/High/Low/Close), Candlesticks,
57 and Filled Candlesticks. These are variations of plots that show the
58 performance of a stock or other financial security.
60 #3111166 "Control legend colorbox width":
61 It is now possible to control the width of the color boxes in the
62 legend, using a class variable which is documented in the manual.
64 #3117873 "Data value labels in more plot types":
65 Data value labels, which show the dependent variable values near the
66 data points, are now available for more plot types: lines, linepoints,
67 points, and squared. (These were previously available only for bars and
70 #3127005 "Ability to suppress X/Y axis lines":
71 New functions SetDrawXAxis() and SetDrawYAxis() were added to control
72 display of the X and Y axis lines. (These lines were probably the only
73 PHPlot elements that could not be turned off.) In special cases, these
74 can be used to produce a "bare" plot image.
77 -----------------------------------------------------------------------------
79 2010-10-03 Release 5.2.0
83 This is the current stable release of PHPlot. This release includes some
84 bug fixes and new features, described below, and a reimplementation of
85 internal processing of colors.
87 The PHPlot reference manual has been updated to match this release.
88 Horizontal plots are now documented in the manual, and the interim
89 documentation in the source release (HorizontalBars.txt) has been removed.
90 The manual is available in HTML format as a separate download from
91 Sourceforge. The manual is also available for on-line viewing from the
92 project home page. Starting with this release, the manual is also
93 available in PDF format from the project home page.
96 Cautions, Important Notes, and Compatibility Issues:
98 Due to changes in color allocation (see bug #3049726 below), image files
99 produced with PHPlot-5.2.0 will differ when compared byte-for-byte with
100 those created by earlier releases, even when the images are identical (as
101 they nearly always are).
103 If you are creating a horizontal plot with any negative X values, and not
104 setting the Y axis position, your plot will change (see bug #3074402 below)
105 because PHPlot no longer leaves the Y axis on the left for horizontal plots.
107 Some internal methods that used to have 'public' visibility are now protected.
108 This will generally prevent you from using them. The list of changed functions
109 can be found in the release ChangeLog. Avoid using any internal methods.
111 If you are making a stackedbar plot with any negative values, PHPlot-5.1.3
112 and earlier took the absolute value of each data value (which was not
113 documented), but PHPlot-5.2.0 does not. See Feature Request #3073679 below.
115 If your plot fills the 256 available color map slots in a palette image,
116 your image may look different with PHPlot-5.2.0 due to changes in color
117 allocation order. This was seen on two of the tests in the PHPlot test
118 suite. These tests tiled a JPEG image into the plot area or image
119 background. Being a truecolor image, the JPEG had a huge number of colors,
120 which filled all available slots in the color map. Additional colors for
121 plot elements had to be approximated, and different colors resulted with
122 PHPlot-5.2.0 versus previous releases. To avoid this problem, either use a
123 truecolor PHPlot object (PHPlot_truecolor constructor), or reduce the
124 number of colors in the background image and convert it to PNG or GIF.
126 This release contains significant changes to PHPlot internals. In particular,
127 variables and functions related to element colors and color handling have
128 changed. Refer to the PHPlot release ChangeLog for more details. Remember,
129 if you rely on accessing any member variable, or on using any non-public
130 function or any function not documented in the reference section of the manual,
131 your code is at risk of breaking with each new release.
134 New features in 5.2.0:
136 #3077554 "Finer control over plot element colors" (partial):
137 The X, Y, and main titles can now have different colors. See the PHPlot
138 Reference Manual entries for SetXTitleColor and SetYTitleColor.
140 #3073679 "Stacked bar plots with negative values":
141 A stacked bar plot can now include negative values, and stacks of negative
142 values will be drawn downwards (or leftwards). See the PHPlot Reference
143 Manual under "Plot Type: stackedbars" for details.
148 #3045131 "SetTransparentColor problems":
149 Setting a transparent color now works whether before or after setting
150 the background color (for example), and also now works with a data color.
152 #3049726 "Optimize color allocation"
153 PHPlot now defers allocating colors until drawing time, and tries to allocate
154 only the colors which are actually needed. For palette images, this results
155 in use of fewer color slots and slightly smaller image files.
157 #3074402 "Fix Y axis default for horizontal plots":
158 When horizontal plots were introduced, an asymmetry with the X and Y axis
159 position defaults was known but left. This behavior was later determined
160 to be unhelpful. So now the Y axis on horizontal plots will default to X=0,
161 or the X value closest to zero within the plot area range. This is the same
162 behavior as for the X axis in vertical plots.
164 #3056991 "Internal methods should be 'protected'":
165 More of the internal PHPlot functions were changed to 'protected' visibility,
166 as the test suite was fixed to not call them directly.
168 #3057000 "Review 'deprecated' methods":
169 One broken deprecated method (SetColor) was removed and one changed.
170 Note that deprecated methods are not documented and not tested.
172 -----------------------------------------------------------------------------
174 2010-08-30 Release 5.1.3
178 This is the current stable release of PHPlot. Additional horizontal plot
179 types and features have been added, however horizontal plots are still
180 considered 'experimental'. A new callback has been added which allows
181 greater control over the data colors. An improved method for accessing
182 TrueType Font (TTF) files means that on many systems TTF text can be used
183 without specifying font paths.
186 Cautions and Important Notes:
188 Since the previous PHPlot release, PHP-5.3.3 and PHP-5.2.14 have been
189 released, and these include a fix for the TrueType Font (TTF) rendering
190 problem. Use of these releases is now recommended.
192 There has been extensive cleanup of the PHPlot code. If you have a
193 customized version of PHPlot, you may find it difficult to update.
195 The "additional data support" script phplot_data.php has been removed from
196 this release. The script has not been developed or tested in a long time,
197 and was found to have numerous problems. The script can still be found in
200 The changes in this release (horizontal plots, custom data color callback,
201 and TrueType Font handling) should not result in any compatibility issues.
204 New features in 5.1.3:
206 #3049703 "Additional horizontal plots and features":
207 + Implemented data values labels in horizontal bar charts.
208 Use: SetXDataLabelPos('plotin').
209 + Add horizontal stacked bar charts, with data value labels.
210 + Add horizontal thinbarline plots.
211 Horizontal plots are still considered 'experimental', and documentation is
212 in the HorizontalBars.txt text file rather than the PHPlot Reference Manual.
214 #3034164 "Extended control of data colors":
215 New callback 'data_color' can be used to customize selection of the color
216 of each bar, line segment, point marker, etc. This is documented in the
217 PHPlot Reference Manual section "Custom Data Color Selection", with new
218 examples in the Examples chapter.
223 #3051906 "Better choice for default TT font":
224 Rather than always using the unlikely 'benjamingothic.ttf' as its default
225 TrueType font name, PHPlot now has a short list of sans-serif fonts, and
226 tries to find one that works if a default TT font is needed. On many
227 systems, this will provide a high-quality default font without help.
229 #3051832 "Let PHP/GD find the font file":
230 Instead of using file existence to validate a TT font file, PHPlot now
231 just tries to use the font. This allows PHP/GD to use its own rules to
232 try to find the font, without needing a pathname. This works on Windows
233 and at least some Linux systems.
235 #3048267 "phplot_data add-on is still broken"
236 Not fixed. phplot_data.php has been removed from the release.
238 -----------------------------------------------------------------------------
240 2010-06-29 Release 5.1.2
244 This is the current stable release of PHPlot. Truecolor image support is no
245 longer considered 'experimental', and is now documented in the reference
246 manual. There is a new experimental feature for horizontal bar charts. This
247 release also contains a bug fix and new feature.
250 Cautions and Important Notes:
252 The advisory against using PHP-5.3.2 or PHP-5.2.13 with PHPlot if you use
253 TrueType fonts (TTF) continues. See the item below for PHPlot-5.1.1. The
254 good news is that this has been fixed by the PHP Team and will be in the
257 Compatibility of data type and plot type are now checked completely. If
258 you used an incorrect data type with certain plot types, your script may no
259 longer work until you fix the data type. Specifically, the area, squared,
260 and thinbarline plot types failed to check the data type they received, and
261 treated anything other than 'data-data' as 'text-data'. If you have a
262 squared plot with data type 'data-data-error', for example (which is not
263 supposed to work), it did produce a plot, but will now result in an error.
265 The addition of horizontal bar charts should not impact any existing plot,
266 with one small exception. The function SetYDataLabelPos() used to accept
267 some additional, undocumented options (plotleft, plotright, both, yaxis)
268 and pass these through to SetYTickLabelPos() "for compatibility". It no
269 longer does so, as some of those are now used for horizontal bar chart
270 labels. To position Y tick labels, use only SetYTickLabelPos().
273 New features in 5.1.2:
275 #3002606 "Add to plot and image border options":
276 SetPlotBorderType() now accepts 'right', 'top', and 'bottom', as well
277 as an array of options. So you can now control exactly which of the 4
278 border sides will be drawn.
279 SetImageBorderType() now accepts 'solid' as a choice. This will use the
280 actual color set with SetImageBorderColor(), rather than the darker
281 shade as type 'plain' does (which may have been a bug).
282 SetImageBorderWidth() is a new function that sets the width of the image
283 border. The defaults are the same as the fixed values used before: 1
284 pixel for plain, 2 pixels for raised. The image border width is now
285 accounted for in margin calculations, if it is greater than 2 (to make
286 sure existing plots will not change).
288 #2885930 "Horizontal Bars":
289 Horizontal bar charts are implemented, as an experimental feature.
290 'Experimental' means they are not yet documented in the reference manual,
291 and subject to change or removal.
292 Refer to the text file HorizontalBars.txt for details.
294 #2947679 (follow-up) "Support for alpha blending/Truecolor":
295 Truecolor support is now documented in the Reference Manual. The interim
296 documentation file Truecolor.txt has been removed. Alpha channel
297 specification now works with both constructors and both image types. This
298 fixes an issue if the base constructor was used with a truecolor background
299 image. (In PHPlot-5.1.1, the result would be a truecolor image, but the
300 alpha channel features were not available.)
305 #3010116 "Bad rendering of title in multi-plot image when using TTF":
306 Make sure the main title is drawn only once, to avoid bad rendering of
307 TTF titles with multiple plots due to anti-aliasing.
309 -----------------------------------------------------------------------------
311 2010-04-04 Release 5.1.1
315 This is the current stable release of PHPlot. This release adds truecolor
316 image support as an experimental feature, fixes a number of bugs and adds
319 The PHPlot reference manual has been updated to match this release. The
320 manual is available as a separate download from Sourceforge. The manual is
321 also available for on-line viewing from the project home page.
323 See the ChangeLog file in the release for more about changes and bug fixes.
326 Cautions and Important Notes:
328 Avoid using PHP-5.3.2 or PHP-5.2.13 with PHPlot if you use TrueType fonts
329 (TTF). Some new bugs were introduced in those releases that adversely
330 affects accurate positioning and rendering of TrueType font text.
333 New features in 5.1.1:
335 #2947679 "Support for alpha blending/Truecolor":
336 PHPlot can now produce truecolor images, with alpha blending of colors and
337 other effects. This is considered an experimental feature, meaning it is
338 not yet documented in the PHPlot Reference Manual, and subject to change.
339 Refer to the text file Truecolor.txt included in the PHPlot release for
340 information on using truecolor.
341 Two drawing changes were made to improve plot appearance with Truecolor:
342 + Filled dots (in points & linepoints plots) are now drawn better. This
343 also makes them look rounder with regular (non-Truecolor) plots.
344 + Area plots have the areas filled without overlapping each area down to
345 the Y axis. This was needed to fix problems with alpha blending, and
346 should have no effect on non-Truecolor plots.
348 #2973995 "Add y-Data to Stackedbars":
349 You can now have Y Data Labels with 'stackedbars' plots. These label the Y
350 values (incremental and total) for each bar. Refer to the reference manual
351 page for SetYDataLabelPos().
356 #2976735 "Improvements and fixes for 'area' plots":
357 Moving X axis works; handle Y<0 better; new 'stackedarea' plot type is a
358 variation on 'area' with the data represented differently.
360 #2974639 "Stacked bars plot breaks with X axis != 0":
363 #2963757 "point_counts undefined error in 5.1.0":
364 Fixed an error introduced in PHPlot-5.1.0 when point size and shape arrays
365 were set to the same size.
367 #2938219 "Bars go in wrong direction":
368 For bar charts with all Y<0, bars will still be drawn down even if Y=0 is
371 -----------------------------------------------------------------------------
373 2009-12-24 Release 5.1.0
377 This is the current stable release of PHPlot. This release fixes a number of
378 bugs and adds some new features. Some of the changes in this release can
379 alter the appearance of plots, so be sure to review the information in this
380 NEWS file and test this release with your application.
382 The PHPlot reference manual has been updated to match this release. The
383 manual is available as a separate download from Sourceforge. The manual is
384 also available for on-line viewing from the project home page.
386 See the ChangeLog file in the release for more about changes and bug fixes.
389 New features in 5.1.0:
391 + A new "contrib" directory has been added for useful add-ons.
392 This currently contains:
393 * prune_labels : Control data label density on X axis.
394 * color_range : Define a gradient map for data colors.
396 + Feature Request 2899921 "Allow different format for data and tick labels"
397 Text angle and format can now be controlled separately for data labels.
399 + Locale loading override
400 New variable locale_override stops PHPlot from getting locale from system.
402 + Translating Coordinates
403 New function GetDeviceXY() to translate world to device coordinates.
405 + New drawing callback
406 New callback 'draw_all', called after all drawing is done.
407 The manual now contains an example of using this new callback and
408 the new GetDeviceXY() function to annotate a plot.
413 #2914403 "Pie + X/Y titles: Undefined property error"
414 X/Y titles are now properly ignored for pie charts.
416 #2908256 "Error: array_sum() should be an array" (drupal)
417 #2916864 "Should at least print legend on pie charts with empty data"
418 Pie charts with invalid data (no Y values > 0) now make an empty plot.
420 #2906436 "Fixes for X Tick Labels vs X Data Labels"
421 Smarter determination of whether to do Tick labels, Data labels, or both.
423 #2900914 "Problem with display of 0 on Y axis"
424 Fixed rounding error that could produce something like Y=8.12345E-16.
426 #2886365 "PHP 5 patch" (Declare all functions and variables in PHP5 style)
427 Most internal PHPlot member functions now have "protected" visibility.
429 #2839547 "SetImageBorderType('none')
430 You can use SetImageBorderType('none') to turn the image border back off.
432 #1795972 "Fix default point shapes"
433 We now have 20 (vs 10) point shapes, with 10 (vs 1) used by default.
435 #1795971 "Fix default data colors"
436 We now have 16 (vs 8) default data colors, no duplicates, all visible.
439 Visible Changes and Possible Incompatibilities:
441 + PHP5 visibility changes (Bug #2886365)
442 Details: Most internal PHPlot member functions now have visibility
443 'protected', rather than all being public. All member variables are
446 Reason for the change: Use the recommended PHP5 syntax, better OO style.
448 Compatibility: If you were calling a PHPlot internal function that got
449 changed to 'protected', this will break. Please report this.
452 + Fix default point shapes (Bug 1795972)
453 Details: We now have 20 (vs 10) point shapes available, and by default we
454 have 10 (vs 1) different shapes in use. The default size is now 6 pixels
455 for all point shapes.
457 Reason for the changes: Using different shapes helps distinguish the data
458 sets. The existing 10 defined shapes were not enough, since some of them
459 are not centered over the points, too small, or otherwise hard to see.
460 The code to synchronize the point shape and size arrays was broken, and
461 some dubious code to adjust sizes to even numbers needed to be fixed.
463 Compatibility (1): If you have a points or linepoints plot with more than
464 one dataset, and you did not use SetPointShapes() to configure the
465 shapes, them your plot will change from using a diamond for all data
466 sets to using different shapes for up to 10 data sets.
468 Compatibility (2): Fixing the point size/point shape array size bug may
469 slightly change the size of some shapes, but it now works the way it
470 was documented and supposed to work.
472 + Fix default data colors (Bug 1795971)
473 Details: Defined a new set of 16 default data colors. The colors are
474 different and contrast well against the default white background.
475 The first 4 colors were not changed.
477 Reason for the change: The default 8 data colors included two instances
478 of orange, and one color which was invisible on a white background.
480 Compatibility: Colors will change on any plot with more than 4 data sets
481 where you did not use SetDataColors() to set your own data colors.
483 + Re-used old function SetXDataLabelAngle()
484 Details: SetXDataLabelAngle() now does something different.
486 Reason for the change: This name was needed for a new function, to set the
487 angle for the X Data Labels. The old use of this function was not
488 documented, and marked "deprecated" in the code since around 2003-12-07.
490 Compatibility: If you are still using SetXDataLabelAngle() to set both Tick
491 and Data label angles, you need to use SetXLabelAngle() instead.
493 + Separate controls for tick and data labels (Feature Request 2899921)
494 Details: New functions SetXDataLabelAngle(), SetYDataLabelAngle(),
495 SetXDataLabelType(), and SetYDataLabelType() to allow separate control
496 over the angle and format of data labels, versus tick labels.
498 Reason for the change: Allow Data Labels to use different formatting and
499 angle compared to Tick Labels.
501 Compatibility: The default behavior has been set up such that there should
502 be no compatibility issues. For example:
503 Old behavior: SetXLabelType() sets the type for both tick and data labels.
504 New behavior: SetXLabelType() sets the type for tick labels and the
505 default type for data labels. SetXDataLabelType() sets the type for
506 data labels (overrides SetXLabelType).
508 + X Tick Labels vs X Data Labels (Bug 2906436)
509 Details: Regarding SetXTickLabelPos() and SetXDataLabelPos(): If only one
510 of them is called, the behavior is unchanged (only that label type will
511 be displayed). If both are called: Do exactly what was requested. If
512 neither was called: display only data labels if any data labels are
513 non-empty, else display only tick labels.
515 Reason for the change: 1) Fix the long-standing problem behavior that by
516 default PHPlot overlays tick and data labels below the X axis. 2) Fix
517 order dependency between setting the position of tick and data labels.
518 3) Prepare for future extension of data labels, and allow both tick
519 and data labels to be on if the programmer enables both.
521 Compatibility: There are some cases where your plot will change.
522 (a) Calls neither SetXDataLabelPos() nor SetXTickLabelPos():
523 Old behavior: Both tick and data labels displayed, possibly overlaid.
524 New behavior: If there are any non-blank data labels, then show only
525 the data labels, not the tick labels. Otherwise, show tick labels.
527 (b) Calls both SetXDataLabelPos() and SetXTickLabelPos(), with other than
528 'none' for each position:
529 Old behavior: The latter call was effective; earlier one ignored.
530 New behavior: Independent of order, both calls are effective.
532 -----------------------------------------------------------------------------
534 2009-06-14 Release 5.0.7
538 This is the current stable release of PHPlot. The release adds one new
539 feature, fixes a few bugs, and changes the license under which PHPlot
542 The PHPlot reference manual has been updated to match this release. The
543 manual is available as a separate download from Sourceforge. The manual is
544 also now available for on-line viewing at http://phplot.sourceforge.net
546 See the ChangeLog file for more about changes and bug fixes.
551 PHPlot is now released on the terms of the GNU Lesser General Public
552 License, version 2.1. (Previous versions of PHPlot were released under
553 a dual "PHP/GPL" license.) The licensing change was authorized by the
554 original author and copyright holder of PHPlot.
557 New feature in 5.0.7:
559 + Plot area margins can now be partially specified, using either
560 SetMarginsPixels or SetPlotAreaPixels. In previous releases of
561 PHPlot you had to either specify all 4 margins or none.
562 Credit to adoll for this feature.
565 Visible Changes and Possible Incompatibilities:
567 + Y data range can change:
568 As a result of the bug fixes in this release, automatically-calculated
569 Y data ranges can change. If you have missing Y values in your data,
570 and you let PHPlot calculate the Y data range (that is, you do not
571 call SetPlotAreaWorld with a Ymin value), then the lower limit for Y
572 can change. If you have a plot with data-data-error data type, different
573 error values for different points, and let PHPlot calculate the Y data
574 range, then either Y limit can change.
580 + Fix for bug 2803900: SetRGBArray('large') does not work:
581 Corrected an array name usage problem. You can now select the large
582 color map. Also PHPlot no longer overrides use of the PHP include
583 path when loading the large color map, and now reports an error if the
584 file is needed and not found.
586 + Fix for bug 2791502 "Error plots treat missing Y values as 0":
587 Missing Y values now with with data-data-error plots.
589 + Fix for bug 2792860 "Wrong DataLabelLines with missing Y":
590 Data label lines are now suppressed at missing Y values.
592 + Fix for bug 2786350 "Missing Y data results in bad auto-range":
593 Missing Y values are now ignored when calculating the Y data range.
594 Bug report and analysis by mrten.
596 + Fix for bug 2786354 "Incorrect auto-range for data-data-error":
597 The Y data range is now correctly calculated for data-data-error plots
598 when the error values differ from point to point.
601 -----------------------------------------------------------------------------
603 2009-01-20 Release 5.0.6
607 This is the current stable release of PHPlot. The purpose of this release
608 is to fix additional problems with text spacing and positioning, and
609 introduce some minor new features.
611 The PHPlot reference manual has been updated to match this release. The
612 manual is available as a separate download from Sourceforge. The manual is
613 also now available for on-line viewing at http://phplot.sourceforge.net
616 New features in 5.0.6:
618 + Allow mixing GD and TrueType font text on the same plot
619 You can use the new method functions SetFontGD() and SetFontTTF() to
620 select a font and font type for text element (labels, titles, etc.) For
621 example, you can have TrueType plot titles, and GD-fixed font labels.
622 SetUseTTF() now sets the default text type, TTF or GD. This is fully
625 + Extended label formatting
626 See the reference manual for more information on these.
628 New label formatting types are added: 'printf' (using a user-defined
629 format), and 'custom' (using a callback function).
631 For 'data' type formatting, a prefix and suffix can be added. (PHPlot
632 previously had an undocumented suffix for 'data' type, which still
635 For 'time' formatting, the format can now be specified in the same function
636 call rather than using SetXTimeFormat and SetYTimeFormat.
638 For 'data' formatting, the precision can now be specified in the same
639 function call, rather than using SetPrecisionX and SetPrecisionY.
641 + Better control over line spacing in multi-line labels
643 Line spacing can now be set separately for each text element using an
644 additional argument to SetFont, SetFontGD, and SetFontTTF. The overall
645 SetLineSpacing() value is the default for each text element that does not
646 have a specific line spacing set.
648 PHPlot now interprets the value set for line spacing as the number of
649 pixels only for GD text. For TrueType text, it is a scale factor for the
650 font's built-in line spacing for TrueType text. The equation used is:
651 interline_spacing = line_spacing * font_natural_spacing / 6
652 where line_spacing is either the global value set with SetLineSpacing
653 or a more specific value set with SetFont(), and font_natural_spacing
654 is the amount of space between lines built-in to the TrueType font. The
655 factor 6 should really be 4 (since PHPlot always used 4 as the default
656 line_spacing, this would give the natural font spacing by default). But
657 the text is too widely spaced with this value, and 6 was chosen to be
658 more compatible for typical font sizes.
660 Visible Changes and Possible Incompatibilities:
663 Multi-line TrueType titles and labels will have different inter-line
664 spacing. Since the text size affects the margin and plot area sizes,
665 this results in slightly different sized features on any plot with
666 multi-line TrueType text.
667 Previous versions of PHPlot used a default 4 pixels for inter-line
668 spacing of multi-line TrueType text, regardless of the font size.
669 PHPlot now uses the 'natural' font inter-line spacing, adjusted by a line
670 spacing parameter (per text type, with a global default).
672 The same change can also increase the size of the legend box slightly.
674 + Internal changes were made to the way font information is stored. Anything
675 that directly references PHPlot internals regarding fonts will break. Usage
676 also changed for the internal functions to size and draw text (ProcessText*,
677 SizeText*) due to font data storage changes.
679 + Changes were made to internal class variables used to store label
680 formatting information. Anything relying on these internals may break.
685 #1932571: Data-Data Plot fails with same X values
686 PHPlot will no longer hang if all X values are the same. But this is
687 interim fix to force the X range to 1 to prevent the hang. Eventually,
688 smarter automatic range code will handle this better.
689 Credit to andyl for finding this.
691 #1891636: Misaligned TTF X Labels
692 PHPlot will now correctly line-up TrueType labels along the X axis. There
693 were small but very noticeable errors before, when the text had descenders
694 or lines with all short letters.
697 -----------------------------------------------------------------------------
699 2008-01-13 Released 5.0.5
703 This is the current stable release of PHPlot. The emphasis of this release
704 is to improve text positioning, margin calculation, and error handling.
706 Although this is considered a stable release, it has a large amount
707 of changed code compared to the previous release 5.0.4. Two of the more
708 complex components of PHPlot - text and margin calculations - were mostly
709 re-written in this release. You are advised to carefully test your own
710 applications with PHPlot-5.0.5 to see how your plots look. Refer to the
711 README.txt file included in the release for information on reporting problems.
713 Starting with this release, PHPlot no longer supports PHP4, since the PHP
714 group officially declared end-of-life for PHP4 as of 31 December 2007.
715 PHPlot-5.0.5 was tested only with PHP-5.2.5 and we are unlikely to address
716 any issues using PHPlot with older versions of PHP.
718 The PHPlot reference manual has been updated to match this release. The
719 manual is available as a separate download from Sourceforge. The manual is
720 now also now available for on-line viewing at http://phplot.sourceforge.net
722 The callback feature added in 5.0.4 is now documented in the reference
723 manual. It is still considered experimental and subject to change, however.
727 Visible Changes and Possible Incompatibilities:
729 + Dropped support for PHP4.
731 + Eliminated remaining order-dependent behavior related to margins and
732 text. PHPlot should now do nothing at all, except record parameters, until
733 you draw the graph with DrawGraph. I believe this was always the intended
734 behavior of PHPlot, but over time perhaps various pre-calculations and
735 dependencies crept in. Fixing this simplifies processing and should lead to
736 more consistent behavior.
738 + The rewritten margin calculation code now uses actual sizes of all tick
739 and data labels and tick marks, rather than guesses. Margins collapse to
740 remove unused elements, but a minimum margin (currently fixed at 15 pixels)
741 is applied so the plot edges don't get to close to the image edges. The
742 result is that most graphs with auto-calculated margins will change in
743 appearance. It most cases, the margins get slightly smaller. In other
744 cases, earlier releases mis-calculated the margins, so this release will
745 produce much neater margins.
747 + The X and Y titles are now offset out from the plot area, not in from the
748 image area. For auto-calculated margins this should not make any
749 difference, but if you use SetMarginsPixels or SetPlotAreaPixels to set
750 larger margins, the axis titles will move in closer to the plot with this
753 + Changes were made to PHPlot internals, including removal of some class
754 variables and functions, and addition of new variables and functions.
755 These are documented in the ChangeLog. Relying on any internal variables
756 or functions in an application using PHPlot is unwise. The following
757 internal functions were removed:
758 SetImageArea() DrawDotSeries() DrawLineSeries() CalcXHeights()
759 CalcYWidths() DrawLabels() InitImage() DrawDashedLine()
760 These were marked 'deprecated', were undocumented and unmaintained.
762 This was replaced with SizeText().
764 + Line spacing set with SetLineSpacing() now affects TTF text as well as
765 GD text. Previously, it only affected GD text. The default line spacing
766 happens to be usable for TTF text.
768 + Changes were made to error handling. PHPlot will now trigger a user-level
769 error after producing an error image, instead of exiting. If no error
770 handler has been set, it will exit, as before. But now the error message
771 should also get logged, or written to the standard error stream, depending
772 on the SAPI in use. You can now establish an error handler to catch most
773 PHPlot errors and do some cleanup before exit.
775 + PHPlot no longer accepts some invalid option values (such as a substring
776 of a valid value, or empty strings) passed to functions. If your
777 application aborts in CheckOption with PHPlot-5.0.5 but 'worked' with
778 previous releases, them you were probably using an invalid option value.
784 #945439: x_tick_label_height not set correctly
785 Exact sizes of labels are now used to calculate margins.
787 #1813070: Bad position for multi-line TrueType text
788 Fixed as part of text functions rewrite. Use correct basepoint
789 (lower left of each line) when positioning text lines.
791 #1813071: Wrong title height for multi-line TTF text
792 Fixed as part of text functions rewrite: calculate height of
793 multi-line text correctly. Also now uses the line-spacing setting.
795 #1813474: DrawText alignment arguments wrong
796 Fixed so 'top' and 'bottom' now have the usual meaning: top means
797 align top of text with reference, bottom means align bottom of text.
798 This was switched before. Changed every internal caller to compensate.
800 #1816844: Fix order dependency for setting titles
801 Defer processing of title strings until DrawGraph(),
802 so it doesn't matter if fonts, etc. are set before or after.
804 #1819668: Horiz. align multi-line text: GD vs TTF
805 The text functions were rewritten to draw TTF text line-by-line,
806 like GD text, and correctly align each line.
808 #1823774: Default Font Path and Error Message
809 Error handling has been improved to make sure a message is logged, in
810 addition to the error image, and use error_trigger rather than exit.
812 #1826513: FIXME in DrawLegend: Max label length
813 The actual size needed for legend text is now used.
815 #1827263: Spoiled up pie-chart if $val is close to zero
816 Fixed by skipping over any segment that rounds to 0 degrees of
817 arc. (The GD function uses integer angles only, and 0 degrees
818 means draw a complete circle.)
820 #1836528: Insufficient checking of parameter values
821 Rewrote validator function to reject improper parameter values.
823 #1843012: Make margins, drawing consistent
824 Margin code logic was rewritten and checked for consistency.
826 #1856207: Margin error with 'xaxis'/'yaxis' position
827 Margin space is now allocated for ticks and labels if their position
828 is 'xaxis' or 'yaxis' and the axis is at the plot edge. This is not
829 a perfect fix (the axis could be close but not at the edge).
832 -----------------------------------------------------------------------------
834 2007-10-20 Released 5.0.4
838 This is the latest stable release of PHPlot. We are abandoning the 'rc'
839 version naming style, because we don't consider these last releases
840 'release candidate' versions. As we continue to make changes to PHPlot,
841 we are not converging toward a final "5.0" release, however we do consider
842 these releases stable and complete enough for production use.
844 This release fixes a number of problems and introduces a few new features.
846 The PHPlot reference manual has also been updated to match this release.
847 New material has been added documenting some of the PHPlot internals.
848 The manual is available as a separate download from Sourceforge.
853 Some code cleanup is going in to this release. It is hoped that these
854 changes will not impact any existing scripts using PHPlot, but will make
855 the PHPlot code itself easier to understand and maintain.
857 PHPlot now avoids making changes outside its own class definition. There
858 are no longer any functions defined outside the class, nor any constants.
859 Three constants (MINY MAXY TOTY) were removed, and 2 functions were removed
860 (see Visible Changes below). Also PHPlot no longer sets the PHP error
861 reporting level to E_ALL. Although we highly recommend setting error
862 reporting to E_ALL in your php.ini file or scripts, it is not right for
863 PHPlot to assume that you want it.
866 Visible Changes and Possible Incompatibilities:
868 Arrays containing color and style information are used with several PHPlot
869 functions to control the plot style array. These functions are:
870 SetPointShapes, SetPointSizes, SetLineWidths, SetLineStyles,
871 SetDataColors, SetDataBorderColors, and SetErrorBarColors.
872 The arrays passed to these functions MUST used sequential integer 0-based
873 indexes. This is what the PHP manual calls "Usual integer indices (starting
874 from zero, increasing by one)". This is the type of array you get in PHP by
875 default if you use array() without specifying key values, or use the
876 empty-bracket assignment operator to add values onto an array. In previous
877 versions of PHPlot, some of these functions would also work with
878 string-indexed or non-sequentially-indexed arrays, but this was not clearly
879 defined. Starting with PHPlot-5.0.4, only arrays with "usual integer
880 indices" work, and other array indexes will cause errors.
882 Some internal-use-only functions have had their usage changed or been removed.
883 If you are using functions that are not documented in the PHPlot Function
884 Reference in the manual, your code may have to be changed.
886 As part of the code cleanup, two functions which were defined outside the
887 PHPlot class were removed: array_pad_array(), and array_merge_php4().
888 If your code used these, you need to fix your code.
890 The routines which accept a color name, value, or array now check for a valid
891 color name. If you specify a color name which is not in your current color
892 table, PHPlot will draw an error and exit. Previously, PHP would report an
893 index error, continue, and get a 'headers already sent' message.
898 #1813021: Miss-positioned right-justified vertical GD text.
899 Fixed DrawText() to correctly position 90 degree right-justified text
900 drawn in a fixed GD font. This could be seen with 90 degree Y tick labels.
902 #1790441 Removed destructor/shutdown function, and no longer recommend
903 using reference assignment when creating a PHPlot object. This was
904 interfering with memory usage.
905 Credit to annajilly for analysis.
907 #1779115 SetLegendWorld() failed because of undefined variables. The
908 required order dependency was too hard to meet. This is now fixed.
909 You can now use SetLegendWorld anywhere before DrawGraph.
911 #1726810 (feature request, but actually a bug fix) Ignore empty strings
912 as data labels when doing time or data label formatting. These would
913 previously produce errors or bad formatting. Now you can omit labels
914 as needed even with time and data formatting.
915 Credit to exgerhardr for finding this.
917 #1605555 Y data labels used wrong font and not formatted (bar charts only).
919 #1208054 Localization of number formatting in 'data' format type. PHPlot
920 will attempt to format the numbers in a way appropriate to your locale.
921 You can also force the formatting with the new function SetNumberFormat.
922 Credit to David Hernández Sanz.
924 #937944 X/Y Tick counts: PHPlot could draw one two few Y tick counts, and
925 one too many X tick counts. This is not a perfect fix, and more work is
926 needed here, but this fixes an error case in both X and Y values.
929 New Features in 5.0.4:
931 New function SetLegendStyle allows control of the alignment of text and
932 color boxes within the legend. Also allows removing the color boxes.
933 Based on bug #1208054.
934 Credit to David Hernández Sanz.
936 New function SetNumberFormat. See bug report #1208054 above.
938 Callbacks are added. PHPlot can call back your functions while generating the
939 plot. This is experimental, and documented only in the file "Callbacks".
940 Credit to annajilly for the idea and design.
942 -----------------------------------------------------------------------------
944 2006-11-13 Released 5.0rc3
948 This is an interim release. It has been a long time since the previous
949 release 5.0rc2, and there have been a lot of changes. There are still more
950 changes likely to go in before we have "5.0", but there are enough for now.
952 The PHPlot Reference Manual has also been released, and is available as a
953 separate download from Sourceforge. PHPlot users and developers are
954 strongly encouraged to read the manual.
956 This release does not include the "doc/" and "examples/" directories of
957 previous releases. The Reference Manual contains more complete and
958 up-to-date information and examples, and I am unable to maintain the doc/
959 and examples/ files while also maintaining the Reference Manual. If you
960 need those files, they can be accessed with the Sourceforge web CVS
966 The emphasis for this release is bug fixing, so there are few new features.
968 + You can now suppress lines or points on individual plots in a linepoints
969 graph. This feature was added because I needed a graph with several
970 linepoints lines, but also with a solid line showing an "80% goal".
971 Use SetPointShapes with the value 'none' in the array to suppress the
972 point markers for that plot (and only draw the line).
973 Use SetLineStyles with the value 'none' in the array to suppress the
974 line for that plot (and only draw the point markers).
977 + Bar charts can have data labels above the bar with the value. Turn
978 these on with SetYDataLabelPos('plotin'). This is somewhat experimental,
979 since there isn't a lot of room for labels on top of the bars and you
980 may find the results are not useful.
985 Here are the more significant changes in this release. These are changes
986 which may affect existing scripts and output from PHPlot. See the
987 ChangeLog file for information about all changes and bug fixes.
989 + A bug fix on bar chart bar borders results in black borders around the
990 bars if shading is turned off. The border was previously covered up,
991 but was supposed to be there. If you need borderless, unshaded bars,
992 you need to use SetDataBorderColors to make the borders the same colors
993 as the bars. [Bug # 1096197]
995 + TrueType font pathname handling was fixed. You no longer need to use
996 SetUseTTF(True). You can either use full paths to the font files with
997 SetDefaultTTFont() and SetFont(), or you can call SetTTFPath() to point
998 to a directory of font files, and then use simple font filenames without
999 paths in SetDefaultTTFont() and SetFont().
1000 [Bug # 1144644 plus several others]
1002 + There have been several fixes regarding automatically calculated ranges
1003 and scales. The result is that you may see less extra space and fewer
1004 tick marks in some cases.
1006 + A fix was made to bar and stackedbar graph bar widths in order to get
1007 the X axis labels to properly center. As part of the fix, the bar widths
1008 now match between the two graph types. (Before this fix, the bars were
1009 narrower in bar graphs compared to the same data plotted as a stacked
1010 bar.) As a result, bar graph bars will now be drawn with wider bars, and
1011 stackedbar graph bars will be narrower. You can adjust this with the new
1012 class variable bar_extra_space. [Bug # 1437912]
1014 + Dot shapes and sizes were off by 1 or 2 slots in the array of shapes or
1015 sizes. After the fix, you may get different dot shapes or sizes per
1016 plot line. [Bug # 1096194]
1021 Since its output is visual (graphics), and it has so many interconnected
1022 modes and options, PHPlot is difficult to test. But at least we are now
1023 trying. I have a collection of PHPlot scripts (currently about 60) and a
1024 script to run through them. The script automatically checks that:
1025 1) Nothing was written to the standard error stream;
1026 2) An image file of size greater than 0 was written;
1027 3) Neither the test script nor PHPlot did exit(). This catches cases
1028 where PHPlot aborts with DrawError().
1030 The automated test is an easy way to check for serious regression, but you
1031 really need to inspect the output files to validate PHPlot. This takes a
1032 little time, and it is easy to overlook problems.
1034 The real issue is test coverage. Just as we can be sure that future
1035 PHPlot releases will pass the test collection, we can also be sure that
1036 future bug reports will be written against untested cases.
1038 --------------------
1040 2006-11-08 PHPlot on Sourceforge has a new maintainer: lbayuk
1042 --------------------
1044 2004-10-24 Released 5.0rc2
1046 --------------------