markushausammann/prince-php

A better PHP wrapper for the awesome PrinceXML PDF creator.

This package has not been officially released yet. Use at your own risk., _(*1)

Installation

This wrapper is PSR-4 autoloading compliant and can be installed via composer. Add the following to your composer.json., _(*2)

"require": {
    "markushausammann/prince-php": "dev-master"
}

API documentation

Set prince path after instance creation

In the official library, the exePath is injected into the constructor, but that makes automatic injection of the prince service harder. Instead use the respective setter., _(*3)

$prince = new Prince();
$prince->setExePath('/your/bin/path');

Please note that the default path is /usr/local/bin/prince. So you have the option of just making sure the binary of a symlink is in that location if you're running Prince on Linux., _(*4)

On Windows, be sure to specify the path to the prince.exe file located within the Engine\bin subfolder of the Prince installation., _(*5)

Conversion methods

There are different combination of sources and end products, the (x)html markup can be provided as string or file and can be returned as file or stream., _(*6)

• convertFileToFile
• convertMultipleFiles
• convertStringToFile
• convertFileToPassthru
• convertMultipleFilesToPassthru
• convertStringToPassthru

Configuration methods

• addStyleSheet
• clearStyleSheets
• addScript
• clearScripts
• addFileAttachment
• clearFileAttachments
• setLicenseFile
• setLicenseKey
• setInputType
• setHTML
• setJavaScript
• setLog
• setBaseURL
• setXInclude
• setHttpUser
• setHttpPassword
• setHttpProxy
• setInsecure
• setFileRoot
• setEmbedFonts
• setSubsetFonts
• setArtificialFonts
• setCompress
• setPDFTitle
• setPDFSubject
• setPDFAuthor
• setPDFKeywords
• setPDFCreator
• setEncrypt
• setEncryptInfo

, _(*7)

public function convertFileToFile($xmlPath, $pdfPath = '', &$messages = array())

Convert an XML or HTML file to a PDF file. Returns true if a PDF file was generated successfully., _(*8)

`xmlPath`

The filename of the input XML or HTML document.

`pdfPath`

The filename of the output PDF file.

`msgs`

An optional array in which to return error and warning messages. Each message is returned as an array of three strings: the message code (`'err'`,`'wrn'` or`'inf'`), the message location (eg. a filename) and the message text.

`returns`

True if a PDF file was generated successfully, false otherwise.

, _(*9)

public function convertMultipleFiles($xmlPaths, $pdfPath = '', &$messages = array())

Convert multiple XML or HTML files to a PDF file. Returns true if a PDF file was generated successfully., _(*10)

`xmlPaths`

An array of the input XML or HTML documents.

`pdfPath`

The filename of the output PDF file.

`msgs`

An optional array in which to return error and warning messages. Each message is returned as an array of three strings: the message code (`'err'`,`'wrn'` or`'inf'`), the message location (eg. a filename) and the message text.

`returns`

True if a PDF file was generated successfully, false otherwise.

, _(*11)

public function convertStringToFile($xmlString, $pdfPath = '', &$messages = array())

Convert an XML or HTML string to a PDF file. Returns true if a PDF file was generated successfully., _(*12)

`xmlString`

A string containing an XML or HTML document.

`pdfPath`

The filename of the output PDF file.

`msgs`

An optional array in which to return error and warning messages. Each message is returned as an array of three strings: the message code (`'err'`,`'wrn'` or`'inf'`), the message location (eg. a filename) and the message text.

`returns`

True if a PDF file was generated successfully, false otherwise.

, _(*13)

public function convertFileToPassthru($xmlPath)

Convert an XML or HTML file to a PDF file, which will be passed through to the output buffer of the current PHP page. Returns true if a PDF file was generated successfully., _(*14)

Currently there is no mechanism to retrieve error/warning messages when using this convert method. However, thesetLog function can be used to direct messages to an external file., _(*15)

`xmlPath`

