addChart

addChart

TRIAL / ADVANCED / PREMIUM

Inserts a chart into a Word document.

Description
public addChart ( array $options )

This method allows the insertion of a chart into a Word document.

You may insert many different types of 2D and 3D charts:

  • 2D:
    • Bar (clustered, stacked and 100% stacked).
    • Column (clustered, stacked and 100% stacked).
    • Pie (simple, exploded, pie of pie and bar of pie).
    • Doughnut.
    • Line.
    • Area.
    • Surface.
    • Radar.
    • XY (scatter).
    • Bubble.
  • 3D:
    • Bar: box (default), cylinder, cone, and pyramid (clustered, stacked and 100% stacked).
    • Column: box (default), cylinder, cone, and pyramid (clustered, stacked and 100% stacked).
    • Pie (simple and exploded).
    • Surface.
    • Line.
  • Extended charts (not supported by all DOCX readers):
    • Box & whisker.
    • Funnel.
    • Histogram.
    • Sunburst.
    • Treemap.
    • Waterfall.

This method also allows adding combo charts, trendlines, grids, labels and many other chart features.

Parameters

Options

This is an array with the following possible keys and values:

Key Type Description
data array This array should contain the legends and data and to be represented in the following format:
'data' => array( 'legend' => array('Series 1', 'Series 2', 'Series 3'), 'data' => array( array( 'name' => 'data 1', 'values' => array(10, 20, 30), ), array( 'name' => 'data 2', 'values' => array(20, 4, 5), ), array( 'name' => 'data 3', 'values' => array(10, 0, 2), ), ) )
You should omit the legend array in charts for which each data array only contains one value like, for example, pie charts.
type String The possible values are:
  • areaChart
  • area3DChart
  • barChart
  • bar3DChart
  • bar3DChartCone
  • bar3DChartCylinder
  • bar3DChartPyramid
  • boxWhiskerChart
  • bubbleChart
  • colChart
  • col3DChart
  • col3DChartCone
  • col3DChartCylinder
  • doughnutChart
  • funnelChart
  • histogramChart
  • lineChart
  • line3DChart
  • ofPieChart (pie of pie and bar of pie charts)
  • pieChart
  • pie3DChart
  • radarChart
  • scatterChart
  • sunburstChart
  • surfaceChart
  • treemapChart
  • waterfallChart
title string The chart title (if any).
border string Border width in points.
chartAlign string Chart alignment: left (default), right or center.
color int Word color scheme for charts:
  • 1: greyscale.
  • 2: default Word color scheme for charts.
  • 3: blue scheme.
  • For the remaining color schemes (up to 48) check the Word interface.
comboChart string Chart to add as a combo chart. Use with the returnChart option. Global styles and properties are shared with the base chart. For bar, col, line, area, and radar charts.
customStyle string Set external color and styles files imported using the importChartStyle method.
excludeExternalData bool If true, don't embed the XLSX into the DOCX. Default as false.
externalXLSX array Possible keys and values are:
  • src => (string) path to the external file.
  • occurrences => (array) (optional) by default the option adds all charts of the source file. If occurrences is not empty, it adds the referenced positions. Value from 1.
float string Floating chart: left, right or center. It only applies if textWrap is not inline (default value).
font string The font to be used. Arial, Calibri...
returnChart bool If true it returns the XML of the chart. To be used with the comboChart option. Default as false.
sizeX int The chart width in centimeters (default value ~ 8.5 cm).
sizeY int The chart height in centimeters (default value ~ 6.0 cm).
textWrap int The way text shoud wrap the chart. Possible values are (check the Word interface for the graphical explanation of the different terms):
  • 0 (inline)
  • 1 (square)
  • 2 (front)
  • 3 (back)
  • 4 (up and bottom)
trendline array Adds trendlines. Compatible with line, bar, col and area 2D charts. Possible keys and values are:
  • color => (string) 0000ff.
  • display_equation => (bool) display equation on chart.
  • display_rSquared => (bool) display R-squared value on chart.
  • intercept => (float) set intercept.
  • line_style => (string) solid, dot, dash, lgDash, dashDot, lgDashDot, lgDashDotDot, sysDash, sysDot, sysDashDot, sysDashDotDot.
  • type => (string) exp, linear, log, poly, power, movingAvg.
  • type_order => (int) for poly and movingAvg types.

