Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,18 @@ file. The format follows
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning
follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- Section columns: `Section::$columns` (`Columns`: `count`, `spaceTwips`,
`separator`, and for unequal columns `widthsTwips` and `spacesTwips`) is
written as `<w:cols>` in the section's `<w:sectPr>` and read back by
`DocxReader`. `DocumentBuilder::columns()` sets the current section's
columns, and `newSection()` takes them too.
- `ColumnBreak` (`<w:br w:type="column"/>`) and the builder's `columnBreak()`:
the text after it starts in the next column. `DocxReader` reads it back,
splitting the paragraph around it as it does for a page break.

## [1.18.0] — 2026-10-28

### Added
Expand Down
12 changes: 10 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -673,6 +673,14 @@ DocumentBuilder::new()
landscape when it is wider than it is tall.
- Without the builder: `new Document($first, followingSections: [$second, …])`;
`Document::sections()` lists them all.
- `columns(new Columns(count: 2, separator: true))` sets the current section's
text columns (`newSection(columns: …)` sets the next one's; a new section is
single-column otherwise). `Columns` takes a `count`, the `spaceTwips`
between columns and a `separator` line; `widthsTwips` (one per column) and
`spacesTwips` (one per gap) make the columns unequal. Written as
`<w:cols>`, read back by `DocxReader`.
- `columnBreak()` (a `ColumnBreak` block) moves the text after it to the top
of the next column; `DocxReader` reads Word's column break back as one.
- Every section but the last ends with its `<w:sectPr>` in the properties
of its last paragraph (a paragraph is added when the section ends in a
table). `DocxReader` reads each section back with its own body, page
Expand Down Expand Up @@ -734,14 +742,14 @@ All elements live under `Dskripchenko\PhpDocx\Element` namespace.
| Element | Type | Notes |
|---|---|---|
| `Document` | root | `{ section: Section, watermarkText: ?string, coreProperties: ?CoreProperties, followingSections: Section[] }` |
| `Section` | container | `{ body, header, footer, pageSetup, firstHeader, firstFooter, evenHeader, evenFooter, start: SectionStart }` |
| `Section` | container | `{ body, header, footer, pageSetup, firstHeader, firstFooter, evenHeader, evenFooter, start: SectionStart, columns: ?Columns }` |
| `Paragraph` | BlockElement | `{ children: InlineElement[], style: ParagraphStyle, headingLevel: ?int, styleId: ?string }` |
| `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, offsetYEmu, position: ?ImagePosition }` |
| `Field` | InlineElement | `{ instruction: string, style: RunStyle }` |
| `LineBreak`, `PageBreak`, `HorizontalRule` | both | marker elements |
| `LineBreak`, `PageBreak`, `ColumnBreak`, `HorizontalRule` | both | marker elements; `ColumnBreak` is `<w:br w:type="column"/>` and has no HTML form |
| `Table` | BlockElement | `{ rows: TableRow[], style, caption, gridColumnsTwips }` |
| `TableRow` | element | `{ cells: TableCell[], isHeader, heightTwips, cantSplit, heightRule }` |
| `TableCell` | element | `{ children: BlockElement[], style: CellStyle }` |
Expand Down
14 changes: 12 additions & 2 deletions docs/de/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -595,6 +595,16 @@ DocumentBuilder::new()
quer, wenn sie breiter als hoch ist.
- Ohne Builder: `new Document($first, followingSections: [$second, …])`;
`Document::sections()` liefert alle.
- `columns(new Columns(count: 2, separator: true))` setzt die Textspalten des
aktuellen Abschnitts (`newSection(columns: …)` die des nächsten; sonst ist
ein neuer Abschnitt einspaltig). `Columns` nimmt die Spaltenzahl `count`,
den Abstand `spaceTwips` und eine Trennlinie `separator`; `widthsTwips`
(eine Breite je Spalte) und `spacesTwips` (ein Abstand je Zwischenraum)
machen die Spalten ungleich breit. Geschrieben als `<w:cols>`, von
`DocxReader` zurückgelesen.
- `columnBreak()` (ein `ColumnBreak`-Block) setzt den folgenden Text an den
Anfang der nächsten Spalte; `DocxReader` liest den Spaltenumbruch von Word
zurück.
- Jeder Abschnitt außer dem letzten endet mit seinem `<w:sectPr>` in den
Eigenschaften seines letzten Absatzes (endet er mit einer Tabelle, wird ein
Absatz angefügt). `DocxReader` liest jeden Abschnitt mit eigenem Inhalt,
Expand Down Expand Up @@ -658,14 +668,14 @@ Alle Elemente leben unter `Dskripchenko\PhpDocx\Element`.
| Element | Typ | Hinweise |
|---|---|---|
| `Document` | root | `{ section: Section, watermarkText: ?string, coreProperties: ?CoreProperties, followingSections: Section[] }` |
| `Section` | container | `{ body, header, footer, pageSetup, firstHeader, firstFooter, evenHeader, evenFooter, start: SectionStart }` |
| `Section` | container | `{ body, header, footer, pageSetup, firstHeader, firstFooter, evenHeader, evenFooter, start: SectionStart, columns: ?Columns }` |
| `Paragraph` | BlockElement | `{ children: InlineElement[], style, headingLevel: ?int, styleId: ?string }` |
| `Run` | InlineElement | `{ text: string, style: RunStyle }` |
| `Hyperlink` | InlineElement | `{ href: ?string, anchor: ?string, children }` |
| `Bookmark` | InlineElement | `{ name: string, children }` |
| `Image` | beides | `{ binary, format, widthEmu, heightEmu, altText, offsetYEmu, position: ?ImagePosition }` |
| `Field` | InlineElement | `{ instruction: string, style: RunStyle }` |
| `LineBreak`, `PageBreak`, `HorizontalRule` | beides | Marker-Elemente |
| `LineBreak`, `PageBreak`, `ColumnBreak`, `HorizontalRule` | beides | Marker-Elemente; `ColumnBreak` ist `<w:br w:type="column"/>`, ohne HTML-Form |
| `Table` | BlockElement | `{ rows: TableRow[], style, caption, gridColumnsTwips }` |
| `TableRow` | element | `{ cells: TableCell[], isHeader, heightTwips, cantSplit, heightRule }` |
| `TableCell` | element | `{ children: BlockElement[], style: CellStyle }` |
Expand Down
12 changes: 10 additions & 2 deletions docs/ru/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -588,6 +588,14 @@ DocumentBuilder::new()
страница альбомная, если она шире, чем выше.
- Без builder'а: `new Document($first, followingSections: [$second, …])`;
`Document::sections()` возвращает все разделы.
- `columns(new Columns(count: 2, separator: true))` задаёт колонки текста
текущего раздела (`newSection(columns: …)` — следующего; иначе новый раздел
одноколоночный). `Columns` принимает число колонок `count`, промежуток
`spaceTwips` и разделительную линию `separator`; `widthsTwips` (по одной
ширине на колонку) и `spacesTwips` (по одному промежутку) делают колонки
неравными. Пишется как `<w:cols>`, `DocxReader` читает обратно.
- `columnBreak()` (блок `ColumnBreak`) переносит следующий за ним текст в
начало следующей колонки; `DocxReader` читает разрыв колонки Word обратно.
- Каждый раздел, кроме последнего, заканчивается своим `<w:sectPr>` в
свойствах последнего абзаца (если раздел заканчивается таблицей,
добавляется абзац). `DocxReader` читает каждый раздел с его содержимым,
Expand Down Expand Up @@ -650,14 +658,14 @@ foreach ($variables as $v) {
| Элемент | Тип | Заметки |
|---|---|---|
| `Document` | root | `{ section: Section, watermarkText: ?string, coreProperties: ?CoreProperties, followingSections: Section[] }` |
| `Section` | container | `{ body, header, footer, pageSetup, firstHeader, firstFooter, evenHeader, evenFooter, start: SectionStart }` |
| `Section` | container | `{ body, header, footer, pageSetup, firstHeader, firstFooter, evenHeader, evenFooter, start: SectionStart, columns: ?Columns }` |
| `Paragraph` | BlockElement | `{ children: InlineElement[], style, headingLevel: ?int, styleId: ?string }` |
| `Run` | InlineElement | `{ text: string, style: RunStyle }` |
| `Hyperlink` | InlineElement | `{ href: ?string, anchor: ?string, children }` |
| `Bookmark` | InlineElement | `{ name: string, children }` |
| `Image` | both | `{ binary, format, widthEmu, heightEmu, altText, offsetYEmu, position: ?ImagePosition }` |
| `Field` | InlineElement | `{ instruction: string, style: RunStyle }` |
| `LineBreak`, `PageBreak`, `HorizontalRule` | both | marker-элементы |
| `LineBreak`, `PageBreak`, `ColumnBreak`, `HorizontalRule` | both | marker-элементы; `ColumnBreak` — `<w:br w:type="column"/>`, в HTML его нет |
| `Table` | BlockElement | `{ rows: TableRow[], style, caption, gridColumnsTwips }` |
| `TableRow` | element | `{ cells: TableCell[], isHeader, heightTwips, cantSplit, heightRule }` |
| `TableCell` | element | `{ children: BlockElement[], style: CellStyle }` |
Expand Down
11 changes: 9 additions & 2 deletions docs/zh/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -573,6 +573,13 @@ DocumentBuilder::new()
- `PageSetup(widthTwips:, heightTwips:)` 可设置任意页面尺寸;宽大于高时为横向。
- 不用构造器:`new Document($first, followingSections: [$second, …])`;
`Document::sections()` 返回所有节。
- `columns(new Columns(count: 2, separator: true))` 设置当前节的分栏
(`newSection(columns: …)` 设置下一节的;否则新节为单栏)。`Columns` 接受栏数
`count`、栏间距 `spaceTwips` 和分隔线 `separator`;`widthsTwips`(每栏一个宽度)
和 `spacesTwips`(每个栏间距一个值)可使各栏不等宽。写为 `<w:cols>`,由
`DocxReader` 读回。
- `columnBreak()`(`ColumnBreak` 块)使其后的文本从下一栏顶部开始;`DocxReader`
会读回 Word 的分栏符。
- 除最后一节外,每节以其 `<w:sectPr>` 结束,写在该节最后一个段落的属性中(若该节以
表格结束,则添加一个段落)。`DocxReader` 逐节读回内容、页面设置、起始方式和页眉;
HTML 序列化器依次输出各节内容,并在每个从新页开始的节之前加分页符。
Expand Down Expand Up @@ -630,14 +637,14 @@ foreach ($variables as $v) {
| 元素 | 类型 | 备注 |
|---|---|---|
| `Document` | root | `{ section: Section, watermarkText: ?string, coreProperties: ?CoreProperties, followingSections: Section[] }` |
| `Section` | container | `{ body, header, footer, pageSetup, firstHeader, firstFooter, evenHeader, evenFooter, start: SectionStart }` |
| `Section` | container | `{ body, header, footer, pageSetup, firstHeader, firstFooter, evenHeader, evenFooter, start: SectionStart, columns: ?Columns }` |
| `Paragraph` | BlockElement | `{ children: InlineElement[], style, headingLevel: ?int, styleId: ?string }` |
| `Run` | InlineElement | `{ text: string, style: RunStyle }` |
| `Hyperlink` | InlineElement | `{ href: ?string, anchor: ?string, children }` |
| `Bookmark` | InlineElement | `{ name: string, children }` |
| `Image` | 两者 | `{ binary, format, widthEmu, heightEmu, altText, offsetYEmu, position: ?ImagePosition }` |
| `Field` | InlineElement | `{ instruction: string, style: RunStyle }` |
| `LineBreak`、`PageBreak`、`HorizontalRule` | 两者 | 标记元素 |
| `LineBreak`、`PageBreak`、`ColumnBreak`、`HorizontalRule` | 两者 | 标记元素;`ColumnBreak` 即 `<w:br w:type="column"/>`,无 HTML 形式 |
| `Table` | BlockElement | `{ rows: TableRow[], style, caption, gridColumnsTwips }` |
| `TableRow` | element | `{ cells: TableCell[], isHeader, heightTwips, cantSplit, heightRule }` |
| `TableCell` | element | `{ children: BlockElement[], style: CellStyle }` |
Expand Down
14 changes: 13 additions & 1 deletion phpstan-baseline.neon
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,12 @@ parameters:
count: 1
path: src/Html/StyleApplier/RunStyleApplier.php

-
message: '#^Instanceof between Dskripchenko\\PhpDocx\\Element\\InlineElement and Dskripchenko\\PhpDocx\\Element\\ColumnBreak will always evaluate to false\.$#'
identifier: instanceof.alwaysFalse
count: 2
path: src/Reader/BodyReader.php

-
message: '#^Instanceof between Dskripchenko\\PhpDocx\\Element\\InlineElement and Dskripchenko\\PhpDocx\\Element\\PageBreak will always evaluate to false\.$#'
identifier: instanceof.alwaysFalse
Expand All @@ -67,7 +73,7 @@ parameters:
path: src/Reader/BodyReader.php

-
message: '#^Method Dskripchenko\\PhpDocx\\Reader\\BodyReader\:\:readRunWithFieldState\(\) should return array\{inlines\: list\<Dskripchenko\\PhpDocx\\Element\\InlineElement\>, state\: string\|null, instr\: string, style\: Dskripchenko\\PhpDocx\\Style\\RunStyle, default\: string, valueSeen\: bool\} but returns array\{inlines\: list\<Dskripchenko\\PhpDocx\\Element\\Field\|Dskripchenko\\PhpDocx\\Element\\Footnote\|Dskripchenko\\PhpDocx\\Element\\Image\|Dskripchenko\\PhpDocx\\Element\\LineBreak\|Dskripchenko\\PhpDocx\\Element\\PageBreak\|Dskripchenko\\PhpDocx\\Element\\Run\>, state\: string\|null, instr\: string, style\: Dskripchenko\\PhpDocx\\Style\\RunStyle, default\: string, valueSeen\: bool\}\.$#'
message: '#^Method Dskripchenko\\PhpDocx\\Reader\\BodyReader\:\:readRunWithFieldState\(\) should return array\{inlines\: list\<Dskripchenko\\PhpDocx\\Element\\InlineElement\>, state\: string\|null, instr\: string, style\: Dskripchenko\\PhpDocx\\Style\\RunStyle, default\: string, valueSeen\: bool\} but returns array\{inlines\: list\<Dskripchenko\\PhpDocx\\Element\\ColumnBreak\|Dskripchenko\\PhpDocx\\Element\\Field\|Dskripchenko\\PhpDocx\\Element\\Footnote\|Dskripchenko\\PhpDocx\\Element\\Image\|Dskripchenko\\PhpDocx\\Element\\LineBreak\|Dskripchenko\\PhpDocx\\Element\\PageBreak\|Dskripchenko\\PhpDocx\\Element\\Run\>, state\: string\|null, instr\: string, style\: Dskripchenko\\PhpDocx\\Style\\RunStyle, default\: string, valueSeen\: bool\}\.$#'
identifier: return.type
count: 1
path: src/Reader/BodyReader.php
Expand All @@ -78,6 +84,12 @@ parameters:
count: 1
path: src/Reader/BodyReader.php

-
message: '#^Result of \|\| is always false\.$#'
identifier: booleanOr.alwaysFalse
count: 1
path: src/Reader/BodyReader.php

-
message: '#^Result of \|\| is always true\.$#'
identifier: booleanOr.alwaysTrue
Expand Down
11 changes: 7 additions & 4 deletions scripts/conformance/generate.php
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@
* writer feature at once: headings, justified paragraphs with spacing and
* indents, tables with header rows, nested ordered lists, multi-part
* headers/footers with page-number fields, bookmarks, hyperlinks, a text
* watermark, a second section (landscape, its own header, a custom page
* size) whose first section ends in a table, and floating pictures (one
* watermark, a second section (landscape, its own header, two unequal
* columns with a separator, a custom page size) whose first section ends in a table, and floating pictures (one
* behind the text on every page from the header, one in the body with text
* wrapped around it). Validated by:
*
Expand All @@ -23,6 +23,7 @@
use Dskripchenko\PhpDocx\Element\ImageFormat;
use Dskripchenko\PhpDocx\Element\ListFormat;
use Dskripchenko\PhpDocx\Style\Alignment;
use Dskripchenko\PhpDocx\Style\Columns;
use Dskripchenko\PhpDocx\Style\HorizontalAnchor;
use Dskripchenko\PhpDocx\Style\ImagePosition;
use Dskripchenko\PhpDocx\Style\ImageWrap;
Expand Down Expand Up @@ -83,10 +84,12 @@
->text('Link: ')
->link('https://github.com/dskripchenko/php-docx', 'repository'))
->table(fn ($t) => $t->row(['A section that ends in a table', 'w:sectPr in an added paragraph']))
->newSection(new PageSetup(orientation: Orientation::Landscape))
->newSection(new PageSetup(orientation: Orientation::Landscape), columns: new Columns(count: 2, separator: true, widthsTwips: [5000, 9418], spacesTwips: [720]))
->header(fn ($h) => $h->paragraph('Landscape section header'))
->heading(2, 'Sections')
->paragraph('A landscape section with a header of its own.')
->paragraph('A landscape section with a header of its own, in two unequal columns with a separator.')
->columnBreak()
->paragraph('After a column break: the second column.')
->newSection(new PageSetup(widthTwips: 8391, heightTwips: 11906), SectionStart::OddPage)
->paragraph('A custom page size, starting on an odd page; it inherits the header.')
->toFile($outDir.'/reference.docx');
Expand Down
9 changes: 9 additions & 0 deletions src/Build/AddsBlockContent.php
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
use Dskripchenko\PhpDocx\Element\BlockElement;
use Dskripchenko\PhpDocx\Element\HorizontalRule;
use Dskripchenko\PhpDocx\Element\Image;
use Dskripchenko\PhpDocx\Element\ColumnBreak;
use Dskripchenko\PhpDocx\Element\PageBreak;
use Dskripchenko\PhpDocx\Element\Paragraph;
use Dskripchenko\PhpDocx\Element\Run;
Expand Down Expand Up @@ -72,6 +73,14 @@ public function pageBreak(): self
return $this;
}

/** Moves the text after it to the next column of the section. */
public function columnBreak(): self
{
$this->blocks[] = new ColumnBreak;

return $this;
}

public function horizontalRule(): self
{
$this->blocks[] = new HorizontalRule;
Expand Down
18 changes: 16 additions & 2 deletions src/Build/DocumentBuilder.php
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
use Dskripchenko\PhpDocx\Document;
use Dskripchenko\PhpDocx\Section;
use Dskripchenko\PhpDocx\Style\CoreProperties;
use Dskripchenko\PhpDocx\Style\Columns;
use Dskripchenko\PhpDocx\Style\PageSetup;
use Dskripchenko\PhpDocx\Style\SectionStart;
use Dskripchenko\PhpDocx\Style\StyleRegistry;
Expand Down Expand Up @@ -69,6 +70,8 @@ final class DocumentBuilder

private SectionStart $start = SectionStart::NextPage;

private ?Columns $columns = null;

/** @var list<Section> sections closed by newSection(), in order */
private array $closedSections = [];

Expand Down Expand Up @@ -209,9 +212,10 @@ public function evenFooter(callable $builderCallback): self
* Ends the current section and starts a new one: the content, headers and
* footers added from here on belong to it. It keeps the page setup unless
* given one, and shows the previous section's headers and footers until it
* sets its own (Word's rule).
* sets its own (Word's rule). Columns are not kept: a new section is
* single-column unless given `$columns`.
*/
public function newSection(?PageSetup $pageSetup = null, SectionStart $start = SectionStart::NextPage): self
public function newSection(?PageSetup $pageSetup = null, SectionStart $start = SectionStart::NextPage, ?Columns $columns = null): self
{
$this->closedSections[] = $this->currentSection();
$this->blocks = [];
Expand All @@ -220,6 +224,15 @@ public function newSection(?PageSetup $pageSetup = null, SectionStart $start = S
$this->evenHeaderBlocks = $this->evenFooterBlocks = [];
$this->pageSetup = $pageSetup ?? $this->pageSetup;
$this->start = $start;
$this->columns = $columns;

return $this;
}

/** Sets the current section's text columns; null for a single column. */
public function columns(?Columns $columns): self
{
$this->columns = $columns;

return $this;
}
Expand Down Expand Up @@ -248,6 +261,7 @@ private function currentSection(): Section
evenHeader: $this->evenHeaderBlocks,
evenFooter: $this->evenFooterBlocks,
start: $this->start,
columns: $this->columns,
);
}

Expand Down
2 changes: 1 addition & 1 deletion src/Element/BlockElement.php
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,6 @@

/**
* A marker interface for the block-level elements of a body, header or footer
* (Paragraph, Table, PageBreak).
* (Paragraph, Table, PageBreak, ColumnBreak).
*/
interface BlockElement {}
13 changes: 13 additions & 0 deletions src/Element/ColumnBreak.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
<?php

declare(strict_types=1);

namespace Dskripchenko\PhpDocx\Element;

/**
* A forced column break (`<w:p><w:r><w:br w:type="column"/></w:r></w:p>`): the
* text after it starts at the top of the next column of the section (see
* `Style\Columns`). In a section with a single column Word treats it as a
* page break.
*/
final readonly class ColumnBreak implements BlockElement {}
Loading
Loading