Permalink
504 lines (358 sloc) 18.4 KB

Elements

Below are the matrix of element availability in each container. The column shows the containers while the rows lists the elements.

Num Element Section Header Footer Cell Text Run Footnote
1 Text v v v v v v
2 Text Run v v v v
3 Link v v v v v v
4 Title v ? ? ? ? ?
5 Preserve Text ? v v v*
6 Text Break v v v v v v
7 Page Break v
8 List v v v v
9 Table v v v v
10 Image v v v v v v
11 Watermark
v
12 OLEObject v v v v v v
13 TOC v
14 Footnote v
v** v**
15 Endnote v
v** v**
16 CheckBox v v v v v
17 TextBox v v v v
18 Field v v v v v v
19 Line v v v v v v
20 Chart v     v    

Legend:

  • v. Available.
  • v*. Available only when inside header/footer.
  • v**. Available only when inside section.
  • -. Not available.
  • ?. Should be available.

Texts

Text can be added by using addText and addTextRun method. addText is used for creating simple paragraphs that only contain texts with the same style. addTextRun is used for creating complex paragraphs that contain text with different style (some bold, other italics, etc) or other elements, e.g. images or links. The syntaxes are as follow:

$section->addText($text, [$fontStyle], [$paragraphStyle]);
$textrun = $section->addTextRun([$paragraphStyle]);

For available styling options see :ref:`font-style` and :ref:`paragraph-style`.

If you want to enable track changes on added text you can mark it as INSERTED or DELETED by a specific user at a given time:

$text = $section->addText('Hello World!');
$text->setChanged(\PhpOffice\PhpWord\Element\ChangedElement::TYPE_INSERTED, 'Fred', (new \DateTime()));

Titles

If you want to structure your document or build table of contents, you need titles or headings. To add a title to the document, use the addTitleStyle and addTitle method. If depth is 0, a Title will be inserted, otherwise a Heading1, Heading2, ...

$phpWord->addTitleStyle($depth, [$fontStyle], [$paragraphStyle]);
$section->addTitle($text, [$depth]);

It's necessary to add a title style to your document because otherwise the title won't be detected as a real title.

Links

You can add Hyperlinks to the document by using the function addLink:

$section->addLink($linkSrc, [$linkName], [$fontStyle], [$paragraphStyle]);

Preserve texts

The addPreserveText method is used to add a page number or page count to headers or footers.

$footer->addPreserveText('Page {PAGE} of {NUMPAGES}.');

Breaks

Text breaks

Text breaks are empty new lines. To add text breaks, use the following syntax. All parameters are optional.

$section->addTextBreak([$breakCount], [$fontStyle], [$paragraphStyle]);

Page breaks

There are two ways to insert a page break, using the addPageBreak method or using the pageBreakBefore style of paragraph.

$section->addPageBreak();

Lists

To add a list item use the function addListItem.

Basic usage:

$section->addListItem($text, [$depth], [$fontStyle], [$listStyle], [$paragraphStyle]);

Parameters:

  • $text. Text that appears in the document.
  • $depth. Depth of list item.
  • $fontStyle. See :ref:`font-style`.
  • $listStyle. List style of the current element TYPE_NUMBER, TYPE_ALPHANUM, TYPE_BULLET_FILLED, etc. See list of constants in PHPWord\Style\ListItem.
  • $paragraphStyle. See :ref:`paragraph-style`.

Advanced usage:

You can also create your own numbering style by changing the $listStyle parameter with the name of your numbering style.

$phpWord->addNumberingStyle(
    'multilevel',
    array(
        'type' => 'multilevel',
        'levels' => array(
            array('format' => 'decimal', 'text' => '%1.', 'left' => 360, 'hanging' => 360, 'tabPos' => 360),
            array('format' => 'upperLetter', 'text' => '%2.', 'left' => 720, 'hanging' => 360, 'tabPos' => 720),
        )
    )
);
$section->addListItem('List Item I', 0, null, 'multilevel');
$section->addListItem('List Item I.a', 1, null, 'multilevel');
$section->addListItem('List Item I.b', 1, null, 'multilevel');
$section->addListItem('List Item II', 0, null, 'multilevel');

