Index

  1. \setasign\SetaPDF2
    1. Core
      1. Text
        1. RichTextBlock
        2. Text
        3. TextBlock

setasign\SetaPDF2\Core\Text

RichTextBlock Class representing a rich-text block which can be drawn onto a canvas object

File: /SetaPDF v2/Core/Text/RichTextBlock.php
Old class name (alias): \SetaPDF_Core_Text_RichTextBlock

Supported tags and attributes

A rich-text block allows you to use a subset of HTML and CSS to style the text. Following HTML tags are interpreted as you know from HTML:

  • <b> / <strong> for bold text
  • <i> / <em> for italic text
  • <u> for underline text
  • <sup> for superscript
  • <sub> for subscript
  • <br> / </br> for a line-break
  • <a href="..."> for a link annotation (please see "Annotations" below)

You can use any other HTML tag such as <span> or <div>, too. Internally these tags are only parsed for their style attribute.

You can use the style attribute to define CSS styles for an element to any tag. Following CSS styles are supported:

  • font-family: (string)
  • font-size: (float|int)(pt|%)
  • color: #RRGGBB hexadecimal notation
  • line-height: (float|int)(%) unitless or percentual value

Fonts

By default, the instance uses the standard font Helvetica and loads the different styles automatically by a predefined font-loader callable.

To use individual fonts and make use of font subsets you have to pass your own font-loader which is a callable with following signature:

function (
    \setasign\SetaPDF2\Core\Document $document,
    string $fontFamily, # The font family as defined in the font-family property.
    string $fontStyle   # An empty string = normal, 'B' = bold, 'I' = italic, 'BI' = bold+italic
): ?SetaPDF_Core_Font_FontInterface`

The font instances created in this callable are bound to the document instance, and you need to take care of caching the instances appropriately to avoid an unneeded overhead. You also should make sure that the callable shares the font instances through different rich-text block instances.

A font-loader for e.g. DejaVuSans could look like:

$loadedFonts = [];
$fontLoader = function (\setasign\SetaPDF2\Core\Document $document, $fontFamily, $fontStyle) use (&$loadedFonts) {
    $cacheKey = $document->getInstanceIdent() . '_' . $fontFamily . '_' . $fontStyle;
    $font = null;
    if (!array_key_exists($cacheKey, $loadedFonts)) {
        if ($fontFamily === 'DejaVuSans' && $fontStyle === '') {
            $font = new \setasign\SetaPDF2\Core\Font\Type0\Subset($document, 'path/to/DejaVuSans.ttf');
        } elseif ($fontFamily === 'DejaVuSans' && $fontStyle === 'B') {
            $font = new \setasign\SetaPDF2\Core\Font\Type0\Subset($document, 'path/to/DejaVuSans-Bold.ttf');
        } elseif ($fontFamily === 'DejaVuSans' && $fontStyle === 'I') {
            $font = new \setasign\SetaPDF2\Core\Font\Type0\Subset($document, 'path/to/DejaVuSans-Oblique.ttf');
        } elseif ($fontFamily === 'DejaVuSans' && $fontStyle === 'BI') {
            $font = new \setasign\SetaPDF2\Core\Font\Type0\Subset($document, 'path/to/DejaVuSans-BoldOblique.ttf');
        }
        $loadedFonts[$cacheKey] = $font;
    }
    return $loadedFonts[$cacheKey];
};

and can be registered by the registerFontLoader() method:

$richTextBlock->registerFontLoader($fontLoader);

In the same step you should set Frutiger as the default font-family:

$richTextBlock->setDefaultFontFamily('DejaVuSans');

Annotations

<a>-Tags will generate annotations which will be added to the current page. This only happens automatically if the given canvas in RichTextBlock::draw() is a page canvas. If it's not you have to add the annotations by yourself into the page.

If multiple words are part of an <a>-Tag only one annotation will be generated and every word will be added as a quad-point into the annotation. Some readers don't (or only partially) support quad-points if you need to support these readers you should use an <a>-tag for every word manually.

Class hierarchy

Summary

Methods

Properties

Properties

$align

protected string RichTextBlock::$align = 'left'
See

$annotationsData

protected ?array RichTextBlock::$annotationsData

$backgroundColor

protected ?\setasign\SetaPDF2\Core\DataStructure\Color\AbstractColor RichTextBlock::$backgroundColor

$bodyNode

protected \DOMElement RichTextBlock::$bodyNode

$borderColor

protected ?\setasign\SetaPDF2\Core\DataStructure\Color\AbstractColor RichTextBlock::$borderColor

$borderWidth

protected int|float RichTextBlock::$borderWidth = 0

$calculatedLines

protected ?array RichTextBlock::$calculatedLines

$defaultFontFamily

protected string RichTextBlock::$defaultFontFamily = 'Helvetica'

$defaultFontSize

protected int|float RichTextBlock::$defaultFontSize = 12

$defaultLineHeight

protected int|float RichTextBlock::$defaultLineHeight = 1.21

$defaultTextColor

protected int|float|string|array|\setasign\SetaPDF2\Core\Type\PdfArray|\setasign\SetaPDF2\Core\DataStructure\Color\AbstractColor RichTextBlock::$defaultTextColor = '#000000'

$document

protected \setasign\SetaPDF2\Core\Document RichTextBlock::$document

$dynamicWidth

protected null|int|float RichTextBlock::$dynamicWidth

Used for caching if no width is given.

$fontLoader

private callable RichTextBlock::$fontLoader

A callback with the signature:

function (
    \\setasign\SetaPDF2\Core\Document $document,
    string $fontFamily,
    string $fontStyle
): ?\\setasign\SetaPDF2\\Core\\Font\\FontInterface`

