dskripchenko/php-docx

Pure-PHP DOCX (Office Open XML) library: bidirectional HTML ↔ DOCX conversion, fluent programmatic builder, variable detection, round-trip-safe AST. No external dependencies beyond standard PHP extensions.

Read this in other languages: English · Русский · 中文 · Deutsch

Features

HTML → DOCX writer — full set of typical layout elements (paragraphs/headings/tables/lists/images/links/fields), inline-style resolution, custom heading registry.
DOCX → HTML reader — parses arbitrary Word/Pages/LibreOffice documents into a typed AST, then serialises back to HTML with inline styles. Style cascade (docDefaults → named → direct), theme colors, numbering reconstruction, vMerge/gridSpan collapse, watermark detection (VML + DrawingML).
Fluent programmatic builder — DocumentBuilder with closure scopes for nested structures (tables, lists, headers).
Variable detection — MERGEFIELD, SDT content controls, configurable text patterns ({{x}}, ${x}, %x%).
Multi-header/footer — default / first-page / even-pages variants with automatic <w:titlePg/> and <w:evenAndOddHeaders/> plumbing.
Round-trip safe — read DOCX → AST → write DOCX produces a valid document; bytes-level differences are limited to whitespace/ordering.
PHP 8.2+ — readonly value-objects, named arguments, constructor promotion, enums.
Zero composer dependencies.

Out of scope

Tracked changes, comments, embedded charts, OLE objects, footnotes/endnotes, SmartArt, math equations (OMML), form fields, custom XML parts.

Requirements

PHP 8.2+
ext-zip, ext-dom, ext-mbstring

Installation

composer require dskripchenko/php-docx

Quick start

1. HTML → DOCX

use Dskripchenko\PhpDocx\Html\Converter;
use Dskripchenko\PhpDocx\Writer\Word2007Writer;

$html = <<<HTML
<h1>Invoice #42</h1>
<p>Total: <strong>500 USD</strong></p>
<table>
  <tr><th>Item</th><th>Qty</th></tr>
  <tr><td>Widget</td><td>2</td></tr>
</table>
<p>Page <page-number/> of <page-total/></p>
HTML;

$doc = (new Converter)->fromHtml($html);
file_put_contents('invoice.docx', (new Word2007Writer)->write($doc));

2. Programmatic builder

use Dskripchenko\PhpDocx\Build\DocumentBuilder;
use Dskripchenko\PhpDocx\Element\ListFormat;

DocumentBuilder::new()
    ->watermark('DRAFT')
    ->header(fn ($h) => $h->paragraph('Acme Inc.'))
    ->footer(fn ($f) => $f->paragraph(fn ($p) => $p
        ->text('Page ')->pageNumber()->text(' of ')->totalPages()
    ))
    ->heading(1, 'Invoice #42')
    ->paragraph(fn ($p) => $p
        ->text('Customer: ')->bold('Acme Co.')
        ->lineBreak()
        ->text('ID: ')->mergeField('CustomerID')
    )
    ->table(fn ($t) => $t
        ->columns(fn ($c) => $c->widthCm(8), fn ($c) => $c->widthCm(3))
        ->headerRow(['Item', 'Qty'])
        ->row(['Widget', '2'])
    )
    ->orderedList(fn ($l) => $l
        ->format(ListFormat::LowerLetter)
        ->item('Net 30 terms')
        ->item('Free shipping')
    )
    ->toFile('invoice.docx');

3. DOCX → HTML / AST

use Dskripchenko\PhpDocx\Reader\DocxReader;
use Dskripchenko\PhpDocx\Reader\DocxPackageReader;
use Dskripchenko\PhpDocx\Reader\VariableDetector;
use Dskripchenko\PhpDocx\Html\Serializer;

$bytes = file_get_contents('input.docx');

$document = (new DocxReader)->read($bytes);

$pkg = (new DocxPackageReader)->read($bytes);
$variables = (new VariableDetector)->detect($pkg);

$imported = (new Serializer)->serialize($document, $variables);

