]>
Commit | Line | Data |
---|---|---|
4188f38a | 1 | Installation |
2 | ============ | |
3 | * Download the .zip file and unzip it | |
4 | * Create a folder e.g. /mpdf on your server | |
5 | * Upload all of the files to the server, maintaining the folders as they are | |
6 | * Ensure that you have write permissions set (CHMOD 6xx or 7xx) for the following folders: | |
7 | /ttfontdata/ - used to cache font data; improves performance a lot | |
8 | /tmp/ - used for some images and ProgressBar | |
9 | /graph_cache/ - if you are using JpGraph in conjunction with mPDF | |
10 | ||
11 | To test the installation, point your browser to the basic example file : [path_to_mpdf_folder]/mpdf/examples/example_basic.php | |
12 | ||
13 | If you wish to define a different folder for temporary files rather than /tmp/ see the note on 'Folder for temporary files' in | |
14 | the section on Installation & Setup in the manual (http://mpdf1.com/manual/). | |
15 | ||
16 | If you have problems, please read the section on troubleshooting in the manual. | |
17 | ||
18 | ||
19 | Fonts | |
20 | ===== | |
21 | I will refer to font names in 2 ways: | |
22 | "CSS font-family name" - mPDF is designed primarily to read HTML and CSS. This is the name used in CSS e.g. | |
23 | <p style="font-family: 'Trebuchet MS';"> | |
24 | ||
25 | "mPDF font-family name" - the name used internally to process fonts. This could be anything you like, | |
26 | but by default mPDF will convert CSS font-family names by removing any spaces and changing | |
27 | to lowercase. Reading the name above, mPDF will look for a "mPDF font-family name" of | |
28 | 'trebuchetms'. | |
29 | ||
30 | The configurable values referred to below are set in the config_fonts.php file | |
31 | ||
32 | When parsing HTML/CSS, mPDF will read the CSS font-family name (e.g. 'Trebuchet MS') and convert | |
33 | by removing any spaces and changing to lowercase, to look for a mPDF font-family name (trebuchetms). | |
34 | ||
35 | Next it will look for a translation (if set) e.g.: | |
36 | $this->fonttrans = array( | |
37 | 'trebuchetms' => 'trebuchet' | |
38 | ) | |
39 | ||
40 | Now the mPDF font-family name to be used is 'trebuchet' | |
41 | ||
42 | If you wish to make this font available, you need to specify the Truetype .ttf font files for each variant. | |
43 | These should be defined in the array: | |
44 | $this->fontdata = array( | |
45 | "trebuchet" => array( | |
46 | 'R' => "trebuc.ttf", | |
47 | 'B' => "trebucbd.ttf", | |
48 | 'I' => "trebucit.ttf", | |
49 | 'BI' => "trebucbi.ttf", | |
50 | ) | |
51 | ) | |
52 | ||
53 | This is the array which determines whether a font is available to mPDF. Each font-family must have a | |
54 | Regular ['R'] file defined - the others (bold, italic, bold-italic) are optional. | |
55 | ||
56 | mPDF will try to load the font-file. If you have defined _MPDF_SYSTEM_TTFONTS at the top of the | |
57 | config_fonts.php file, it will first look for the font-file there. This is useful if you are running | |
58 | mPDF on a computer which already has a folder with TTF fonts in (e.g. on Windows) | |
59 | ||
60 | If the font-file is not there, or _MPDF_SYSTEM_TTFONTS is not defined, mPDF will look in the folder | |
61 | /[your_path_to_mpdf]/ttfonts/ | |
62 | ||
63 | Note that the font-file names are case-sensitive and can contain capitals. | |
64 | ||
65 | If the folder /ttfontdata/ is writeable (CHMOD 644 or 755), mPDF will save files there which it can | |
66 | re-use next time it accesses a particular font. This will significantly improve processing time | |
67 | and is strongly recommended. | |
68 | ||
69 | mPDF should be able to read most TrueType Unicode font files with a .ttf extension | |
70 | Truetype fonts with .ttf extension that are OpenType also work OK. | |
71 | TrueType collections (.ttc) will also work if they contain TrueType Unicode fonts. | |
72 | ||
73 | ||
74 | Character substitution | |
75 | ---------------------- | |
76 | Most people will have access to a Pan-Unicode font with most Unicode characters in it such as | |
77 | Arial Unicode MS. Set $this->backupSubsFont = array('arialunicodems'); at the top of the config_fonts.php file | |
78 | to use this font when substituting any characters not found in the specific font being used. | |
79 | ||
80 | Example: | |
81 | You can set $mpdf->useSubstitutions = true; at runtime | |
82 | or $this->useSubstitutions = true; in the config.php file | |
83 | ||
84 | <p style="font-family: 'Comic Sans MS'">This text contains a Thai character ม which does not exist | |
85 | in the Comic Sans MS font file</p> | |
86 | ||
87 | When useSubstitutions is true, mPDF will try to find substitutions for any missing characters: | |
88 | 1) firstly looks if the character is available in the inbuilt Symbols or ZapfDingbats fonts; | |
89 | 2) [If defined] looks in each of the the font(s) set by $this->backupSubsFont array | |
90 | ||
91 | NB There is an increase in processing time when using substitutions, and even more so if | |
92 | a backupSubsFont is defined. | |
93 | ||
94 | Controlling mPDF mode | |
95 | ===================== | |
96 | The first parameter of new mPDF('') works as follows: | |
97 | new mPDF('c') - forces mPDF to only use the built-in [c]ore Adobe fonts (Helvetica, Times etc) | |
98 | ||
99 | new mPDF('') - default - font subsetting behaviour is determined by the configurable variables | |
100 | $this->maxTTFFilesize and $this->percentSubset (see below) | |
101 | Default values are set so that: 1) very large font files are always subset | |
102 | 2) Fonts are embedded as subsets if < 30% of the characters are used | |
103 | ||
104 | new mPDF('..-x') - used together with a language or language/country code, this will cause | |
105 | mPDF to use only in-built core fonts (Helvetica, Times) if the language specified is appropiate; | |
106 | otherwise it will force subsetting (equivalent to using "") | |
107 | e.g. new mPDF('de-x') or new mPDF('pt-BR-x') will use in-built core fonts | |
108 | and new mPDF('ru-x') will use subsets of any available TrueType fonts | |
109 | The languages that use core fonts are defined in config_cp.php (using the value $coreSuitable). | |
110 | ||
111 | new mPDF('..+aCJK') new mPDF('+aCJK') | |
112 | new mPDF('..-aCJK') new mPDF('-aCJK') | |
113 | - used optionally together with a language or language/country code, +aCJK will force mPDF | |
114 | to use the Adobe non-embedded CJK fonts when a passage is marked with e.g. "lang: ja" | |
115 | This can be used at runtime to override the value set for $mpdf->useAdobeCJK in config.php | |
116 | Use in conjunction with settings in config_cp.php | |
117 | ||
118 | For backwards compatibility, new mPDF('-s') and new mPDF('s') will force subsetting by | |
119 | setting $this->percentSubset=100 (see below) | |
120 | new mPDF('utf-8-s') and new mPDF('ar-s') are also recognised | |
121 | ||
122 | Language/Country (ll-cc) | |
123 | ------------------------ | |
124 | You can use a language code ('en') or language/country code ('en-GB') to control which | |
125 | mode/fonts are used. The behaviour is set up in config_cp.php file. | |
126 | The default settings show some of the things you can do: | |
127 | new mPDF('de') - as German is a Western European langauge, it is suitable to use the Adobe core fonts. | |
128 | Using 'de' alone will do nothing, but if you use ('de-x'), this will use core fonts. | |
129 | new mPDF('th') - many fonts do not contain the characters necessary for Thai script. The value $unifonts | |
130 | defines a restricted list of fonts available for mPDF to use. | |
131 | ||
132 | NB <html dir="rtl"> or <body dir="rtl"> are supported. | |
133 | ||
134 | ||
135 | ||
136 | Configuration variables changed | |
137 | =============================== | |
138 | Configuration variables are documented in the on-line manual (http://mpdf1.com/manual/). | |
139 | ||
140 | ||
141 | Font folders | |
142 | ============ | |
143 | If you wish to define your own font file folders (perhaps to share), | |
144 | you can define the 2 constants in your script before including the mpdf.php script e.g.: | |
145 | ||
146 | define('_MPDF_TTFONTPATH','your_path/ttfonts/'); | |
147 | define('_MPDF_TTFONTDATAPATH','your_path/ttfontdata/'); // should be writeable | |
148 |