Index

  1. \SetaPDF
    1. Core
    2. Core
      1. Text
      2. Text
        1. Block
        2. RichTextBlock

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

File: /SetaPDF v2/Core/Text/RichTextBlock.php

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 SetaPDF_Core_Font_Type0_Subset($document, 'path/to/DejaVuSans.ttf');
        } elseif ($fontFamily === 'DejaVuSans' && $fontStyle === 'B') {
            $font = new SetaPDF_Core_Font_Type0_Subset($document, 'path/to/DejaVuSans-Bold.ttf');
        } elseif ($fontFamily === 'DejaVuSans' && $fontStyle === 'I') {
            $font = new SetaPDF_Core_Font_Type0_Subset($document, 'path/to/DejaVuSans-Oblique.ttf');
        } elseif ($fontFamily === 'DejaVuSans' && $fontStyle === 'BI') {
            $font = new SetaPDF_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');

Class hierarchy

Summary

Methods

Properties

Properties

$align

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

$backgroundColor

protected SetaPDF_Core_DataStructure_Color|null SetaPDF_Core_Text_RichTextBlock::$backgroundColor

$bodyNode

protected DOMElement SetaPDF_Core_Text_RichTextBlock::$bodyNode

$borderColor

protected SetaPDF_Core_DataStructure_Color|null SetaPDF_Core_Text_RichTextBlock::$borderColor

$borderWidth

protected int|float SetaPDF_Core_Text_RichTextBlock::$borderWidth = 0

$calculatedLines

protected null|array SetaPDF_Core_Text_RichTextBlock::$calculatedLines

$defaultFontFamily

protected string SetaPDF_Core_Text_RichTextBlock::$defaultFontFamily = 'Helvetica'

$defaultFontSize

protected int|float SetaPDF_Core_Text_RichTextBlock::$defaultFontSize = 12

$defaultLineHeight

protected int|float SetaPDF_Core_Text_RichTextBlock::$defaultLineHeight = 1.21

$defaultTextColor

protected int|float|string|array|SetaPDF_Core_Type_Array|SetaPDF_Core_DataStructure_Color SetaPDF_Core_Text_RichTextBlock::$defaultTextColor = '#000000'

$document

protected SetaPDF_Core_Document SetaPDF_Core_Text_RichTextBlock::$document

$dynamicWidth

protected null|int|float SetaPDF_Core_Text_RichTextBlock::$dynamicWidth

Used for caching if no width is given.

$fontLoader

private callable SetaPDF_Core_Text_RichTextBlock::$fontLoader

A callback with the signature function (SetaPDF_Core_Document $document, string $fontFamily, string $fontStyle): ?SetaPDF_Core_Font_FontInterface

$locale

protected string SetaPDF_Core_Text_RichTextBlock::$locale

$paddingBottom

protected int|float SetaPDF_Core_Text_RichTextBlock::$paddingBottom = 0

$paddingLeft

protected int|float SetaPDF_Core_Text_RichTextBlock::$paddingLeft = 0

$paddingRight

protected int|float SetaPDF_Core_Text_RichTextBlock::$paddingRight = 0

$paddingTop

protected int|float SetaPDF_Core_Text_RichTextBlock::$paddingTop = 0

$strict

protected bool SetaPDF_Core_Text_RichTextBlock::$strict = false

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

$width

protected null|int|float SetaPDF_Core_Text_RichTextBlock::$width

Methods

__construct()

public SetaPDF_Core_Text_RichTextBlock::__construct ()
Parameters
$document : SetaPDF_Core_Document
 

calculateItemWidths()

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

calculateLineHeights()

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

calculateLines()

protected SetaPDF_Core_Text_RichTextBlock::calculateLines (
void
): array|null
Exceptions

Throws SetaPDF_Core_Exception

draw()

public SetaPDF_Core_Text_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 SetaPDF_Core_Exception

Throws SetaPDF_Core_Font_Exception

Throws SetaPDF_Core_Type_Exception

Throws SetaPDF_Core_Type_IndirectReference_Exception

Throws SetaPDF_Exception_NotImplemented

drawBorderAndBackground()

protected SetaPDF_Core_Text_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 SetaPDF_Core_Exception

drawText()

protected SetaPDF_Core_Text_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 SetaPDF_Core_Exception

Throws SetaPDF_Core_Font_Exception

Throws SetaPDF_Core_Type_Exception

Throws SetaPDF_Core_Type_IndirectReference_Exception

Throws SetaPDF_Exception_NotImplemented

fixWordsWithNbsp()

protected SetaPDF_Core_Text_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 SetaPDF_Core_Text_RichTextBlock::getAlign (
void
): string

Get the text alignment.

getBackgroundColor()

public SetaPDF_Core_Text_RichTextBlock::getBackgroundColor (
void
): null|SetaPDF_Core_DataStructure_Color

Get the background color object.

getBorderColor()

public SetaPDF_Core_Text_RichTextBlock::getBorderColor (
void
): null|SetaPDF_Core_DataStructure_Color

Get the border color object.

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

getBorderWidth()

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

Get the border width.

getDefaultFontFamily()

public SetaPDF_Core_Text_RichTextBlock::getDefaultFontFamily (
void
): string

getDefaultFontSize()

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

getDefaultLineHeight()

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

getDefaultTextColor()

public SetaPDF_Core_Text_RichTextBlock::getDefaultTextColor (
void
): SetaPDF_Core_DataStructure_Color

getHeight()

public SetaPDF_Core_Text_RichTextBlock::getHeight (
void
): float

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

Exceptions

Throws SetaPDF_Core_Exception

getPaddingBottom()

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

Get the bottom padding.

getPaddingLeft()

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

Get the left padding.

getPaddingRight()

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

Get the right padding.

getPaddingTop()

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

Get the top padding.

getTextWidth()

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

Returns the width of the text block without padding.

Exceptions

Throws SetaPDF_Core_Exception

getWidth()

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

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

Exceptions

Throws SetaPDF_Core_Exception

loadFont()

protected SetaPDF_Core_Text_RichTextBlock::loadFont (
string $fontFamily, string $fontStyle
): SetaPDF_Core_Font_FontInterface
Parameters
$fontFamily : string
 
$fontStyle : string
 
Exceptions

Throws SetaPDF_Core_Exception

parseChilds()

protected SetaPDF_Core_Text_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 SetaPDF_Core_Exception

parseNode()

protected SetaPDF_Core_Text_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 SetaPDF_Core_Exception

parseText()

protected SetaPDF_Core_Text_RichTextBlock::parseText (
void
): array

Split the text into word blocks

Exceptions

Throws SetaPDF_Core_Exception

parseTextBlocks()

protected SetaPDF_Core_Text_RichTextBlock::parseTextBlocks (
array $items
): void
Parameters
$items : array
 

registerDefaultFontLoader()

public SetaPDF_Core_Text_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 SetaPDF_Core_Text_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
  • registerDefaultFontLoader

setAlign()

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

Set the text alignment.

Parameters
$align : string
 
See

setBackgroundColor()

public SetaPDF_Core_Text_RichTextBlock::setBackgroundColor (): void

Set the background color.

Parameters
$color : SetaPDF_Core_DataStructure_Color|int|float|string|array|SetaPDF_Core_Type_Array
 
See

setBorderColor()

public SetaPDF_Core_Text_RichTextBlock::setBorderColor (): void

Set the border color.

Parameters
$color : SetaPDF_Core_DataStructure_Color|int|float|string|array|SetaPDF_Core_Type_Array
 
See

setBorderWidth()

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

Set the border width.

Parameters
$borderWidth : int|float
 

setDefaultFontFamily()

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

setDefaultFontSize()

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

setDefaultLineHeight()

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

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

setDefaultTextColor()

public SetaPDF_Core_Text_RichTextBlock::setDefaultTextColor (): void
Parameters
$color : int|float|string|array|SetaPDF_Core_Type_Array|SetaPDF_Core_DataStructure_Color
 

setPadding()

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

Set the padding.

Parameters
$padding : int|float
 

setPaddingBottom()

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

Set the bottom padding.

Parameters
$paddingBottom : int|float
 

setPaddingLeft()

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

Set the left padding.

Parameters
$paddingLeft : int|float
 

setPaddingRight()

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

Set the right padding.

Parameters
$paddingRight : int|float
 

setPaddingTop()

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

Set the top padding.

Parameters
$paddingTop : int|float
 

setStrict()

public SetaPDF_Core_Text_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 SetaPDF_Core_Text_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 SetaPDF_Core_Text_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
 

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