Chart display properties

Key Type Description
axPos array Position of the axis (r, l, t, b). Each value of the array for each position (if a value if null avoids adding it).
formatCode string Number format.
formatDataLabels array Possible keys and values are:
  • rotation => (int).
  • position => (string) center, insideEnd, insideBase, outsideEnd.
haxLabel string Label for the horizontal axis.
haxLabelDisplay bool How to display the label of the horizontal axis. Possible values are: vertical, horizontal, rotated.
hgrid int Horizontal grid. Possible values are:
  • 0 (no grid)
  • 1 (only major grid lines - default)
  • 2 (only minor grid lines)
  • 3 (both major and minor grid lines)
horizontalOffset int Given in emus (1cm = 360000 emus).
majorUnit float Major unit value for bar, col, line, area, radar and scatter charts.
minorUnit float Minor unit value for bar, col, line, area, radar and scatter charts.
orientation array Orientation of the axis, from min to max (minMax) or max to min (maxMin). Each value of the array for each axis (if a value if null avoids adding it).
scalingMax float Scaling max value for bar, col, line, area, radar and scatter charts.
scalingMin float Scaling max value for bar, col, line, area, radar and scatter charts.
stylesTitle array Possible keys and values are:
  • bold => (boolean).
  • color => (string) ffffff, ff0000....
  • font => (string) Arial, Times New Roman....
  • fontSize => (int) 1420, 2000... Size as drawing content (10 to 400000). 1420 as default..
  • italic => (boolean).
vaxLabel string Label for the vertical axis.
vaxLabelDisplay bool How to display the label of the horizontal axis. Possible values are: vertical, horizontal, rotated.
verticalOffset int Given in emus (1cm = 360000 emus).
vgrid int Vertical grid. Possible values are:
  • 0 (no grid)
  • 1 (only major grid lines - default)
  • 2 (only minor grid lines)
  • 3 (both major and minor grid lines)

The available parameters to display legends and data include:

Key Type Description
legendOverlay bool If true the legend may overlay the chart. This option may hinder the legibility of the data so it is only recommended if it is crucial to "save space".
legendPos string The possible values are:
  • b (bottom)
  • l (left)
  • r (right)
  • t (top)
  • none
showCategory bool If true shows the categories inside the chart.
showLegendKey bool If true shows the legend values.
showPercent bool If true shows the percentage values.
showSeries bool If true shows the series values.
showTable bool If true shows the chart data in an associated table.
showValue bool If true shows the chart data values.

Further configuration options for specific chart types are:

Key Type Description
Bar and column charts
gapWidth int Gap width.
groupBar string Different ways to group data. Possible values are: clustered, stacked, percentStacked and standard.
overlap int Overlap.
tickLblPos string Tick label position.
Pie and doughnut charts
explosion int Distance among different sectors.
holeSize int Size of the inner hole (only doughnut charts).
ofPieCharts: pie of pie and bar of pie charts
custSplit array Custom split. Array (zero based) of values that goes in the second chart. For example: array(3,4,7) will pick the fourth, fifth and eighth value.
gapWidth int Distance between the two charts.
secondPieSize int Percentage size of the auxiliary chart.
splitType string How to split the two charts. Possible values are:
  • auto (default split type)
  • cust (custom Split)
  • percent (split by percentage)
  • pos (split by position)
  • val (split by value)
splitPos int Determines the threshold value to split the charts.
subtype string Defines if the auxiliary chart is a pie or bar chart. Possible values are pie or bar.
Line and scatter (XY) charts
smooth mixed If true it smooths the line. '0' forces disabling it
symbol string The possible symbol values are:
  • Line charts: none, dot, plus, square, star, triangle, x, diamond, circle and dash.
  • Scatter charts: dot and line.
symbolSize int The size of the symbol used.
Radar charts
deleteAxisValues bool If true remove the axis values.
style string Defines the radar chart style. Possible values are:
  • radar (lines without dots).
  • marker (lines with dots).
  • filled (filled enclosed area).