For available styling options see :ref:`numbering-level-style`.

Tables

To add tables, rows, and cells, use the addTable, addRow, and addCell methods:

$table = $section->addTable([$tableStyle]);
$table->addRow([$height], [$rowStyle]);
$cell = $table->addCell($width, [$cellStyle]);

Table style can be defined with addTableStyle:

$tableStyle = array(
    'borderColor' => '006699',
    'borderSize'  => 6,
    'cellMargin'  => 50
);
$firstRowStyle = array('bgColor' => '66BBFF');
$phpWord->addTableStyle('myTable', $tableStyle, $firstRowStyle);
$table = $section->addTable('myTable');

For available styling options see :ref:`table-style`.

Cell span

You can span a cell on multiple columns by using gridSpan or multiple rows by using vMerge.

$cell = $table->addCell(200);
$cell->getStyle()->setGridSpan(5);

See Sample_09_Tables.php for more code sample.

Images

To add an image, use the addImage method to sections, headers, footers, textruns, or table cells.

$section->addImage($src, [$style]);
  • $src. String path to a local image, URL of a remote image or the image data, as a string. Warning: Do not pass user-generated strings here, as that would allow an attacker to read arbitrary files or perform server-side request forgery by passing file paths or URLs instead of image data.
  • $style. See :ref:`image-style`.

Examples:

$section = $phpWord->addSection();
$section->addImage(
    'mars.jpg',
    array(
        'width'         => 100,
        'height'        => 100,
        'marginTop'     => -1,
        'marginLeft'    => -1,
        'wrappingStyle' => 'behind'
    )
);
$footer = $section->addFooter();
$footer->addImage('http://example.com/image.php');
$textrun = $section->addTextRun();
$textrun->addImage('http://php.net/logo.jpg');
$source = file_get_contents('/path/to/my/images/earth.jpg');
$textrun->addImage($source);

Watermarks

To add a watermark (or page background image), your section needs a header reference. After creating a header, you can use the addWatermark method to add a watermark.

$section = $phpWord->addSection();
$header = $section->addHeader();
$header->addWatermark('resources/_earth.jpg', array('marginTop' => 200, 'marginLeft' => 55));

Objects

You can add OLE embeddings, such as Excel spreadsheets or PowerPoint presentations to the document by using addOLEObject method.

$section->addOLEObject($src, [$style]);

Table of contents

To add a table of contents (TOC), you can use the addTOC method. Your TOC can only be generated if you have add at least one title (See "Titles").

$section->addTOC([$fontStyle], [$tocStyle], [$minDepth], [$maxDepth]);
  • $fontStyle. See font style section.
  • $tocStyle. See available options below.
  • $minDepth. Minimum depth of header to be shown. Default 1.
  • $maxDepth. Maximum depth of header to be shown. Default 9.

Options for $tocStyle:

  • tabLeader. Fill type between the title text and the page number. Use the defined constants in \PhpOffice\PhpWord\Style\TOC.
  • tabPos. The position of the tab where the page number appears in twip.
  • indent. The indent factor of the titles in twip.

Footnotes & endnotes

You can create footnotes with addFootnote and endnotes with addEndnote in texts or textruns, but it's recommended to use textrun to have better layout. You can use addText, addLink, addTextBreak, addImage, addOLEObject on footnotes and endnotes.

On textrun:

$textrun = $section->addTextRun();
$textrun->addText('Lead text.');
$footnote = $textrun->addFootnote();
$footnote->addText('Footnote text can have ');
$footnote->addLink('http://test.com', 'links');
$footnote->addText('.');
$footnote->addTextBreak();
$footnote->addText('And text break.');
$textrun->addText('Trailing text.');
$endnote = $textrun->addEndnote();
$endnote->addText('Endnote put at the end');

On text:

$section->addText('Lead text.');
$footnote = $section->addFootnote();
$footnote->addText('Footnote text.');

By default the footnote reference number will be displayed with decimal number starting from 1. This number uses the FooterReference style which you can redefine with the addFontStyle method. Default value for this style is array('superScript' => true);

The footnote numbering can be controlled by setting the FootnoteProperties on the Section.