The filename of the input XML or HTML document.

`returns`

True if a PDF file was generated successfully, false otherwise.

Note that to have the browser correctly display the PDF output, the following two lines will be needed before the convert method is called:, _(*16)

header('Content-Type: application/pdf')
header('Content-Disposition: inline; filename="foo.pdf"');`

You may also specify attachment for the Content-Disposition header instead of inline, so that the browser will prompt the user to save the PDF file instead of displaying it., _(*17)

, _(*18)

public function convertMultipleFilesToPassthru($xmlPaths)

Convert multiple XML or HTML files to a PDF file, which will be passed through to the output buffer of the current PHP page. Returns true if a PDF file was generated successfully., _(*19)

Currently there is no mechanism to retrieve error/warning messages when using this convert method. However, thesetLog function can be used to direct messages to an external file., _(*20)

`xmlPaths`

An array of the input XML or HTML documents.

`returns`

True if a PDF file was generated successfully, false otherwise.

Note that to have the browser correctly display the PDF output, the following two lines will be needed before the convert method is called:, _(*21)

header('Content-Type: application/pdf')
header('Content-Disposition: inline; filename="foo.pdf"');`

You may also specify attachment for the Content-Disposition header instead of inline, so that the browser will prompt the user to save the PDF file instead of displaying it., _(*22)

, _(*23)

public function convertStringToPassthru($xmlString)

Convert an XML or HTML string to a PDF file, which will be passed through to the output buffer of the current PHP page. Returns true if a PDF file was generated successfully., _(*24)

Currently there is no mechanism to retrieve error/warning messages when using this convert method. However, thesetLog function can be used to direct messages to an external file., _(*25)

`xmlString`

A string containing an XML or HTML document.

`returns`

True if a PDF file was generated successfully, false otherwise.

Note that to have the browser correctly display the PDF output, the following two lines will be needed before the convert method is called:, _(*26)