$locale

protected string RichTextBlock::$locale

$paddingBottom

protected int|float RichTextBlock::$paddingBottom = 0

$paddingLeft

protected int|float RichTextBlock::$paddingLeft = 0

$paddingRight

protected int|float RichTextBlock::$paddingRight = 0

$paddingTop

protected int|float RichTextBlock::$paddingTop = 0

$strict

protected bool RichTextBlock::$strict = false

If true an error will be thrown if a tag or style isn't supported.

$width

protected null|int|float RichTextBlock::$width

Methods

__construct()

public RichTextBlock::__construct ()
Parameters
$document : \setasign\SetaPDF2\Core\Document
 

calculateItemWidths()

protected RichTextBlock::calculateItemWidths (
array $items
): array
Parameters
$items : array
 

calculateLineHeights()

protected RichTextBlock::calculateLineHeights (
array $lines
): array
Parameters
$lines : array
 

calculateLines()

protected RichTextBlock::calculateLines (
void
): ?array
Exceptions

Throws \setasign\SetaPDF2\Core\Exception

draw()

public RichTextBlock::draw (
\setasign\SetaPDF2\Core\Canvas\Canvas $canvas,
int|float $x = 0.0,
int|float $y = 0.0
): void

Draws the text block onto a canvas.

Parameters
$canvas : \setasign\SetaPDF2\Core\Canvas\Canvas
 
$x : int|float

The lower left x-value of the text block

$y : int|float

The lower left y-value of the text block

Exceptions

Throws \setasign\SetaPDF2\Core\Exception

Throws \setasign\SetaPDF2\Core\Font\Exception

Throws \setasign\SetaPDF2\Core\Type\Exception

Throws \setasign\SetaPDF2\Core\Type\IndirectReference\Exception

Throws \setasign\SetaPDF2\NotImplementedException

drawBorderAndBackground()

protected RichTextBlock::drawBorderAndBackground (
\setasign\SetaPDF2\Core\Canvas\Canvas $canvas,
int|float $x,
int|float $y
): void

Draws the border and background onto the canvas.

Parameters
$canvas : \setasign\SetaPDF2\Core\Canvas\Canvas
 
$x : int|float

The lower left x-value of the text block

$y : int|float

The lower left y-value of the text block

Exceptions

Throws \setasign\SetaPDF2\Core\Exception

drawText()

protected RichTextBlock::drawText (
\setasign\SetaPDF2\Core\Canvas\Canvas $canvas,
float|int $x,
float|int $y
): void
Parameters
$canvas : \setasign\SetaPDF2\Core\Canvas\Canvas
 
$x : float|int
 
$y : float|int
 
Exceptions

Throws \setasign\SetaPDF2\Core\Exception

Throws \setasign\SetaPDF2\Core\Font\Exception

Throws \setasign\SetaPDF2\Core\Type\Exception

Throws \setasign\SetaPDF2\Core\Type\IndirectReference\Exception

Throws \setasign\SetaPDF2\NotImplementedException

fixWordsWithNbsp()

protected RichTextBlock::fixWordsWithNbsp (
array $lines
): array

Split up words which contain spaces created by  . Primarily needed for proper justify alignment as   spaces are also stretched.

Parameters
$lines : array
 

getAlign()

public RichTextBlock::getAlign (
void
): string

Get the text alignment.

getAnnotationsData()

