Practical phpdocx

Pictures and images

Introduction

Adding images to new documents is as easy as inserting texts, either in the body of the document, headers, footers, comments, endnotes, footnotes or background.

If you use a template, you can both replace an existing image and replace a text placeholder for an image.

Valid format files for working with images are JPG, PNG, GIF, BMP and SVG. Base64 images can also be added.

Adding images

The method for adding new images is addImage:

$image = array(
    'src' => 'image.png',
    'textWrap' => 1,
    'spacingRight' => 15,
    'float' => 'left',
);

$docx->addImage($image);

The method for adding SVG contents is addSVG:

$docx->addSVG($svgContent);

Backgrounds

If instead of inserting an image in the document you want to place it as document background, use addBackgroundImage:

public function addBackgroundImage($src)

You have to indicate the path of the image in it. For example:

$docx->addBackgroundImage('image.jpg');

Replacing images in a template

phpdocx includes two methods to replace images in templates.

replacePlaceholderImage method

public function replacePlaceholderImage($variable, $src, $options = array())

replacePlaceholderImage replaces an image present in a document for the new one. The available parameters are:

$variable: Name of the placeholder.
$scr: Path to the new image.
The third parameter is optional. It's an array which can have these keys:
- firstMatch: it just replaces the first placeholder, with the name of the placeholder.
- target: target of the variable like document, header, footer, comment, endnote or footnote.
- dpi: dots per inch.
- width: the value in cm (float) or 'auto' (use image size), 0 to not change the previous size
- height: the value in cm (float) or 'auto' (use image size), 0 to not change the previous size
- mime: forces a mime type (image/jpg, image/jpeg, image/png, image/gif)
- streamMode: if true, uses src path as stream. PHP 5.4 or greater needed to autodetect the mime type; otherwise set it using mime option. Default is false
- replaceShapes: if true, replace images in shapes too. Default is false

To make this replacement you have to define an image or images attribute to replace.

In order to do this, just right click on it, open the image properties and search for the field alternate text (this name may vary in each version of MS Word). Type in this field the name of the placeholder, for example: $IMAGE$.

For example, to replace an image in the header:

$image = array(
    'height' => 3,
    'width' => 3,
    'target' => 'header',
);

$docx->replacePlaceholderImage('IMAGE','logo.jpg', $image);

replaceVariableByWordFragment method

The second method for adding images in a template replaces a placeholder with a WordFragment. replaceVariableByWordFragment is the method to use:

public function replaceVariableByWordFragment($variables, $options = array())

For example, to replace the placeholder IMAGE with a picture, after creating the new image instantiating the class WordFragment type this code:

$image = new WordFragment($docx, 'document');
$image->addImage(array('src' => 'image.png' , 'scaling' => 50, 'float' => 'right', 'textWrap' => 1));

And replace it by calling replaceVariableByWordFragment:

$docx->replaceVariableByWordFragment(array('IMAGE' => $image), array('type' => 'block'));

Tips and tricks

To add a background color instead of a background image, use setBackgroundColor:

public function setBackgroundColor($color)

The value of $color is hexadecimal, for example:

$docx->setBackgroundColor('FFFFCC');

With the preset settings of Word the background images won't appear in the printed document. Add it as a watermark using watermarkDocx:

public function watermarkDocx($source, $target, $type = 'text', $options = array())

This method is available for the Advanced and Premium licenses.

Replacing more than an image in a template

Due to Word internal functioning, to replace two or more images in a template with the method replacePlaceholderImage, it's necessary to insert a different image for each one you want to replace. Otherwise just the last image will be replaced.

This happens because Word reuses the same picture in the file DOCX, which causes a wrong replacement when there are more than one substitution in the template.

This won't happen working with the method replaceVariableByWordFragment.

Next - Graphic charts