Zeta Components - high quality PHP components

Zeta Components Manual :: Docs For Class ezcDocumentPdfHaruDriver

Document::ezcDocumentPdfHaruDriver

Class ezcDocumentPdfHaruDriver

Pdf driver based on pecl/haru

Haru is a pecl extension for PDF rendering, based on libahru, available at http://libharu.org. The haru library does not yet implement support for any unicode encodings, so there will be issues with non-ASCII characters occuring in the passed texts. On the other hand it is the fastest driver currently available for PDF rendering.

The extension can be installed using the pear command:

  1.   pear install pecl/haru

The driver is currently the default driver, but can be explicitely set using:

  1.   // Load the docbook document and create a PDF from it
  2.   $pdf = new ezcDocumentPdf();
  3.   $pdf->options->driver = new ezcDocumentPdfHaruDriver();
  4.   $pdf->createFromDocbook( $docbook );
  5.   file_put_contents( __FILE__ . '.pdf', $pdf );

Source for this file: /Document/src/document/pdf/driver/haru.php

ezcDocumentPdfDriver
   |
   --ezcDocumentPdfHaruDriver
Version:   //autogen//

Inherited Constants

From ezcDocumentPdfDriver:
ezcDocumentPdfDriver::FONT_BOLD    Bold text
ezcDocumentPdfDriver::FONT_OBLIQUE    Italic text
ezcDocumentPdfDriver::FONT_PLAIN    Normal text

Member Variables

protected array $currentFont = array(
'name' => 'sans-serif',
'style' => self::FONT_PLAIN,
'size' => 28.5,
'font' => null,
)
Name and style of default font / currently used font
protected haruPage $currentPage
Reference to the page currently rendered on
protected HaruDoc $document
Haru Document instance
protected HaruDoc $dummyDoc
Dummy document to provide font width estimations, before we actually know what kind of pages will be rendered.
protected array $encodings = array(
'StandardEncoding' => 'ISO_8859-1', // Assumption
'MacRomanEncoding' => 'MAC',
'WinAnsiEncoding' => 'ISO_8859-1',
'ISO8859-2' => 'ISO_8859-2',
'ISO8859-3' => 'ISO_8859-3',
'ISO8859-4' => 'ISO_8859-4',
'ISO8859-5' => 'ISO_8859-5',
'ISO8859-6' => 'ISO_8859-6',
'ISO8859-7' => 'ISO_8859-7',
'ISO8859-8' => 'ISO_8859-8',
'ISO8859-9' => 'ISO_8859-9',
'ISO8859-10' => 'ISO_8859-10',
'ISO8859-11' => 'ISO_8859-11',
'ISO8859-13' => 'ISO_8859-12',
'ISO8859-14' => 'ISO_8859-13',
'ISO8859-15' => 'ISO_8859-14',
'ISO8859-16' => 'ISO_8859-16',
'CP1250' => 'CP1250',
'CP1251' => 'CP1251',
'CP1252' => 'CP1252',
'CP1253' => 'CP1253',
'CP1254' => 'CP1254',
'CP1255' => 'CP1255',
'CP1256' => 'CP1256',
'CP1257' => 'CP1257',
'CP1258' => 'CP1258',
'KOI8-R' => 'KOI8-R',
/*
* @todo: Find out how about the respective equivalents in inconv
* encoding notation.
'GB-EUC-H' => '',
'GB-EUC-V' => '',
'GBK-EUC-H' => '',
'GBK-EUC-V' => '',
'ETen-B5-H' => '',
'ETen-B5-V' => '',
'90ms-RKSJ-H' => '',
'90ms-RKSJ-V' => '',
'90msp-RKSJ-H' => '',
'EUC-H' => '',
'EUC-V' => '',
'KSC-EUC-H' => '',
'KSC-EUC-V' => '',
'KSCms-UHC-H' => '',
'KSCms-UHC-HW-H' => '',
'KSCms-UHC-HW-V' => '',
*/
)
Encodings known by libharu.

