This is the NEWS file for PHPlot, with release documentation. The project web site is https://github.com/AJRepo/PHPlot/ The project home page is https://github.com/PHPLot/PHPlot// Refer the the ChangeLog file for detailed source changes. See NEWS_part1.txt for older release documentation. ----------------------------------------------------------------------------- 2022-12-28 Release 8.0.0-RC1 === Overview: This is the RC1 release of PHPlot tested with PHP 8.1 and linted with PSR-12. This brings PHPLot better into alignment with community standards as of 2023: * Explicitly defining public functions as "public" * Specifying a namespace (PHPlot\PHPlot) * Matching Composer standards (e.g. phplot -> src, phplotest -> test) * creating a composer.json === Cautions, Important Notes, and Compatibility Issues: --- Directory name change from /phplot/ to /src/ and from /phplottest/ to /test/ --- Moving to a specified namespace means a change in defining the PHPlot object. If you get the error: `PHP Fatal error: Uncaught Error: Class "PHPlot" not found` look at specifying the full namespace. E.g. if you have `$plot = new PHPlot(800, 600);` try changing to `$plot = new PHPlot\PHPlot\PHPlot(800, 600);` --- PSR-12 standards states that all subclasses get moved to their own file, thus phplot_truecolor.php is a new file, which used to be part of file phplot.php. if you had `require_once 'phplot.php';` and also wanted to use truecoloer add the following line `require_once 'phplot_truecolor.php';` see area2.php for an example. ----------------------------------------------------------------------------- 015-11-01 Release 6.2.0 === Overview: This is the current stable release of PHPlot. This is the first release that will work with the upcoming PHP-7. This release also adds two new plot types. The PHPlot Reference Manual has been updated to match this release. === Cautions, Important Notes, and Compatibility Issues: PHP-7 deprecated use of older-style class constructor method names, where the constructor name matches the class name. The PHPlot class constructor name in this release has been fixed to work with PHP-7. This release also works with PHP-5.4, 5.5, and 5.6. However, there is a compatibility issue with extended classes. This applies even if you are using PHP-5. If you define a class which extends the PHPlot class, you must use this syntax to call the PHPlot constructor from your class constructor: parent::__construct(...); // Call parent class constructor This syntax also works in previous releases of PHPlot. However, the following syntax also worked in older releases, and will no longer work: $this->PHPlot(...); // Do Not Use This to call parent class constructor or: parent::PHPlot(...); // Do Not Use This Either You must use the correct syntax parent::__construct() even if using PHP-5. If you are using PHP-7 with PHPlot, here are a few other items to be aware of. (Some of these affected the PHPlot test suite.) + PHPlot uses is_numeric() to check for missing points in the data array. Starting with PHP-7, hexadecimal strings are no longer considered numeric. This means if your data array contains the string "0x10", for example, PHPlot will consider that to be the number 16 when using PHP-5.x, but will treat it as a missing point with PHP-7. (Unquoted hexadecimal values are still numbers.) + PHP-7 no longer allows multiple function parameters with the same name. A typical case which fails in PHP-7 is: function myfunction($s, $unused, $unused); // Fails in PHP-7 This broke some PHPlot Test Suite scripts that implemented PHPlot callbacks with unused parameters. + New objects cannot be assigned by reference. Very old versions of the PHPlot Reference Manual had this syntax (and there may still be some old versions out there): $plot =& new PHPlot(600, 400); // Do not use & + Division by zero no longer results in E_WARNING, but you end up with one of the special float values +INF, -INF, or NAN instead. === Bugs Fixed in 6.2.0: Fixed bug #170 "replace eval() ...": This was a request to remove use of eval() from SetDashedStyle(), because eval() makes people nervous about security, and is not supported by some Virtual Machines. Removed eval() by using a string template instead of a code string for the dashed line pattern. There are no changes in usage or behavior. Fixed bug #172 "Fixes for PHP7": This release now works with PHP-7 (currently pre-release). The constructor name was changed; there were no problems with the rest of the code. (Although several scripts in the PHPlot Test Suite also had to be fixed.) Any class that extends PHPlot must now use the correct syntax to call the parent constructor: parent::__construct(...). If they used the old syntax $this->PHPlot(...) they will not work (even with PHP-5.x). === New features in 6.2.0: Feature Request #55 "Method documentation in PHPDoc format": PHPlot now uses "phpdoc"-style comments in the code, which apparently is supported by some editors/IDEs. Note that the PHPlot Reference Manual does currently make use of these comments. Feature Request #56 "Hidden Y values when zero": The request was for a way to hide Y label values when zero, but the implementation is much more general. When using 'printf' label formatting type, you can now specify 1, 2, or 3 separate format strings. These are applied in the same way spreadsheets support cell format strings: which format is used depends on the sign of the value. Feature Request #57 "squarefilled plot type": Two new plot types are added: 'squaredarea' and 'stackedsquaredarea'. These are like area and stackedarea, but the edges are stepped like 'squared' plots. Feature Request #58 "Data borders for area plot types": After data borders support was added to the two new plot types 'squaredarea' and 'stackedsquaredarea', this was extended to the existing, similar plot types 'area' and 'stackedarea'. Data borders are off by default for all 4 plot types. ----------------------------------------------------------------------------- 2013-05-11 Release 6.1.0 === Overview: This is the current stable release of PHPlot. This release includes two new plot type features (which were not completed in time to make it into PHPlot-6.0.0). The PHPlot Reference Manual has been updated to match this release. === Cautions, Important Notes, and Compatibility Issues: There are no new compatibility issues in this release. However, if upgrading from PHPlot-5.8.0 or older, please read the Cautions, Important Notes, and Compatibility Issues from the PHPlot-6.0.0 release. Everything there is still applicable. === Bugs Fixed in 6.1.0: (none) === New features in 6.1.0: Feature Request #47 "Extend horizontal plots to more types": This feature request was mostly implemented in PHPlot-6.0.0, except for horizontal error plots, which are now implemented. A new data type 'data-data-yx-error' is used for horizontal error plots of type lines, points, and linepoints. Feature request #52 "Box Plots": A new plot type 'boxes' is added. This produces a Box Plot, which is used to present a 5-number statistical summary of a data set. ----------------------------------------------------------------------------- 2013-04-03 Release 6.0.0 === Overview: This is the current stable release of PHPlot. This release includes a significant rewrite how PHPlot automatically calculates the plot area range and tick increments from the data points. A number of new features and bug fixes are also included. The PHPlot Reference Manual has been updated to match this release. A previously-experimental feature to help create HTML image maps is now fully documented in the manual. === Cautions, Important Notes, and Compatibility Issues: There are some important compatibility issues you need to be aware of before upgrading to PHPlot-6.0.0 from any previous version. Many scripts will produce different-looking plots with PHPlot-6.0.0 compared to earlier versions. This is mostly due to changes in the automatic plot range and tick increment calculations. Also, some scripts may fail, if they access PHPlot class internal variables (properties) which have been changed to have 'protected' visibility. See the details below. + Plot range calculations changed PHPlot-6.0.0 uses a completely new method to calculate each of the 4 limits of the plot area which are not defined using SetPlotAreaWorld(). As a result, most plots that don't use SetPlotAreaWorld() with all 4 coordinates given will look different under PHPlot-6.0.0. The two most notable changes are that PHPlot-6.0.0 will usually stretch the range to include zero (if the range does not already include zero), and under most conditions will ensure that the X axis and Y axis both start and end at a tick mark position (even if tick marks and labels are not visible). See bug #101 below. + Tick increment calculations changed PHPlot-6.0.0 uses a completely new method to calculate tick increments along the X axis and Y axis. This only occurs if the tick increments have not been set using SetXTickIncrement() or SetNumXTicks() for X, and SetYTickIncrement() or SetNumXTicks() for Y. If you let PHPlot calculate the tick increments, your plot will likely have fewer or more tick intervals than before, and the tick increment will be different. In general, PHPlot-6.0.0 makes much better choices for tick increment. See bug #132 below. + Class variable visibility changed Most PHPlot class variables now have 'protected' visibility, so they are no longer accessible from scripts that use the class. If your script directly accesses PHPlot class variables - other than those documented in the manual for 'tuning' - your script will not work with PHPlot-6.0.0. This change was necessary because some internal class variables change in each PHPlot release, and it is impossible to maintain compatibility with direct access to all these class variables. If your script breaks because of variable visibility changes, please: (1) see if you can use a public PHPlot class function instead, or (2) post a message to the PHPlot help forum explaining why you need access to a particular class variable. + SetPlotAreaWorld() now validates arguments Starting with PHPlot-6.0.0, the SetPlotAreaWorld() function checks non-NULL arguments for validity. For both X and Y, it is required that min < max if both are specified. If you have a script that calls SetPlotAreaWorld() with max <= min for either X or Y, that script will now fail. On the other hand, some valid cases where you specify only one end of a range would previously fail and now work. + SetRGBArray() now validates argument If you use SetRGBArray() to load a custom color map but pass an invalid argument (not an array or one of the known keywords), PHPlot will now fail with an error message. In previous releases, a default black/white color map was loaded in that case, with no error reported. + Removed order dependency: number of ticks and tick increment If you want to control the tick increments (rather than letting PHPlot calculate them), you should set either the number of ticks (SetNumXTicks(), SetNumYTicks()) or the tick increment (SetXTickIncrement(), SetYTickIncrement()), but not both, for each axis. If you do set both, PHPlot-5.8.0 and earlier will use the last setting you made, and ignore the other. PHPlot-6.0.0 gives priority to the tick increment setting and ignores the number of ticks, regardless of the order. (The new behavior is consistent with the PHPlot design goal that you can use the various Set*() functions in any order and get the same plot.) === Bugs Fixed in 6.0.0: Fixed bug #101 Fix automatic Y range calculations": PHPlot now calculates the Y (and X) ranges using a completely different method, which is described in the manual. There are new functions to 'tune' the algorithm used, and of course you can still set the range limits manually. In most cases, PHPlot now makes much better choices for the plot range limits. Fixed bug #132 "Improve tick interval calculations": PHPlot now by default picks a tick increment which is 1, 2, or 5 times a power of 10, for much more 'natural' results. There are alternate algorithms for selecting a 'binary' (power of 2) or date/time-based tick increment instead. Rather than simply dividing the plot range by 10, PHPlot now selects a tick increment based on the above requirement and which results in at least 8 (by default) tick intervals. Of course, you can still specify the tick increment(s) directly. Fixed bug #164 "Calculated defaults applied to subsequent plots": This has been fixed for the cases of grid visibility, X data label angle, and label format. A new bug #168 was written for a remaining issue with label position defaults. This only apples when creating multiple plots on a single image (overlay or side-by-side). Fixed bug #165 "Missing axis labels on some empty plots": In some cases, X axis labels would be absent for a plot with an empty data array. PHPlot will now draw the axis labels even when the data array is empty. Fixed bug #166 "Legend, UsePointShapes, and shape='none'": PHPlot will now fall back to using a point marker in the legend when doing a linepoints plot with a dataset using 'none' as the point shape (rather than doing no marker at all). This only applies with SetLegendUseShapes(True). Fixed bug #167 "Fails to find a default font on Ubuntu": Ubuntu (via Debian) changed the installation path for the TrueType font that PHPlot used as a default, causing font selection to fail. The new font installation path has been added to the search list, and now PHPlot can find the default TrueType font on Ubuntu. === New features in 6.0.0: Feature request #29 "Finer control over plot element colors": This was an open-ended feature request that is partially implemented and now closed. New functions were added to control element colors. (Some other functions were added in previous releases.) In PHPlot-6.0.0, these functions were added: SetLegendBgColor() for legend background color; SetLegendTextColor() for legend text color, and functions for pie chart border colors (see feature request #46 below). Feature request #45 "Control pie chart start angle": Implemented with new functions SetPieStartAngle() and SetPieDirection(). The angle for the first segment, and the direction (clockwise or counter-clockwise) can now be set for pie charts. Feature request #46 "Control pie chart borders": Implemented with new functions SetDrawPieBorders() and SetPieBorderColor(). Pie segment borders can now be on (default for unshaded) or off (default for shaded), and the color can be set independent of other elements. Feature request #47 "Extend horizontal plots to more types": This is partially implemented. Horizontal lines, linepoints, and points plots are now implemented. Error plot versions of those horizontal plot types are not yet implemented, but will probably be in the next release 6.1.0 (with the introduction of a new data type). Note: In implementing feature request #47, the code for 'error' and 'non-error' versions of the 3 plot types above were merged. A side effect of this is that data value labels (the labels within the plot area, identifying the data value at each point) now work for error plots, if enabled. However, the default label position at 90 degrees will be crossed by the positive error bar. To avoid this, you can use the tuning variable data_value_label_angle; for example setting it to 45 degrees. Feature request #50 "Control legend colorbox borders": Implemented with new function SetLegendColorboxBorders(). There are now 3 choices for the borders around color boxes in the legend: 1) use the 'text' color (the default, and compatible with PHPlot-5.8.0 and older); 2) use data border colors; and 3) disable the borders. Note: Along with the implementation of feature request #50, a new function SetDrawDataBorders() was added to control drawing the data borders on bars and stackedbars plots. This supports having the same style (borders with matching color, or no borders) on both the legend color boxes and the data bars. The default is backward compatible: borders on unshaded plots, and no borders on shaded plots. Feature request #51 "Lines instead of colorboxes in legend": Implemented with existing function SetLegendUseShapes(). PHPlot now has the option of showing short line segments (with correct color and width) in the legend, rather than color boxes. This applies to lines and squared plots only. ----------------------------------------------------------------------------- 2012-04-06 Release 5.8.0 === Overview: This is the current stable release of PHPlot. This release adds several new features, including the ability to generate "streaming plots" - a video stream showing updated plot data. The PHPlot Reference Manual has been updated to match this release. === Cautions, Important Notes, and Compatibility Issues: There are no known compatibility issues in upgrading from PHPlot-5.7.0 to this release. For issues with previous releases, see below in this file. === Bugs Fixed in 5.8.0: Fix bug #3506408 "Data Label Lines vs new plot types": Data label lines do work with bubble plots. This is now documented. Data label lines did not work well with OHLC plot types. This was never documented to work, and is now disabled. === New features in 5.8.0: Feature request #3488042 "Display only some data value labels": Custom label formatting functions now have access to the data point row and column for data value labels, and to the row for axis data labels. You can now filter or modify labels based on their position in the data array. Documentation was updated. Feature request #3501500 "Looping plot section (updating plot data)": PHPlot can now produce "streaming plots", with updating data presented as a Motion-JPEG stream. Documentation has been added to the reference manual. Feature request #3515519 "Support object serialize/unserialize": You can now serialize and unserialize a PHPlot object, subject to some minor restrictions. Details are in the PHPlot Reference Manual. ----------------------------------------------------------------------------- 2012-02-25 Release 5.7.0 === Overview: This is the current stable release of PHPlot. This release includes several bug fixes, new color controls for labels, a new feature for application-level error handling, and an experimental feature for creating plot image maps. The PHPlot reference manual has been updated to match this release. === Cautions, Important Notes, and Compatibility Issues: This release includes a change in how the color is set for data value labels. (These are the labels inside the plot area that identify the tops of bars, for example.) This can change the color of some labels. See the bug report "Wrong color for data value labels" below. This release reverts a change from PHPlot-5.4.0 to stackedbars plots. It affects plots with stacked bar segments of size 0 that are at the top or end of a stack. Starting in PHPlot-5.4.0, a zero-size segment at the top or end would result in a color 'cap' on the bar stack, using the data color of the zero-size segment. In PHPlot-5.7.0 this has been fixed. This will change the appearance of some stackedbars plots. See the bug report "Top dropshadow [sic] of stacked bars..." === Bugs Fixed in 5.7.0: #3396931 "Top dropshadow of stacked bars is always the same color": PHPlot will no longer draw a color 'cap' at the top or end of a bar stack if the last segment has a 0 value. (The term 'dropshadow' isn't correct.) Drawing the color for zero-size segments started in PHPlot-5.4.0 as part of the fix for bug #3296884, but the behavior was unexpected, so it was reverted. In general, PHPlot will now ignore segments with size 0, and if a stack contains all 0 values it will not be drawn. (The exception is if the axis is moved.) #3488064 "Pie label failures in locales with comma decimal": Two work-arounds are implemented for what is essentially a PHP problem with locales that use something other than a period (typically comma) for the decimal separator. When formatting labels as type 'data', PHPlot loads the locale settings to get the separator characters, but now it resets ('unloads') the settings afterwards. This helps avoid an error seen in PHPlot-5.6.0 with pie chart labels, where an incidental conversion of the label to a string resulted in use of the comma separator, followed by PHP failing to convert the number back to floating point because of the comma. The second work-around is to avoid the conversion to string, in the case where the pie label has a single value. Together, these work-arounds should prevent the problem, but this is an imperfect fix. #3486834 "Wrong color for data value labels": PHPlot was using the 'title' color (SetTitleColor()) for data value labels, which was wrong, as the title color is for the 3 plot title strings. PHPlot will now use the general text color (SetTextColor()) for data value labels, same as tick labels and axis data labels. This will change the appearance of some plots. In order to help with the compatibility issue, 4 new functions are introduced to control the colors of individual label types: SetTickLabelColor(), SetPieLabelColor(), SetDataLabelColor(), and SetDataValueLabelColor(). The defaults have been set up to be compatible (except for data value labels). Details are in the PHPlot Reference Manual. === New features in 5.7.0: #3442041 "Provide data for generating image maps": An experimental feature has been added to allow a callback function to process the coordinates of individual plotted data points. This is most useful for generating an HTML image map for the plot. Refer to the text file Imagemaps.txt included in the PHPlot release for details. Caution: This is an experimental feature. It is subject to change, and not yet documented in the reference manual. #3481195 "Custom message image": A new function DrawMessage() has been implement for special cases where you need to display an image containing a message, rather than a plot. This extends the PHPlot error reporting mechanism, and is intended for application-level errors. More information and an example can be found in the PHPlot Reference Manual. ----------------------------------------------------------------------------- 2012-01-02 Release 5.6.0 === Overview: This is the current stable release of PHPlot. This release includes significant changes to pie charts. There are new ways to label pie charts, and PHPlot does a better job calculating the size and positioning the labels. The PHPlot reference manual has been updated to match this release. === Cautions, Important Notes, and Compatibility Issues: Pie charts will change appearance when you upgrade to PHPlot-5.6.0 from any previous release. This is due to changes resulting from bug #3403297, described below. You may notice these changes: 1. The pie chart itself will usually be drawn larger, taking up more of the image. This may result in interference with a plot legend. 2. Pie chart labels will be closer to the edge of the pie, if you are letting the label positions default. If you are using SetLabelScalePosition() to set the label positions, the results may vary even more. 3. Text alignment on pie chart labels will change. 4. World Coordinates are now undefined with pie charts. If you are producing pie charts with PHPlot, you should review the output of your scripts before using PHPlot-5.6.0 in production. If the output is not acceptable, one or more of these steps might help: 1. If pie charts are too large, and/or interfere with a legend, try moving the legend. Alternatively, use SetPlotAreaPixels() or SetMarginsPixels() to limit the plot area. Note, however, that starting in this release PHPlot sizes the pie so the labels fit inside the plot area too. You can control this with SetPieAutoSize(). 2. If you want labels positioned just outside the pie chart, do not call SetLabelScalePosition(), or set the value to the default 0.5. If you want labels just inside the pie, use 0.49. If you want labels to be about half-way inside the pie, use 0.25. (In previous releases, PHPlot multiple the label scale position by 1.2 before using it to position the labels, but this was not documented.) 3. Your pie chart script will report errors if you use GetDeviceXY(), SetLegendWorld(), or SetLegendPosition(...,..., 'world'). This is because these functions require world coordinates, and world coordinates are not defined for pie charts. (Previous releases did define a world coordinate space for pie charts, but the values were meaningless.) === Bugs Fixed in 5.6.0: #3403297 Pie chart sizing and label issues: In addition to the fixes listed here, new features were added as a result of this bug fix (see New features below). + Use both width and height of the pie when calculating its maximum size. (The bug was that the pie diameter would be sized to fit in the smaller of the image width and height. But a shaded pie is oval, so when the width if the pie was sized to the height of the image, the pie was too small.) + Fixed the text alignment of pie labels so they extend more naturally away from the pie chart (if outside the pie). (Don't just use center/center alignment for all labels.) + Do not multiply the label scale position by 1.2 in the hope that this will prevent labels from overlapping the pie. Use the label scale position as intended, and take other measures to prevent label overlap (such as fixing the text alignment). + Label positions along the bottom of the pie are now adjusted to account for the pie shading depth. + Plot area borders now work with pie charts. Use SetPlotBorderType() to enable them. The default is not to draw borders. === New features in 5.6.0: A number of new features were added as a result of bug #3403297, described above. The new features are: + Use the new function SetPieLabelType() to select the type of pie labels to be displayed. Labels can show segment percentages, segment values, string labels, or any other value using a custom function. + SetPieLabelType() also allows control over formatting of pie labels, similar to the way X and Y tick and data labels can be formatted. + Plot labels can be suppressed with SetLabelScalePosition(0). + The aspect ratio of shaded pies can be controlled with a tuning variable $pie_diam_factor. The default remains 0.5, making the pie height equal to half its width. #413925 Table of values: This very old feature request was implemented by adding a new script to the "contrib" directory. The data_table.php script contains a function to draw a simple table of values on a PHPlot image. Examples are provided. ----------------------------------------------------------------------------- For older releases, see NEWS_part1.txt