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[![Latest Stable Version](https://poser.pugx.org/mpdf/mpdf/v/stable)](https://packagist.org/packages/mpdf/mpdf)
8[![Build Status](https://travis-ci.org/mpdf/mpdf.svg?branch=development)](https://travis-ci.org/mpdf/mpdf)
9[![Total Downloads](https://poser.pugx.org/mpdf/mpdf/downloads)](https://packagist.org/packages/mpdf/mpdf)
10[![License](https://poser.pugx.org/mpdf/mpdf/license)](https://packagist.org/packages/mpdf/mpdf)
11
12
13> Note: If you are viewing this file on mPDF GitHub repository homepage or on Packagist, please note that
14> the default repository branch is `development` which can differ from the last stable release.
15
16Requirements
17============
18
19PHP versions and extensions
20---------------------------
21
22- `mPDF >=7.0` is supported on PHP `^5.6 || ~7.0.0 || ~7.1.0 || ~7.2.0`
23- `PHP 7.3` is supported since `mPDF v7.1.7`
24- `PHP 7.4` is supported since `mPDF v8.0.4`
25
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 correct 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
102Online manual
103=============
104
105Online manual is available at https://mpdf.github.io/.
106
107For general questions or troubleshooting please use the [mpdf tag](https://stackoverflow.com/questions/tagged/mpdf) at Stack Overflow (and not the project's issue tracker).
108
109Contributing
110============
111
112Please read before submitting issues and pull requests the [CONTRIBUTING.md](https://github.com/mpdf/mpdf/blob/development/.github/CONTRIBUTING.md) file.
113
114Unit Testing
115============
116
117Unit testing for mPDF is done using [PHPUnit](https://phpunit.de/).
118
119To get started, run `composer install` from the command line while in the mPDF root directory
120(you'll need [composer installed first](https://getcomposer.org/download/)).
121
122To execute tests, run `vendor/bin/phpunit` from the command line while in the mPDF root directory.
123
124Any assistance writing unit tests for mPDF is greatly appreciated. If you'd like to help, please
125note that any PHP file located in the `/tests/` directory will be autoloaded when unit testing.
126
127[1]: https://mpdf.github.io
128