public RichTextBlock::getAnnotationsData (
void
): ?array

Returns the data for the annotation which have to be added to the page. Will be null until calling the method draw().

getBackgroundColor()

public RichTextBlock::getBackgroundColor (
void
): ?\setasign\SetaPDF2\Core\DataStructure\Color\AbstractColor

Get the background color object.

getBorderColor()

public RichTextBlock::getBorderColor (
void
): ?\setasign\SetaPDF2\Core\DataStructure\Color\AbstractColor

Get the border color object.

If no border color is defined a greyscale black color will be returned.

getBorderWidth()

public RichTextBlock::getBorderWidth (
void
): int|float

Get the border width.

getDefaultFontFamily()

public RichTextBlock::getDefaultFontFamily (
void
): string

getDefaultFontSize()

public RichTextBlock::getDefaultFontSize (
void
): float|int

getDefaultLineHeight()

public RichTextBlock::getDefaultLineHeight (
void
): float|int

getDefaultTextColor()

public RichTextBlock::getDefaultTextColor (
void
): \setasign\SetaPDF2\Core\DataStructure\Color\AbstractColor

getHeight()

public RichTextBlock::getHeight (
void
): float

Returns the height of the text block including padding and border.

Exceptions

Throws \setasign\SetaPDF2\Core\Exception

getPaddingBottom()

public RichTextBlock::getPaddingBottom (
void
): int|float

Get the bottom padding.

getPaddingLeft()

public RichTextBlock::getPaddingLeft (
void
): int|float

Get the left padding.

getPaddingRight()

public RichTextBlock::getPaddingRight (
void
): int|float

Get the right padding.

getPaddingTop()

public RichTextBlock::getPaddingTop (
void
): int|float

Get the top padding.

getTextWidth()

public RichTextBlock::getTextWidth (
void
): int|float

Returns the width of the text block without padding.

Exceptions

Throws \setasign\SetaPDF2\Core\Exception

getWidth()

public RichTextBlock::getWidth (
void
): int|float

Returns the width of the rich-text including padding and border.

Exceptions

Throws \setasign\SetaPDF2\Core\Exception

loadFont()

protected RichTextBlock::loadFont (
string $fontFamily,
string $fontStyle
): \setasign\SetaPDF2\Core\Font\FontInterface
Parameters
$fontFamily : string
 
$fontStyle : string
 
Exceptions

Throws \setasign\SetaPDF2\Core\Exception

parseChilds()

protected RichTextBlock::parseChilds (
\DOMNode $node,
string $fontFamily,
int|float $fontSize,
\setasign\SetaPDF2\Core\DataStructure\Color\AbstractColor $color,
string $fontStyle,
int|float $lineHeight,
array $fontDecoration,
?array{link: string, uuid: string} $link
): array
Parameters
$node : \DOMNode
 
$fontFamily : string
 
$fontSize : int|float
 
$color : \setasign\SetaPDF2\Core\DataStructure\Color\AbstractColor
 
$fontStyle : string
 
$lineHeight : int|float
 
$fontDecoration : array
 
$link : ?array{link: string, uuid: string}
 
Exceptions

Throws \setasign\SetaPDF2\Core\Exception

parseNode()

protected RichTextBlock::parseNode (
\DOMNode $node,
string $fontFamily,
int|float $fontSize,
\setasign\SetaPDF2\Core\DataStructure\Color\AbstractColor $color,
string $fontStyle,
int|float $lineHeight,
array $fontDecoration,
?array{link: string, uuid: string} $link
): array
Parameters
$node : \DOMNode
 
$fontFamily : string
 
$fontSize : int|float
 
$color : \setasign\SetaPDF2\Core\DataStructure\Color\AbstractColor
 
$fontStyle : string
 
$lineHeight : int|float
 
$fontDecoration : array
 
$link : ?array{link: string, uuid: string}
 
Exceptions

Throws \setasign\SetaPDF2\Core\Exception

parseText()

protected RichTextBlock::parseText (
void
): array

Split the text into word blocks

Exceptions

Throws \setasign\SetaPDF2\Core\Exception

parseTextBlocks()

protected RichTextBlock::parseTextBlocks (
array $items
): array
Parameters
$items : array
 

registerDefaultFontLoader()

public RichTextBlock::registerDefaultFontLoader (
array &$loadedFonts = array ( )
): void

Registers the default font-loader which handles the standard font Helvetica.

Parameters
$loadedFonts : array

Memorized loaded fonts. If you're using multiple RichTextBlocks these should share the same $loadedFonts array.

registerFontLoader()

