/libs/DomPDF/www/usage.php
PHP | 532 lines | 516 code | 16 blank | 0 comment | 5 complexity | 47e1499856eb43233af2a8c764092bed MD5 | raw file
Possible License(s): LGPL-2.1, BSD-3-Clause
- <?php include("head.inc"); ?>
- <div id="toc">
- <h2>On this page:</h2>
- <ul>
- <?php echo li_arrow() ?><a href="#usage">Usage</a></li>
- <ul><?php echo li_arrow() ?><a href="#web">Invoking via the web</a></li>
- <?php echo li_arrow() ?><a href="#cli">Invoking via the command line</a></li>
- <?php echo li_arrow() ?><a href="#class">Using the dompdf class directly</a></li>
- <?php echo li_arrow() ?><a href="#method_summary">dompdf class reference</a></li>
- </ul>
- <?php echo li_arrow() ?><a href="#inline">Inline PHP support</a></li>
- </ul>
- </div>
- <a name="usage"> </a>
- <h2>Usage</h2>
- <p>The dompdf.php script included in the distribution can be used both from
- the <a href="#cli">command line</a> or via a <a href="#web">web browser</a>.
- Alternatively, the dompdf class can be used <a href="#class">directly</a>.</p>
- <a name="web"> </a>
- <h3>Invoking dompdf via the web</h3>
- <p>The dompdf.php script is not intended to be an interactive page. It
- receives input parameters via $_GET and can stream a PDF directly to the
- browser. This makes it possible to embed links to the script in a page that
- look like static PDF links, but are actually dynamically generated. This
- method is also useful as a redirection target.</p>
- <p>dompdf.php accepts the following $_GET variables:</p>
- <table>
- <tr><td class="bar1" colspan="3"> </td></tr>
- <tr>
- <td class="input">input_file</td> <td>required</td>
- <td class="description">a rawurlencoded() path to the HTML file to process. Remote files
- (http/ftp) are supported if fopen wrappers are enabled.</td>
- </tr>
- <tr>
- <td class="input">paper</td> <td>optional</td>
- <td class="description">the paper size. Defaults to 'letter' (unless the default has been
- changed in dompdf_config.inc.php). See include/pdf_adapter.cls.php, or
- invoke dompdf.php on the command line with the -l switch for accepted paper
- sizes.</td>
- </tr>
- <tr>
- <td class="input">orientation</td> <td>optional</td>
- <td class="description">'portrait' or 'landscape'. Defaults to 'portrait'.</td>
- </tr>
- <tr>
- <td class="input">base_path</td> <td>optional</td>
- <td class="description">the base path to use when resolving relative links (images or CSS
- files). Defaults to the directory containing the file being accessed.
- (This option is useful for pointing dompdf at your CSS files even though the
- HTML file may be elsewhere.)</td>
- </tr>
- <tr>
- <td class="input">output_file</td> <td>optional</td>
- <td class="description">the rawurlencoded() name of the output file. Defaults to 'dompdf_out.pdf'.</td>
- </tr>
- <tr>
- <td class="input">save_file</td> <td>optional</td>
- <td class="description">If present (i.e. <code>isset($_GET["save_file"]) == true');</code>),
- output_file is saved locally, Otherwise the file is streamed directly to the client.</td>
- </tr>
- <tr><td class="bar2" colspan="3"> </td></tr>
- </table>
- <p>One technique for generating dynamic PDFs is to generate dynamic HTML as you
- normally would, except instead of displaying the output to the browser, you
- use output buffering and write the output to a temporary file. Once this
- file is saved, you redirect to the dompdf.php script. If you use a
- templating engine like Smarty, you can simply do:</p>
- <pre>
- <?php
- $tmpfile = tempnam("/tmp", "dompdf_");
- file_put_contents($tmpfile, $smarty->fetch()); // Replace $smarty->fetch()
- // with your HTML string
- $url = "dompdf.php?input_file=" . rawurlencode($tmpfile) .
- "&paper=letter&output_file=" . rawurlencode("My Fancy PDF.pdf");
- header("Location: http://" . $_SERVER["HTTP_HOST"] . "/$url");
- ?>
- </pre>
- <p>If you use any stylesheets, you may need to provide the
- <code>base_path</code> option to tell dompdf where to look for them, as they
- are not likely relative to /tmp ;).</p>
- <a name="cli"> </a>
- <h3>Invoking dompdf via the command line</h3>
- <p>You can execute dompdf.php using the following command:</p>
- <pre>$ php -f dompdf.php -- [options]</pre>
- <p>(If you find yourself using only the cli interface, you can add
- <code>#!/usr/bin/php</code> as the first line of dompdf.php to invoke dompdf.php
- directly.)</p>
- <p>dompdf.php is invoked as follows:</p>
- <table>
- <tr><td class="bar1" colspan="2"> </td></tr>
- <tr>
- <td colspan="2" class="input">$ ./dompdf.php [options] html_file</td>
- </tr>
- <tr>
- <td colspan="2"><code>html_file</code> can be a filename, a url if
- fopen_wrappers are enabled, or the '-' character to read from standard input.</td>
- </tr>
- <tr>
- <td class="input">-h</td>
- <td class="description">Show a brief help message</td>
- </tr>
- <tr>
- <td class="input">-l</td>
- <td class="description">list available paper sizes</td>
- </tr>
- <tr>
- <td class="input">-p size</td>
- <td class="description">paper size; something like 'letter', 'A4', 'legal', etc. Thee default is 'letter'</td>
- </tr>
- <tr>
- <td class="input">-o orientation</td>
- <td class="description">either 'portrait' or 'landscape'. Default is 'portrait'.</td>
- </tr>
- <tr>
- <td class="input">-b path</td>
- <td class="description">the base path to use when resolving relative links
- (images or CSS files). Default is the directory of html_file.</td>
- </tr>
- <tr>
- <td class="input">-f file</td>
- <td class="description">the output filename. Default is the input <code>[html_file].pdf</code>.</td>
- </tr>
- <tr>
- <td class="input">-v</td>
- <td class="description">verbose: display html parsing warnings and file not found errors.</td>
- </tr>
- <tr>
- <td class="input">-d</td>
- <td class="description">very verbose: display oodles of debugging output;
- every frame in the tree is printed to stdout.</td>
- </tr>
- <tr><td class="bar2" colspan="2"> </td></tr>
- </table>
- <p>Examples:</p>
- <pre>
- $ php -f dompdf.php -- my_resume.html
- $ ./dompdf.php -b /var/www/ ./web_stuff/index.html
- $ echo '<html><body>Hello world!</body></html>' | ./dompdf.php -
- </pre>
- <a name="class"> </a>
- <h3>Using the dompdf class directly</h3>
- <p>Using the dompdf class directly is fairly straightforward:
- <pre>
- <?php
- require_once("dompdf_config.inc.php");
- $html =
- '<html><body>'.
- '<p>Put your html here, or generate it with your favourite '.
- 'templating system.</p>'.
- '</body></html>';
- $dompdf = new DOMPDF();
- $dompdf->load_html($html);
- $dompdf->render();
- $dompdf->stream("sample.pdf");
- ?>
- </pre></p>
- <p>Below is a summary of the methods available in the dompdf class. For complete details,
- see the <a href="http://www.digitaljunkies.ca/dompdf/doc/">API
- documentation</a> for the class interface definition.</p>
- <a name="method_summary"> </a>
- <h3>Method Summary</h3>
- <ul class="method-summary">
- <?php echo li_arrow() ?><span class="method-result">DOMPDF</span> <a href="#method__construct">__construct</a>()</li>
- <?php echo li_arrow() ?><span class="method-result">string</span> <a href="#methodget_base_path">get_base_path</a>()</li>
- <?php echo li_arrow() ?><span class="method-result">string</span> <a href="#methodget_host">get_host</a>()</li>
- <?php echo li_arrow() ?><span class="method-result">string</span> <a href="#methodget_protocol">get_protocol</a>()</li>
- <?php echo li_arrow() ?><span class="method-result">Frame_Tree</span> <a href="#methodget_tree">get_tree</a>()</li>
- <?php echo li_arrow() ?><span class="method-result">void</span> <a href="#methodload_html">load_html</a>(<span class="var-type">string</span> <span class="var-name">$str</span>)</li>
- <?php echo li_arrow() ?><span class="method-result">void</span> <a href="#methodload_html_file">load_html_file</a>(<span class="var-type">string</span> <span class="var-name">$file</span>)</li>
- <?php echo li_arrow() ?><span class="method-result">string</span> <a href="#methodoutput">output</a>()</li>
- <?php echo li_arrow() ?><span class="method-result">void</span> <a href="#methodrender">render</a>()</li>
- <?php echo li_arrow() ?><span class="method-result">void</span> <a href="#methodset_base_path">set_base_path</a>(<span class="var-type">string</span> <span class="var-name">$path</span>)</li>
- <?php echo li_arrow() ?><span class="method-result">void</span> <a href="#methodset_host">set_host</a>(<span class="var-type">string</span> <span class="var-name">$host</span>)</li>
- <?php echo li_arrow() ?><span class="method-result">void</span> <a href="#methodset_paper">set_paper</a>(<span class="var-type">string</span> <span class="var-name">$size</span>, [<span class="var-type">string</span> <span class="var-name">$orientation</span> = "portrait"])</li>
- <?php echo li_arrow() ?><span class="method-result">void</span> <a href="#methodset_protocol">set_protocol</a>(<span class="var-type">string</span> <span class="var-name">$proto</span>)</li>
- <?php echo li_arrow() ?><span class="method-result">void</span> <a href="#methodstream">stream</a>(<span class="var-type">string</span> <span class="var-type">$filename</span>, [<span class="var-type">mixed</span> <span class="var-name">$options</span> = null])</li>
- </ul>
- <div class="method-definition" style="background-position: 10px bottom;">
- <a name="method__construct" id="__construct"><!-- --></a>
- <div class="method-header">
- <span class="method-title">Constructor __construct</span> (line <span class="line-number">163</span>)
- </div>
- <p class="short-description">Class constructor</p>
- <div class="method-signature">
- <span class="method-result">DOMPDF</span>
- <span class="method-name">__construct</span>()
- </div>
- </div>
- <div class="method-definition" style="background-position: 302px bottom;">
- <a name="methodget_base_path" id="get_base_path"><!-- --></a>
- <div class="method-header">
- <span class="method-title">get_base_path</span> (line <span class="line-number">227</span>)
- </div>
- <p class="short-description">Returns the base path</p>
- <div class="method-signature">
- <span class="method-result">string</span>
- <span class="method-name">get_base_path</span>()
- </div>
- </div>
- <div class="method-definition" style="background-position: 710px bottom;">
- <a name="methodget_canvas" id="get_canvas"><!-- --></a>
- <div class="method-header">
- <span class="method-title">get_canvas</span> (line <span class="line-number">234</span>)
- </div>
- <p class="short-description">Return the underlying Canvas instance (e.g. CPDF_Adapter, GD_Adapter)</p>
- <div class="method-signature">
- <span class="method-result">Canvas</span>
- <span class="method-name">get_canvas</span>()
- </div>
- </div>
- <div class="method-definition" style="background-position: 252px bottom;">
- <a name="methodget_host" id="get_host"><!-- --></a>
- <div class="method-header">
- <span class="method-title">get_host</span> (line <span class="line-number">220</span>)
- </div>
- <p class="short-description">Returns the base hostname</p>
- <div class="method-signature">
- <span class="method-result">string</span>
- <span class="method-name">get_host</span>()
- </div>
- </div>
- <div class="method-definition" style="background-position: 498px bottom;">
- <a name="methodget_protocol" id="get_protocol"><!-- --></a>
- <div class="method-header">
- <span class="method-title">get_protocol</span> (line <span class="line-number">213</span>)
- </div>
- <p class="short-description">Returns the protocol in use</p>
- <div class="method-signature">
- <span class="method-result">string</span>
- <span class="method-name">get_protocol</span>()
- </div>
- </div>
- <div class="method-definition" style="background-position: 39px bottom;">
- <a name="methodget_tree" id="get_tree"><!-- --></a>
- <div class="method-header">
- <span class="method-title">get_tree</span> (line <span class="line-number">182</span>)
- </div>
- <p class="short-description">Returns the underlying Frame_Tree object</p>
- <div class="method-signature">
- <span class="method-result">Frame_Tree</span>
- <span class="method-name">get_tree</span>()
- </div>
- </div>
- <div class="method-definition" style="background-position: 653px bottom;">
- <a name="methodload_html" id="load_html"><!-- --></a>
- <div class="method-header">
- <span class="method-title">load_html</span> (line <span class="line-number">272</span>)
- </div>
- <p class="short-description">Loads an HTML string</p>
- <p class="description"><p>Parse errors are stored in the global array _dompdf_warnings.</p></p>
- <div class="method-signature">
- <span class="method-result">void</span>
- <span class="method-name">load_html</span>(<span class="var-type">string</span> <span class="var-name">$str</span>)
- </div>
-
- <ul class="parameters">
- <li>
- <span class="var-type">string</span>
- <span class="var-name">$str</span><span class="var-description">: HTML text to load</span></li>
- </ul>
- </div>
- <div class="method-definition" style="background-position: 479px bottom;">
- <a name="methodload_html_file" id="load_html_file"><!-- --></a>
- <div class="method-header">
- <span class="method-title">load_html_file</span> (line <span class="line-number">245</span>)
- </div>
- <p class="short-description">Loads an HTML file</p>
- <p class="description"><p>Parse errors are stored in the global array _dompdf_warnings.</p></p>
- <div class="method-signature">
- <span class="method-result">void</span>
- <span class="method-name">load_html_file</span>(<span class="var-type">string</span> <span class="var-name">$file</span>)
- </div>
-
- <ul class="parameters">
- <li>
- <span class="var-type">string</span>
- <span class="var-name">$file</span><span class="var-description">: a filename or url to load</span></li>
- </ul>
- </div>
- <div class="method-definition" style="background-position: 182px bottom;">
- <a name="methodoutput" id="output"><!-- --></a>
- <div class="method-header">
- <span class="method-title">output</span> (line <span class="line-number">451</span>)
- </div>
- <p class="short-description">Returns the PDF as a string</p>
- <div class="method-signature">
- <span class="method-result">string</span>
- <span class="method-name">output</span>()
- </div>
- </div>
- <div class="method-definition" style="background-position: 741px bottom;">
- <a name="methodrender" id="render"><!-- --></a>
- <div class="method-header">
- <span class="method-title">render</span> (line <span class="line-number">373</span>)
- </div>
- <p class="short-description">Renders the HTML to PDF</p>
-
- <div class="method-signature">
- <span class="method-result">void</span>
- <span class="method-name">render</span>()
- </div>
- </div>
- <div class="method-definition" style="background-position: 824px bottom;">
- <a name="methodset_base_path" id="set_base_path"><!-- --></a>
- <div class="method-header">
- <span class="method-title">set_base_path</span> (line <span class="line-number">206</span>)
- </div>
- <p class="short-description">Sets the base path</p>
- <div class="method-signature">
- <span class="method-result">void</span>
- <span class="method-name">set_base_path</span>(<span class="var-type">string</span> <span class="var-name">$path</span>)
- </div>
-
- <ul class="parameters">
- <li>
- <span class="var-type">string</span>
- <span class="var-name">$path</span></li>
- </ul>
- </div>
- <div class="method-definition" style="background-position: 519px bottom;">
- <a name="methodset_host" id="set_host"><!-- --></a>
- <div class="method-header">
- <span class="method-title">set_host</span> (line <span class="line-number">199</span>)
- </div>
- <p class="short-description">Sets the base hostname</p>
-
- <div class="method-signature">
- <span class="method-result">void</span>
- <span class="method-name">set_host</span>(<span class="var-type">string</span> <span class="var-name">$host</span>)
- </div>
-
- <ul class="parameters">
- <li>
- <span class="var-type">string</span>
- <span class="var-name">$host</span></li>
- </ul>
- </div>
- <div class="method-definition" style="background-position: 391px bottom;">
- <a name="methodset_paper" id="set_paper"><!-- --></a>
- <div class="method-header">
- <span class="method-title">set_paper</span> (line <span class="line-number">353</span>)
- </div>
- <p class="short-description">Sets the paper size & orientation</p>
-
- <div class="method-signature">
- <span class="method-result">void</span>
- <span class="method-name">set_paper</span>(<span class="var-type">string</span> <span class="var-name">$size</span>, [<span class="var-type">string</span> <span class="var-name">$orientation</span> = <span class="var-default">"portrait"</span>])
- </div>
-
- <ul class="parameters">
- <li>
- <span class="var-type">string</span>
- <span class="var-name">$size</span><span class="var-description">: 'letter', 'legal', 'A4', etc. See CPDF_Adapter::$PAPER_SIZES</span></li>
- <li>
- <span class="var-type">string</span>
- <span class="var-name">$orientation</span><span class="var-description">: 'portrait' or 'landscape'</span></li>
- </ul>
- </div>
- <div class="method-definition" style="background-position: 672px bottom;">
- <a name="methodset_protocol" id="set_protocol"><!-- --></a>
- <div class="method-header">
- <span class="method-title">set_protocol</span> (line <span class="line-number">192</span>)
- </div>
- <p class="short-description">Sets the protocol to use (http://, file://, ftp:// etc.)</p>
-
- <div class="method-signature">
- <span class="method-result">void</span>
- <span class="method-name">set_protocol</span>(<span class="var-type">string</span> <span class="var-name">$proto</span>)
- </div>
-
- <ul class="parameters">
- <li>
- <span class="var-type">string</span>
- <span class="var-name">$proto</span></li>
- </ul>
- </div>
- <div class="method-definition" style="background-position: 146px bottom;">
- <a name="methodstream" id="stream"><!-- --></a>
- <div class="method-header">
- <span class="method-title">stream</span> (line <span class="line-number">441</span>)
- </div>
- <p class="short-description">Streams the PDF to the client</p>
- <p class="description">
- <p>The file will always open a download dialog. The options parameter
- controls the output headers. Accepted headers
- are:<br/><br/>
- 'Accept-Ranges' => 1 or 0 - if this is not set to 1, then this
- header is not included, off by default. This header seems to have
- caused some problems despite the fact that it is supposed to solve
- them, so I am leaving it off by default.<br/><br/>
- 'compress' = > 1 or 0 - apply content stream compression, this is
- on (1) by default<br/><br/>
- 'Attachment' => 1 or 0 - if 1, force the browser to open a download
- dialog, on (1) by default</p>
- </p>
-
- <div class="method-signature">
- <span class="method-result">void</span>
- <span class="method-name">stream</span>(<span class="var-type">string</span> <span class="var-name">$filename</span>, [<span class="var-type">array</span> <span class="var-name">$options</span> = <span class="var-default">null</span>])
- </div>
-
- <ul class="parameters">
- <li>
- <span class="var-type">string</span>
- <span class="var-name">$filename</span><span class="var-description">: the name of the streamed file</span> </li>
- <li>
- <span class="var-type">array</span>
- <span class="var-name">$options</span><span class="var-description">: header options (see above)</span> </li>
- </ul>
- </div>
- <a name="inline"> </a>
- <h2>Inline PHP Support</h2>
- <p>dompdf supports two varieties of inline PHP code. All PHP evaluation is
- controlled by the <code>DOMPDF_ENABLE_PHP</code> configuration option. If it is set to
- false, then no PHP code is executed. Otherwise, PHP is evaluated in two
- passes:</p>
- <p>The first pass is useful for inserting dynamic data into your PDF. You can
- do this by embedding <?php ?> tags in your HTML file, as you would in a
- normal .php file. This code is evaluated prior to parsing the HTML, so you
- can echo any text or markup and it will appear in the rendered PDF.</p>
- <p>The second pass is useful for performing drawing operations on the
- underlying PDF class directly. You can do this by embedding PHP code within
- <script type="text/php"> </script> tags. This code is evaluated
- during the rendering phase and you have access to a few internal objects and
- operations. In particular, the <code>$pdf</code> variable is the current instance of
- Canvas. Using this object, you can write and draw directly on the
- current page. Using the <code>Canvas::open_object()</code>,
- <code>Canvas::close_object()</code> and
- <code>Canvas::add_object()</code> methods, you can create text and
- drawing objects that appear on every page of your PDF (useful for headers &
- footers).</p>
- <p>The following variables are defined for you during the second pass of PHP
- execution:</p>
- <pre>
- $pdf the current instance of Canvas
- $PAGE_NUM the current page number
- $PAGE_COUNT the total number of pages in the document
- </pre>
- <p>For more complete documentation of the Canvas API, see the <a
- href="http://www.digitaljunkies.ca/dompdf/doc/">API documentation</a>.</p>
- <?php include("foot.inc"); ?>