Label format type 'data' expects the tick label, data label, or pie label values to be numbers, and formats the values as floating point numbers with a separator between every group of thousands and a fixed number of decimal places. You can set the number of digits of precision, with the default being 1 digit. You can also set a prefix and/or suffix string (such as a currency symbol or percent sign). PHPlot will try to set the thousands grouping separator and decimal separator according to your locale, but this can be overridden if necessary.

For example:

$plot->SetYLabelType('data', 2, '$');

This might format the value 1234.567 as "$1,234.57" (depending on locale).

Label format type 'time' expects the tick or data label values to be a PHP time value (number of seconds since a fixed base data, the Unix Epoch). PHPlot will format the labels according to the format string you provide. Refer to the PHP documentation for strftime() for details on the format string.

For example:

$plot->SetXLabelType('time', $format);

If a label value is the numeric equivalent of "31 December 2004 at 1:23:45 pm" (which is 1104517425 on some platforms), the following table shows some examples of the result with different values of $format:

(This formatting type is generally not applicable to pie chart labels.)

While date/time formatting can be useful, for X values it may be easier to just format the label values in your PHP code and put the result into the label positions in the data array. If you need date/time formatting for Y values (and it is hard to imagine where that would be useful), you have no option but to use the 'time' format labels for tick values.

Label format type 'printf' expects one, two, or three additional arguments specifying printf format strings, and formats the label value according to the format string(s). If a single format string is given, it is used for the label values. The format string must contain exactly one conversion specification (%-code) which consumes a single argument. For example:

$plot->SetYLabelType('printf', '%8.2e parsecs');

This might produce a label like " 1.23e+8 parsecs".

If two format strings are provided, the first is used to format the value of the label if it is greater than or equal to zero. The second format string is used to format the absolute value of the label if the label value is less than zero.

If three format strings are provided, the first is used to format the value of the label if it is greater than zero. The second format string is used to format the absolute value of the label if the label value is less than zero. The third is used to format the value of the label if it is zero. In some applications, it may be appropriate to use an empty string as the third format string, which will suppress the display of labels with a value of zero.

A user-defined function can be provided to format labels. Specify formatting type 'custom', and provide the name of your function as a string. (This is actually a PHP callback type argument, which can also be an array containing an object and a method name. See the PHP documentation on callbacks for more details.) You can provide an additional argument which will be passed to your function when formatting labels (a pass-through argument).

In this example, the user-provided function is called my_formatter, and you want an additional argument $data passed to the function.

$plot->SetYLabelType('custom', 'my_formatter', $data);

Your formatting function will accept 1 or 2 arguments (or more - see below).

function my_formatter($label, $arg)
{
    ...
    return $some_result;
}

The function will be called with $label set to the value of the label to be formatted, and is expected to return the formatted label text. $arg is a pass-through argument that has whatever value you used with SetXLabelType (etc.). In the above example, this is $data. You need to declare this second argument in your function only if you are using a pass-through argument.

You can also use PHP anonymous functions for custom label formatting. This avoids having to define a function elsewhere in your code, and keeps the custom label formatting code near where it is being used. This is recommended only when the custom label formatting code is relatively short^[3]. Anonymous functions can also take advantage of the PHP use clause to inherit variables from the parent scope.

Here is an example of a custom label formatting function that uses an anonymous function to offset the Y axis label by an amount in a local variable.

$offset = 10; // A local variable
...
$plot->SetYLabelType('custom', function ($y) use ($offset) {
     return ($y - $offset); } );

Custom label formatting is extremely flexible. You can convert values into another format (for example, degrees, minutes, seconds), or look up values in an external array (see Section 5.40, “Example - Bubbles Plot”), for example. However, using this method, you can only selectively format or display labels based on their value. For even more control, use the additional arguments provided to the formatting function which are described in the next section.

When you use 'custom' formatting type, PHPlot actually provides 0, 1, or 2 additional arguments to your callback. These identify the row, or row and column, of the data point being labeled. You can use these extra arguments in your callback for selective formatting or filtering based on the position of the point being plotted in your data array.

PHPlot provides the following additional arguments to a custom label formatting callback (after the label value and pass-through arguments):

You need not declare these arguments unless you are using them, but if you do declare them, it is safer to make them optional with default NULL. (If you are only using the custom callback function for one specific type of label, you can omit the defaults.) For example:

function my_formatter($label, $arg, $row=NULL, $column=NULL)
{
    ...
    return $some_result;
}

The row argument value is an index starting with zero that numbers the rows in your data array. This corresponds to the ordinal position of the independent variable (X for vertical plots, Y for horizontal plots). This is also the outer index of your data array.

The column argument value is an index starting with zero that numbers the data sets in each row. This corresponds to the ordinal position of the dependent variable (Y for vertical plots, X for horizontal plots). Note that this is not simply the inner index of your data array, because the data array rows also have labels, and (depending on the data type) may contain other values. For example, given the data type data-data and this data array:

$data = array(
    array('Jan', 1,  10, 11, 12),
    array('Feb', 2,  20, 21, 22),
    array('Mar', 3,  30, 31, 32),
);

When formatting a data value label for X=2, Y=22 (the 3rd data set in the row labeled 'Feb'), PHPlot will call a custom label formatting function like this:

my_formatter(22, $passthrough, 1, 2);

That is, row=1 and column=2.

As described in Section 3.6.5.4, “Formatting Labels: 'custom' type”, your callback function returns the value of the formatted label. You can return an empty string to display no label. This can be used to display data value labels for only one data set, for example - just return an empty string if $column is not equal to the index of the data set you want to label.

See Section 5.43, “Example - Custom Data Value Label Formatting” for an example.