public RichTextBlock::registerFontLoader (
callable $resolveFont
): void

Register a font loader.

Please note that you MUST cache the results of this callback per document.

Parameters
$resolveFont : callable

A callable with the following signature:

function (
    \\setasign\SetaPDF2\Core\Document $document,
    string $fontFamily,
    string $fontStyle
): ?\\setasign\SetaPDF2\Core\Font\FontInterface
See

setAlign()

public RichTextBlock::setAlign (
string $align
): void

Set the text alignment.

Parameters
$align : string
 
See

setBackgroundColor()

public RichTextBlock::setBackgroundColor (): void

Set the background color.

Parameters
$color : \setasign\SetaPDF2\Core\DataStructure\Color\AbstractColor|int|float|string|array|\setasign\SetaPDF2\Core\Type\PdfArray
 
See

setBorderColor()

public RichTextBlock::setBorderColor (): void

Set the border color.

Parameters
$color : \setasign\SetaPDF2\Core\DataStructure\Color\AbstractColor|int|float|string|array|\setasign\SetaPDF2\Core\Type\PdfArray
 
See

setBorderWidth()

public RichTextBlock::setBorderWidth (
int|float $borderWidth
): void

Set the border width.

Parameters
$borderWidth : int|float
 

setDefaultFontFamily()

public RichTextBlock::setDefaultFontFamily (
string $fontFamily
): void
Parameters
$fontFamily : string
 

setDefaultFontSize()

public RichTextBlock::setDefaultFontSize (
int|float $fontSize
): void
Parameters
$fontSize : int|float
 

setDefaultLineHeight()

public RichTextBlock::setDefaultLineHeight (
int|float $lineHeight
): void
Parameters
$lineHeight : int|float

The unitless line-height (e.g 1 or 1.4)

setDefaultTextColor()

public RichTextBlock::setDefaultTextColor (): void
Parameters
$color : int|float|string|array|\setasign\SetaPDF2\Core\Type\PdfArray|\setasign\SetaPDF2\Core\DataStructure\Color\AbstractColor
 

setPadding()

public RichTextBlock::setPadding (
int|float $padding
): void

Set the padding.

Parameters
$padding : int|float
 

setPaddingBottom()

public RichTextBlock::setPaddingBottom (
int|float $paddingBottom
): void

Set the bottom padding.

Parameters
$paddingBottom : int|float
 

setPaddingLeft()

public RichTextBlock::setPaddingLeft (
int|float $paddingLeft
): void

Set the left padding.

Parameters
$paddingLeft : int|float
 

setPaddingRight()

public RichTextBlock::setPaddingRight (
int|float $paddingRight
): void

Set the right padding.

Parameters
$paddingRight : int|float
 

setPaddingTop()

public RichTextBlock::setPaddingTop (
int|float $paddingTop
): void

Set the top padding.

Parameters
$paddingTop : int|float
 

setStrict()

public RichTextBlock::setStrict (
bool $strict = true
): void

If true an error will be thrown if a tag or style isn't supported.

Parameters
$strict : bool
 

setText()

public RichTextBlock::setText (
string $text,
string $locale = 'en_US'
): void

Set the rich-text.

The text is cleaned-up and passed to a body node in a raw HTML template which is then loaded by \DOMDocument::loadHTML() method. Entity loading, network access and error handling is disabled by using LIBXML_NONET | LIBXML_NOERROR as the $options parameter. For PHP < 8 also libxml_disable_entity_loader() is used to disable entity loading.

Parameters
$text : string

An UTF-8 string

$locale : string

INTL locale used for the break behaviour

setTextWidth()

public RichTextBlock::setTextWidth (
null|int|float $width
): void

Set the width of the rich-text. Padding is not included in this width.

Parameters
$width : null|int|float
 

writeAnnotations()

public RichTextBlock::writeAnnotations (
\setasign\SetaPDF2\Core\Document\Page $page,
?array $annotationsData = null,
?\setasign\SetaPDF2\Core\Geometry\Matrix $transformationMatrix = null
): void

Write the annotations into the given page.

Parameters
$page : \setasign\SetaPDF2\Core\Document\Page
 
$annotationsData : ?array

If not given, the annotations from the last draw() call will be used.

$transformationMatrix : ?\setasign\SetaPDF2\Core\Geometry\Matrix

If given, all positions will be adjusted to the matrix.

Exceptions

Throws \setasign\SetaPDF2\Core\Type\Exception


© 2025 Setasign GmbH & Co. KG · Contact / Imprint · Data Privacy Statement (German)