Libharu sadly does not know any encoding which is capable of representing the full unicode charset. It only knows about several encodings representing subsets of it. This is a list of all available encodings which will just be tried to use for input strings, mapped to their iconv equivalents.
protected array $fonts = array(
'sans-serif' => array(
self::FONT_PLAIN => 'Helvetica',
self::FONT_BOLD => 'Helvetica-Bold',
self::FONT_OBLIQUE => 'Helvetica-Oblique',
3 => 'Helvetica-BoldOblique',
),'serif'=>array(self::FONT_PLAIN=>'Times-Roman',self::FONT_BOLD=>'Times-Bold',self::FONT_OBLIQUE=>'Times-Oblique',3=>'Times-BoldOblique',),'monospace'=>array(self::FONT_PLAIN=>'Courier',self::FONT_BOLD=>'Courier-Bold',self::FONT_OBLIQUE=>'Courier-Oblique',3=>'Courier-BoldOblique',),'Symbol'=>array(self::FONT_PLAIN=>'Symbol',),'ZapfDingbats'=>array(self::FONT_PLAIN=>'ZapfDingbats',),)
Array with fonts, and their equivalents for bold and italic markup. This array will be extended when loading new fonts, but contains the builtin fonts by default.

The fourth value for each font is bold + oblique, the index is the bitwise and combination of the repective combinations. Each font MUST have at least a value for FONT_PLAIN assigned.
protected array $internalTargets = array()
Internal targets

Target objects for all rendered internal targets, to be used when rendering the internal links at the end of the processing.
protected array $pages
Page instances, given as an array, indexed by their page number starting with 0.
protected array $pendingInternalLinks = array()
List of internal links.

Internal links can only be rendered at the very last items in a PDF, because *all* internal targets must already be known.
protected array $permissionMapping = array(
ezcDocumentPdfOptions::EDIT => HaruDoc::ENABLE_EDIT,
ezcDocumentPdfOptions::PRINTABLE => HaruDoc::ENABLE_PRINT,
ezcDocumentPdfOptions::COPY => HaruDoc::ENABLE_COPY,
ezcDocumentPdfOptions::MODIFY => HaruDoc::ENABLE_EDIT_ALL,
)
Mapping of native permission flags, to Haru permission flags

Inherited Member Variables

From ezcDocumentPdfDriver
protected ezcDocumentPdfDriver::$options

Method Summary

public void __construct( )
Construct driver
public void addExternalLink( $x , $y , $width , $height , $url )
Add an external link
public void addInternalLink( $x , $y , $width , $height , $target )
Add an internal link
public void addInternalLinkTarget( $id )
Add an internal link target
public float calculateWordWidth( $word )
Calculate the rendered width of the current word
public void createPage( $width , $height )
Create a new page
public void drawImage( $file , $type , $x , $y , $width , $height )
Draw image
protected void drawPath( $points )
Draw path specified by the given points array
public void drawPolygon( $points , $color )
Draw a fileld polygon
public void drawPolyline( $points , $color , $width , [ $close = true] )
Draw a polyline
public void drawWord( $x , $y , $word )
Draw word at given position
public float getCurrentLineHeight( )
Get current line height
protected void initialize( )
Initialize haru documents
public void registerFont( $name , $type , $pathes )
Register a font
protected void renderInternalLinks( )
Render internal links
public string save( )
Generate and return PDF
public void setMetaData( $key , $value )
Set metadata
protected void setPermissions( $permissions )
Set permissions for PDF document
public void setTextFormatting( $type , $value )
Set text formatting option
public void trySetFont( $name , $style )
Try to set font

Inherited Methods