header('Content-Type: application/pdf')
header('Content-Disposition: inline; filename="foo.pdf"');`

You may also specify attachment for the Content-Disposition header instead of inline, so that the browser will prompt the user to save the PDF file instead of displaying it., _(*27)

, _(*28)

public function addStyleSheet($cssPath)

Add a CSS style sheet that will be applied to each input document. TheaddStyleSheet function can be called more than once to add multiple style sheets. This function can called before calling a convert function., _(*29)

`cssPath`

The filename of the CSS style sheet to apply.

, _(*30)

public function clearStyleSheets()

Clear all of the CSS style sheets accumulated by callingaddStyleSheet., _(*31)

, _(*32)

public function addScript($jsPath)

Add a JavaScript script that will be run before conversion. TheaddScript function can be called more than once to add multiple scripts. This function can be called before calling a convert function., _(*33)

`jsPath`

The filename of the script to run.

, _(*34)

public function clearScripts()

Clear all of the scripts accumulated by callingaddScript., _(*35)

, _(*36)

public function addFileAttachment($filePath)

Add a file attachment that will be attached to the PDF file. TheaddFileAttachment can be called more than once to add multiple file attachments., _(*37)

`filePath`

The filename of the file attachment.

, _(*38)

public function clearFileAttachments()

Clear all of the file attachments accumulated by callingaddFileAttachment., _(*39)

, _(*40)

public function setLicenseFile($file)

Specify the license file., _(*41)

`file`

The filename of the license file.

, _(*42)

public function  setLicenseKey($key)

Specify the license key., _(*43)

`key`

The license key.

, _(*44)

public function setInputType($inputType)

Specify the input type of the document., _(*45)

`inputType`

Can take a value of : "xml", "html" or "auto".

, _(*46)

public function setHTML($html)

Specify whether documents should be parsed as HTML or XML/XHTML., _(*47)

`html`

True if all documents should be treated as HTML.

, _(*48)

public function setJavaScript($js)

Specify whether JavaScript found in documents should be run., _(*49)

`js`

True if document scripts should be run.

, _(*50)

public function setLog($logFile)

Specify a file that Prince should use to log error/warning messages., _(*51)

`logFile`

The filename that Prince should use to log error/warning messages, or '' to disable logging.

, _(*52)

public function setBaseURL($baseURL)

Specify the base URL of the input document., _(*53)

`baseURL`

The base URL or path of the input document, or ''.

, _(*54)

public function setXInclude($xinclude)

Specify whether XML Inclusions (XInclude) processing should be applied to input documents. XInclude processing will be performed by default unless explicitly disabled., _(*55)

`xinclude`

False to disable XInclude processing.

, _(*56)

public function setHttpUser($user)

Specify a username to use when fetching remote resources over HTTP., _(*57)

`user`

The username to use for basic HTTP authentication.

, _(*58)

public function setHttpPassword($password)

Specify a password to use when fetching remote resources over HTTP., _(*59)

`password`

The password to use for basic HTTP authentication.

, _(*60)

public function setHttpProxy($proxy)

Specify the URL for the HTTP proxy server, if needed., _(*61)

`proxy`

The URL for the HTTP proxy server.

, _(*62)

public function setInsecure($insecure)

Specify whether to disable SSL verification., _(*63)

, _(*64)

`insecure`

If set to true, SSL verification is disabled. (not recommended)

public function setFileRoot($fileRoot) Specify the root directory for absolute filenames. This can be used when converting a local file that uses absolute paths to refer to web resources. For example, /images/logo.jpg can be rewritten to /usr/share/images/logo.jpg by specifying "/usr/share" as the root.

`fileRoot`

The path to prepend to absolute filenames.

public function setEmbedFonts($embedFonts) Specify whether fonts should be embedded in the output PDF file. Fonts will be embedded by default unless explicitly disabled.

`embedFonts`

False to disable PDF font embedding.

public function setSubsetFonts($subsetFonts) Specify whether embedded fonts should be subset in the output PDF file. Fonts will be subset by default unless explicitly disabled.

`subsetFonts`

False to disable PDF font subsetting.

public function setArtificialFonts($artificialFonts) Specify whether artificial bold/italic fonts should be generated if necessary. Artificial fonts are enabled by default.

`artificialFonts`

False to disable artificial bold/italic fonts.

public function setCompress($compress) Specify whether compression should be applied to the output PDF file. Compression will be applied by default unless explicitly disabled.

`compress`

False to disable PDF compression.

public function setPDFTitle($pdfTitle) Specify the document title for PDF metadata. public function setPDFSubject($pdfSubject) Specify the document subject for PDF metadata. public function setPDFAuthor($pdfAuthor) Specify the document author for PDF metadata. public function setPDFKeywords($pdfKeywords) Specify the document keywords for PDF metadata. public function setPDFCreator($pdfCreator) Specify the document creator for PDF metadata. public function setEncrypt($encrypt) Specify whether encryption should be applied to the output PDF file. Encryption will not be applied by default unless explicitly enabled.

`encrypt`

True to enable PDF encryption.

public function setEncryptInfo($keyBits, $userPassword, $ownerPassword, $disallowPrint = false, $disallowModify = false, $disallowCopy = false, $disallowAnnotate = false) Set the parameters used for PDF encryption. Calling this method will also enable encryption, equivalent to calling`setEncrypt(true)`. It should be called before calling a convert method for encryption information to be applied.

`keyBits`

The size of the encryption key in bits (must be 40 or 128).

`userPassword`

The user password for the PDF file (may be empty).

`ownerPassword`

The owner password for the PDF file (may be empty).

`disallowPrint`

True to disallow printing of the PDF file.

`disallowModify`

True to disallow modification of the PDF file.

`disallowCopy`

True to disallow copying from the PDF file.

`disallowAnnotate`

True to disallow annotation of the PDF file.

Copyright © 2005-2013 YesLogic Pty. Ltd.