Surface charts
wireframe bool If true the surface is shown as a wireframe.

Additional available options for 3D charts:

Key Type Description
perspective int Perspective angle. Angles beyond 25 degrees provoke a big distortion in the 3D chart representation.
rotX int Rotation angle with respect to the vertical axis. Standard values are between 10 and 20 degrees.
rotY int Rotation angle with respect to the horizontal axis. Standard values are between 10 and 20 degrees.

Theme options (Available in Premium licenses):

Key Type Description
chartArea array backgroundColor
gridLines array
  • capType
  • color
  • dashType
  • width
horizontalAxis array
  • textBold
  • textDirection: horizontal, rotate90, rotate270
  • textItalic
  • textSize
  • textUnderline (DrawingML values such as none, sng, dash)
legendArea array
  • backgroundColor
  • textBold
  • textItalic
  • textSize
  • textUnderline
plotArea array backgroundColor
serDataLabels array
  • formatCode
  • position (bottom, center, insideEnd, insideBase, left, outsideEnd, right, top). Each chart type supports specific positions.
  • showCategory
  • showLegendKey
  • showPercent
  • showSeries
  • showValue
serMarkerOptions array
  • borderColor: FF0000...
  • color: FF0000...
  • size: 1 to 73
  • symbol: none, dot, plus, square, star, triangle, x, diamond, circle, dash
serRgbColors array series colors
valueDataLabels array
  • position (bottom, center, insideEnd, insideBase, left, outsideEnd, right, top). Each chart type supports specific positions.
  • showCategory
  • showLegendKey
  • showPercent
  • showSeries
  • showValue
valueRgbColors array values colors
verticalAxis array
  • textBold
  • textDirection (horizontal, rotate90, rotate270)
  • textItalic
  • textSize
  • textUnderline (DrawingML values such as none, sng, dash)
Return values

no data, legends or values.

externalXLSX values are not valid.

Exceptions

Method not available.

Code samples

Example #1

The resulting Word document looks like:

Example #2

The resulting Word document looks like:

Example #3

The resulting Word document looks like:

Example #4

The resulting Word document looks like:

Release notes
  • phpdocx 15.5:
    • serMarkerOptions option.
    • throw Exception if there are no legends or values.
    • extra check to avoid throwing an error when using a not supported theme chart option with combo charts.
  • phpdocx 15.0:
    • box & whisker, funnel, waterfall, histogram, sunburst and treemap chart types.
    • deleteAxisValues and excludeExternalData options.
  • phpdocx 14.0:
    • avoid setting legend styles if the legend doesn't exist.
  • phpdocx 13.5:
    • position and valueDataLabels options.
  • phpdocx 12.5:
    • serDataLabels option.
    • gapWidth and overlap options for bar and column chart types.
    • close ZIP file using the externalXLSX option.
  • phpdocx 12.0:
    • htmlspecialchars applied in name, title, haxLabel and vaxLabel options.
  • phpdocx 11.0:
    • orientation and axPos options.
    • formatCode option in pie and doughnut chart types.
    • formatDataLabels option in pie chart types.
    • add multiple series in scatter chart types.
  • phpdocx 10.0:
    • theme legends (bold, italic, size, underline) and grid lines (cap type, color, dash type, width) options.
    • smooth option can be set as 0.
  • phpdocx 9.5:
    • theme chart options.
    • supported custom legends in scatter chart types.
  • phpdocx 9.0:
    • improved performance: external files moved to an internal PHP structure.
  • phpdocx 8.0:
    • formatCode option.
  • phpdocx 7.5:
    • new data structure to allow repeating name values, trend lines, combo charts.
    • charts can be edited when the DOCX is opened.
    • majorUnit, minorUnit, scalingMax and scalingMin options in bar, col, line, area, radar and scatter chart types.
    • smooth option in line and scatter chart types.
    • styles for titles, show legend keys and series labels, format data labels in col and bar chart types (rotation and position).
    • externalXLSX option.
  • phpdocx 6.0:
    • majorUnit and minorUnit options.