From ezcDocumentPdfDriver
public void ezcDocumentPdfDriver::__construct()
Construct driver
public void ezcDocumentPdfDriver::addExternalLink()
Add an external link
public void ezcDocumentPdfDriver::addInternalLink()
Add an internal link
public void ezcDocumentPdfDriver::addInternalLinkTarget()
Add an internal link target
public abstract float ezcDocumentPdfDriver::calculateWordWidth()
Calculate the rendered width of the current word
public abstract void ezcDocumentPdfDriver::createPage()
Create a new page
public abstract void ezcDocumentPdfDriver::drawImage()
Draw image
public void ezcDocumentPdfDriver::drawPolygon()
Draw a fileld polygon
public void ezcDocumentPdfDriver::drawPolyline()
Draw a polyline
public abstract void ezcDocumentPdfDriver::drawWord()
Draw word at given position
public abstract float ezcDocumentPdfDriver::getCurrentLineHeight()
Get current line height
public void ezcDocumentPdfDriver::registerFont()
Register a font
public abstract string ezcDocumentPdfDriver::save()
Generate and return PDF
public void ezcDocumentPdfDriver::setMetaData()
Set metadata
public void ezcDocumentPdfDriver::setOptions()
Set compression
public abstract void ezcDocumentPdfDriver::setTextFormatting()
Set text formatting option

Methods

__construct

void __construct( )

Construct driver

Creates a new document instance maintaining all document context.

Redefinition of:
Method Description
ezcDocumentPdfDriver::__construct() Construct driver

addExternalLink

void addExternalLink( float $x , float $y , float $width , float $height , string $url )

Add an external link

Add an external link to the rectangle specified by its top-left position, width and height. The last parameter is the actual URL to link to.

Parameters:
Name Type Description
$x float
$y float
$width float
$height float
$url string
Redefinition of:
Method Description
ezcDocumentPdfDriver::addExternalLink() Add an external link

addInternalLink

void addInternalLink( float $x , float $y , float $width , float $height , string $target )

Add an internal link

Add an internal link to the rectangle specified by its top-left position, width and height. The last parameter is the target identifier to link to.

Parameters:
Name Type Description
$x float
$y float
$width float
$height float
$target string
Redefinition of:
Method Description
ezcDocumentPdfDriver::addInternalLink() Add an internal link

addInternalLinkTarget

void addInternalLinkTarget( string $id )

Add an internal link target

Add an internal link to the current page. The last parameter is the target identifier.

Parameters:
Name Type Description
$id string
Redefinition of:
Method Description
ezcDocumentPdfDriver::addInternalLinkTarget() Add an internal link target

calculateWordWidth

float calculateWordWidth( string $word )

Calculate the rendered width of the current word

Calculate the width of the passed word, using the currently set text formatting options.

Parameters:
Name Type Description
$word string
Redefinition of:
Method Description
ezcDocumentPdfDriver::calculateWordWidth() Calculate the rendered width of the current word

createPage

void createPage( float $width , float $height )

Create a new page

Create a new page in the PDF document with the given width and height.

Parameters:
Name Type Description
$width float
$height float
Redefinition of:
Method Description
ezcDocumentPdfDriver::createPage() Create a new page

drawImage

void drawImage( string $file , string $type , float $x , float $y , float $width , float $height )

Draw image

Draw image at the defined position. The first parameter is the (absolute) path to the image file, and the second defines the type of the image. If the driver cannot handle this aprticular image type, it should throw an exception.

The further parameters define the location where the image should be rendered and the dimensions of the image in the rendered output. The dimensions do not neccesarily match the real image dimensions, and might require some kind of scaling inside the driver depending on the used backend.

Parameters:
Name Type Description
$file string
$type string
$x float
$y float
$width float
$height float
Redefinition of:
Method Description
ezcDocumentPdfDriver::drawImage() Draw image

drawPath

void drawPath( $points )

Draw path specified by the given points array

Parameters:
Name Type Description
$points array

drawPolygon

void drawPolygon( $points , $color )

Draw a fileld polygon

