replacePlaceholderImage

WORD CONTENTS
LAYOUT & SETTINGS
TEMPLATES
FORMAT CONVERSION
DOCXPATH
DOCXUTILITIES
DOCXPATHUTILITIES
PDFUTILITIES
DOCXCUSTOMIZER
PERFORMANCE
BULK PROCESSING
TRACKING
CRYPTOPHPDOCX
DIGITAL SIGNATURE
ARTIFICIAL INTELLIGENCE
XLSXUTILITIES
PPTXUTILITIES
BLOCKCHAIN
VARIANT

replacePlaceholderImage

TRIAL / ADVANCED / PREMIUM

Replaces a placeholder within an image by a new image.

Description
public replacePlaceholderImage (string $variable, string $src [, array $options])

This method allows to replace a placeholder image that may be fully formatted in Word (border, shadows, effects...) by an image of our choice.

If one does not set the width, height and/or dpi options the method will use the corresponding data taken from the original placeholder image.

The placeholder image should be tagged using the alternate text option of the Word interface (this may depend on the Word version).

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

variable

The name of the variable that identifies the placeholder image.

src

The 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.

options

The possible keys and values of this array are:

Key Type Description
firstMatch boolean If the variable appears more than once within the Word document and firstMatch is set to true, phpdocx will only replace the first occurrence of the variable within the Word document.
replaceShapes bool If true, replace images in shapes too. Default as false.
target string Possible values are: document, header, footer, footnote, endnote or comment.
width mixed

The value in:

  • cm (float)
  • 'auto' (string) (use image size)
  • 0 (int) to not change the previous size
  • 'fit' (string) fit the image in the placeholder image size
height mixed

The value in:

  • cm (float)
  • 'auto' (string) (use image size)
  • 0 (int) to not change the previous size
  • 'fit' (string) fit the image in the placeholder image size
dpi int Dots per inch. This parameter is only taken into account if width or height are set to auto.
mime string Forces a mime (image/jpg, image/jpeg, image/png, image/gif, image/bmp, image/webp).
resourceMode bool If true, uses src as image resource (GD). The image resource is transformed to PNG automatically. Default as false.
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 is false.
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

Release notes
  • phpdocx 16.0:
    • fit value to set width and height sizes.
    • extra check to avoid duplicated relationships with headers and footers that include images embedded in shapes.
    • replaced rand with mt_rand in the class.
  • phpdocx 15.0:
    • WebP images.
  • phpdocx 13.5:
    • resourceMode option.
  • phpdocx 13.0:
    • optimized working with documents with many images.
  • phpdocx 12.5:
    • set a new random ID to the replaced image.
  • phpdocx 12.0:
    • base64 images.
    • default 96 dpi if the image has 0 dpi and no custom dpi is set.
    • replaceShapes option.
  • phpdocx 11.0:
    • BMP images.
    • extra check to get the correct image type when working with image streams.
  • phpdocx 9.0:
    • improved the internal method to get the dpi value from PNG images.
  • phpdocx 7.5:
    • supported stream images.