echo $imported->bodyHtml;
echo $imported->headerHtml;
echo $imported->footerHtml;
echo $imported->watermarkText;
$imported->pageSettings;
$imported->variables;
$imported->media;

HTML → DOCX

Input HTML must use inline styles only (no <style> blocks). Use a CSS-inliner upstream if needed.

Supported elements

Category	HTML tags
Text blocks	`<p>`, `<h1..h6>`, `<div>`, `<pre>`, `<blockquote>`
Inline marks	`<strong>/<b>`, `<em>/<i>`, `<u>`, `<s>/<del>`, `<sup>`, `<sub>`, `<mark>`
Code/teletype	`<code>`, `<kbd>`, `<samp>`, `<var>`, `<cite>`, `<dfn>`, `<q>`, `<small>`
Links	`<a href>` external, `<a href="#anchor">` internal, `<a id>` bookmarks
Images	`<img src="data:image/...;base64,...">`
Tables	`<table>`, `<thead>/<tbody>`, `<tr>`, `<th>/<td>`, `<colgroup>/<col>`, `<caption>`, `colspan`, `rowspan`
Lists	`<ul>`, `<ol type="a/A/i/I" start="N">`, `<li value="N">`, `<dl>/<dt>/<dd>`
Custom tags	`<page-number/>`, `<page-total/>`, `<current-date format="...">`, `<page-break>`
Layout	`<hr>`, `<br>`, `<figure>/<figcaption>`

Inline styles

The converter understands style="…" properties:

Run-level: font-family, font-size, font-weight, font-style, text-decoration, color, background-color
Paragraph-level: text-align, margin, text-indent, line-height, border, padding
Table-level: width, border, border-collapse
Cell-level: width, padding, border, vertical-align, background-color

Custom tags

<p>Page <page-number/> of <page-total/></p>
<p>Generated on <current-date format="dd.MM.yyyy"/></p>

These become OOXML field codes (<w:fldSimple w:instr="PAGE">).

Custom heading styles

use Dskripchenko\PhpDocx\Style\StyleRegistry;
use Dskripchenko\PhpDocx\Style\RunStyle;
use Dskripchenko\PhpDocx\Style\ParagraphStyle;
use Dskripchenko\PhpDocx\Style\Alignment;

$styles = (new StyleRegistry)
    ->heading(1, new RunStyle(sizeHalfPoints: 44, bold: true), new ParagraphStyle(alignment: Alignment::Center))
    ->heading(2, new RunStyle(sizeHalfPoints: 28, bold: true));

$writer = new Word2007Writer($styles);

Programmatic builder API

The Build namespace provides a fluent API for assembling DOCX documents block by block, finalising to the same immutable AST that the HTML pipeline produces.

DocumentBuilder

Entry point. Accumulates body, header/footer, watermark, page setup.

use Dskripchenko\PhpDocx\Build\DocumentBuilder;
use Dskripchenko\PhpDocx\Style\PageSetup;
use Dskripchenko\PhpDocx\Style\PaperSize;
use Dskripchenko\PhpDocx\Style\Orientation;

$doc = DocumentBuilder::new()
    ->pageSetup(new PageSetup(
        paperSize: PaperSize::A4,
        orientation: Orientation::Portrait,
    ))
    ->watermark('CONFIDENTIAL')
    ->heading(1, 'Report')
    ->paragraph('Body')
    ->build();           // → Document AST

$bytes = DocumentBuilder::new()->paragraph('Hi')->toBytes();
$count = DocumentBuilder::new()->paragraph('Hi')->toFile('out.docx');

ParagraphBuilder

Inside ->paragraph(fn ($p) => …):

->paragraph(fn ($p) => $p
    ->text('plain ')
    ->bold('bold ')
    ->italic('italic ')
    ->underline('under ')
    ->strike('strike ')
    ->sup('super')->text('script ')
    ->sub('sub')->text('script ')
    ->styled('red', fn ($s) => $s->color('ff0000')->bold())
    ->lineBreak()
    ->link('https://example.com', 'website')
    ->internalLink('section1', 'go to section 1')
    ->bookmark('anchor1', 'anchor target')
    ->pageNumber()
    ->totalPages()
    ->currentDate('yyyy-MM-dd')
    ->mergeField('CustomerName')
    ->image($img)
    ->imageFromFile('/path/to/logo.png', widthPx: 150, altText: 'Logo')
)

