addImage

addImage

TRIAL / ADVANCED / PREMIUM

Inserts an image into the Word document.

Description
public addImage ( array $options )

You may use this method to insert images (jpg, gif, png, bmp or webp) into the Word document.

You may easily control:

  • the embedding and positioning of the image within a complex paragraph.
  • the size (if not explicitely given, phpdocx tries to read the width and height from the image headers).
  • the dpi or dots per inch (by default they are taken from the image headers or set to 96 dpi).
  • the scale (default 100%).
  • the target: main document (default), headers, footers...

Together with some general formatting options.

If one wishes to insert an image within a complex paragraph or a table one should use this method in combination with the addText or the addTable method.

To download images from remote URLs, please check that allow_url_fopen is enabled in the PHP config. If the remote images use HTTPS, please check that PHP is using a valid certification file and the SSL configuration is correct: More information.

Parameters

options

The possible keys and values are:

Key Type Description
src string Path to the image or base64 string or stream to be inserted into the Word document. If a stream is added, use with the streamMode option.
borderColor string hexadecimal color: FF0000.
borderStyle string Possible values are:
  • solid
  • dot
  • dash
  • lgDash
  • dashDot
  • lgDashDot
  • lgDashDotDot
  • sysDash
  • sysDot
  • sysDashDot
  • sysDashDotDot
borderWidth int Given in emus (1cm = 360000 emus).
caption array
  • 'bookmarkName' (string) set a custom bookmark name
  • 'color' (string) text color
  • 'keepNext' (bool) keep in the same page the current paragraph with next paragraph. Default as false
  • 'label' (string) set a custom label (Figure by default)
  • 'lineSpacing' (int) text line spacing
  • 'position' (string) below (default), above
  • 'showLabel' (bool) show default value Figure
  • 'styleName' (string) allow setting a custom style name, useful to generate table of figures based on style names
  • 'sz' (int) text size
  • 'text' (string) text of the caption
descr string Custom descr value.
dpi int Dots per inch.
float string (left, right, center) floating image. It only applies if textWrap is not inline (default value).
height int Image height in pixels.
horizontalOffset int Given in emus (1cm = 360000 emus). Only applies if the image is not floating.
hyperlink string Image link.
imageAlign string Image alignment: right, center...
mime string Forces a mime (image/jpg, image/jpeg, image/png, image/gif, image/bmp, image/webp).
relativeToHorizontal string margin (default), page, column, character, leftMargin, rightMargin, insideMargin, outsideMargin. Not compatible with inline text wrapping.
relativeToVertical string margin, page, line (default), paragraph, topMargin, bottomMargin, insideMargin, outsideMargin. Not compatible with inline text wrapping.
resourceMode bool If true, uses src as image resource (GD). The image resource is transformed to PNG automatically. Default as false.
scaling int % of size: 50, 100.
spacingTop int Spacing top in pixels.
spacingBottom int Spacing bottom in pixels.
spacingLeft int Spacing left in pixels.
spacingRight int Spacing right in pixels.
streamMode bool If true, uses src as stream. PHP 5.4 or greater needed to autodetect the mime type; otherwise set it using mime option. Default as false.
target string document (default value), defaultHeader, firstHeader, evenHeader, defaultFooter, firstFooter, evenFooter, comment, endnote or footnote.
textWrap int Text wrap:
  • 0 (inline)
  • 1 (square)
  • 2 (front)
  • 3 (back)
  • 4 (top and bottom)
verticalAlign string top, center, bottom. To be used with relativeFromVertical.
verticalOffset int Given in emus (1cm = 360000 emus).
width int Image width in pixels.
Exceptions

Image does not exist.

Image format not supported.

getimagesizefromstring not available using streamMode and mime/height/width values are not set.

Code samples

Example #1

The resulting Word document looks like:

Example #2

The resulting Word document looks like:

Release notes
  • phpdocx 15.0:
    • WebP images.
  • phpdocx 13.5:
    • resourceMode option.
    • position and keepNext options for captions.
    • improved autonumeric values when captions use the same style name.
  • phpdocx 12.0:
    • base64 images.
    • default 96 dpi if the image has 0 dpi and no custom dpi is set.
    • bookmarkName option for captions.
    • handle autonumeric id by the style name when adding captions.
    • bookmarks wrap the full content of the caption.
    • descr option.
    • htmlspecialchars applied in descr option.
  • phpdocx 11.0:
    • BMP images.
    • extra check to get the correct image type when working with image streams.
  • phpdocx 10.0:
    • label option for captions.
    • renamed show_label to showLabel for captions.
  • phpdocx 9.0:
    • improved the internal method to get the dpi value from PNG images.
  • phpdocx 7.5:
    • supported stream images.
    • relativeToHorizontal and relativeToVertical options.
  • phpdocx 6.5:
    • hyperlink option.
  • phpdocx 6.0:
    • caption styles.
  • phpdocx 5.5:
    • caption option.