1mPDF is a PHP library which generates PDF files from UTF-8 encoded HTML. 2 3It is based on [FPDF](http://www.fpdf.org/) and [HTML2FPDF](http://html2fpdf.sourceforge.net/) 4(see [CREDITS](CREDITS.txt)), with a number of enhancements. mPDF was written by Ian Back and is released 5under the [GNU GPL v2 licence](LICENSE.txt). 6 7[](https://packagist.org/packages/mpdf/mpdf) 8[](https://packagist.org/packages/mpdf/mpdf) 9[](https://packagist.org/packages/mpdf/mpdf) 10 11 12> ⚠ If you are viewing this file on mPDF GitHub repository homepage or on Packagist, please note that 13> the default repository branch is `development` which can differ from the last stable release. 14 15Requirements 16============ 17 18PHP versions and extensions 19--------------------------- 20 21- `mPDF >=7.0` is supported on `PHP ^5.6 || ~7.0.0 || ~7.1.0 || ~7.2.0` 22- `PHP 7.3` is supported since `mPDF v7.1.7` 23- `PHP 7.4` is supported since `mPDF v8.0.4` 24- `PHP 8.0` is supported since `mPDF v8.0.10` 25- `PHP 8.1` is supported as of `mPDF v8.0.13` 26 27PHP `mbstring` and `gd` extensions have to be loaded. 28 29Additional extensions may be required for some advanced features such as `zlib` for compression of output and 30embedded resources such as fonts, `bcmath` for generating barcodes or `xml` for character set conversion 31and SVG handling. 32 33Known server caveats 34-------------------- 35 36mPDF has some problems with fetching external HTTP resources with single threaded servers such as `php -S`. A proper 37server such as nginx (php-fpm) or Apache is recommended. 38 39Support us 40========== 41 42Consider supporting development of mPDF with a donation of any value. [Donation button][1] can be found on the 43[main page of the documentation][1]. 44 45Installation 46============ 47 48Official installation method is via composer and its packagist package [mpdf/mpdf](https://packagist.org/packages/mpdf/mpdf). 49 50``` 51$ composer require mpdf/mpdf 52``` 53 54Usage 55===== 56 57The simplest usage (since version 7.0) of the library would be as follows: 58 59```php 60<?php 61 62require_once __DIR__ . '/vendor/autoload.php'; 63 64$mpdf = new \Mpdf\Mpdf(); 65$mpdf->WriteHTML('<h1>Hello world!</h1>'); 66$mpdf->Output(); 67 68``` 69 70This will output the PDF inline to the browser as `application/pdf` Content-type. 71 72Setup & Configuration 73===================== 74 75All [configuration directives](https://mpdf.github.io/reference/mpdf-variables/overview.html) can 76be set by the `$config` parameter of the constructor. 77 78It is recommended to set one's own temporary directory via `tempDir` configuration variable. 79The directory must have write permissions (mode `775` is recommended) for users using mPDF 80(typically `cli`, `webserver`, `fpm`). 81 82**Warning:** mPDF will clean up old temporary files in the temporary directory. Choose a path dedicated to mPDF only. 83 84 85```php 86<?php 87 88$mpdf = new \Mpdf\Mpdf(['tempDir' => __DIR__ . '/tmp']); 89 90``` 91 92By default, the temporary directory will be inside vendor directory and will have write permissions from 93`post_install` composer script. 94 95For more information about custom temporary directory see the note on 96[Folder for temporary files](https://mpdf.github.io/installation-setup/folders-for-temporary-files.html) 97in the section on Installation & Setup in the [manual][1]. 98 99If you have problems, please read the section on 100[troubleshooting](https://mpdf.github.io/troubleshooting/known-issues.html) in the manual. 101 102About CSS support and development state 103======================================= 104 105mPDF as a whole is a quite dated software. Nowadays, better alternatives are available, albeit not written in PHP. 106 107Use mPDF if you cannot use non-PHP approach to generate PDF files or if you want to leverage some of the benefits of mPDF 108over browser approach – color handling, pre-print, barcodes support, headers and footers, page numbering, TOCs, etc. 109But beware that a HTML/CSS template tailored for mPDF might be necessary. 110 111If you are looking for state of the art CSS support, mirroring existing HTML pages to PDF, use headless Chrome. 112 113mPDF will still be updated to enhance some internal capabilities and to support newer versions of PHP, 114but better and/or newer CSS support will most likely not be implemented. 115 116Online manual 117============= 118 119Online manual is available at https://mpdf.github.io/. 120 121General troubleshooting 122============= 123 124For general questions or troubleshooting please use [Discussions](https://github.com/mpdf/mpdf/discussions). 125 126You can also use the [mpdf tag](https://stackoverflow.com/questions/tagged/mpdf) at Stack Overflow as the StackOverflow user base is more likely to answer you in a timely manner. 127 128Contributing 129============ 130 131Before submitting issues and pull requests please read the [CONTRIBUTING.md](https://github.com/mpdf/mpdf/blob/development/.github/CONTRIBUTING.md) file. 132 133Unit Testing 134============ 135 136Unit testing for mPDF is done using [PHPUnit](https://phpunit.de/). 137 138To get started, run `composer install` from the command line while in the mPDF root directory 139(you'll need [composer installed first](https://getcomposer.org/download/)). 140 141To execute tests, run `composer test` from the command line while in the mPDF root directory. 142 143Any assistance writing unit tests for mPDF is greatly appreciated. If you'd like to help, please 144note that any PHP file located in the `/tests/` directory will be autoloaded when unit testing. 145 146[1]: https://mpdf.github.io 147