Paragraph-level styling:

->paragraph(fn ($p) => $p
    ->alignCenter()           // or alignRight()/alignJustify()
    ->indentMm(left: 20, firstLine: 10)
    ->spacingPt(before: 6, after: 12)
    ->text('Indented & spaced')
)

TableBuilder

use Dskripchenko\PhpDocx\Build\{TableBuilder, TableRowBuilder, TableCellBuilder, ColumnBuilder};

->table(fn (TableBuilder $t) => $t
    ->caption('Sales 2026')
    ->column(fn (ColumnBuilder $c) => $c->widthCm(6))
    ->column(fn (ColumnBuilder $c) => $c->widthCm(3))
    ->widthPercent(100)
    ->alignCenter()
    ->cellMarginsMm(2)
    ->headerRow(['Item', 'Price'])
    ->row(['Apple', '10 USD'])
    ->row(fn (TableRowBuilder $r) => $r
        ->cell('Banana')
        ->cell(fn (TableCellBuilder $c) => $c
            ->backgroundColor('ffeb3b')
            ->valignCenter()
            ->paragraph(fn ($p) => $p->bold('20 USD'))
        )
    )
)

Spans and merges:

->row(fn ($r) => $r
    ->cell(fn ($c) => $c->gridSpan(2)->paragraph('Wide header'))
)
->row(fn ($r) => $r
    ->cell(fn ($c) => $c->rowSpan(2)->paragraph('Tall'))
    ->cell('right')
)

ListBuilder

use Dskripchenko\PhpDocx\Build\ListBuilder;
use Dskripchenko\PhpDocx\Element\ListFormat;

->bulletList(fn (ListBuilder $l) => $l
    ->item('First')
    ->item('Second', fn ($n) => $n
        ->item('Nested A')
        ->item('Nested B')
    )
)

->orderedList(fn (ListBuilder $l) => $l
    ->format(ListFormat::LowerLetter)   // a, b, c
    ->startAt(3)
    ->item('item starts at "c"')
)

RunStyleBuilder

Used inside ->styled(text, fn (RunStyleBuilder) => …) or standalone via RunStyleBuilder::new()->…->build().

RunStyleBuilder::new()
    ->bold()
    ->italic()
    ->underline()
    ->strike()
    ->color('ff0000')
    ->backgroundColor('eeeeee')
    ->highlight('yellow')
    ->fontFamily('Arial')
    ->fontSizePt(14.5)
    ->build();

Length helpers

Convert common units to OOXML twips (1 twip = 1/20 pt). Used wherever a twip int is expected.

use Dskripchenko\PhpDocx\Build\Length;

Length::pt(12);     // 240
Length::mm(20);     // 1134
Length::cm(2.5);    // 1417
Length::inch(0.5);  // 720
Length::px(100);    // 1500  (CSS px @ 96 DPI)

Most builders expose unit-aware shortcuts:

TableBuilder: widthPt/widthMm/widthCm/widthInches, cellMarginsMm/cellMarginsPt
TableCellBuilder: widthPt/Mm/Cm/Inches, paddingMm/Pt/Cm/Inches
ColumnBuilder: widthPt/Mm/Cm/Inches/Px
ParagraphBuilder: indentMm/Cm/Pt/Inches, spacingPt/Mm
RunStyleBuilder: fontSizePt

DOCX → HTML (Reader)

High-level: DocxReader

use Dskripchenko\PhpDocx\Reader\DocxReader;

$document = (new DocxReader)->read(file_get_contents('input.docx'));
// → Document (AST)

This runs the full pipeline: package unpack → styles resolve → body/header/footer parsing → vMerge/list reconstruction → image extraction → watermark detection → page setup.

