Merge pull request #171 from zbateson/2.0

2.0

README.md

@@ -14,21 +14,45 @@ The goals of this project are to be:
 * Standards-compliant but forgiving
 * Tested where possible
 
-To include it for use in your project, please install via composer:
+To include it for use in your project, install via composer:
 
 ```
 composer require zbateson/mail-mime-parser
 ```
 
 ## Sponsors
 
-A huge thank you to my first sponsor. <3
+[![SecuMailer](sponsors/logo-secumailer.png)](https://secumailer.com)
 
-[![SecuMailer](https://mail-mime-parser.org/sponsors/logo-secumailer.png)](https://secumailer.com)
+A huge thank you to [all my sponsors](https://github.com/sponsors/zbateson). <3
 
-## Deprecation Notice (since 1.2.1)
+If this project's helped you, please consider [sponsoring me](https://github.com/sponsors/zbateson).
 
-getContentResourceHandle, getTextResourceHandle, and getHtmlResourceHandle have all been deprecated due to #106. fread() will only return a single byte of a multibyte char, and so will cause potentially unexpected results/warnings in some cases, and psr7 streams should be used instead. Note that this deprecation doesn’t apply to getBinaryContentResourceHandle or getResourceHandle.
+## Removal Notice (since 2.0.0)
+
+`getContentResourceHandle`, `getTextResourceHandle`, and `getHtmlResourceHandle` have all been deprecated in 1.2.1 and removed in 2.0.0. fread() will only return a single byte of a multibyte char, and so will cause potentially unexpected results/warnings in some cases, and psr7 streams should be used instead. Note that `getBinaryContentResourceHandle` and `getResourceHandle` are still available.
+
+## Change in 2.0
+
+Upgrade to 2.0 to take advantage of the new on-demand parser which parses parts of a message as they're requested.  This means reading only the headers from a larger message is as fast as a smaller message because the whole message is no longer parsed (similarly reading just the content and not a message's large attachments is also much faster.)
+
+Because of the on-demand parsing, starting in 2.0, the passed resource handle or stream must remain open while the returned message object is still in use.
+
+Old code:
+```php
+$handle = fopen('file.mime', 'r');
+$message = $mailParser->parse($handle);         // returns `IMessage`
+fclose($handle);
+```
+
+New code:
+```php
+// attaches the resource handle to the returned `IMessage` if the second parameter
+// is true.  The resource handle is closed when the IMessage is destroyed.
+$message = $mailParser->parse(fopen('file.mime', 'r'), true);
+```
+
+For a more complete list of changes, please visit the [2.0 Upgrade Guide](https://mail-mime-parser.org/upgrade-2.0).
 
 ## Requirements
 
@@ -46,8 +70,9 @@ $mailParser = new MailMimeParser();
 
 $handle = fopen('file.mime', 'r');
 // parse() accepts a string, resource or Psr7 StreamInterface
-$message = $mailParser->parse($handle);         // returns `Message`
-fclose($handle);
+// pass `true` as the second argument to attach the passed $handle and close
+// it when the IMessage is destroyed.
+$message = $mailParser->parse($handle, false);         // returns `IMessage`
 
 // OR: use this procedurally (Message::from also accepts a string,
 // resource or Psr7 StreamInterface
@@ -88,16 +113,21 @@ $dest = \GuzzleHttp\Psr7\stream_for(
 // OR: more simply if saving or copying to another stream
 $att->saveContent('my-file.ext');               // writes to my-file.ext
 $att->saveContent($stream);                     // copies to the stream
+
+// close only when $message is no longer being used.
+fclose($handle);
+
 ```
 
 ## Documentation
 
 * [Usage Guide](https://mail-mime-parser.org/)
-* [API Reference](https://mail-mime-parser.org/api/1.3)
+* [API Reference](https://mail-mime-parser.org/api/2.0)
 
-## Upgrading to 1.x
+## Upgrading to 1.x or 2.x
 
-* [Upgrade Guide](https://mail-mime-parser.org/upgrade-1.0)
+* [1.x Upgrade Guide](https://mail-mime-parser.org/upgrade-1.0)
+* [2.x Upgrade Guide](https://mail-mime-parser.org/upgrade-2.0)
 
 ## License
 

build.xml

@@ -63,6 +63,7 @@
             <arg path="${project.basedir}/src"/>
             <arg value="-t"/>
             <arg path="${api-dir}"/>
+            <arg value="--defaultpackagename=MailMimeParser"/>
             <arg value="--title=MailMimeParser ${api-version}"/>
         </exec>
 

composer.json

@@ -22,10 +22,11 @@
         "php": ">=5.4",
         "guzzlehttp/psr7": "^1.7.0|^2.0",
         "zbateson/mb-wrapper": "^1.0.1",
-        "zbateson/stream-decorators": "^1.0.6"
+        "zbateson/stream-decorators": "^1.0.6",
+        "pimple/pimple": "^3.0"
     },
     "require-dev": {
-        "sanmai/phpunit-legacy-adapter": "^6.3 || ^8",
+        "sanmai/phpunit-legacy-adapter": "^6.3 || ^8.2",
         "mikey179/vfsstream": "^1.6.0"
     },
     "suggest": {