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

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

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

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|integer)(pt|%)
  • color: #RRGGBB hexadecimal notation
  • line-height: (float|integer)(%) unitless or percentual value

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 (
    SetaPDF_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 (SetaPDF_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 <a href="/api-reference/setapdf/c/setasign.SetaPDF2.Core.Font.Type0.Subset">\setasign\SetaPDF2\Core\Font\Type0\Subset</a>($document, 'path/to/DejaVuSans.ttf');
        } elseif ($fontFamily === 'DejaVuSans' && $fontStyle === 'B') {
            $font = new <a href="/api-reference/setapdf/c/setasign.SetaPDF2.Core.Font.Type0.Subset">\setasign\SetaPDF2\Core\Font\Type0\Subset</a>($document, 'path/to/DejaVuSans-Bold.ttf');
        } elseif ($fontFamily === 'DejaVuSans' && $fontStyle === 'I') {
            $font = new <a href="/api-reference/setapdf/c/setasign.SetaPDF2.Core.Font.Type0.Subset">\setasign\SetaPDF2\Core\Font\Type0\Subset</a>($document, 'path/to/DejaVuSans-Oblique.ttf');
        } elseif ($fontFamily === 'DejaVuSans' && $fontStyle === 'BI') {
            $font = new <a href="/api-reference/setapdf/c/setasign.SetaPDF2.Core.Font.Type0.Subset">\setasign\SetaPDF2\Core\Font\Type0\Subset</a>($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');

Class hierarchy

Summary

Methods

Properties

Properties

$align

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

$backgroundColor

protected ?\SetaPDF_Core_DataStructure_Color RichTextBlock::$backgroundColor

$bodyNode

protected \DOMElement RichTextBlock::$bodyNode

$borderColor

protected ?\SetaPDF_Core_DataStructure_Color 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|\SetaPDF_Core_Type_Array|\SetaPDF_Core_DataStructure_Color RichTextBlock::$defaultTextColor = '#000000'

$document

protected \SetaPDF_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 (
    \\SetaPDF_Core_Document $document,
    string $fontFamily,
    string $fontStyle
): ?\\SetaPDF_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 : \SetaPDF_Core_Document
 

calculateItemWidths()

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

calculateLineHeights()

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

calculateLines()

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

Throws \setasign\SetaPDF2\Core\Exception

draw()

public RichTextBlock::draw (
\SetaPDF_Core_Canvas $canvas,
int|float $x,
int|float $y
): void

Draws the text block onto a canvas.

Parameters
$canvas : \SetaPDF_Core_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 (
\SetaPDF_Core_Canvas $canvas,
int|float $x,
int|float $y
): void

Draws the border and background onto the canvas.

Parameters
$canvas : \SetaPDF_Core_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 (
\SetaPDF_Core_Canvas $canvas,
float|int $x,
float|int $y
): void
Parameters
$canvas : \SetaPDF_Core_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.

getBackgroundColor()

public RichTextBlock::getBackgroundColor (
void
): ?\SetaPDF_Core_DataStructure_Color

Get the background color object.

getBorderColor()

public RichTextBlock::getBorderColor (
void
): ?\SetaPDF_Core_DataStructure_Color

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
): \SetaPDF_Core_DataStructure_Color

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
): \SetaPDF_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,
\SetaPDF_Core_DataStructure_Color $color,
string $fontStyle,
int|float $lineHeight,
array $fontDecoration
): array
Parameters
$node : \DOMNode
 
$fontFamily : string
 
$fontSize : int|float
 
$color : \SetaPDF_Core_DataStructure_Color
 
$fontStyle : string
 
$lineHeight : int|float
 
$fontDecoration : array
 
Exceptions

Throws \setasign\SetaPDF2\Core\Exception

parseNode()

protected RichTextBlock::parseNode (
\DOMNode $node,
string $fontFamily,
int|float $fontSize,
\SetaPDF_Core_DataStructure_Color $color,
string $fontStyle,
int|float $lineHeight,
array $fontDecoration
): array
Parameters
$node : \DOMNode
 
$fontFamily : string
 
$fontSize : int|float
 
$color : \SetaPDF_Core_DataStructure_Color
 
$fontStyle : string
 
$lineHeight : int|float
 
$fontDecoration : array
 
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
): void
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 (
    \\SetaPDF_Core_Document $document,
    string $fontFamily,
    string $fontStyle
): ?\\SetaPDF_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 : \SetaPDF_Core_DataStructure_Color|int|float|string|array|\SetaPDF_Core_Type_Array
 
See

setBorderColor()

public RichTextBlock::setBorderColor (): void

Set the border color.

Parameters
$color : \SetaPDF_Core_DataStructure_Color|int|float|string|array|\SetaPDF_Core_Type_Array
 
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|\SetaPDF_Core_Type_Array|\SetaPDF_Core_DataStructure_Color
 

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
 

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