Low-level: DocxPackageReader

If you need the raw OOXML parts:

use Dskripchenko\PhpDocx\Reader\DocxPackageReader;

$pkg = (new DocxPackageReader)->read($bytes);

$pkg->documentXml;           // \DOMDocument
$pkg->stylesXml;             // ?\DOMDocument
$pkg->numberingXml;          // ?\DOMDocument
$pkg->themeXml;              // ?\DOMDocument
$pkg->settingsXml;           // ?\DOMDocument
$pkg->headers;               // array<path, \DOMDocument>
$pkg->footers;               // array<path, \DOMDocument>
$pkg->media;                 // array<path, bytes>
$pkg->documentRelationships();  // list<Relationship>
$pkg->resolveDocumentRel('rId7');  // Relationship

Serializer: AST → HTML

use Dskripchenko\PhpDocx\Html\Serializer;

$imported = (new Serializer)->serialize($document, $variables);

// ImportedDocument:
$imported->bodyHtml;         // string
$imported->headerHtml;       // ?string
$imported->footerHtml;       // ?string
$imported->watermarkText;    // ?string
$imported->pageSettings;     // PageSetup
$imported->variables;        // list<DetectedVariable>
$imported->media;            // array<filename, bytes>

HTML output uses inline styles only — re-loadable into the same library via Html\Converter::fromHtml($imported->bodyHtml).

Headers, footers & watermarks

Three header/footer types are supported per section: default, first (title page), even (even pages). Word automatically renders the right one based on page number.

DocumentBuilder::new()
    ->header(fn ($h) => $h->paragraph('Default header'))
    ->firstHeader(fn ($h) => $h->paragraph('Cover page'))
    ->evenHeader(fn ($h) => $h->paragraph(fn ($p) => $p
        ->text('Page ')->pageNumber()
    ))
    ->footer(fn ($f) => $f->paragraph('© 2026 Acme'))
    ->firstFooter(fn ($f) => $f->paragraph('Confidential'))
    ->evenFooter(fn ($f) => $f->paragraph('Even footer'))
    ->paragraph('Body')
    ->toFile('with-headers.docx');

The writer automatically:

emits <w:titlePg/> in sectPr when first-page header/footer is set
emits word/settings.xml with <w:evenAndOddHeaders/> when even header/footer is set

Watermark

DocumentBuilder::new()
    ->watermark('DRAFT')
    ->paragraph('Body')
    ->toFile('with-watermark.docx');

Renders as a 45°-rotated VML text shape on every page.

Variable detection

Scans an imported DOCX for three kinds of variables:

MERGEFIELD — Word mail-merge native, both simple <w:fldSimple> and complex <w:fldChar> form.
SDT content controls — <w:sdt> with <w:tag w:val="...">.
Text patterns — configurable regexes (defaults: {{name}}, ${name}, %name%).

use Dskripchenko\PhpDocx\Reader\VariableDetector;

$pkg = (new DocxPackageReader)->read($bytes);
$detector = new VariableDetector;     // defaults
// Or with custom regexes:
$detector = new VariableDetector(['/\[\[(\w+)\]\]/']);

$variables = $detector->detect($pkg);
foreach ($variables as $v) {
    echo "{$v->name} ({$v->source->value})";
    echo " placeholder='{$v->placeholder}'";
    echo " sample='{$v->sampleValue}'\n";
}

Detection runs across body + all headers + all footers. Results are deduplicated by (source, name).

Length helpers

See Length helpers above. Conversion table:

Unit	Twips	Pt	Notes
1 twip	1	0.05	OOXML native
1 pt	20	1	typography
1 mm	~57	2.83	metric
1 cm	~567	28.35	metric
1 inch	1440	72	imperial
1 px	15	0.75	CSS @ 96 DPI

AST overview

All elements live under Dskripchenko\PhpDocx\Element namespace.

