@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
1# php-mime-mail-parser
2
3A fully tested email parser for PHP 8.0+ (mailparse extension wrapper).
4
5It's the most effective PHP email parser around in terms of performance, foreign character encoding, attachment handling, and ease of use.
6Internet Message Format RFC [822](https://tools.ietf.org/html/rfc822), [2822](https://tools.ietf.org/html/rfc2822), [5322](https://tools.ietf.org/html/rfc5322).
7
8[](https://github.com/php-mime-mail-parser/php-mime-mail-parser/releases)
9[](https://packagist.org/packages/php-mime-mail-parser/php-mime-mail-parser)
10[](LICENSE)
11
12## Why?
13
14This extension can be used to...
15 * Parse and read email from Postfix
16 * Read messages (Filename extension: `.eml`)
17 * Create webmail
18 * Store email information such a subject, HTML body, attachments, etc. into a database
19
20## Is it reliable?
21
22Yes. All known issues have been reproduced, fixed and tested.
23
24We use GitHub Actions, Codecov, Codacy to help ensure code quality. You can see real-time statistics below:
25
26[](https://github.com/php-mime-mail-parser/php-mime-mail-parser/actions/workflows/main.yml)
27[](https://codecov.io/gh/php-mime-mail-parser/php-mime-mail-parser)
28[](https://www.codacy.com/gh/php-mime-mail-parser/php-mime-mail-parser/dashboard?utm_source=github.com&utm_medium=referral&utm_content=php-mime-mail-parser/php-mime-mail-parser&utm_campaign=Badge_Grade)
29
30## How do I install it?
31
32The easiest way is via [Composer](https://getcomposer.org/).
33
34To install the latest version of PHP MIME Mail Parser, run the command below:
35
36 composer require php-mime-mail-parser/php-mime-mail-parser
37
38## Requirements
39
40The following versions of PHP are supported:
41
42* PHP 8.0
43* PHP 8.1
44* PHP 8.2
45* PHP 8.3
46* PHP 8.4
47
48Previous Versions:
49
50| PHP Compatibility | Version |
51|-------------------|-----------------------------|
52| HHVM | [php-mime-mail-parser 2.11.1](https://github.com/php-mime-mail-parser/php-mime-mail-parser/releases/tag/2.11.1) |
53| PHP 5.4 | [php-mime-mail-parser 2.11.1](https://github.com/php-mime-mail-parser/php-mime-mail-parser/releases/tag/2.11.1) |
54| PHP 5.5 | [php-mime-mail-parser 2.11.1](https://github.com/php-mime-mail-parser/php-mime-mail-parser/releases/tag/2.11.1) |
55| PHP 5.6 | [php-mime-mail-parser 3.0.4](https://github.com/php-mime-mail-parser/php-mime-mail-parser/releases/tag/3.0.4) |
56| PHP 7.0 | [php-mime-mail-parser 3.0.4](https://github.com/php-mime-mail-parser/php-mime-mail-parser/releases/tag/3.0.4) |
57| PHP 7.1 | [php-mime-mail-parser 5.0.5](https://github.com/php-mime-mail-parser/php-mime-mail-parser/releases/tag/5.0.5) |
58| PHP 7.2 | [php-mime-mail-parser 7.1.2](https://github.com/php-mime-mail-parser/php-mime-mail-parser/releases/tag/7.1.2) |
59| PHP 7.3 | [php-mime-mail-parser 7.1.2](https://github.com/php-mime-mail-parser/php-mime-mail-parser/releases/tag/7.1.2) |
60| PHP 7.4 | [php-mime-mail-parser 7.1.2](https://github.com/php-mime-mail-parser/php-mime-mail-parser/releases/tag/7.1.2) |
61
62Make sure you have the mailparse extension (http://php.net/manual/en/book.mailparse.php) properly installed. The command line `php -m | grep mailparse` needs to return "mailparse".
63
64
65### Install mailparse extension
66
67#### Debian, Ubuntu & derivatives
68```
69sudo apt install php-cli php-mailparse
70```
71
72#### MacOS
73```
74brew install php
75pecl install mailparse
76```
77
78#### Other platforms
79```
80sudo apt install php-cli php-pear php-dev php-mbstring
81pecl install mailparse
82```
83
84#### From source
85
86AAAAMMDD should be `php-config --extension-dir`
87```
88git clone https://github.com/php/pecl-mail-mailparse.git
89cd pecl-mail-mailparse
90phpize
91./configure
92sed -i 's/#if\s!HAVE_MBSTRING/#ifndef MBFL_MBFILTER_H/' ./mailparse.c
93make
94sudo mv modules/mailparse.so /usr/lib/php/AAAAMMDD/
95echo "extension=mailparse.so" | sudo tee /etc/php/8.4/mods-available/mailparse.ini
96sudo phpenmod mailparse
97```
98
99#### Windows
100You need to download mailparse DLL from http://pecl.php.net/package/mailparse and add the line `extension=php_mailparse.dll` to `php.ini` accordingly.
101
102## How do I use it?
103
104### Loading an email
105
106You can load an email in 4 differents ways:
107
108```php
109require_once __DIR__.'/vendor/autoload.php';
110
111$path = 'path/to/email.eml';
112$parser = new PhpMimeMailParser\Parser();
113
114// 1. Either specify a file path (string)
115$parser->setPath($path);
116
117// 2. or specify the raw mime mail text (string)
118$parser->setText(file_get_contents($path));
119
120// 3. or specify a php file resource (stream)
121$parser->setStream(fopen($path, "r"));
122
123// 4. or specify a stream to work with a mail server (stream)
124$parser->setStream(fopen("php://stdin", "r"));
125```
126
127### Get the metadata of the message
128
129Get the sender and the receiver:
130
131```php
132$rawHeaderTo = $parser->getHeader('to');
133// return "test" <test@example.com>, "test2" <test2@example.com>
134
135$arrayHeaderTo = $parser->getAddresses('to');
136// return [["display"=>"test", "address"=>"test@example.com", false]]
137
138$rawHeaderFrom = $parser->getHeader('from');
139// return "test" <test@example.com>
140
141$arrayHeaderFrom = $parser->getAddresses('from');
142// return [["display"=>"test", "address"=>"test@example.com", "is_group"=>false]]
143```
144
145Get the subject:
146
147```php
148$subject = $parser->getHeader('subject');
149```
150
151Get other headers:
152
153```php
154$stringHeaders = $parser->getHeadersRaw();
155// return all headers as a string, no charset conversion
156
157$arrayHeaders = $parser->getHeaders();
158// return all headers as an array, with charset conversion
159```
160
161### Get the body of the message
162
163```php
164$text = $parser->getMessageBody('text');
165// return the text version
166
167$html = $parser->getMessageBody('html');
168// return the html version
169
170$htmlEmbedded = $parser->getMessageBody('htmlEmbedded');
171// return the html version with the embedded contents like images
172
173```
174
175### Get attachments
176
177Save all attachments in a directory
178
179```php
180$parser->saveAttachments('/path/to/save/attachments/');
181// return all attachments saved in the directory (include inline attachments)
182
183$parser->saveAttachments('/path/to/save/attachments/', false);
184// return all attachments saved in the directory (exclude inline attachments)
185
186// Save all attachments with the strategy ATTACHMENT_DUPLICATE_SUFFIX (default)
187$parser->saveAttachments('/path/to/save/attachments/', false, Parser::ATTACHMENT_DUPLICATE_SUFFIX);
188// return all attachments saved in the directory: logo.jpg, logo_1.jpg, ..., logo_100.jpg, YY34UFHBJ.jpg
189
190// Save all attachments with the strategy ATTACHMENT_RANDOM_FILENAME
191$parser->saveAttachments('/path/to/save/attachments/', false, Parser::ATTACHMENT_RANDOM_FILENAME);
192// return all attachments saved in the directory: YY34UFHBJ.jpg and F98DBZ9FZF.jpg
193
194// Save all attachments with the strategy ATTACHMENT_DUPLICATE_THROW
195$parser->saveAttachments('/path/to/save/attachments/', false, Parser::ATTACHMENT_DUPLICATE_THROW);
196// return an exception when there is attachments duplicate.
197
198```
199
200Get all attachments
201
202```php
203$attachments = $parser->getAttachments();
204// return an array of all attachments (include inline attachments)
205
206$attachments = $parser->getAttachments(false);
207// return an array of all attachments (exclude inline attachments)
208```
209
210
211Loop through all attachments
212```php
213foreach ($attachments as $attachment) {
214 echo 'Filename : '.$attachment->getFilename().'<br>';
215 // return logo.jpg
216
217 echo 'Filesize : '.filesize($attach_dir.$attachment->getFilename()).'<br>';
218 // return 1000
219
220 echo 'Filetype : '.$attachment->getContentType().'<br>';
221 // return image/jpeg
222
223 echo 'MIME part string : '.$attachment->getMimePartStr().'<br>';
224 // return the whole MIME part of the attachment
225
226 $stream = $attachment->getStream();
227 // get the stream of the attachment file
228
229 $attachment->save('/path/to/save/myattachment/', Parser::ATTACHMENT_DUPLICATE_SUFFIX);
230 // return the path and the filename saved (same strategy available than saveAttachments)
231}
232```
233
234## Postfix configuration to manage email from a mail server
235
236To forward mails from [Postfix](http://www.postfix.org/) to the PHP script above, add this line at the end of your `/etc/postfix/master.cf`
237(to specify myhook to send all emails to the script `test.php`):
238
239```
240myhook unix - n n - - pipe
241 flags=F user=www-data argv=php -c /etc/php5/apache2/php.ini -f /var/www/test.php ${sender} ${size} ${recipient}
242```
243
244Edit this line (register myhook)
245```
246smtp inet n - - - - smtpd
247 -o content_filter=myhook:dummy
248```
249
250The PHP script must use the fourth method (see above) to work with this configuration.
251
252And finally the easiest way is to use my SaaS https://mailcare.io
253
254
255## Can I contribute?
256
257Feel free to contribute!
258
259 git clone https://github.com/php-mime-mail-parser/php-mime-mail-parser
260 cd php-mime-mail-parser
261 composer install
262 ./vendor/bin/phpunit
263
264If you report an issue, please provide the raw email that triggered it. This helps us reproduce the issue and fix it more quickly.
265
266## License
267
268The php-mime-mail-parser/php-mime-mail-parser is open-sourced software licensed under the [MIT license](http://opensource.org/licenses/MIT)