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-05-27 Release 5.4.0
11 This is the current stable release of PHPlot. This release includes some
12 bug fixes and new features. New features include new legend positioning
13 modes, legends using point shapes instead of color boxes, and the ability
14 to 'anchor' tick marks at a specific value. PHPlot now includes a class
15 constant containing the release version as PHPlot::version.
17 The PHPlot reference manual has been updated to match this release.
20 Cautions, Important Notes, and Compatibility Issues:
22 This release changes legend text positioning. Legend text is now vertically
23 centered rather than bottom aligned. This can change the appearance of some
24 plots, but the difference is usually not significant. See "Center vertical
25 alignment for legend text" below.
27 This release changes how stackedbars plots handle segments of size zero.
28 This will change the appearance of some plots, especially if the axis is
29 moved from 0. See "Undefined variables with stackedbars" below.
34 #3292529 Legend doesn't use data color callback:
35 This was determined to be the correct behavior, but undocumented. It has
36 now been documented in the reference manual.
38 #3294604 Center vertical alignment for legend text:
39 Legend text lines are now centered vertically to the color boxes (or
40 point shapes) rather than being bottom aligned. The difference is not
41 noticeable with the default font size and line spacing, because there was
42 no extra vertical space anyway. But with bigger fonts, and especially with
43 additional line spacing, the text now looks better because of the center
46 #3296884 Undefined variable with stackedbars:
47 PHPlot will no longer report an undefined variable warning if a stackedbars
48 plot starts with a stack containing all zero segments. (This was actually
49 fixed in PHPlot-5.3.2.) Furthermore, PHPlot now handles zero segments in
50 stackedbars plots differently. Zero values are no longer ignored. An
51 initial zero segment will be drawn as a bar segment if the axis is moved in
52 the opposite direction to the bar stack direction. A zero at the end will be
53 drawn as a cap with the data color, if shading is on.
56 New features in 5.4.0:
58 #3303654 Force tick mark at specific value:
59 New functions SetXTickAnchor() and SetYTickAnchor() were added. These tell
60 PHPlot to adjust the first tick mark value so that the specified anchor
61 position will coincide with a tick mark and grid position (or it would, if
62 the data range were extended to include it). Documentation has been
63 updated, including new examples.
65 #3292825 Use point shape markers in legend box:
66 New function SetLegendUseShapes() will enable use of point shapes in the
67 legend, rather than color boxes. The default is color boxes, so existing
68 plots will not change. This only works for points and linepoints plots.
69 Documentation has been updated.
71 #3291155 More flexible legend positioning:
72 New function SetLegendPosition() allows new ways to position the legend:
73 relative to the image, plot area, title, or using world coordinates, with
74 an optional pixel offset. There is another new function GetLegendSize() to
75 get the legend box size; this can be used to adjust the plot margins if you
76 want the legend outside the plot area and inside the margins. Documentation
79 -----------------------------------------------------------------------------
81 2011-05-06 Release 5.3.2
85 This is the current stable release of PHPlot. This release was produced to
86 address a single bug (see below), using a branch off of PHPlot-5.3.1.
87 (This is because the current development version, which will become
88 PHPlot-5.4.0, already has half of a big two-part change to legend
89 processing committed. So the bug fix was released without waiting for the
90 new work to be completed.)
95 #3296884 "Undefined variable with stackedbars":
96 A temporary fix was made against phplot-5.3.1 to avoid an undefined
97 variable error when the first stack in a stackedbars plot has all zero
98 values. The fix avoids the error message, and the plots are OK in most
99 cases. There are still issues with label position, and if the axis
100 is moved. These will be addressed in a future fix.
103 -----------------------------------------------------------------------------
105 2011-01-15 Release 5.3.1
109 This is the current stable release of PHPlot. This release focuses on
110 providing better support and documentation for creating multiple plots on a
113 The PHPlot reference manual has been updated to match this release. Some
114 new material has been added, including a new section on multiple plots per
115 image, and a new example of overlay plots.
120 #3143586 "Multiple plots per image - fixes & docs":
121 The reference manual now contains a section on multiple plots, and a
122 new example. A bug was fixed with SetLegendWorld and multiple plots.
123 Image border will now be drawn at most once. It is now possible to
124 restore the default 'automatic' behavior for axis positioning. Other
125 functions were changed to make arguments optional, so when called with
126 no arguments they reset to the default. The reference manual has been
127 updated with these changes too.
129 #3147397 "Data colors missing with multiple plots":
130 The fix for bug #3049726 "Optimize color allocation" caused a problem
131 with multiple plots. This has been fixed. PHPlot will no longer truncate
132 the data color table at each plot. It will still only allocate data colors
133 as needed, but all of the pre-set or configured data colors will be
134 available for each plot.
137 -----------------------------------------------------------------------------
139 2010-12-04 Release 5.3.0
143 This is the current stable release of PHPlot. This release includes new
144 plot types and some new features.
146 The PHPlot reference manual has been updated to match this release. Some of
147 the sections have been moved, there are new examples for the new plot types,
148 and a new section on tunable parameters has been added.
151 New features in 5.3.0:
153 #3093483 "Investing support chart types":
154 Added 3 new plot types: Basic OHLC (Open/High/Low/Close), Candlesticks,
155 and Filled Candlesticks. These are variations of plots that show the
156 performance of a stock or other financial security.
158 #3111166 "Control legend colorbox width":
159 It is now possible to control the width of the color boxes in the
160 legend, using a class variable which is documented in the manual.
162 #3117873 "Data value labels in more plot types":
163 Data value labels, which show the dependent variable values near the
164 data points, are now available for more plot types: lines, linepoints,
165 points, and squared. (These were previously available only for bars and
168 #3127005 "Ability to suppress X/Y axis lines":
169 New functions SetDrawXAxis() and SetDrawYAxis() were added to control
170 display of the X and Y axis lines. (These lines were probably the only
171 PHPlot elements that could not be turned off.) In special cases, these
172 can be used to produce a "bare" plot image.
175 -----------------------------------------------------------------------------
177 2010-10-03 Release 5.2.0
181 This is the current stable release of PHPlot. This release includes some
182 bug fixes and new features, described below, and a reimplementation of
183 internal processing of colors.
185 The PHPlot reference manual has been updated to match this release.
186 Horizontal plots are now documented in the manual, and the interim
187 documentation in the source release (HorizontalBars.txt) has been removed.
188 The manual is available in HTML format as a separate download from
189 Sourceforge. The manual is also available for on-line viewing from the
190 project home page. Starting with this release, the manual is also
191 available in PDF format from the project home page.
194 Cautions, Important Notes, and Compatibility Issues:
196 Due to changes in color allocation (see bug #3049726 below), image files
197 produced with PHPlot-5.2.0 will differ when compared byte-for-byte with
198 those created by earlier releases, even when the images are identical (as
199 they nearly always are).
201 If you are creating a horizontal plot with any negative X values, and not
202 setting the Y axis position, your plot will change (see bug #3074402 below)
203 because PHPlot no longer leaves the Y axis on the left for horizontal plots.
205 Some internal methods that used to have 'public' visibility are now protected.
206 This will generally prevent you from using them. The list of changed functions
207 can be found in the release ChangeLog. Avoid using any internal methods.
209 If you are making a stackedbar plot with any negative values, PHPlot-5.1.3
210 and earlier took the absolute value of each data value (which was not
211 documented), but PHPlot-5.2.0 does not. See Feature Request #3073679 below.
213 If your plot fills the 256 available color map slots in a palette image,
214 your image may look different with PHPlot-5.2.0 due to changes in color
215 allocation order. This was seen on two of the tests in the PHPlot test
216 suite. These tests tiled a JPEG image into the plot area or image
217 background. Being a truecolor image, the JPEG had a huge number of colors,
218 which filled all available slots in the color map. Additional colors for
219 plot elements had to be approximated, and different colors resulted with
220 PHPlot-5.2.0 versus previous releases. To avoid this problem, either use a
221 truecolor PHPlot object (PHPlot_truecolor constructor), or reduce the
222 number of colors in the background image and convert it to PNG or GIF.
224 This release contains significant changes to PHPlot internals. In particular,
225 variables and functions related to element colors and color handling have
226 changed. Refer to the PHPlot release ChangeLog for more details. Remember,
227 if you rely on accessing any member variable, or on using any non-public
228 function or any function not documented in the reference section of the manual,
229 your code is at risk of breaking with each new release.
232 New features in 5.2.0:
234 #3077554 "Finer control over plot element colors" (partial):
235 The X, Y, and main titles can now have different colors. See the PHPlot
236 Reference Manual entries for SetXTitleColor and SetYTitleColor.
238 #3073679 "Stacked bar plots with negative values":
239 A stacked bar plot can now include negative values, and stacks of negative
240 values will be drawn downwards (or leftwards). See the PHPlot Reference
241 Manual under "Plot Type: stackedbars" for details.
246 #3045131 "SetTransparentColor problems":
247 Setting a transparent color now works whether before or after setting
248 the background color (for example), and also now works with a data color.
250 #3049726 "Optimize color allocation"
251 PHPlot now defers allocating colors until drawing time, and tries to allocate
252 only the colors which are actually needed. For palette images, this results
253 in use of fewer color slots and slightly smaller image files.
255 #3074402 "Fix Y axis default for horizontal plots":
256 When horizontal plots were introduced, an asymmetry with the X and Y axis
257 position defaults was known but left. This behavior was later determined
258 to be unhelpful. So now the Y axis on horizontal plots will default to X=0,
259 or the X value closest to zero within the plot area range. This is the same
260 behavior as for the X axis in vertical plots.
262 #3056991 "Internal methods should be 'protected'":
263 More of the internal PHPlot functions were changed to 'protected' visibility,
264 as the test suite was fixed to not call them directly.
266 #3057000 "Review 'deprecated' methods":
267 One broken deprecated method (SetColor) was removed and one changed.
268 Note that deprecated methods are not documented and not tested.
270 -----------------------------------------------------------------------------
272 2010-08-30 Release 5.1.3
276 This is the current stable release of PHPlot. Additional horizontal plot
277 types and features have been added, however horizontal plots are still
278 considered 'experimental'. A new callback has been added which allows
279 greater control over the data colors. An improved method for accessing
280 TrueType Font (TTF) files means that on many systems TTF text can be used
281 without specifying font paths.
284 Cautions and Important Notes:
286 Since the previous PHPlot release, PHP-5.3.3 and PHP-5.2.14 have been
287 released, and these include a fix for the TrueType Font (TTF) rendering
288 problem. Use of these releases is now recommended.
290 There has been extensive cleanup of the PHPlot code. If you have a
291 customized version of PHPlot, you may find it difficult to update.
293 The "additional data support" script phplot_data.php has been removed from
294 this release. The script has not been developed or tested in a long time,
295 and was found to have numerous problems. The script can still be found in
298 The changes in this release (horizontal plots, custom data color callback,
299 and TrueType Font handling) should not result in any compatibility issues.
302 New features in 5.1.3:
304 #3049703 "Additional horizontal plots and features":
305 + Implemented data values labels in horizontal bar charts.
306 Use: SetXDataLabelPos('plotin').
307 + Add horizontal stacked bar charts, with data value labels.
308 + Add horizontal thinbarline plots.
309 Horizontal plots are still considered 'experimental', and documentation is
310 in the HorizontalBars.txt text file rather than the PHPlot Reference Manual.
312 #3034164 "Extended control of data colors":
313 New callback 'data_color' can be used to customize selection of the color
314 of each bar, line segment, point marker, etc. This is documented in the
315 PHPlot Reference Manual section "Custom Data Color Selection", with new
316 examples in the Examples chapter.
321 #3051906 "Better choice for default TT font":
322 Rather than always using the unlikely 'benjamingothic.ttf' as its default
323 TrueType font name, PHPlot now has a short list of sans-serif fonts, and
324 tries to find one that works if a default TT font is needed. On many
325 systems, this will provide a high-quality default font without help.
327 #3051832 "Let PHP/GD find the font file":
328 Instead of using file existence to validate a TT font file, PHPlot now
329 just tries to use the font. This allows PHP/GD to use its own rules to
330 try to find the font, without needing a pathname. This works on Windows
331 and at least some Linux systems.
333 #3048267 "phplot_data add-on is still broken"
334 Not fixed. phplot_data.php has been removed from the release.
336 -----------------------------------------------------------------------------
338 2010-06-29 Release 5.1.2
342 This is the current stable release of PHPlot. Truecolor image support is no
343 longer considered 'experimental', and is now documented in the reference
344 manual. There is a new experimental feature for horizontal bar charts. This
345 release also contains a bug fix and new feature.
348 Cautions and Important Notes:
350 The advisory against using PHP-5.3.2 or PHP-5.2.13 with PHPlot if you use
351 TrueType fonts (TTF) continues. See the item below for PHPlot-5.1.1. The
352 good news is that this has been fixed by the PHP Team and will be in the
355 Compatibility of data type and plot type are now checked completely. If
356 you used an incorrect data type with certain plot types, your script may no
357 longer work until you fix the data type. Specifically, the area, squared,
358 and thinbarline plot types failed to check the data type they received, and
359 treated anything other than 'data-data' as 'text-data'. If you have a
360 squared plot with data type 'data-data-error', for example (which is not
361 supposed to work), it did produce a plot, but will now result in an error.
363 The addition of horizontal bar charts should not impact any existing plot,
364 with one small exception. The function SetYDataLabelPos() used to accept
365 some additional, undocumented options (plotleft, plotright, both, yaxis)
366 and pass these through to SetYTickLabelPos() "for compatibility". It no
367 longer does so, as some of those are now used for horizontal bar chart
368 labels. To position Y tick labels, use only SetYTickLabelPos().
371 New features in 5.1.2:
373 #3002606 "Add to plot and image border options":
374 SetPlotBorderType() now accepts 'right', 'top', and 'bottom', as well
375 as an array of options. So you can now control exactly which of the 4
376 border sides will be drawn.
377 SetImageBorderType() now accepts 'solid' as a choice. This will use the
378 actual color set with SetImageBorderColor(), rather than the darker
379 shade as type 'plain' does (which may have been a bug).
380 SetImageBorderWidth() is a new function that sets the width of the image
381 border. The defaults are the same as the fixed values used before: 1
382 pixel for plain, 2 pixels for raised. The image border width is now
383 accounted for in margin calculations, if it is greater than 2 (to make
384 sure existing plots will not change).
386 #2885930 "Horizontal Bars":
387 Horizontal bar charts are implemented, as an experimental feature.
388 'Experimental' means they are not yet documented in the reference manual,
389 and subject to change or removal.
390 Refer to the text file HorizontalBars.txt for details.
392 #2947679 (follow-up) "Support for alpha blending/Truecolor":
393 Truecolor support is now documented in the Reference Manual. The interim
394 documentation file Truecolor.txt has been removed. Alpha channel
395 specification now works with both constructors and both image types. This
396 fixes an issue if the base constructor was used with a truecolor background
397 image. (In PHPlot-5.1.1, the result would be a truecolor image, but the
398 alpha channel features were not available.)
403 #3010116 "Bad rendering of title in multi-plot image when using TTF":
404 Make sure the main title is drawn only once, to avoid bad rendering of
405 TTF titles with multiple plots due to anti-aliasing.
407 -----------------------------------------------------------------------------
409 2010-04-04 Release 5.1.1
413 This is the current stable release of PHPlot. This release adds truecolor
414 image support as an experimental feature, fixes a number of bugs and adds
417 The PHPlot reference manual has been updated to match this release. The
418 manual is available as a separate download from Sourceforge. The manual is
419 also available for on-line viewing from the project home page.
421 See the ChangeLog file in the release for more about changes and bug fixes.
424 Cautions and Important Notes:
426 Avoid using PHP-5.3.2 or PHP-5.2.13 with PHPlot if you use TrueType fonts
427 (TTF). Some new bugs were introduced in those releases that adversely
428 affects accurate positioning and rendering of TrueType font text.
431 New features in 5.1.1:
433 #2947679 "Support for alpha blending/Truecolor":
434 PHPlot can now produce truecolor images, with alpha blending of colors and
435 other effects. This is considered an experimental feature, meaning it is
436 not yet documented in the PHPlot Reference Manual, and subject to change.
437 Refer to the text file Truecolor.txt included in the PHPlot release for
438 information on using truecolor.
439 Two drawing changes were made to improve plot appearance with Truecolor:
440 + Filled dots (in points & linepoints plots) are now drawn better. This
441 also makes them look rounder with regular (non-Truecolor) plots.
442 + Area plots have the areas filled without overlapping each area down to
443 the Y axis. This was needed to fix problems with alpha blending, and
444 should have no effect on non-Truecolor plots.
446 #2973995 "Add y-Data to Stackedbars":
447 You can now have Y Data Labels with 'stackedbars' plots. These label the Y
448 values (incremental and total) for each bar. Refer to the reference manual
449 page for SetYDataLabelPos().
454 #2976735 "Improvements and fixes for 'area' plots":
455 Moving X axis works; handle Y<0 better; new 'stackedarea' plot type is a
456 variation on 'area' with the data represented differently.
458 #2974639 "Stacked bars plot breaks with X axis != 0":
461 #2963757 "point_counts undefined error in 5.1.0":
462 Fixed an error introduced in PHPlot-5.1.0 when point size and shape arrays
463 were set to the same size.
465 #2938219 "Bars go in wrong direction":
466 For bar charts with all Y<0, bars will still be drawn down even if Y=0 is
469 -----------------------------------------------------------------------------
471 2009-12-24 Release 5.1.0
475 This is the current stable release of PHPlot. This release fixes a number of
476 bugs and adds some new features. Some of the changes in this release can
477 alter the appearance of plots, so be sure to review the information in this
478 NEWS file and test this release with your application.
480 The PHPlot reference manual has been updated to match this release. The
481 manual is available as a separate download from Sourceforge. The manual is
482 also available for on-line viewing from the project home page.
484 See the ChangeLog file in the release for more about changes and bug fixes.
487 New features in 5.1.0:
489 + A new "contrib" directory has been added for useful add-ons.
490 This currently contains:
491 * prune_labels : Control data label density on X axis.
492 * color_range : Define a gradient map for data colors.
494 + Feature Request 2899921 "Allow different format for data and tick labels"
495 Text angle and format can now be controlled separately for data labels.
497 + Locale loading override
498 New variable locale_override stops PHPlot from getting locale from system.
500 + Translating Coordinates
501 New function GetDeviceXY() to translate world to device coordinates.
503 + New drawing callback
504 New callback 'draw_all', called after all drawing is done.
505 The manual now contains an example of using this new callback and
506 the new GetDeviceXY() function to annotate a plot.
511 #2914403 "Pie + X/Y titles: Undefined property error"
512 X/Y titles are now properly ignored for pie charts.
514 #2908256 "Error: array_sum() should be an array" (drupal)
515 #2916864 "Should at least print legend on pie charts with empty data"
516 Pie charts with invalid data (no Y values > 0) now make an empty plot.
518 #2906436 "Fixes for X Tick Labels vs X Data Labels"
519 Smarter determination of whether to do Tick labels, Data labels, or both.
521 #2900914 "Problem with display of 0 on Y axis"
522 Fixed rounding error that could produce something like Y=8.12345E-16.
524 #2886365 "PHP 5 patch" (Declare all functions and variables in PHP5 style)
525 Most internal PHPlot member functions now have "protected" visibility.
527 #2839547 "SetImageBorderType('none')
528 You can use SetImageBorderType('none') to turn the image border back off.
530 #1795972 "Fix default point shapes"
531 We now have 20 (vs 10) point shapes, with 10 (vs 1) used by default.
533 #1795971 "Fix default data colors"
534 We now have 16 (vs 8) default data colors, no duplicates, all visible.
537 Visible Changes and Possible Incompatibilities:
539 + PHP5 visibility changes (Bug #2886365)
540 Details: Most internal PHPlot member functions now have visibility
541 'protected', rather than all being public. All member variables are
544 Reason for the change: Use the recommended PHP5 syntax, better OO style.
546 Compatibility: If you were calling a PHPlot internal function that got
547 changed to 'protected', this will break. Please report this.
550 + Fix default point shapes (Bug 1795972)
551 Details: We now have 20 (vs 10) point shapes available, and by default we
552 have 10 (vs 1) different shapes in use. The default size is now 6 pixels
553 for all point shapes.
555 Reason for the changes: Using different shapes helps distinguish the data
556 sets. The existing 10 defined shapes were not enough, since some of them
557 are not centered over the points, too small, or otherwise hard to see.
558 The code to synchronize the point shape and size arrays was broken, and
559 some dubious code to adjust sizes to even numbers needed to be fixed.
561 Compatibility (1): If you have a points or linepoints plot with more than
562 one dataset, and you did not use SetPointShapes() to configure the
563 shapes, them your plot will change from using a diamond for all data
564 sets to using different shapes for up to 10 data sets.
566 Compatibility (2): Fixing the point size/point shape array size bug may
567 slightly change the size of some shapes, but it now works the way it
568 was documented and supposed to work.
570 + Fix default data colors (Bug 1795971)
571 Details: Defined a new set of 16 default data colors. The colors are
572 different and contrast well against the default white background.
573 The first 4 colors were not changed.
575 Reason for the change: The default 8 data colors included two instances
576 of orange, and one color which was invisible on a white background.
578 Compatibility: Colors will change on any plot with more than 4 data sets
579 where you did not use SetDataColors() to set your own data colors.
581 + Re-used old function SetXDataLabelAngle()
582 Details: SetXDataLabelAngle() now does something different.
584 Reason for the change: This name was needed for a new function, to set the
585 angle for the X Data Labels. The old use of this function was not
586 documented, and marked "deprecated" in the code since around 2003-12-07.
588 Compatibility: If you are still using SetXDataLabelAngle() to set both Tick
589 and Data label angles, you need to use SetXLabelAngle() instead.
591 + Separate controls for tick and data labels (Feature Request 2899921)
592 Details: New functions SetXDataLabelAngle(), SetYDataLabelAngle(),
593 SetXDataLabelType(), and SetYDataLabelType() to allow separate control
594 over the angle and format of data labels, versus tick labels.
596 Reason for the change: Allow Data Labels to use different formatting and
597 angle compared to Tick Labels.
599 Compatibility: The default behavior has been set up such that there should
600 be no compatibility issues. For example:
601 Old behavior: SetXLabelType() sets the type for both tick and data labels.
602 New behavior: SetXLabelType() sets the type for tick labels and the
603 default type for data labels. SetXDataLabelType() sets the type for
604 data labels (overrides SetXLabelType).
606 + X Tick Labels vs X Data Labels (Bug 2906436)
607 Details: Regarding SetXTickLabelPos() and SetXDataLabelPos(): If only one
608 of them is called, the behavior is unchanged (only that label type will
609 be displayed). If both are called: Do exactly what was requested. If
610 neither was called: display only data labels if any data labels are
611 non-empty, else display only tick labels.
613 Reason for the change: 1) Fix the long-standing problem behavior that by
614 default PHPlot overlays tick and data labels below the X axis. 2) Fix
615 order dependency between setting the position of tick and data labels.
616 3) Prepare for future extension of data labels, and allow both tick
617 and data labels to be on if the programmer enables both.
619 Compatibility: There are some cases where your plot will change.
620 (a) Calls neither SetXDataLabelPos() nor SetXTickLabelPos():
621 Old behavior: Both tick and data labels displayed, possibly overlaid.
622 New behavior: If there are any non-blank data labels, then show only
623 the data labels, not the tick labels. Otherwise, show tick labels.
625 (b) Calls both SetXDataLabelPos() and SetXTickLabelPos(), with other than
626 'none' for each position:
627 Old behavior: The latter call was effective; earlier one ignored.
628 New behavior: Independent of order, both calls are effective.
630 -----------------------------------------------------------------------------
632 2009-06-14 Release 5.0.7
636 This is the current stable release of PHPlot. The release adds one new
637 feature, fixes a few bugs, and changes the license under which PHPlot
640 The PHPlot reference manual has been updated to match this release. The
641 manual is available as a separate download from Sourceforge. The manual is
642 also now available for on-line viewing at http://phplot.sourceforge.net
644 See the ChangeLog file for more about changes and bug fixes.
649 PHPlot is now released on the terms of the GNU Lesser General Public
650 License, version 2.1. (Previous versions of PHPlot were released under
651 a dual "PHP/GPL" license.) The licensing change was authorized by the
652 original author and copyright holder of PHPlot.
655 New feature in 5.0.7:
657 + Plot area margins can now be partially specified, using either
658 SetMarginsPixels or SetPlotAreaPixels. In previous releases of
659 PHPlot you had to either specify all 4 margins or none.
660 Credit to adoll for this feature.
663 Visible Changes and Possible Incompatibilities:
665 + Y data range can change:
666 As a result of the bug fixes in this release, automatically-calculated
667 Y data ranges can change. If you have missing Y values in your data,
668 and you let PHPlot calculate the Y data range (that is, you do not
669 call SetPlotAreaWorld with a Ymin value), then the lower limit for Y
670 can change. If you have a plot with data-data-error data type, different
671 error values for different points, and let PHPlot calculate the Y data
672 range, then either Y limit can change.
678 + Fix for bug 2803900: SetRGBArray('large') does not work:
679 Corrected an array name usage problem. You can now select the large
680 color map. Also PHPlot no longer overrides use of the PHP include
681 path when loading the large color map, and now reports an error if the
682 file is needed and not found.
684 + Fix for bug 2791502 "Error plots treat missing Y values as 0":
685 Missing Y values now with with data-data-error plots.
687 + Fix for bug 2792860 "Wrong DataLabelLines with missing Y":
688 Data label lines are now suppressed at missing Y values.
690 + Fix for bug 2786350 "Missing Y data results in bad auto-range":
691 Missing Y values are now ignored when calculating the Y data range.
692 Bug report and analysis by mrten.
694 + Fix for bug 2786354 "Incorrect auto-range for data-data-error":
695 The Y data range is now correctly calculated for data-data-error plots
696 when the error values differ from point to point.
699 -----------------------------------------------------------------------------
701 2009-01-20 Release 5.0.6
705 This is the current stable release of PHPlot. The purpose of this release
706 is to fix additional problems with text spacing and positioning, and
707 introduce some minor new features.
709 The PHPlot reference manual has been updated to match this release. The
710 manual is available as a separate download from Sourceforge. The manual is
711 also now available for on-line viewing at http://phplot.sourceforge.net
714 New features in 5.0.6:
716 + Allow mixing GD and TrueType font text on the same plot
717 You can use the new method functions SetFontGD() and SetFontTTF() to
718 select a font and font type for text element (labels, titles, etc.) For
719 example, you can have TrueType plot titles, and GD-fixed font labels.
720 SetUseTTF() now sets the default text type, TTF or GD. This is fully
723 + Extended label formatting
724 See the reference manual for more information on these.
726 New label formatting types are added: 'printf' (using a user-defined
727 format), and 'custom' (using a callback function).
729 For 'data' type formatting, a prefix and suffix can be added. (PHPlot
730 previously had an undocumented suffix for 'data' type, which still
733 For 'time' formatting, the format can now be specified in the same function
734 call rather than using SetXTimeFormat and SetYTimeFormat.
736 For 'data' formatting, the precision can now be specified in the same
737 function call, rather than using SetPrecisionX and SetPrecisionY.
739 + Better control over line spacing in multi-line labels
741 Line spacing can now be set separately for each text element using an
742 additional argument to SetFont, SetFontGD, and SetFontTTF. The overall
743 SetLineSpacing() value is the default for each text element that does not
744 have a specific line spacing set.
746 PHPlot now interprets the value set for line spacing as the number of
747 pixels only for GD text. For TrueType text, it is a scale factor for the
748 font's built-in line spacing for TrueType text. The equation used is:
749 interline_spacing = line_spacing * font_natural_spacing / 6
750 where line_spacing is either the global value set with SetLineSpacing
751 or a more specific value set with SetFont(), and font_natural_spacing
752 is the amount of space between lines built-in to the TrueType font. The
753 factor 6 should really be 4 (since PHPlot always used 4 as the default
754 line_spacing, this would give the natural font spacing by default). But
755 the text is too widely spaced with this value, and 6 was chosen to be
756 more compatible for typical font sizes.
758 Visible Changes and Possible Incompatibilities:
761 Multi-line TrueType titles and labels will have different inter-line
762 spacing. Since the text size affects the margin and plot area sizes,
763 this results in slightly different sized features on any plot with
764 multi-line TrueType text.
765 Previous versions of PHPlot used a default 4 pixels for inter-line
766 spacing of multi-line TrueType text, regardless of the font size.
767 PHPlot now uses the 'natural' font inter-line spacing, adjusted by a line
768 spacing parameter (per text type, with a global default).
770 The same change can also increase the size of the legend box slightly.
772 + Internal changes were made to the way font information is stored. Anything
773 that directly references PHPlot internals regarding fonts will break. Usage
774 also changed for the internal functions to size and draw text (ProcessText*,
775 SizeText*) due to font data storage changes.
777 + Changes were made to internal class variables used to store label
778 formatting information. Anything relying on these internals may break.
783 #1932571: Data-Data Plot fails with same X values
784 PHPlot will no longer hang if all X values are the same. But this is
785 interim fix to force the X range to 1 to prevent the hang. Eventually,
786 smarter automatic range code will handle this better.
787 Credit to andyl for finding this.
789 #1891636: Misaligned TTF X Labels
790 PHPlot will now correctly line-up TrueType labels along the X axis. There
791 were small but very noticeable errors before, when the text had descenders
792 or lines with all short letters.
795 -----------------------------------------------------------------------------
797 2008-01-13 Released 5.0.5
801 This is the current stable release of PHPlot. The emphasis of this release
802 is to improve text positioning, margin calculation, and error handling.
804 Although this is considered a stable release, it has a large amount
805 of changed code compared to the previous release 5.0.4. Two of the more
806 complex components of PHPlot - text and margin calculations - were mostly
807 re-written in this release. You are advised to carefully test your own
808 applications with PHPlot-5.0.5 to see how your plots look. Refer to the
809 README.txt file included in the release for information on reporting problems.
811 Starting with this release, PHPlot no longer supports PHP4, since the PHP
812 group officially declared end-of-life for PHP4 as of 31 December 2007.
813 PHPlot-5.0.5 was tested only with PHP-5.2.5 and we are unlikely to address
814 any issues using PHPlot with older versions of PHP.
816 The PHPlot reference manual has been updated to match this release. The
817 manual is available as a separate download from Sourceforge. The manual is
818 now also now available for on-line viewing at http://phplot.sourceforge.net
820 The callback feature added in 5.0.4 is now documented in the reference
821 manual. It is still considered experimental and subject to change, however.
825 Visible Changes and Possible Incompatibilities:
827 + Dropped support for PHP4.
829 + Eliminated remaining order-dependent behavior related to margins and
830 text. PHPlot should now do nothing at all, except record parameters, until
831 you draw the graph with DrawGraph. I believe this was always the intended
832 behavior of PHPlot, but over time perhaps various pre-calculations and
833 dependencies crept in. Fixing this simplifies processing and should lead to
834 more consistent behavior.
836 + The rewritten margin calculation code now uses actual sizes of all tick
837 and data labels and tick marks, rather than guesses. Margins collapse to
838 remove unused elements, but a minimum margin (currently fixed at 15 pixels)
839 is applied so the plot edges don't get to close to the image edges. The
840 result is that most graphs with auto-calculated margins will change in
841 appearance. It most cases, the margins get slightly smaller. In other
842 cases, earlier releases mis-calculated the margins, so this release will
843 produce much neater margins.
845 + The X and Y titles are now offset out from the plot area, not in from the
846 image area. For auto-calculated margins this should not make any
847 difference, but if you use SetMarginsPixels or SetPlotAreaPixels to set
848 larger margins, the axis titles will move in closer to the plot with this
851 + Changes were made to PHPlot internals, including removal of some class
852 variables and functions, and addition of new variables and functions.
853 These are documented in the ChangeLog. Relying on any internal variables
854 or functions in an application using PHPlot is unwise. The following
855 internal functions were removed:
856 SetImageArea() DrawDotSeries() DrawLineSeries() CalcXHeights()
857 CalcYWidths() DrawLabels() InitImage() DrawDashedLine()
858 These were marked 'deprecated', were undocumented and unmaintained.
860 This was replaced with SizeText().
862 + Line spacing set with SetLineSpacing() now affects TTF text as well as
863 GD text. Previously, it only affected GD text. The default line spacing
864 happens to be usable for TTF text.
866 + Changes were made to error handling. PHPlot will now trigger a user-level
867 error after producing an error image, instead of exiting. If no error
868 handler has been set, it will exit, as before. But now the error message
869 should also get logged, or written to the standard error stream, depending
870 on the SAPI in use. You can now establish an error handler to catch most
871 PHPlot errors and do some cleanup before exit.
873 + PHPlot no longer accepts some invalid option values (such as a substring
874 of a valid value, or empty strings) passed to functions. If your
875 application aborts in CheckOption with PHPlot-5.0.5 but 'worked' with
876 previous releases, them you were probably using an invalid option value.
882 #945439: x_tick_label_height not set correctly
883 Exact sizes of labels are now used to calculate margins.
885 #1813070: Bad position for multi-line TrueType text
886 Fixed as part of text functions rewrite. Use correct basepoint
887 (lower left of each line) when positioning text lines.
889 #1813071: Wrong title height for multi-line TTF text
890 Fixed as part of text functions rewrite: calculate height of
891 multi-line text correctly. Also now uses the line-spacing setting.
893 #1813474: DrawText alignment arguments wrong
894 Fixed so 'top' and 'bottom' now have the usual meaning: top means
895 align top of text with reference, bottom means align bottom of text.
896 This was switched before. Changed every internal caller to compensate.
898 #1816844: Fix order dependency for setting titles
899 Defer processing of title strings until DrawGraph(),
900 so it doesn't matter if fonts, etc. are set before or after.
902 #1819668: Horiz. align multi-line text: GD vs TTF
903 The text functions were rewritten to draw TTF text line-by-line,
904 like GD text, and correctly align each line.
906 #1823774: Default Font Path and Error Message
907 Error handling has been improved to make sure a message is logged, in
908 addition to the error image, and use error_trigger rather than exit.
910 #1826513: FIXME in DrawLegend: Max label length
911 The actual size needed for legend text is now used.
913 #1827263: Spoiled up pie-chart if $val is close to zero
914 Fixed by skipping over any segment that rounds to 0 degrees of
915 arc. (The GD function uses integer angles only, and 0 degrees
916 means draw a complete circle.)
918 #1836528: Insufficient checking of parameter values
919 Rewrote validator function to reject improper parameter values.
921 #1843012: Make margins, drawing consistent
922 Margin code logic was rewritten and checked for consistency.
924 #1856207: Margin error with 'xaxis'/'yaxis' position
925 Margin space is now allocated for ticks and labels if their position
926 is 'xaxis' or 'yaxis' and the axis is at the plot edge. This is not
927 a perfect fix (the axis could be close but not at the edge).
930 -----------------------------------------------------------------------------
932 2007-10-20 Released 5.0.4
936 This is the latest stable release of PHPlot. We are abandoning the 'rc'
937 version naming style, because we don't consider these last releases
938 'release candidate' versions. As we continue to make changes to PHPlot,
939 we are not converging toward a final "5.0" release, however we do consider
940 these releases stable and complete enough for production use.
942 This release fixes a number of problems and introduces a few new features.
944 The PHPlot reference manual has also been updated to match this release.
945 New material has been added documenting some of the PHPlot internals.
946 The manual is available as a separate download from Sourceforge.
951 Some code cleanup is going in to this release. It is hoped that these
952 changes will not impact any existing scripts using PHPlot, but will make
953 the PHPlot code itself easier to understand and maintain.
955 PHPlot now avoids making changes outside its own class definition. There
956 are no longer any functions defined outside the class, nor any constants.
957 Three constants (MINY MAXY TOTY) were removed, and 2 functions were removed
958 (see Visible Changes below). Also PHPlot no longer sets the PHP error
959 reporting level to E_ALL. Although we highly recommend setting error
960 reporting to E_ALL in your php.ini file or scripts, it is not right for
961 PHPlot to assume that you want it.
964 Visible Changes and Possible Incompatibilities:
966 Arrays containing color and style information are used with several PHPlot
967 functions to control the plot style array. These functions are:
968 SetPointShapes, SetPointSizes, SetLineWidths, SetLineStyles,
969 SetDataColors, SetDataBorderColors, and SetErrorBarColors.
970 The arrays passed to these functions MUST used sequential integer 0-based
971 indexes. This is what the PHP manual calls "Usual integer indices (starting
972 from zero, increasing by one)". This is the type of array you get in PHP by
973 default if you use array() without specifying key values, or use the
974 empty-bracket assignment operator to add values onto an array. In previous
975 versions of PHPlot, some of these functions would also work with
976 string-indexed or non-sequentially-indexed arrays, but this was not clearly
977 defined. Starting with PHPlot-5.0.4, only arrays with "usual integer
978 indices" work, and other array indexes will cause errors.
980 Some internal-use-only functions have had their usage changed or been removed.
981 If you are using functions that are not documented in the PHPlot Function
982 Reference in the manual, your code may have to be changed.
984 As part of the code cleanup, two functions which were defined outside the
985 PHPlot class were removed: array_pad_array(), and array_merge_php4().
986 If your code used these, you need to fix your code.
988 The routines which accept a color name, value, or array now check for a valid
989 color name. If you specify a color name which is not in your current color
990 table, PHPlot will draw an error and exit. Previously, PHP would report an
991 index error, continue, and get a 'headers already sent' message.
996 #1813021: Miss-positioned right-justified vertical GD text.
997 Fixed DrawText() to correctly position 90 degree right-justified text
998 drawn in a fixed GD font. This could be seen with 90 degree Y tick labels.
1000 #1790441 Removed destructor/shutdown function, and no longer recommend
1001 using reference assignment when creating a PHPlot object. This was
1002 interfering with memory usage.
1003 Credit to annajilly for analysis.
1005 #1779115 SetLegendWorld() failed because of undefined variables. The
1006 required order dependency was too hard to meet. This is now fixed.
1007 You can now use SetLegendWorld anywhere before DrawGraph.
1009 #1726810 (feature request, but actually a bug fix) Ignore empty strings
1010 as data labels when doing time or data label formatting. These would
1011 previously produce errors or bad formatting. Now you can omit labels
1012 as needed even with time and data formatting.
1013 Credit to exgerhardr for finding this.
1015 #1605555 Y data labels used wrong font and not formatted (bar charts only).
1017 #1208054 Localization of number formatting in 'data' format type. PHPlot
1018 will attempt to format the numbers in a way appropriate to your locale.
1019 You can also force the formatting with the new function SetNumberFormat.
1020 Credit to David Hernández Sanz.
1022 #937944 X/Y Tick counts: PHPlot could draw one two few Y tick counts, and
1023 one too many X tick counts. This is not a perfect fix, and more work is
1024 needed here, but this fixes an error case in both X and Y values.
1027 New Features in 5.0.4:
1029 New function SetLegendStyle allows control of the alignment of text and
1030 color boxes within the legend. Also allows removing the color boxes.
1031 Based on bug #1208054.
1032 Credit to David Hernández Sanz.
1034 New function SetNumberFormat. See bug report #1208054 above.
1036 Callbacks are added. PHPlot can call back your functions while generating the
1037 plot. This is experimental, and documented only in the file "Callbacks".
1038 Credit to annajilly for the idea and design.
1040 -----------------------------------------------------------------------------
1042 2006-11-13 Released 5.0rc3
1046 This is an interim release. It has been a long time since the previous
1047 release 5.0rc2, and there have been a lot of changes. There are still more
1048 changes likely to go in before we have "5.0", but there are enough for now.
1050 The PHPlot Reference Manual has also been released, and is available as a
1051 separate download from Sourceforge. PHPlot users and developers are
1052 strongly encouraged to read the manual.
1054 This release does not include the "doc/" and "examples/" directories of
1055 previous releases. The Reference Manual contains more complete and
1056 up-to-date information and examples, and I am unable to maintain the doc/
1057 and examples/ files while also maintaining the Reference Manual. If you
1058 need those files, they can be accessed with the Sourceforge web CVS
1064 The emphasis for this release is bug fixing, so there are few new features.
1066 + You can now suppress lines or points on individual plots in a linepoints
1067 graph. This feature was added because I needed a graph with several
1068 linepoints lines, but also with a solid line showing an "80% goal".
1069 Use SetPointShapes with the value 'none' in the array to suppress the
1070 point markers for that plot (and only draw the line).
1071 Use SetLineStyles with the value 'none' in the array to suppress the
1072 line for that plot (and only draw the point markers).
1075 + Bar charts can have data labels above the bar with the value. Turn
1076 these on with SetYDataLabelPos('plotin'). This is somewhat experimental,
1077 since there isn't a lot of room for labels on top of the bars and you
1078 may find the results are not useful.
1083 Here are the more significant changes in this release. These are changes
1084 which may affect existing scripts and output from PHPlot. See the
1085 ChangeLog file for information about all changes and bug fixes.
1087 + A bug fix on bar chart bar borders results in black borders around the
1088 bars if shading is turned off. The border was previously covered up,
1089 but was supposed to be there. If you need borderless, unshaded bars,
1090 you need to use SetDataBorderColors to make the borders the same colors
1091 as the bars. [Bug # 1096197]
1093 + TrueType font pathname handling was fixed. You no longer need to use
1094 SetUseTTF(True). You can either use full paths to the font files with
1095 SetDefaultTTFont() and SetFont(), or you can call SetTTFPath() to point
1096 to a directory of font files, and then use simple font filenames without
1097 paths in SetDefaultTTFont() and SetFont().
1098 [Bug # 1144644 plus several others]
1100 + There have been several fixes regarding automatically calculated ranges
1101 and scales. The result is that you may see less extra space and fewer
1102 tick marks in some cases.
1104 + A fix was made to bar and stackedbar graph bar widths in order to get
1105 the X axis labels to properly center. As part of the fix, the bar widths
1106 now match between the two graph types. (Before this fix, the bars were
1107 narrower in bar graphs compared to the same data plotted as a stacked
1108 bar.) As a result, bar graph bars will now be drawn with wider bars, and
1109 stackedbar graph bars will be narrower. You can adjust this with the new
1110 class variable bar_extra_space. [Bug # 1437912]
1112 + Dot shapes and sizes were off by 1 or 2 slots in the array of shapes or
1113 sizes. After the fix, you may get different dot shapes or sizes per
1114 plot line. [Bug # 1096194]
1119 Since its output is visual (graphics), and it has so many interconnected
1120 modes and options, PHPlot is difficult to test. But at least we are now
1121 trying. I have a collection of PHPlot scripts (currently about 60) and a
1122 script to run through them. The script automatically checks that:
1123 1) Nothing was written to the standard error stream;
1124 2) An image file of size greater than 0 was written;
1125 3) Neither the test script nor PHPlot did exit(). This catches cases
1126 where PHPlot aborts with DrawError().
1128 The automated test is an easy way to check for serious regression, but you
1129 really need to inspect the output files to validate PHPlot. This takes a
1130 little time, and it is easy to overlook problems.
1132 The real issue is test coverage. Just as we can be sure that future
1133 PHPlot releases will pass the test collection, we can also be sure that
1134 future bug reports will be written against untested cases.
1136 --------------------
1138 2006-11-08 PHPlot on Sourceforge has a new maintainer: lbayuk
1140 --------------------
1142 2004-10-24 Released 5.0rc2
1144 --------------------