Element	Type	Notes
`Document`	root	`{ section: Section, watermarkText: ?string }`
`Section`	container	`{ body, header, footer, pageSetup, firstHeader, firstFooter, evenHeader, evenFooter }`
`Paragraph`	BlockElement	`{ children: InlineElement[], style: ParagraphStyle, headingLevel: ?int }`
`Run`	InlineElement	`{ text: string, style: RunStyle }`
`Hyperlink`	InlineElement	`{ href: ?string, anchor: ?string, children: InlineElement[] }`
`Bookmark`	InlineElement	`{ name: string, children: InlineElement[] }`
`Image`	both	`{ binary, format, widthEmu, heightEmu, altText }`
`Field`	InlineElement	`{ instruction: string, style: RunStyle }`
`LineBreak`, `PageBreak`, `HorizontalRule`	both	marker elements
`Table`	BlockElement	`{ rows: TableRow[], style, caption, gridColumnsTwips }`
`TableRow`	element	`{ cells: TableCell[], isHeader, heightTwips }`
`TableCell`	element	`{ children: BlockElement[], style: CellStyle }`
`ListNode`	BlockElement	`{ items: ListItem[], ordered, format, startAt }`
`ListItem`	element	`{ children: InlineElement[], nestedList: ?ListNode }`

Styles live under Dskripchenko\PhpDocx\Style:

RunStyle — font, weight, italic, color, size, highlight, …
ParagraphStyle — alignment, indents, spacing, borders
CellStyle — width, padding, borders, valign, gridSpan, rowSpan
TableStyle — width, borders, alignment, cell margins, layout
PageSetup, PaperSize, Orientation, Alignment, VerticalAlign, BorderStyle, Border, BorderSet

Round-trip

$bytes1 = file_get_contents('original.docx');
$doc = (new DocxReader)->read($bytes1);
$bytes2 = (new Word2007Writer)->write($doc);
file_put_contents('roundtrip.docx', $bytes2);

The library targets semantic round-trip safety, not byte equality — content, structure and styling survive, but XML ordering and whitespace may differ.

In-scope round-trip features:

Paragraphs/headings with all run formatting
Tables with vMerge/gridSpan reconstruction
Lists (bullet/decimal/letter/roman) with arbitrary nesting
Images with EMU sizes and alt text
Hyperlinks (external + internal anchors) and bookmarks
Headers/footers (default/first/even) and watermarks
Field codes (PAGE, NUMPAGES, DATE, MERGEFIELD)
Page setup (size, orientation, margins)

Out-of-scope features are silently dropped (footnotes, comments, equations, etc.).

Architecture

HTML (inline styles)
       │
       ▼  Html\Converter
   Document (AST)  ◀──── DocumentBuilder (programmatic)
       │
       ▼  Writer\Word2007Writer
   DOCX bytes
       ▲
       │  Reader\DocxReader
   Document (AST)
       │
       ▼  Html\Serializer
   ImportedDocument (bodyHtml, headerHtml, footerHtml, variables, media)

The same Document AST is shared by HTML conversion, programmatic construction and DOCX reading — every entry/exit point operates on typed value-objects.

Development

composer install
composer test       # phpunit suite (~340 tests)
composer stan       # phpstan level 8

License

MIT — see LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 37 Commits
docs		docs
src		src
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
composer.json		composer.json
phpstan.neon		phpstan.neon
phpunit.xml		phpunit.xml

Folders and files

Latest commit

History

Repository files navigation

dskripchenko/php-docx

Table of contents

Features

Out of scope

Requirements

Installation

Quick start

1. HTML → DOCX

2. Programmatic builder

3. DOCX → HTML / AST

HTML → DOCX

Supported elements

Inline styles

Custom tags

Custom heading styles

Programmatic builder API

DocumentBuilder

ParagraphBuilder

TableBuilder

ListBuilder

RunStyleBuilder

Length helpers

DOCX → HTML (Reader)

High-level: DocxReader

Low-level: DocxPackageReader

Serializer: AST → HTML

Headers, footers & watermarks

Watermark

Variable detection

Length helpers

AST overview

Round-trip

Architecture

Development

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages