README.md
1# mailparse library for PHP 7
2
3Mailparse is an extension for parsing and working with email messages.
4
5It can deal with rfc822 and rfc2045 (MIME) compliant messages.
6
7Mailparse is stream based, which means that it does not keep in-memory
8copies of the files it processes - so it is very resource efficient
9when dealing with large messages.
10
11Version 2.1.6 is for PHP 5
12
13## OO Syntax
14
15```php
16<?php
17$file = "/path/to/rfc822/compliant/message";
18// parse the message in $file.
19// The file MUST remain in existence until you are finished using
20// the object, as mailparse does not cache the file in memory.
21// You can also use two alternative syntaxes:
22//
23// Read the message from a variable:
24// $msg = new MimeMessage("var", $message);
25//
26// Read the message from a stream (from fopen).
27// The stream MUST be seekable, or things will not work correctly.
28// Also, you MUST NOT fclose the stream until you have finished
29// using the message object (or any child objects it returns).
30// $msg = new MimeMessage("stream", $fp);
31//
32$msg = new MimeMessage("file", $file);
33
34// Process the message.
35display_part_info("message", $msg);
36
37// Little function to display things
38function display_part_info($caption, &$msgpart)
39{
40 echo "Message part: $caption\n";
41
42 // The data member corresponds to the information
43 // available from the mailparse_msg_get_part_data function.
44 // You can access a particular header like this:
45 // $subject = $msgpart->data["headers"]["subject"];
46 var_dump($msgpart->data);
47
48 echo "The headers are:\n";
49 // Display the headers (in raw format) to the browser output.
50 // You can also use:
51 // $msgpart->extract_headers(MAILPARSE_EXTRACT_STREAM, $fp);
52 // to write the headers to the supplied stream at it's current
53 // position.
54 //
55 // $var = $msgpart->extract_headers(MAILPARSE_EXTRACT_RETURN);
56 // to return the headers in a variable.
57 $msgpart->extract_headers(MAILPARSE_EXTRACT_OUTPUT);
58
59 // Display the body if this part is intended to be displayed:
60 $n = $msgpart->get_child_count();
61
62 if ($n == 0) {
63 // Return the body as a string (the MAILPARSE_EXTRACT parameter
64 // acts just as it does in extract_headers method.
65 $body = $msgpart->extract_body(MAILPARSE_EXTRACT_RETURN);
66 echo htmlentities($body);
67
68 // This function tells you about any uuencoded attachments
69 // that are present in this part.
70 $uue = $msgpart->enum_uue();
71 if ($uue !== false) {
72 var_dump($uue);
73 foreach($uue as $index => $data) {
74 // $data => array("filename" => "original filename",
75 // "filesize" => "size of extracted file",
76 // );
77
78 printf("UUE[%d] %s (%d bytes)\n",
79 $index, $data["filename"],
80 $data["filesize"]);
81
82 // Display the extracted part to the output.
83 $msgpart->extract_uue($index, MAILPARSE_EXTRACT_OUTPUT);
84
85 }
86 }
87
88 } else {
89 // Recurse and show children of that part
90 for ($i = 0; $i < $n; $i++) {
91 $part =& $msgpart->get_child($i);
92 display_part_info("$caption child $i", $part);
93 }
94 }
95}
96
97```
98
99
100The rest of this document may be out of date! Take a look at the [mailparse section of the online manual](http://php.net/manual/en/book.mailparse.php) for more hints about this stuff.
101
102$mime = mailparse_rfc2045_parse_file($file);
103$ostruct = mailparse_rfc2045_getstructure($mime);
104foreach($ostruct as $st) {
105 $section = mailparse_rfc2045_find($mime, $st);
106 $struct[$st] = mailparse_rfc2045_getinfo($section);
107}
108var_dump($struct);
109?>
110array mailparse_rfc822_parse_addresses(string addresses)
111 parses an rfc822 compliant recipient list, such as that found in To: From:
112 headers. Returns a indexed array of assoc. arrays for each recipient:
113 array(0 => array("display" => "Wez Furlong", "address" => "wez@php.net"))
114
115resource mailparse_rfc2045_create()
116 Create a mime mail resource
117
118boolean mailparse_rfc2045_parse(resource mimemail, string data)
119 incrementally parse data into the supplied mime mail resource.
120 Concept: you can stream portions of a file at a time, rather than read
121 and parse the whole thing.
122
123
124resource mailparse_rfc2045_parse_file(string $filename)
125 Parse a file and return a $mime resource.
126 The file is opened and streamed through the parser.
127 This is the optimal way of parsing a mail file that
128 you have on disk.
129
130
131array mailparse_rfc2045_getstructure(resource mimemail)
132 returns an array containing a list of message parts in the form:
133 array("1", "1.1", "1.2")
134
135resource mailparse_rfc2045_find(resource mimemail, string partname)
136 returns an mime mail resource representing the named section
137
138array mailparse_rfc2045_getinfo(resource mimemail)
139 returns an array containing the bounds, content type and headers of the
140 section.
141
142mailparse_rfc2045_extract_file(resource mimemail, string filename[, string
143 callbackfunc])
144 Extracts/decodes a message section from the supplied filename.
145 If no callback func is supplied, it outputs the results into the current
146 output buffer, otherwise it calls the callback with a string parameter
147 containing the text.
148 The contents of the section will be decoded according to their transfer
149 encoding - base64, quoted-printable and uuencoded text are supported.
150
151All operations are done incrementally; streaming the input and output so that
152memory usage is on the whole lower than something like procmail or doing this
153stuff in PHP space. The aim is that it stays this way to handle large
154quantities of email.
155
156
157TODO:
158=====
159
160. Add support for binhex encoding?
161. Extracting a message part without decoding the transfer encoding so that
162 eg: pgp-signatures can be verified.
163
164. Work the other way around - build up a rfc2045 compliant message file from
165 simple structure information and filenames/variables.
166
167vim:tw=78
168vim600:syn=php:tw=78
169