Controlling Newlines Within PHPWord Text Runs
Working with document generation in PHPWord often involves a specific mental model that trips up many developers: the distinction between section-level operations and element-level operations. You might encounter a scenario where you have populated a paragraph or text run with content, only to realize you need an explicit line break within that specific block of text. The common instinct is to call $section->addTextBreak(2), but if your goal is strictly internal to a text run, this approach fails because it appends the break to the section immediately following the current element. Conversely, attempting to invoke $textrun->addTextBreak(2) results in a fatal error because ElementInterface (which Element implements) does not expose an addTextBreak method directly.
To achieve a new line within a text run, you must manipulate the underlying XML structure or utilize specific methods available on the paragraph element itself. In PHPWord's architecture, a "text run" is typically represented by a SimpleElementInterface. The most robust way to insert a line break inside a continuous text flow is to create a new paragraph element with zero height and no formatting, effectively acting as a hard newline token within the logical flow of your document.
Here is how you can structure this programmatically:
use PhpOffice\PhpWord\Element\TextRun;
use PhpOffice\PhpWord\Style\Paragraph;
// Create a text run containing initial content
$section->addTextRun(function (TextRun $run) {
// Add your first line of text
$run->addText('This is the first line of text. ');
// To force a new line within the same logical block,
// you cannot use addTextBreak on the section or the run directly.
// Instead, you must add a paragraph element with specific properties
// that mimic a manual line break.
// Method 1: Add a paragraph with zero height (Hard Newline)
$run->addParagraph('This is the second line.', [
'spaceBefore' => 0,
'spaceAfter' => 0,
'alignment' => \PhpOffice\PhpWord\Element\TextRun::ALIGN_LEFT,
// Ensure the paragraph doesn't add extra vertical space that breaks flow
]);
});
Alternatively, if you are dealing with a SimpleElementInterface directly and need to insert a break without creating a full paragraph object overhead, you can manipulate the XML element properties. However, PHPWord generally abstracts this away by requiring the use of addParagraph. The key trade-off here is semantic: adding a new paragraph element creates a distinct block in the DOM tree, whereas addTextBreak on the section adds a non-printing break to the section layout.
When designing complex documents, relying solely on text runs can lead to formatting inconsistencies if you are not careful with spacing. If you need a soft return (a space followed by a newline without extra vertical padding), simply appending a space and using the paragraph method described above works well. If you require a hard break that respects specific margins or indentation, the paragraph approach offers more control than trying to hack the section's break counter.
Be aware that addTextBreak is designed for section-level pagination control. It tells the renderer "move to the next page" or "insert vertical space between sections," not "start a new line inside this paragraph." Confusing these two concepts leads to the exact error observed in your scenario. By using addParagraph with minimal spacing properties, you maintain the logical flow within your text run while achieving the visual result of a new line. This pattern ensures compatibility across different export formats (HTML, PDF) that PHPWord supports, as it adheres to the standard document structure expectations.