Draw any filled polygon, filled using the defined color. The color should be passed as an array with the keys "red", "green", "blue" and optionally "alpha". Each key should have a value between 0 and 1 associated.

The polygon itself is specified as an array of two-tuples, specifying the x and y coordinate of the point.

Parameters:
Name Type Description
$points array
$color array
Redefinition of:
Method Description
ezcDocumentPdfDriver::drawPolygon() Draw a fileld polygon

drawPolyline

void drawPolyline( $points , $color , float $width , [bool $close = true] )

Draw a polyline

Draw any non-filled polygon, filled using the defined color. The color should be passed as an array with the keys "red", "green", "blue" and optionally "alpha". Each key should have a value between 0 and 1 associated.

The polyline itself is specified as an array of two-tuples, specifying the x and y coordinate of the point.

The thrid parameter defines the width of the border and the last parameter may optionally be set to false to not close the polygon (draw another line from the last point to the first one).

Parameters:
Name Type Description
$points array
$color array
$width float
$close bool
Redefinition of:
Method Description
ezcDocumentPdfDriver::drawPolyline() Draw a polyline

drawWord

void drawWord( float $x , float $y , string $word )

Draw word at given position

Draw the given word at the given position using the currently set text formatting options.

The coordinate specifies the left bottom edge of the words bounding box.

Parameters:
Name Type Description
$x float
$y float
$word string
Redefinition of:
Method Description
ezcDocumentPdfDriver::drawWord() Draw word at given position

getCurrentLineHeight

float getCurrentLineHeight( )

Get current line height

Return the current line height in millimeter based on the current font and text rendering settings.

Redefinition of:
Method Description
ezcDocumentPdfDriver::getCurrentLineHeight() Get current line height

initialize

void initialize( )

Initialize haru documents

registerFont

void registerFont( string $name , int $type , $pathes )

Register a font

Registers a font, which can be used by its name later in the driver. The given type is either self::FONT_PLAIN or a bitwise combination of self::FONT_BOLD and self::FONT_OBLIQUE.

The third paramater specifies an array of pathes with references to font definition files. Multiple pathes may be specified to provide the same font using different types, because not all drivers may process all font types.

Parameters:
Name Type Description
$name string
$type int
$pathes array
Redefinition of:
Method Description
ezcDocumentPdfDriver::registerFont() Register a font

renderInternalLinks

void renderInternalLinks( )

Render internal links

Internal links can only be rendered at the very last items in a PDF, because *all* internal targets must already be known.

save

string save( )

Generate and return PDF

Return the generated binary PDF content as a string.

Redefinition of:
Method Description
ezcDocumentPdfDriver::save() Generate and return PDF

setMetaData

void setMetaData( string $key , string $value )

Set metadata

Set document meta data. The meta data types are identified by a list of keys, common to PDF, like: title, author, subject, created, modified.

The values are passed like embedded in the docbook document and might need to be reformatted.

Parameters:
Name Type Description
$key string
$value string
Redefinition of:
Method Description
ezcDocumentPdfDriver::setMetaData() Set metadata

setPermissions

void setPermissions( int $permissions )

Set permissions for PDF document

Parameters:
Name Type Description
$permissions int

setTextFormatting

void setTextFormatting( string $type , mixed $value )

Set text formatting option

Set a text formatting option. The names of the options are the same used in the PCSS files and need to be translated by the driver to the proper backend calls.

Parameters:
Name Type Description
$type string
$value mixed
Redefinition of:
Method Description
ezcDocumentPdfDriver::setTextFormatting() Set text formatting option

trySetFont

void trySetFont( string $name , int $style )

Try to set font

Stays with the old font, if the newly specified font is not available.

If the font does not support the given style, it falls back to the style used beforehand, and if this is also not support the plain style will be used.

Parameters:
Name Type Description
$name string
$style int
Documentation generated by phpDocumentor 1.4.3