Usually documents are “enriched” with images that may either have a specific purpose or a purely ornamental one.

Docxpresso allows you to insert images with a high level of customization regarding:

  • Display: they can be inserted inline, floating in a paragrpah, inserted in a table cell, etcetera.
  • Size and format: one can use their default size or scale them at will as well as customize their surrounding borders.

The supported image formats include:

  • JPG (or JPEG),
  • PNG,
  • GIF and
  • BMP.

The core method responsible of inserting an image is the image method which public API is given by:

Signature

public image ($options)

Parameters

  • $options (type: array). This array has the following available keys and values:

    • src (type: string). The path to the image we want to insert or directly a base64 encoded image . This option is, of course, mandatory.
    • title (type: string). The image title, though not mandatory, should be included for accesibility reasons.
    • description (type: string). The image description, though not mandatory, should be included for accesibility reasons.
    • style (type: string). A string of styles in CSS format.

The relevant CSS style type styles that one may apply to an image include (where ‘*’ in this context stands for top, right, bottom or left).

  • Size (if not set the package will automatically compute the dimensions out of the image size and dpi):
    • width: the image width.
    • height: the image height.
  • Borders (individual borders are not supported):
    • border: shorthand for border properties.
    • border-color: sets the border color.
    • border-style: sets the border line style.
    • border-width: sets the border width.
  • Display:
    • float: it can be left, right and also center.
    • margin: specifies all margin widths in one shot.
    • margin-*: specifies one margin at a time.
    • padding: specifies all padding widths in one shot.
    • padding-*: specifies one padding at a time.

Let us start inserting a centered image:

<?php
/**
* This sample script inserts a centered image
 */
require_once 'pathToDocxpresso/CreateDocument.inc';
$doc = new DocxpressoCreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//insert some text
$doc->paragraph(array('text' => 'A centered image:'));
//insert an image
$doc->paragraph()->style('text-align: center;')
		->image(array('src' => 'openoffice.jpg'));
//insert some text
$doc->paragraph(array('text' => 'A final sentence.'));
//include in the render method the path where you want your document to be saved
$doc->render('simple_centered_image' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'simple_centered_image' . $format . '">Download document</a>';

DOWNLOAD:download pdfdownload docdownload docxdownload odtdownload rtf

Let us now work out another simple example where the image is floating to the left of a paragraph with text wrapping around it:

<?php
/**
* This sample script inserts a floating image
 */
require_once 'pathToDocxpresso/CreateDocument.inc';
$doc = new DocxpressoCreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//insert some text
$doc->paragraph(array('text' => 'A paragraph with a floating image:'));
//insert a floating image
$doc->image(array('src' => 'openoffice.jpg', 'style' => 'float: left; margin-right: 0.3cm'));
//insert wrapping text
for ($j = 0; $j < 10; $j++){
    $doc->paragraph(array('text' => 'This text content should be wrapping the image. we repeat it quite a few times so you can see the effect.'));
}
//include in the render method the path where you want your document to be saved
$doc->render('floating_image' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'floating_image' . $format . '">Download document</a>';

DOWNLOAD:download pdfdownload docdownload docxdownload odtdownload rtf

One could also float an image in the middle of a paragraph so there also would be text on top of it. This only requires an slight modification of the above script.

<?php
/**
 * This sample script inserts a floating image in the middle of a paragraph
 */
require_once 'pathToDocxpresso/CreateDocument.inc';
$doc = new DocxpressoCreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//insert some text
$doc->paragraph(array('text' => 'A paragraph with a floating image in the middle:'));
//insert the containing paragraph
$p = $doc->paragraph()->style('text-align: justify;');
//insert floating image in the middle of the paragraph
for ($j = 0; $j < 10; $j++){
    $p->text(array('text' => 'This text content should be wrapping the image. we repeat it quite a few times so you can see the effect. '));
}
$p->image(array('src' => 'openoffice.jpg', 'style' => 'float: right; margin-left: 0.4cm'));
for ($j = 0; $j < 10; $j++){
    $p->text(array('text' => 'This text content should be wrapping the image. we repeat it quite a few times so you can see the effect. '));
}
//include in the render method the path where you want your document to be saved
$doc->render('floating_image_middle_paragraph' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'floating_image_middle_paragraph' . $format . '">Download document</a>';

DOWNLOAD:download pdfdownload docdownload docxdownload odtdownload rtf

Additional formatting

One may also add a border to the image with the standard border CSS property.

Let us now do that and comment on some glitches that show up in the MS Word rendering formats:

<?php
/**
* This sample script inserts a floating image with a black border
 */
require_once 'pathToDocxpresso/CreateDocument.inc';
$doc = new DocxpressoCreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//insert some text
$doc->paragraph(array('text' => 'A paragraph with a floating image:'));
//insert a floating image
$doc->image(array('src' => 'openoffice.jpg', 'style' => 'float: left; margin-right: 0.5cm; border: 1pt solid black'));
//insert wrapping text
for ($j = 0; $j < 10; $j++){
    $doc->paragraph(array('text' => 'This text content should be wrapping the image. we repeat it quite a few times so you can see the effect.'));
}
//include in the render method the path where you want your document to be saved
$doc->render('floating_image' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'floating_image' . $format . '">Download document</a>';

DOWNLOAD:download pdfdownload docdownload docxdownload odtdownload rtf

As you can check there are some current limitations of the rendering of image borders in .docx format as well as regarding margins and paddings.

If Word is your target output format a way to overcome this limitation, besides the obvious workarounds of either preparing your images with all the required options embedded (canvas size and borders) or using tables for layout, is to trigger the legacy option in the render method.