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.
Text can be added by using addText
and addTextRun
methods. 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]);
$text
. Text to be displayed in the document.$fontStyle
. Seefont-style
.$paragraphStyle
. Seeparagraph-style
.
For available styling options see font-style
and 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()));
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]);
depth
.$fontStyle
. Seefont-style
.$paragraphStyle
. Seeparagraph-style
.$text
. Text to be displayed in the document. This can be string or a PhpOfficePhpWordElementTextRun
It's necessary to add a title style to your document because otherwise the title won't be detected as a real title.
You can add Hyperlinks to the document by using the function addLink:
$section->addLink($linkSrc, [$linkName], [$fontStyle], [$paragraphStyle]);
$linkSrc
. The URL of the link.$linkName
. Placeholder of the URL that appears in the document.$fontStyle
. Seefont-style
.$paragraphStyle
. Seeparagraph-style
.
The addPreserveText
method is used to add a page number or page count to headers or footers.
$footer->addPreserveText('Page {PAGE} of {NUMPAGES}.');
Text breaks are empty new lines. To add text breaks, use the following syntax. All parameters are optional.
$section->addTextBreak([$breakCount], [$fontStyle], [$paragraphStyle]);
$breakCount
. How many lines.$fontStyle
. Seefont-style
.$paragraphStyle
. Seeparagraph-style
.
There are two ways to insert a page break, using the addPageBreak
method or using the pageBreakBefore
style of paragraph.
$section->addPageBreak();
Lists can be added by using addListItem
and addListItemRun
methods. addListItem
is used for creating lists that only contain plain text. addListItemRun
is used for creating complex list items that contains texts with different style (some bold, other italics, etc) or other elements, e.g. images or links. The syntaxes are as follow:
Basic usage:
$section->addListItem($text, [$depth], [$fontStyle], [$listStyle], [$paragraphStyle]);
$listItemRun = $section->addListItemRun([$depth], [$listStyle], [$paragraphStyle])
Parameters:
$text
. Text that appears in the document.$depth
. Depth of list item.$fontStyle
. Seefont-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
. Seeparagraph-style
.
See Sample_14_ListItem.php
for more code sample.
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 numbering-level-style
.
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 table-style
.
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.
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
. Seeimage-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);
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));
You can add OLE embeddings, such as Excel spreadsheets or PowerPoint presentations to the document by using addOLEObject
method.
$section->addOLEObject($src, [$style]);
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.
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 \PhpOffice\PhpWord\ComplexType\FootnoteProperties();
//sets the position of the footnote (pageBottom (default), beneathText, sectEnd, docEnd)
$fp->setPos(\PhpOffice\PhpWord\ComplexType\FootnoteProperties::POSITION_BENEATH_TEXT);
//set the number format to use (decimal (default), upperRoman, upperLetter, ...)
$fp->setNumFmt(\PhpOffice\PhpWord\SimpleType\NumberFormat::LOWER_ROMAN);
//force starting at other than 1
$fp->setNumStart(2);
//when to restart counting (continuous (default), eachSect, eachPage)
$fp->setNumRestart(\PhpOffice\PhpWord\ComplexType\FootnoteProperties::RESTART_NUMBER_EACH_PAGE);
//And finaly, set it on the Section
$section->setFootnoteProperties($fp);
Checkbox elements can be added to sections or table cells by using addCheckBox
.
$section->addCheckBox($name, $text, [$fontStyle], [$paragraphStyle])
$name
. Name of the check box.$text
. Text to be displayed in the document.$fontStyle
. Seefont-style
.$paragraphStyle
. Seeparagraph-style
.
To be completed
Currently the following fields are supported:
- PAGE
- NUMPAGES
- DATE
- XE
- INDEX
$section->addField($fieldType, [$properties], [$options], [$fieldText], [$fontStyle])
$fontStyle
. Seefont-style
.
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 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.
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 chart-style
.
check out the Sample_32_Chart.php for more options and styling.
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 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)));