Paragraphs & Inline Content¶

Paragraph represents one PHP-owned ODT paragraph. It combines inline text, text styles, line breaks, tabs, hyperlinks, paragraph styling, and embedded structured elements.

use OdtTemplateEngine\Elements\Paragraph;

$paragraph = (new Paragraph())
    ->addText('Invoice ', ['bold' => true])
    ->addText('#2026-001')
    ->addLineBreak()
    ->addText('Paid', ['color' => '#008000']);

Unless noted otherwise, authoring methods are fluent and return the same Paragraph.

Construction and paragraph styles¶

public function __construct(
    ?string $paragraphStyle = null,
    array $paragraphStyleOptions = []
)

$paragraphStyle references a named paragraph style. When style options are supplied without a name, the engine generates a paragraph style name for the definition.

setParagraphStyle()¶

Recommended

public function setParagraphStyle(string $styleName): self

References the named paragraph style. Supplying a style name without style options is a style reference, not a request to redefine that Writer style.

setParagraphStyleOptions()¶

Recommended

public function setParagraphStyleOptions(array $options): self

Replaces the paragraph's current option array. It does not merge with the previous array.

If no paragraph style name exists, a generated name is assigned.

Paragraph option contract¶

The following friendly keys are mapped by the current paragraph style mapper:

StyleOptionSplitter recognizes align as a convenience alias for text-align and weight as a convenience alias for font-weight. setParagraphStyleOptions() stores the supplied array immediately, but the paragraph's style-requirement materialization subsequently passes it through that splitter, so these two aliases are supported here as well. This is specific to the structured paragraph pipeline and must not be assumed for unrelated style APIs.

Native-prefixed keys remain an Advanced compatibility escape hatch and should not replace the friendly API in normal application code.

Text¶

addText()¶

Recommended

public function addText(string $text, array $style = []): self

Appends text and optionally defines an inline text style.

Text option contract¶

Native fo: and style: keys are passed through by the mapper as an Advanced compatibility escape hatch.

The alias weight is normalized to font-weight only at APIs that use StyleOptionSplitter; Paragraph::addText() itself does not run that normalization.

Line breaks and tabs¶

public function addLineBreak(int $count = 1): self
public function addTab(): self

addLineBreak() appends $count ODT line-break elements. A zero or negative count adds none. addTab() appends one ODT tab.

Tab definitions and tabbed text¶

Advanced

public function addTabStopDefinition(
    float $position,
    string $alignment = 'left'
): self

public function addTabStop(
    float $position,
    string $alignment = 'left',
    ?string $text = null,
    array $style = []
): self

addTabStopDefinition() adds a paragraph tab-stop definition; the numeric position is serialized in centimeters.

addTabStop() appends a tab to the paragraph's inline content and may append text after it. Despite its name, it does not add the paragraph tab-stop definition itself. Define the tab position separately when the layout depends on it.

The convenience methods addTabularLines(), addKeyValueLine(), and addTabsWithTexts() remain supported Advanced helpers for tab-based layouts. They use the same paragraph tab-stop and inline text mechanisms.

Hyperlinks¶

addHyperlink()¶

Recommended for unstyled hyperlinks · Known 1.0 limitation for styled hyperlinks

public function addHyperlink(
    string $text,
    string $href,
    array $style = []
): self

Creates a native ODT hyperlink with xlink:href, xlink:type="simple", and xlink:show="new".

Unstyled hyperlinks are covered by current focused tests.

Known limitation: the current addHyperlink() implementation records the supplied style on the rendered span but does not register that style in the paragraph's style-requirement map. Therefore the 1.0 reference does not promise correct materialization of a styled hyperlink through this method.

addPHyperLink() is a historical compatibility variant that performs that style registration. It remains discoverable for compatibility but is not the preferred name for new API design.

Embedded elements¶

public function addElement(OdtElement $element): self

Embeds a structured child such as an image into the paragraph.

List compatibility methods¶

setBulleted(), setNumbered(), and isList() are retained public list-related behavior. Prefer ListElement or the RichText list conveniences when constructing new multi-item lists; their detailed contract belongs to the list reference.

Compatibility and infrastructure helpers¶

applyTextStyle() is a compatibility helper used when mixed style arrays are propagated into existing content. Public materialization/style-discovery methods inherited from OdtElement are not normal application authoring API.

See also¶

• Structured Content
• RichText