Prince PHP class

The prince.php file defines a class called Prince that contains methods that can be called to convert XML and HTML documents into PDF.

Note that the Prince class requires PHP 5, and will not work as is with PHP 4.

Constructor

When instantiating the Prince class, pass in the full path of the prince executable to the constructor as a string argument. For example, on Linux or MacOS X:

$prince = new Prince('/usr/local/bin/prince');

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

Conversion methods

public function convert_file($xmlPath, &$msgs = array())

Convert an XML or HTML file to a PDF file. The name of the output PDF file will be the same as the name of the input file but with an extension of ".pdf". Returns true if a PDF file was generated successfully.

xmlPath: The filename of the input XML or HTML document.
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.
return: True if a PDF file was generated successfully, false otherwise.

public function convert_file_to_file($xmlPath, $pdfPath, &$msgs = array())

Convert an XML or HTML file to a PDF file. Returns true if a PDF file was generated successfully.

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.
return: True if a PDF file was generated successfully, false otherwise.

public function convert_string_to_passthru($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.

Currently there is no mechanism to retrieve error/warning messages when using this convert method. However, the setLog function can be used to direct messages to an external file.

xmlString: A string containing an XML or HTML document.
return: 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:

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.

public function convert_string_to_file($xmlString, $pdfPath, &$msgs = array())

Convert an XML or HTML string to a PDF file. Returns true if a PDF file was generated successfully.

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.
return: True if a PDF file was generated successfully, false otherwise.

Configuration methods

public function addStyleSheet($cssPath)

Add a CSS style sheet that will be applied to each input document. The addStyleSheet function can be called more than once to add multiple style sheets. This function should be called before calling a convert function.

cssPath: The filename of the CSS style sheet to apply.

public function clearStyleSheets()

Clear all of the CSS style sheets accumulated by calling addStyleSheet.

public function setHTML($html)

Specify whether documents should be parsed as HTML or XML/XHTML.

html: True if all documents should be treated as HTML.

public function setLog($logFile)

Specify a file that Prince should use to log error/warning messages.

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

public function setBaseURL($baseURL)

Specify the base URL of the input document.

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

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.

xinclude: False to disable XInclude processing.

public function setHttpUser($user)

Specify a username to use when fetching remote resources over HTTP.

user: The username to use for basic HTTP authentication.

public function setHttpPassword($password)

Specify a password to use when fetching remote resources over HTTP.

password: The password to use for basic HTTP authentication.

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 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 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.