$fp = new PhpWord\SimpleType\FootnoteProperties();
//sets the position of the footnote (pageBottom (default), beneathText, sectEnd, docEnd)
$fp->setPos(FootnoteProperties::POSITION_DOC_END);
//set the number format to use (decimal (default), upperRoman, upperLetter, ...)
$fp->setNumFmt(FootnoteProperties::NUMBER_FORMAT_LOWER_ROMAN);
//force starting at other than 1
$fp->setNumStart(2);
//when to restart counting (continuous (default), eachSect, eachPage)
$fp->setNumRestart(FootnoteProperties::RESTART_NUMBER_EACH_PAGE);
//And finaly, set it on the Section
$section->setFootnoteProperties($properties);

Checkboxes

Checkbox elements can be added to sections or table cells by using addCheckBox.

$section->addCheckBox($name, $text, [$fontStyle], [$paragraphStyle])

Textboxes

To be completed

Fields

Currently the following fields are supported:

  • PAGE
  • NUMPAGES
  • DATE
  • XE
  • INDEX
$section->addField($fieldType, [$properties], [$options], [$fieldText])

See \PhpOffice\PhpWord\Element\Field for list of properties and options available for each field type. Options which are not specifically defined can be added. Those must start with a \.

For instance for the INDEX field, you can do the following (See Index Field for list of available options ):

//the $fieldText can be either a simple string
$fieldText = 'The index value';

//or a 'TextRun', to be able to format the text you want in the index
$fieldText = new TextRun();
$fieldText->addText('My ');
$fieldText->addText('bold index', ['bold' => true]);
$fieldText->addText(' entry');
$section->addField('XE', array(), array(), $fieldText);

//this actually adds the index
$section->addField('INDEX', array(), array('\\e "   " \\h "A" \\c "3"'), 'right click to update index');

Line

Line elements can be added to sections by using addLine.

$lineStyle = array('weight' => 1, 'width' => 100, 'height' => 0, 'color' => 635552);
$section->addLine($lineStyle);

Available line style attributes:

  • weight. Line width in twip.
  • color. Defines the color of stroke.
  • dash. Line types: dash, rounddot, squaredot, dashdot, longdash, longdashdot, longdashdotdot.
  • beginArrow. Start type of arrow: block, open, classic, diamond, oval.
  • endArrow. End type of arrow: block, open, classic, diamond, oval.
  • width. Line-object width in pt.
  • height. Line-object height in pt.
  • flip. Flip the line element: true, false.

Chart

Charts can be added using

$categories = array('A', 'B', 'C', 'D', 'E');
$series = array(1, 3, 2, 5, 4);
$chart = $section->addChart('line', $categories, $series, $style);

For available styling options see :ref:`chart-style`.

check out the Sample_32_Chart.php for more options and styling.

Comments

Comments can be added to a document by using addComment. The comment can contain formatted text. Once the comment has been added, it can be linked to any element with setCommentStart.

// first create a comment
$comment= new \PhpOffice\PhpWord\Element\Comment('Authors name', new \DateTime(), 'my_initials');
$comment->addText('Test', array('bold' => true));

// add it to the document
$phpWord->addComment($comment);

$textrun = $section->addTextRun();
$textrun->addText('This ');
$text = $textrun->addText('is');
// link the comment to the text you just created
$text->setCommentStart($comment);

If no end is set for a comment using the setCommentEnd, the comment will be ended automatically at the end of the element it is started on.

Track Changes

Track changes can be set on text elements. There are 2 ways to set the change information on an element. Either by calling the setChangeInfo(), or by setting the TrackChange instance on the element with setTrackChange().

$phpWord = new \PhpOffice\PhpWord\PhpWord();

// New portrait section
$section = $phpWord->addSection();
$textRun = $section->addTextRun();

$text = $textRun->addText('Hello World! Time to ');

$text = $textRun->addText('wake ', array('bold' => true));
$text->setChangeInfo(TrackChange::INSERTED, 'Fred', time() - 1800);

$text = $textRun->addText('up');
$text->setTrackChange(new TrackChange(TrackChange::INSERTED, 'Fred'));

$text = $textRun->addText('go to sleep');
$text->setChangeInfo(TrackChange::DELETED, 'Barney', new \DateTime('@' . (time() - 3600)));