API quick guide
API quick guide
Each new version of phpdocx adds features and methods to the library. After years of continuous development, the whole of the public API methods has reached such a huge number that it demands a certain knowledge to get through it.
This section summarizes the methods according to its practical utility. The complete list of methods can be found on the API documentation page.
The group of elements meant to insert new contents is one of the most extensives. Thanks to these methods it is possible to add:
- bookmarks (addBookmark)
- line and page breaks (addBreak)
- charts (addChart)
- comments (addComment)
- cross-references (addCrossReference)
- dates (addDateAndHour)
- endnotes (addEndnote)
- external files (addExternalFile)
- footnotes (addFootnote)
- form elements (addFormElement)
- headings (addHeading)
- images (addImage)
- links (addLink)
- lists (addList)
- merge fields (addMergeField)
- OLE files (addOLE)
- online videos (addOnlineVideo)
- page numbers (addPageNumber)
- simple fields (addSimpleField)
- shapes (addShape)
- structure document tags (addStructureDocumentTag)
- svg contents (addSVG)
- tables (addTable)
- table of contents (addTableContents)
- table of figures (addTableFigures)
- paragraphs (addText)
- text boxes (addTextBox)
- WordFragments (addWordFragment)
The combined use of these methods, along with the WordFragment flexibility, is the base to add contents in new documents and templates. Each method includes styling options and lots of customizing features.
It is also possible to import contents from other DOCX with the importContents method.
The available methods aimed to work with templates allow to replace placeholders, strings and values in lists and tables, as well as more complex operations like replacing contents as a whole or inserting new elements in any place of the main document whatsoever.
These are the methods for replacing placeholders:
- replaceVariableByText, for text strings
- replacePlaceholderImage, for images
- replaceListVariable, for lists
- replaceTableVariable, for tables
- replaceVariableByWordFragment, to replace placeholders by WordFragments
DOCXPath comes with two replacing and inserting methods that offer even more flexibility: replaceWordContent, that replaces a content by a WordFragment, and insertWordFragment, to insert a WordFragment before or after an existing content.
Other methods to modify values in documents are:
- parseCheckboxes and tickCheckBoxes, ticks or unticks checkboxes
- modifyInputFields, modifies input fields values
- modifyMergeFields, modifies merge fields values
- replaceVariableByExternalFile, replaces a placeholder by a external document (only compatible with MS Word 2007 or newer)
- searchAndColor, searches and colors strings
- searchAndHighlight, searches and highlights strings
- searchAndReplace, searches and replaces strings
- setTemplateSymbol, sets a new template symbol to be used for the templates
Premium licenses include Bulk processing methods to to generate multiple documents from a template with maximum performance.
Besides the styling options found on the content methods, it is also possible to create custom styles with the following ones:
- createCharacterStyle, character styles
- createListStyle, list styles
- createParagraphStyle, paragraph styles
- createTableStyle, table styles
- setDefaultFont, to choose the default font
- setDocumentDefaultStyles to set the global default styles of the document
- getWordStyles, returns the styles used by contents
- embedFont, embeds a font
In case of needing to import custom styles from existing DOCX instead of creating them dinamically, the next three methods can do the task: importListStyle, importStyles and parseStyles.
Basic and Advanced licenses included support for color schemes using addChart. Premium licenses include theme options to customize colors of series and values, add backgrounds, style axis and apply other chart styles.
Lastly, the customizeWordContent method can change existing styles of a document on the fly.
The group of methods that define and customize the layout of a document is divided between the ones that assign global and particular properties (addProperties, docxSettings and modifyDocxSettings), add and modify line numbering (addLineNumbering and setLineNumbering), insert colors and borders (addPageBorders and setBackgroundColor), establish paper type, size and margins (modifyPageLayout) and apply rtl languages (setRTL).
Images can be added to a document with addImage or as a background with the help of addBackgroundImage and watermarkDocx.
On the other hand, shapes are added by calling the addShape method.
The addChart method allows to place graphs by setting multiple parameters to define their properties, styles, generate combo charts, trend lines and many more options.
Basic and Advanced licenses included support for color schemes. Premium licenses include theme options to customize colors of series and values, add backgrounds, style axis and apply other chart styles.
If a DOCX contains a chart that needs some changes, replaceChartData lets to define new values, texts and more.
MathML is a standard format to work with maths equations. MS Word uses OMML as its equations language.
phpdocx includes addMathEquation to convert MathML equations to OMML, and transformOMMLToMathML for the opposite operation. The latter method is the one transformDocAdvHTML calls to transform the contents of a DOCX to HTML.
It is possible to obtain information of a document and its content thanks to several methods:
- indexer, extracts contents, styles, images, people...
- getStatistics, document statistics: pages, words, images...
- getTemplateVariables, gets the template placeholders
- getTemplateVariablesType, gets the template placeholders and their types
- getWordContents, returns text contents of a DOCXPath query
- getDocxPathQueryInfo, information from a DOCXPath query
- getWordFiles, returns file contents from the document
- getWordStyles, returns styles used by contents of a DOCXPath query
Blocks allow to set content groups that can be deleted with deleteBlock, replaced with replaceBlock or cloned, replacing placeholders if needed, with cloneBlock. To clean blocks placeholders, use clearBlocks.
The way to transform HTML and CSS to Word is by using the method embedHtml. For templates, the required method is replaceVariableByHTML. Premium licenses include HTML Extended and CSS Extended, to invoke phpdocx methods with custom HTML tags and add custom styles.
The opposite conversion (DOCX to HTML/CSS) is performed with transformDocAdvHTML.
With the help of the available methods it is possible to convert from one document format to another, from the easier tasks, TXT <=> DOCX with DOCX2TXT and TXT2DOCX to more complex transformations from DOCX to PDF, DOC <=> DOCX and others like RTF and ODT through transformDocument, and DOCX <=> HTML with embedHtml and transformDocAdvHTML.
In order to obtain maximum performance when working with templates, the optimizeTemplate method repairs all placeholders, which skips the whole parsing of XML of contents for each placeholder, spedding up the use of the template methods.
The parseDocx method generates and serializes in-memory DOCX in order to save and reuse them later.
Optimum performance when generating a DOCX can be achieved with zipStream, which doesn't generate documents in the file system but in memory, which returns them directly as a stream.
Existing DOCX documents can be optimized using optimizeDocx.
The different protection levels for documents are all supported: protectDOCX and protectPDF, for protection and encryptDOCX, encryptXLSX, encryptPPTX and encryptPDF for encryption.
It is also possible to sign documents via signDOCX, signXLSX, signPPTX and signPDF.
In case of need of protection just for specific parts of a document, the method addPermProtection allows to do it.
The available methods to work with sections allow to create new ones (addSection), delete them (removeSection) or divide them in separate documents (splitDocx).
It is also feasible to merge several documents while retaining its contents with mergeDocx and mergeDocxAt.
The addHeader and addFooter methods add headers and footers respectively. In case of wanting to import headers and footers from an existing DOCX, it can be done by calling importHeadersAndFooters.
It is viable either to merge PDF documents with mergePdf, to divide them by pages with splitPdf, get information with indexer, or to remove pages using removePagesPdf.
transformDocument, a method included with the conversion plugin, transforms document formats as DOCX, ODT, RTF and others to PDF while keeping styles and contents, as long as the format grants it.
protectPDF and encryptPDF methods protect and encrypt PDF documents. For the task of a digital sign, the signPDF functionality is the right choice.
Finally, watermarkPdf adds texts and images as document watermarks and addBackgroundImage adds an image as background.
To move or clone contents in templates or documents created from scratch, DOCXPath provides two powerful methods: cloneWordContent, which clone contents, and moveWordContent, which move them.
If it is necessary to delete contents, the following methods are ready for use:
- removeWordContent, deletes content with a DOCXPath query
- removeFooters, deletes footers
- removeHeaders, deletes headers
- searchAndRemove, searches and deletes text strings
- removeTemplateVariable, deletes placeholders along with the template symbols
- removeChapter, deletes a whole chapter
- watermarkRemove, erases a watermark
In case of need of inserting some OOXML directly on a document, it is possible to use addWordML or replace a placeholder with replaceVariableByWordML.
Contents can be replaced and removed in XLSX and PPTX documents using the following methods:
- searchAndReplace, replaces contents in XLSX documents
- removeSheet, removes sheets
- splitXlsx, splits XLSX documents
- searchAndReplace, replaces contents in PPTX documents
- removeSlide, removes slides
- splitPptx, splits PPTX documents
Some specific methods are available to track added, replaced or modified contents in a document, even accepting or rejecting changes.
The enableTracking method activates change tracking. After activation, the compatible methods include the corresponding tracking tags. E.g., when inserting paragraphs or deleting contents. The disableTracking method deactivates tracking.
Accepting or rejecting contents and styles tracked in a document require the acceptTracking and rejectTracking methods.
The addPerson method includes the people who participate in the document.
Using addBibliography, addCitation and addSource methods allow generating a full bibliography adding cites with sources, for example to create a research paper.
Besides all the methods above mentioned, phpdocx includes many others like: rawSearchAndReplace, that replaces strings in any XML present in the DOCX, setEncodeUTF8, that turns text encoding to UTF8, setLanguage, that changes default language or addMacroFromDoc to add an existing macro to a DOCX.
Document generation is done with createDocx. This method creates the document in the file system. To create a document and download it afterwards, run createDocxAndDownload. Generation as a stream is available with zipStream.
Strict and transitional variants are supported using the following methods: generateStrictVariant and generateTransitionalVariant.
The API page of each method details for which license(s) is available.