include/dompdf/www/install.php

   1 <?php include("head.inc");?>
   2
   3 <div id="toc">
   4 <h2>On this page:</h2>
   5 <ul>
   6 <?php echo li_arrow() ?><a href="#requirements">Requirements</a></li>
   7 <?php echo li_arrow() ?><a href="#installation">Installation</a></li>
   8 <?php echo li_arrow() ?><a href="#fonts">Font Installation</a></li>
   9 <ul>
  10 <?php echo li_arrow() ?><a href="#all_platforms">Note for all platforms</a></li>
  11 <?php echo li_arrow() ?><a href="#unix">Linux/Unix</a></li>
  12 <ul><?php echo li_arrow() ?><a href="#load_font"><pre>load_font.php</pre></a></li></ul>
  13 <?php echo li_arrow() ?><a href="#windows">Windows</a></li>
  14 </ul>
  15 <?php echo li_arrow() ?><a href="#hacking">Hacking</a></li>
  16 </ul>
  17 </div>
  18
  19 <a name="requirements"> </a>
  20 <h2>Requirements</h2>
  21
  22 <ul>
  23
  24 <li style="list-style-image: url('images/star_03.gif');">PHP 5.0.0+
  25 (although most later pre-5.0 snaps should work as well) with the DOM
  26 extension enabled.</li>
  27
  28 <li style="list-style-image: url('images/star_05.gif');">Some fonts.  PDFs
  29 internally support Helvetica, Times-Roman, Courier &amp; Zapf-Dingbats, but
  30 if you wish to use other fonts you will need to install some fonts.  dompdf
  31 supports the same fonts as the underlying PDF backends: Type 1 (.pfb
  32 with the corresponding .afm) and TrueType (.ttf).  At the minimum, you
  33 should probably have the Microsoft core fonts (now available at: <a
  34 href="http://corefonts.sourceforge.net/">http://corefonts.sourceforge.net/</a>).
  35 See <a href="#fonts">below</a> for font installation instructions.</li>
  36
  37 <li style="list-style-image: url('images/star_04.gif');">ttf2pt1 (available
  38 at <a
  39 href="http://ttf2pt1.sourceforge.net">http://ttf2pt1.sourceforge.net</a>) is
  40 required to install new ttf fonts when using the CPDF backend.</li>
  41
  42 </ul>
  43
  44 <a name="installation"> </a>
  45 <h2>Installation</h2>
  46
  47 <ol>
  48 <li>Untar/unzip the source package in a directory accessible by your webserver.</li>
  49
  50 <li>Edit dompdf_config.inc.php to fit your installation.  If you leave
  51 the DOMPDF_PDF_BACKEND setting at 'auto' dompdf will use PDFLib if it
  52 is installed, otherwise it will use the bundled R&amp;OS CPDF class.</li>
  53
  54 <li><p>Give your webserver write permission on the path specified in
  55 <code>DOMPDF_FONT_DIR</code> (lib/fonts by default).  Under *nix, ideally
  56 you can make the webserver group the owner of this directory and give the
  57 directory group write permissions.  For example, on Debian systems, apache
  58 runs as the www-data user:</p>
  59 <pre>
  60    $ chgrp www-data lib/fonts
  61    $ chmod g+w lib/fonts
  62 </pre>
  63 <p>If your user is not a member of the www-data group or you do not have
  64 root priviledges, you can make the directory world writable and set the
  65 sticky bit:</p>
  66 <pre>
  67    $ chmod 1777 lib/fonts
  68 </pre>
  69 </li>
  70 </ol>
  71
  72 <a name="fonts"> </a>
  73 <h2>Font Installation</h2>
  74
  75 <a name="all_platforms"> </a>
  76 <h3>Note for all platforms</h3>
  77
  78 <p>PDFs include support by default for Helvetica, Times-Roman, Courier and
  79 ZapfDingbats.  You do not need to install any font files if you wish to use
  80 these fonts.  This has the advantage of reducing the size of the resulting
  81 PDF, because additional fonts must be embedded in the PDF.</p>
  82
  83 <p>Also, if you have problems installing the font files, you can try and use
  84 the distributed dompdf_font_family_cache.dist file in lib/fonts.  Copy this
  85 file to lib/fonts/dompdf_font_family_cache and edit it directly to match the
  86 files present in your lib/fonts directory.</p>
  87
  88 <a name="unix"> </a>
  89 <h3>Linux/Unix</h3>
  90
  91 <p>The load_font.php utility installs and converts TrueType fonts for use with
  92 dompdf.  Since CSS uses the concept of font families (i.e. the same face can
  93 be rendered in differnt styles &amp; weights) dompdf needs to know which actual
  94 font files belong to which font family and which style.  For example, the
  95 Microsoft core font pack includes the files Verdana.ttf, Verdana_Italic.ttf,
  96 Verdana_Bold.ttf and Verdana_Bold_Italic.ttf.  All four of these files need
  97 to be present in the dompdf font directory (<code>DOMPDF_FONT_DIR</code>), and entries
  98 need to be made in the dompdf_font_family_cache file.</p>
  99
 100 <p>Given the font family name and the path to the 'normal' font face file
 101 (Verdana.ttf, in our example), load_font.php will search for the bold,
 102 italic and bold italic font face files in the same directory as the
 103 specified file.  It searches for files with the same base name followed by
 104 '_Bold', 'B', or 'b' (similarly for italic and bold italic).  If it can not
 105 find the correct files, you can specify them on the command line.</p>
 106
 107 <p>In addition to copying the files to the dompdf font directory, it also
 108 generates .afm files.  The R&amp;OS CPDF class requires both the ttf file and an
 109 afm file, which describes glyph metrics.  The afm file is generated using
 110 the ttf2pt1 utlity (available at <a
 111 href="http://ttf2pt1.sourceforge.net">http://ttf2pt1.sourceforge.net</a>).
 112 If you are using the PDFLib backend, you will not need to create afm
 113 files for the fonts.</p>
 114
 115 <a name="load_font"> </a>
 116 <p>load_font.php usage:</p>
 117
 118 <table>
 119 <tr><td class="bar1" colspan="2">&nbsp;</td></tr>
 120 <tr>
 121 <td colspan="2" class="input">$ ./load_font.php font-family n_file [b_file] [i_file] [bi_file]</td>
 122 </tr>
 123
 124 <tr>
 125 <td class="input">font_family</td>
 126 <td class="description">the name of the font, e.g. Verdana, 'Times New Roman', monospace, sans-serif.</td>
 127 </tr>
 128
 129 <tr>
 130 <td class="input">n_file</td>
 131 <td class="description">the .pfb or .ttf file for the normal, non-bold, non-italic face of the font.</td>
 132 </tr>
 133
 134 <tr>
 135 <td class="input">{b|i|bi}_file</td>
 136 <td class="description">the files for each of the respective (bold, italic, bold-italic) faces.</td>
 137 </tr>
 138
 139 <tr><td class="bar2" colspan="2">&nbsp;</td></tr>
 140 </table>
 141
 142 <p>Examples:</p>
 143 <pre>
 144 $ ./load_font.php silkscreen /usr/share/fonts/truetype/slkscr.ttf
 145
 146 $ ./load_font.php 'Times New Roman' /mnt/c_drive/WINDOWS/Fonts/times.ttf
 147
 148 $ php -f load_font.php -- sans-serif /home/dude_mcbacon/myfonts/Verdana.ttf \
 149                                      /home/dude_mcbacon/myfonts/V_Bold.ttf
 150 </pre>
 151
 152 <a name="windows"> </a>
 153 <h3>Windows</h3>
 154
 155 <p>(Note I don't have a windows test box at the moment, so these instructions
 156 may not work...  If someone has tried this and has any suggestions for me,
 157 please send me an email!)</p>
 158
 159 <p>Read the Linux/Unix section above first, as most of it applies.  The main
 160 difference is the ttf2pt1 utility.  Fortunately, there is a windows version,
 161 available at <a
 162 href="http://gnuwin32.sourceforge.net/packages/ttf2pt1.htm">http://gnuwin32.sourceforge.net/packages/ttf2pt1.htm</a>.
 163 You will have to edit your dompdf_config.inc.php file to point to the path
 164 where you installed ttf2pt1.</p>
 165
 166 <p>You will also need the cli version of PHP in order to execute
 167 load_font.php, however it's usage is the same (see the last example above).</p>
 168
 169
 170
 171 <?php include("foot.inc");?>