This document describes LNC's Prince installation including file locations and site-specific modifications which may be useful in diagnosing problems with the current installation or performing a new installation on a new or existing server.
Obtain the Prince XML RPM package here:
http://www.princexml.com/download/
Install Prince as root in the default installation directory.
This will add the following files/directories:
/usr/bin/prince/usr/lib/prince/bin/prince
You do not actually need to know this when coding using the Prince PHP class. Simply pass the path to the shell script as a parameter and Prince does the rest. The shell script is created automatically during the installation process.
/usr/lib/prince//usr/lib/prince/license/license.dat
<license id=”1000101″>
<name>Server License (Academic)</name>
<vendor>YesLogic</vendor>
<product>Prince</product>
<version>5.1</version>
<end-user>The University of North Carolina at Chapel Hill</end-user>
<date>2006-09-06</date>
<signature>46F4DE5F793EDE559973D099105BBEE7</signature>
<option id=”upgrades”>20070906</option>
</license>
The above license is valid with Prince version 6.0 (currently rev 2) even though the license itself specifies version 5.1.
/usr/lib/prince/style/fonts.css
We modified this file in order to eliminate error messages, as the default Prince installation assumes the existence of some font paths that do not exist on our servers.
There are two scripts that enable Prince to work with PHP in our installation. One is a Prince PHP class supplied by the fine folks at Prince XML, and the other is an interface script written for use here at LEARN NC that allows our systems to use the vendor-supplied PHP class.
The vendor-supplied script may be obtained here (zipped archive):
http://www.princexml.com/download/accessories/
The zipped archive should be uncompressed into the following directory:
/var/www/html/lp/includes/prince/
The Prince PHP class is contained in the following file from the above archive:
/var/www/html/lp/includes/prince/prince.php
We use this script exactly as supplied by the vendor (unmodified), so, in theory, we should be able to replace it with new versions as they are released and nothing should break. In practice this has not always been true, though the current version has proved to be reliable in service. The previous prince.php script had a bug which caused the conversion method to return false even after the successful rendering of a PDF output file, but the current script responds correctly and predictably and required no modifications for use with our systems. Because of this, it may be prudent to leave it alone rather than choose to upgrade it each time a new script is released, unless we have a need for a specific piece of new functionality not provided by the current version. The script provides a couple of different conversion methods, and we use the one known as “convert2” here at LNC. The zipped archive includes a README.TXT file that documents the use of the vendor-supplied PHP class script which may prove to be useful if we wish to expand our use of Prince at some point in the future. Among the unused options are various switches to regulate the use of the PDF output file after download including password protection as well as disallowing printing, modifying, copying, or annotation.
The second script is located here:
/var/www/html/lp/admin/pdf_gen.php
This script includes (requires) the vendor-supplied script, and handles all of the necessary support operations to allow the vendor-supplied script to work. There are a few methods of interest. The first method sets the error log location. The second is used to clear any existing stylesheets that have been set in the Prince object (probably not necessary, but keeps things tidy), while the third sets the stylesheet for the document that is about to be rendered. Finally, the convert2 method performs the actual PDF rendering.
Here is a snippet of code from pdf_gen:
$newpdf = new Prince($exepath);
$newpdf->setLog(’/var/www/html/lp/pdf/prince_errors.log’);
$newpdf->clearStyleSheets();
$newpdf->addStyleSheet($csspath);
$result = $newpdf->convert2($xmlpath, $pdfpath);
The above code is the bit that actually performs the PDF rendering. The rest is largely support code to prepare for, log, and clean up after the rendering transaction. pdf_gen uses cURL to intercept the LearnPress-rendered page and then write it temporarily to the filesystem in HTML form for Prince’s use during the PDF rendering process. This is necessary because the convert2 method requires an actual filesystem file as input if you wish to have an actual filesystem file as output, (and we do, as we keep the rendered files in /lp/pdf rather than render them on-the-fly with each request). This is a useful item to know when troubleshooting, as it is very easy to comment out the cleanup line in pdf_gen that normally deletes the HTML input file after processing so that you can use it during manual rendering (which is typically done only when there is a problem). Incidentally, the convert3 method supposedly allows conversion to file or browser stream from streamed input, but it proved difficult to get this to work in practice, so we are using convert2.
If you wish to retain the source HTML file generated by LearnPress for use in troubleshooting Prince via command line, comment out the following line in pdf_gen:
unlink($temppath);
This will leave the source HTML file intact in /lp/pdf.
One quick and not-terribly-soiled way to ascertain the result of a given PDF rendering is to check the Prince error log which is located here:
/lp/pdf/prince_errors.log
This log records whether or not the file in question rendered successfully as well as many other useful things including any HTML formatting errors in the source document, image format problems, font problems, character set issues, etc. The newest entries are at the bottom of the file.
The next logical step in troubleshooting any Prince issue is to attempt to render the PDF file via command line. This is probably best done from within the /lp/pdf directory, and you will likely need to use sudo so that you have the necessary permissions to allow Prince to write the PDF output file in the specified directory.
Here are two examples of the command line rendering of a PDF document using Prince.
First, the easy way:
cd /var/www/html/lp/pdf
sudo prince inputfilename.html --debug
The output from --debug will go to standard output. The output filename will be the same as the input filename except it will have a PDF extension. The --debug switch should be included if you desire verbose output, but it is not strictly necessary for troubleshooting, as Prince automatically sends any errors to standard output (albeit in abbreviated form).
Now the more complex way, in which the input type, style sheet, input file, and output file are explicitly specified:
cd /var/www/html/lp/pdf
sudo prince -i html inputfilename.html -s /path/to/print/stylesheet.css -o ./outputfilename.pdf --debug
These techniques should provide enough useful information to help resolve nearly any issue that may arise. If not, then the vendor’s support forum at Prince XML is a good resource to explore. Your question may have been asked in the forum before, and may already have an answer posted. If not, you may post your question and the vendor will usually respond promptly.
The Prince XML support forum can be found here:
http://www.princexml.com/bb/