README_4_2.txt 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389
  1. ===========================
  2. mPDF v4.2 (27/01/2010)
  3. ===========================
  4. Bug fixes
  5. ---------
  6. - empty variable (undefined var, false, null, array() etc.) sent to WriteHTML produced error message "Invalid UTF-8"
  7. - CJK in tables when not using CJK (utf-8-s) autosized very small as characters did not word-wrap
  8. - parsing stylesheets: background image not recognised if containbed uppercase characters in file name
  9. - "double" border on table used white between the lines instead of current background colour
  10. - mPDFI: template documents overwriting HTML headers
  11. - $this->shrink_tables_to_fit = 0 or false caused fatal errors
  12. - background color or images not printing correctly when breaking across pages
  13. - background not printed for List inside a block element
  14. - columns starting near end of page with no room for a line triggering column change (resulting in text misplaced) not page break
  15. - table cell not calculating cell height correctly when "orphan" characters (;:,.?! etc.) at end of line
  16. - table breaking page in column 2 when col 1 is rowspan'ned
  17. - margin-collapse at top of page not working if bookmark/annotation/indexentry/toc
  18. - column break triggered by HR triggering a second column break
  19. - an empty 'position:fixed' element with no/auto width or height caused fatal error
  20. - mPDFI: function Overwrite (to change text in existing PDF) - fatal error if using with encrypted file
  21. Bug - not fixed - see below
  22. - WriteHTML('',2) with '2' parameter not recognising 'margin-collapse:collapse' for DIVs or 'line-height' set in default CSS 'BODY'
  23. New or Updated Files
  24. --------------------
  25. mpdf.php
  26. classes/gif.php
  27. classes/indic.php
  28. compress.php
  29. config.php
  30. config_cp.php
  31. config_fonts.php
  32. mpdf.css
  33. includes/sub_core.php
  34. mpdfi/mpdfi.php
  35. unifont/ar_k_001.uni2gn.php
  36. All files in new folder: /progress/*.*
  37. NEW FOLDER /tmp/ required with read/write permissions - used for temporary image files or progress bars
  38. New fonts: zn_hannom_a and unBatang_0613 available as CJK font pack
  39. zn_hannom_a - contains all characters in SJIS, BIG-5, GBK, and HKCSS codepages (Japanes & Chinese)
  40. (except greek and cyrillic characters, and HKCS > U+x20000;)
  41. unbatang_0613 - all characters in UHC codepage (Korean)
  42. Changes to configuration files
  43. ==============================
  44. config_cp.php
  45. -------------
  46. Mainly just tidied up, and:
  47. default: $cp = "UTF-8"; $spacing = ""; break; // Don't need to set unifonts - will make all available if omitted/left blank
  48. Default spacing set to '' (i.e. mixed character/word)
  49. spacing=C removed for Vietnamese (?why there) to allow spacing as for any european text
  50. spacing=C added to Thai (should have been there all along)
  51. config.php
  52. ----------
  53. $defaultCSS changed to make appearance closer to that of browsers:
  54. img { margin: 0; vertical-align: baseline; }
  55. table { margin: 0; }
  56. textarea { vertical-align: text-bottom; }
  57. (See also notes on line-height)
  58. New Configuration variables in 4.2:
  59. $this->useSubstitutionsMB = false; // Substitute missing characters in UTF-8(multibyte) documents - from core fonts
  60. $this->falseBoldWeight = 5; // Weight for bold text when using an artificial (outline) bold; value 0 (off) - 10 (rec. max)
  61. $this->collapseBlockMargins = true; // Allows top and bottom margins to collapse between block elements
  62. $this->progressBar = false; // Shows progress-bars whilst generating file
  63. $this->normalLineheight = 1.33; // Value used for line-height when CSS specified as 'normal' (default)
  64. // When writing a block element with position:fixed and overflow:auto, mPDF scales it down to fit in the space
  65. // by repeatedly rewriting it and making adjustments. These values give the adjustments used, depending how far out
  66. // the previous guess was. The higher the number, the quicker it will finish, but the less accurate the fit may be.
  67. // FPR1 is for coarse adjustments, and FPR4 for fine adjustments when it is getting closer.
  68. $this->incrementFPR1 = 10;
  69. $this->incrementFPR2 = 20;
  70. $this->incrementFPR3 = 30;
  71. $this->incrementFPR4 = 50;
  72. mpdf.css
  73. --------
  74. Now contains (commented out) lines to return behaviour to pre-4.2 behaviour:
  75. img { margin: 0.83em 0; vertical-align: bottom; }
  76. table { margin: 0.5em; }
  77. textarea { vertical-align: top; }
  78. Font updates:
  79. =============
  80. Indic Tamil numeral for Zero missing - converted to standard zero 0 (in classes/indic.php)
  81. ar_k_001.uni2gn.php - reference to small 'z' missing - now added (works with subsets but not with full font)
  82. WriteHTML($html,2)
  83. ==================
  84. WriteHTML($html,2) i.e. with the ,2 did not set BODY CSS - this was unintentional, and has been changed in 4.2
  85. Line-height and margin-collapse were therefore not cascaded through the document; the line-height defaulted to 1.2,
  86. and margin-collapse (which collapses top and bottom margins at the top of pages) was not enabled.
  87. If you used ",2" and want to keep layout:
  88. - Change $this->normalLineheight = 1.2; in config.php
  89. - Change defaultCSS: 'MARGIN-COLLAPSE' => 'none', in config.php
  90. NB also $this->collapseBlockMargins = false; NB This does between block elements
  91. NB You cannot now reset default font during document by redefining vars e.g. $mpdf->default_font = 'xxx'
  92. Now WriteHTML(,2) - does NOT read metatags, <style> or stylesheets from HTML, <html> or <body> inline CSS
  93. - DOES use defaultCSS, and stored CSS and stored cascading CSS
  94. - DOES use the above to overwrite defaultfont, defaultfontsize
  95. - DOES use the above to set (cascading) margin-collapse (pagetops) and line-height from BODY
  96. - therefore problem trying to set default_font, default_lineheight_correction etc programmatically
  97. - use SetDefaultFont(), SetDefaultFontSize() - (now altered to update $defaultCSS and $CSS['BODY'][''])
  98. - new SetDefaultBodyCSS($property, $value) - use to update [BODY] line-height etc. during program e.g. columns example
  99. NEW FEATURES
  100. ============
  101. PROGRESS BAR
  102. ------------
  103. You can now show a progress bar whilst mPDF generates the file.
  104. It is not recommended for regular use - it loads a separate HTML page to the browser, and may slow things down.
  105. May be useful if the end-user is waiting a long time, or for development purposes.
  106. 1) You need to define _MPDF_URI as a relative path or URI (NOT a relative file system path)
  107. - call this in your script before instantiating the class: new mPDF()
  108. 2) Call $mpdf->StartProgressBarOutput(0|1|2); in your script before using WriteHTML(), OR
  109. - or set $this->progressBar = 0|1|2; in config.php file (0 off, 1 simple, 2 advanced)
  110. StartProgressBarOutput(2) shows a more advanced/complex set of progress bars (default = 1)
  111. Note on defined Paths:
  112. _MPDF_PATH must be a relative or absolute file system path
  113. _MPDF_URI must be a relative or absolute URI (seen from the browser's point of view)
  114. mPDF will usually be able to automatically set _MPDF_PATH if you do not define it, but it cannot set _MPDF_URI
  115. Example:
  116. Your script is at: http://subdomain.mydomain.com/script.php = /homepages/123456/htdocs/public/subdomain/script.php
  117. Your MPDF file is: http://www.mydomain.com/mpdf41/mpdf.php = /homepages/123456/htdocs/public/mpdf41/mpdf.php
  118. _MPDF_PATH (from script.php to mpdf folder) - can be:
  119. ../mpdf41/ or
  120. /homepages/123456/htdocs/public/mpdf41/
  121. It cannot be http://www.mydomain.com/mpdf41/
  122. _MPDF_URI must be:
  123. http://www.mydomain.com/mpdf41/
  124. It cannot be a relative path - because you can't have ../ from the subdomain URI
  125. IF _MPDF_URI is not defined - mPDF silently ignores and leaves out the progress bar (or if debug gives warning)
  126. LINE-HEIGHT
  127. -----------
  128. The handling of line-height has been generally overhauled. Also some anomalies have been unearthed, so the layout of
  129. your documents may change with v4.2.
  130. The most significant change is that prior to v4.2, line-height was inherited as a factor of the fontsize i.e.
  131. <div id="1" style="font-size: 14pt; line-height: 28pt;"><div id="2" style="font-size: 28pt;">
  132. When the line-height was applied to div 1, it was calculated to be 2 x the fontsize - this was the value inerited by div 2
  133. which therefore set a line-height of 2 x 28 = 56pt.
  134. Inheritance now follows the CSS2 recommendation:
  135. * normal is inherited as "normal"
  136. * 1.2 is inherited as a factor
  137. * 120% is converted to an actual value and then inherited as the computed value
  138. * em is converted to an actual value and then inherited as the computed value
  139. * px pt mm are inherited as fixed values
  140. The value used for 'normal' is now defined in config.php by $normalLineheight (default 1.33) rather than $default_lineheight_correction (1.2)
  141. The defaultCSS BODY>>LINE-HEIGHT is now set as 'normal' rather than 1.33
  142. Block-level elements and lists use $normalLineheight as default now (unless overridden by CSS style)
  143. Lists inherit from containing block-level element, and lists inherit from containing lists.
  144. Tables do not inherit from containing block (as per browsers).
  145. Table default line-height is set by $defaultCSS in config.php
  146. So the $defaultCSS 'BODY' line-height sets for all except tables.
  147. Line-height can be set on UL,OL at every level, but not on LI items
  148. Line-height can only be set on top-level table (not nested tables, nor table cells TD/TH).
  149. Textarea - does not support CSS line-height - can change for whole document using $this->textarea_lineheight in config.php
  150. Algorithm used for line-height:
  151. If line-height set on a block-level element is an ABSOLUTE value (including %, em) it is fixed for the line unless:
  152. A font size on the line (e.g. in a span) is greater than the computed line-height for that line
  153. An image has a height greater than the computed line-height for that line
  154. e.g. <div style="font-size: 12pt; line-height: 2em;">Hallo <span style="font-size: 26pt">World...
  155. - line-height will increase from 24pt (2em x 12pt) to 26pt
  156. The vertical positioning of the text baseline will remain equally spaced unless:
  157. images exceed the initial line-height.
  158. large fontsize >= 0.8 x the initial line-height.
  159. e.g. <div style="font-size: 10pt; line-height: 2em;">Hallo <span style="font-size: 18pt">World...
  160. If line-height is set to be less than the fontsize, this will be respected UNLESS a larger fontsize (eg in span) or an image is included
  161. on the line, in which case the line-height is expanded to fit -
  162. LISTS - will always expand to the largest fontsize (including the bullet or number).
  163. If line-height is a number/factor:
  164. Line height will be based on the largest fontsize (x factor) or image height (NOT x factor) on the line.
  165. The vertical positioning of the text baseline will be adjusted so the centre-line runs through the
  166. middle of the largest font-size on the line.
  167. This gives results which roughly match browsers, but note that not even IE8 and FF3 are exactly the same in detail.
  168. A line-height cannot be defined as a number (factor) less than 1.0 - it will be set as 1.0
  169. Absolute values that are less than 1 (including e.g. 80%) are respected - unless a larger fontsize or an image on the line.
  170. Line-height - Backwards compatability?
  171. --------------------------------------
  172. The default settings should generally give the same results as pre-4.2 version, unless you specified absolute line-heights in your CSS.
  173. If you did, the only way is to go back and edit your CSS stylesheets.
  174. If you use WriteHTML($html,2) with the '2' parameter - see notes above.
  175. If you set $mpdf->default_lineheight_correction programmatically -
  176. The old example file for columns used WriteHTML('',2) - see below - and
  177. $mpdf->default_lineheight_correction = 1.1;
  178. This no longer works because the defaultCSS value for line-height overrides this.
  179. You can use:
  180. $mpdf->SetDefaultBodyCSS('line-height', 1.1); // A new function
  181. MARGIN-COLLAPSE BETWEEN BLOCK ELEMENTS
  182. --------------------------------------
  183. mPDF has always allowed margins to be collapsed at the top and bottom of pages (although see notes on WruiteHTML('',2) )
  184. This is specified by the custom CSS property "margin-collapse: collapse"
  185. mPDF 4.2 also allows margins to collapse between block elements on the page. This is the default behaviour in browsers,
  186. and has been enabled in mPDF by default.
  187. NB IMPORTANT - THIS MAY CHANGE THE APPEARANCE OF YOUR DOCUMENTS *****
  188. A configuration variable in config.php enables/disables this (default=true):
  189. $this->collapseBlockMargins = true; // mPDF 4.2 Allows top and bottom margins to collapse between block elements
  190. Change this to false if you wish to retain the layout of your previous files.
  191. Margin collapse works between lists, tables and all standard block-level elements (DIV, P, H1-6 etc.)
  192. NB Firefox does not collapse table margins, but IE8 does.
  193. TABLE RESIZING
  194. --------------
  195. mPDF attempts to layout tables according to HTML and CSS specifications. However, because of
  196. the difference between screen and paged media, mPDF resizes tables when necessary to make
  197. them fit the page. This will happen if the minimum table-width is greater than the page-width.
  198. Minimum table-width is defined as the minimum width to accomodate the longest word in each
  199. column i.e. words will never be split.
  200. This resizing (minimum-width) can be disabled using a custom CSS property "overflow" on the
  201. TABLE tag. There are 4 options:
  202. <table style="overflow: auto"> (this is the default, using resizing)
  203. <table style="overflow: visible"> (disables resizing, but allows overflow to show)
  204. <table style="overflow: hidden"> (disables resizing, and hides/clips any overflow)
  205. <table style="overflow: wrap"> (forces words to break as necessary)
  206. NB You cannot disable automatic resizing if a row-height is greater than the page-height.
  207. This only works on the top-level table (i.e. ignored on "nested" tables).
  208. overflow: visible will not extend the containing block element.
  209. Ignored on rotated tables.
  210. Ignored if columns are being used.
  211. ARTIFICIAL BOLD & ITALIC
  212. ------------------------
  213. mPDF will create "artificial" bold & italic font styles if they are not available as separate
  214. font files.
  215. A configuration variable in config.php can vary how bold is bold:
  216. $this->falseBoldWeight = 5; // Weight for bold text when using an artificial (outline) bold; value 0 (off) - 10 (rec. max)
  217. CSS "DOUBLE" BORDER-STYLE
  218. -------------------------
  219. CSS support for "double" border on block elements. NB Tables support the full range of CSS values for
  220. border-style; block elements now support just solid and double.
  221. CHARACTER SUBSTITUTION IN UTF-8
  222. -------------------------------
  223. Character substitution is used in codepaged PDF files (e.g. win-1252) to enable characters which exist in the core Adobe fonts
  224. (including symbols and zapfdingbats) to be displayed when they do not exist in the font currently being used.
  225. Character substitution in UTF-8 files was possible but erratic prior to v4.0 - then disabled in v4.0
  226. v4.2 introduces a new implementation of character substitution. When enabled, any characters which do not exist in the current
  227. font - but which do exist in the document's default font - will be substituted.
  228. There will be a time penalty for using this, as each character is inspected to check if it exists in the current font.
  229. This may be useful for some of the specialist fonts such as arabic, indic and CJK.
  230. A configuration variable in config.php enables/disables this (default=false):
  231. $this->useSubstitutionsMB = false; // Substitute missing characters in UTF-8(multibyte) documents - from core font
  232. IMAGES
  233. ------
  234. Image handling has been completely overhauled (again!) in 4.2
  235. (See the discussion: http://mpdf.bpm1.com/forum/comments.php?DiscussionID=180&page=1#Item_6)
  236. IMPORTANT - a new folder is required [your_mpdf_folder]/tmp/ with read/write permissions.
  237. PNG files (unless with alpha channel or interlaced), JPG and WMF images are read directly and are most efficient on resources.
  238. GIF files use the GD library - if available - this is quick, but can use enormous amount of memory for large files.
  239. GIF files without the GD library are very, very slow - it is recommended to change the image type if at all possible.
  240. PNG files with alpha channel or interlaced require the GD library, and can use large amoutns of memory.
  241. Images generated by a script e.g. myimage.php should be handled exactly the same as a native image file type.
  242. NB The 'compress' utility no longer does anything other than IMAGES or IMAGES-WMF
  243. BACKGROUND-IMAGES
  244. -----------------
  245. Background-gradient and background-image can now co-exist (layers = bgcolor < gradient < image)
  246. This works for BODY and also for block elements or tables.
  247. IMAGE DATA FROM PHP
  248. -------------------
  249. A PHP variable containing image data can be passed directly to mPDF. You need to allocate the data to a class variable
  250. (you can make any name up) e.g.
  251. $mpdf->myvariable = file_get_contents('alpha.png');
  252. The image can then be referred to by use of "var:varname" instead of a file name,
  253. either in src="" or direct to Image() function e.g.
  254. $html = '<img src="var:myvariable" />';
  255. $mpdf->WriteHTML($html);
  256. - OR -
  257. $mpdf->Image('var: myvariable',0,0);
  258. IMAGE - VERTICAL-ALIGN & MARGIN
  259. -------------------------------
  260. Vertical-alignment of images has been rewritten. All of the CSS properties are now supported:
  261. top, bottom, middle, baseline, text-top, and text-bottom.
  262. 'baseline' is now set as the default value for images in defaultCSS (config.php)
  263. and 'text-bottom' as the default for textarea.
  264. In-line images can now be individually aligned (vertically) i.e. different alignments can co-exist on one line.
  265. The defaultCSS value for margin on images has been changed to 0. Prior to 4.2, the default values of margin (0.3-0.5em)
  266. and vertical-align (bottom) could be used to approximately align the image with the text baseline.
  267. The new default values should therefore not significantly change appearances in most cases.
  268. These new values are consistent with most browsers.
  269. IMAGE - PADDING
  270. ---------------
  271. CSS property padding is now supported for images <IMG>. Default is set in defaultCSS to 0
  272. CSS @PAGE SELECTOR
  273. ------------------
  274. The functions AddPage() and TOCpagebreak() have an extra last parameter = $pagesel i.e. named @page selector
  275. The @page can also be specified in:
  276. <pagebreak page-selector="pagename"
  277. <formfeed page-selector="pagename"
  278. <tocpagebreak toc-page-selector="pagename" page-selector="pagename"
  279. Different headers/footers can be specified on :first :left and :right pages.
  280. "odd-header-name" etc is still recognised on @page or @page name (and takes priority over newer method "footer"/"header")
  281. but new custom properties "header" and "footer" are recognised on ALL, i.e. @page :left
  282. Other values are now recognised on :first, :left and :right selectors
  283. i.e. as well as header/footer, you can specify margins, backgrounds etc
  284. One exception is margin-right and margin-left:
  285. Left/right-margins must be the same for every page (of that @page name), or mirrored using $mpdf->mirrorMargins;
  286. margin-right and margin-left are ignored when set on :left or :right selectors
  287. See the example given in discussion forum: http://mpdf.bpm1.com/forum/comments.php?DiscussionID=177&page=1#Comment_658
  288. LISTS IN TABLES
  289. ---------------
  290. If using a UTF-8 document, and the current font contains the necessary characters, it will use disc, circle and square
  291. as bullets instead of a hyphen (-)