Merge branch 'hotfix/8'

Close #8
Close #11

.gitignore

@@ -6,7 +6,9 @@
 .*.sw*
 .*.un~
 nbproject
+doc/html/
 tmp/
+zf-mkdoc-theme/
 
 clover.xml
 composer.lock

.travis.yml

@@ -10,6 +10,16 @@ branches:
 cache:
   directories:
     - $HOME/.composer/cache
+    - $HOME/.local
+    - zf-mkdoc-theme
+
+env:
+  global:
+    - SITE_URL: https://zendframework.github.io/zend-mime
+    - GH_USER_NAME: "Matthew Weier O'Phinney"
+    - GH_USER_EMAIL: [email protected]
+    - GH_REF: github.com/zendframework/zend-mime.git
+    - secure: "KDeiKN5RyCXfmsQ49zOE61VNW8dr0EJXU4AKKstdAU5dhEmz62czPkuyAvWWGcDlGgkW3egR7lhNylYgZaUovi1DpbxaWEVBmApy/+g/JKLZH7QJM9r80XhRicSRp/kutuqCIOMBqEeSMw6HKOAlImvypwf1jXyVYlC9vahHKal6BQciA0deNqvNGgInyW/UihAL4U3stWM1d1ZbHhKAkBnXA6ttdsR60WlkvfEpW/yV2HVVl0pyauOHwNv2mWtovj6K+AL0F1KBPR6EozgfkEKvHxtrQWTzn6A0RqOVRmnLiQbzKsi1G0NBTDdKe2HRmGqJ1xyrP94cQ//IkOJoz26TiUqRdKAKFO/BEpoTbhY+9vepnsFkE54fLmstEkbP9Ebc3BnxguGgDrEVIDHVhO/eNgj2SbJNFZa6VHVaDbGWE4avRPQHRxxmSqqDq5wDjZgGWi+iqYy4ph5g1Fp5Y9v3S1HM9hmqiqMBvLnZf2To4w3uQxF/FjGnDdQ7L0lASUHXcrbsxw9zumeeaKdvL2uDdUsdmhuyWAKzpq4BDDkwOrfWK9SCk0Fh11yeRWbGiMvByccqczATVjbGCDly8Hg/jsdglmN+sZVCDWnuMOuFVzeUpQQ3mCzoyuZmPZhYwAEwA6lnQyHrt8/nkC7Mfooaik0i723SqROJWb0ibkg="
 
 matrix:
   fast_finish: true
@@ -20,6 +30,8 @@ matrix:
     - php: 5.6
       env:
         - EXECUTE_TEST_COVERALLS=true
+        - DEPLOY_DOCS="$(if [[ $TRAVIS_BRANCH == 'master' && $TRAVIS_PULL_REQUEST == 'false' ]]; then echo -n 'true' ; else echo -n 'false' ; fi)"
+        - PATH="$HOME/.local/bin:$PATH"
     - php: 7
     - php: hhvm 
   allow_failures:
@@ -41,6 +53,10 @@ script:
   - if [[ $EXECUTE_TEST_COVERALLS == 'true' ]]; then ./vendor/bin/phpunit --coverage-clover clover.xml ; fi
   - if [[ $EXECUTE_TEST_COVERALLS != 'true' ]]; then ./vendor/bin/phpunit ; fi
   - if [[ $EXECUTE_CS_CHECK == 'true' ]]; then ./vendor/bin/php-cs-fixer fix -v --diff --dry-run ; fi
+  - if [[ $DEPLOY_DOCS == "true" && "$TRAVIS_TEST_RESULT" == "0" ]]; then wget -O theme-installer.sh "https://raw.githubusercontent.com/zendframework/zf-mkdoc-theme/master/theme-installer.sh" ; chmod 755 theme-installer.sh ; ./theme-installer.sh ; fi
+
+after_success:
+  - if [[ $DEPLOY_DOCS == "true" ]]; then echo "Preparing to build and deploy documentation" ; ./zf-mkdoc-theme/deploy.sh ; echo "Completed deploying documentation" ; fi
 
 after_script:
   - if [[ $EXECUTE_TEST_COVERALLS == 'true' ]]; then ./vendor/bin/coveralls ; fi

CHANGELOG.md

@@ -2,11 +2,14 @@
 
 All notable changes to this project will be documented in this file, in reverse chronological order by release.
 
-## 2.5.2 - TBD
+## 2.5.2 - 2016-04-20
 
 ### Added
 
-- Nothing.
+- [#8](https://github.com/zendframework/zend-mime/pull/8) and
+  [#11](https://github.com/zendframework/zend-mime/pull/11) port documentation
+  from the zf-documentation repo, and publish it to
+  https://zendframework.github.io/zend-mime/
 
 ### Deprecated
 

doc/book/index.html

@@ -0,0 +1,10 @@
+<div class="container">
+  <div class="jumbotron">
+    <h1>zend-mime</h1>
+
+    <p>Create and parse MIME messages and parts.</p>
+
+    <pre><code class="language-bash">$ composer require zendframework/zend-mime</code></pre>
+  </div>
+</div>
+

doc/book/index.md

@@ -0,0 +1 @@
+../../README.md

doc/book/intro.md

@@ -0,0 +1,52 @@
+# Introduction
+
+`Zend\Mime\Mime` is a support class for handling multipart
+[MIME](https://en.wikipedia.org/wiki/MIME) messages;
+[zend-mail](https://github.com/zendframework/zend-mail) relies on it for both
+parsing and creating multipart messages. [`Zend\Mime\Message`](message.md) can
+also be consumed by applications requiring general MIME support.
+
+## Static Methods and Constants
+
+`Zend\Mime\Mime` provides a set of static helper methods to work with MIME:
+
+- `Zend\Mime\Mime::isPrintable()`: Returns `TRUE` if the given string contains
+  no unprintable characters, `FALSE` otherwise.
+- `Zend\Mime\Mime::encode()`: Encodes a string with the specified encoding.
+- `Zend\Mime\Mime::encodeBase64()`: Encodes a string into base64 encoding.
+- `Zend\Mime\Mime::encodeQuotedPrintable()`: Encodes a string with the
+  quoted-printable mechanism.
+- `Zend\Mime\Mime::encodeBase64Header()`: Encodes a string into base64 encoding
+  for Mail Headers.
+- `Zend\Mime\Mime::encodeQuotedPrintableHeader()`: Encodes a string with the
+  quoted-printable mechanism for Mail Headers.
+- `Zend\Mime\Mime::mimeDetectCharset()`: detects if a string is encoded as
+  ASCII, Base64, or quoted-printable.
+
+`Zend\Mime\Mime` defines a set of constants commonly used with MIME messages:
+
+* `Zend\Mime\Mime::TYPE_OCTETSTREAM`: 'application/octet-stream'
+* `Zend\Mime\Mime::TYPE_TEXT`: 'text/plain'
+* `Zend\Mime\Mime::TYPE_HTML`: 'text/html'
+* `Zend\Mime\Mime::ENCODING_7BIT`: '7bit'
+* `Zend\Mime\Mime::ENCODING_8BIT`: '8bit'
+* `Zend\Mime\Mime::ENCODING_QUOTEDPRINTABLE`: 'quoted-printable'
+* `Zend\Mime\Mime::ENCODING_BASE64`: 'base64'
+* `Zend\Mime\Mime::DISPOSITION_ATTACHMENT`: 'attachment'
+* `Zend\Mime\Mime::DISPOSITION_INLINE`: 'inline'
+* `Zend\Mime\Mime::MULTIPART_ALTERNATIVE`: 'multipart/alternative'
+* `Zend\Mime\Mime::MULTIPART_MIXED`: 'multipart/mixed'
+* `Zend\Mime\Mime::MULTIPART_RELATED`: 'multipart/related'
+
+## Instantiating Zend\\Mime
+
+When instantiating a `Zend\Mime\Mime` object, a MIME boundary is stored that is
+used for all instance calls. If the constructor is called with a string
+parameter, this value is used as the MIME boundary; if not, a random MIME
+boundary is generated.
+
+A `Zend\Mime\Mime` object has the following methods:
+
+- `boundary()`: Returns the MIME boundary string.
+- `boundaryLine()`: Returns the complete MIME boundary line.
+- `mimeEnd()`: Returns the complete MIME end boundary line.

doc/book/message.md

@@ -0,0 +1,68 @@
+# Zend\\Mime\\Message
+
+`Zend\Mime\Message` represents a MIME compliant message that can contain one or
+more separate Parts (represented as [Zend\Mime\Part](part.md) instances).
+Encoding and boundary handling are handled transparently by the class.
+`Message` instances can also be generated from MIME strings.
+
+## Instantiation
+
+There is no explicit constructor for `Zend\Mime\Message`.
+
+## Adding MIME Parts
+
+[Zend\Mime\Part](part.md) instances can be added to a given `Message` instance by
+calling `->addPart($part)`
+
+An array with all [Part](part.md) instances in the `Message` is returned from
+the method `getParts()`. The `Part` instances can then be modified on
+retrieveal, as they are stored in the array as references. If parts are added
+to the array or the sequence is changed, the array needs to be passed back to
+the `Message` instance by calling `setParts($partsArray)`.
+
+The function `isMultiPart()` will return `TRUE` if more than one part is
+registered with the `Message` instance; when true, the instance will generate a
+multipart MIME message.
+
+## Boundary handling
+
+`Zend\Mime\Message` usually creates and uses its own `Zend\Mime\Mime` instance
+to generate a boundary.  If you need to define the boundary or want to change
+the behaviour of the `Mime` instance used by `Message`, you can create the
+`Mime` instance yourself and register it with your `Message` using the
+`setMime()` method; this is an atypical occurrence.
+
+`getMime()` returns the `Mime` instance to use when rendering the message via
+`generateMessage()`.
+
+`generateMessage()` renders the `Message` content to a string.
+
+## Parsing a string to create a Zend\\Mime\\Message object
+
+`Zend\Mime\Message` defines a static factory for parsing MIME-compliant message
+strings and returning a `Zend\Mime\Message` instance:
+
+```php
+$message = Zend\Mime\Message::createFromMessage($string, $boundary);
+```
+
+## Available methods
+
+`Zend\Mime\Message` contains the following methods:
+
+- `getParts`: Get the all `Zend\Mime\Part`s in the message.
+- `setParts($parts)`: Set the array of `Zend\Mime\Part`s for the message.
+- `addPart(Zend\Mime\Part $part)`: Append a new `Zend\Mime\Part` to the
+  message.
+- `isMultiPart`: Check if the message needs to be sent as a multipart MIME
+  message.
+- `setMime(Zend\Mime\Mime $mime)`: Set a custom `Zend\Mime\Mime` object for the
+  message.
+- `getMime`: Get the `Zend\Mime\Mime` object for the message.
+- `generateMessage($EOL = Zend\Mime\Mime::LINEEND)`: Generate a MIME-compliant
+  message from the current configuration.
+- `getPartHeadersArray($partnum)`: Get the headers of a given part as an array.
+- `getPartHeaders($partnum, $EOL = Zend\Mime\Mime::LINEEND)`: Get the headers
+  of a given part as a string.
+- `getPartContent($partnum, $EOL = Zend\Mime\Mime::LINEEND)`: Get the encoded
+  content of a given part as a string.

doc/book/part.md

@@ -0,0 +1,67 @@
+# Zend\\Mime\\Part
+
+`Zend\Mime\Part` represents a single part of a MIME message. It contains the
+actual content of the message part, plus information about its encoding,
+content type, and original filename. Finally, it provides a method for
+generating a string from the stored data.
+
+`Zend\Mime\Part` objects can be added to [Zend\Mime\Message](message.md)
+instances to assemble a complete multipart message.
+
+## Instantiation
+
+`Zend\Mime\Part` is instantiated with a string representing the message part's
+content. The type is assumed to be OCTET-STREAM, with an 8-bit encoding. After
+instantiating a `Zend\Mime\Part`, meta information can be set directly on its
+attributes:
+
+```php
+public $type = Zend\Mime\Mime::TYPE_OCTETSTREAM;
+public $encoding = Zend\Mime\Mime::ENCODING_8BIT;
+public $id;
+public $disposition;
+public $filename;
+public $description;
+public $charset;
+public $boundary;
+public $location;
+public $language;
+```
+
+## Methods for rendering the message part to a string
+
+`getContent()` returns the encoded content of the `Zend\Mime\Part` as a string
+using the encoding specified in the attribute `$encoding`. Valid values are
+`Zend\Mime\Mime::ENCODING_*`. Character set conversions are not performed.
+
+`getHeaders()` returns the MIME headers for the `Part` as generated from the
+information in the publicly accessible attributes. The attributes of the object
+need to be set correctly before this method is called.
+
+- `$charset` has to be set to the actual charset of the content if it is a text
+  type (text or HTML).
+- `$id` may be set to identify a Content-ID for inline images in an HTML mail.
+- `$filename` specifies the name of the file at the time of creation.
+- `$disposition` defines if the file should be treated as an attachment or if
+  it is used inside the (HTML) mail (inline).
+- `$description` is only used for informational purposes.
+- `$boundary` defines the string to use as a part boundary.
+- `$location` can be used as resource URI that has relation to the content.
+- `$language` defines the content language.
+
+## Available methods
+
+A `Zend\Mime\Part` object has the following methods:
+
+- `isStream`: Check if this `Part` can be read as a stream. You can specify a
+  PHP stream resource when creating the content in order to reduce CPU and/or
+  memory overhead; if you do, this value will be toggled to `true`.
+- `getEncodedStream`: If the `Part` was created with a stream, return a
+  filtered stream for reading the content. Useful for large file attachments.
+- `getContent($EOL = Zend\Mime\Mime::LINEEND)`: Get the content of the current
+  `Zend\Mime\Part` in the given encoding.
+- `getRawContent`: Get the raw, unencoded content for the current `Part`.
+- `getHeadersArray($EOL = Zend\Mime\Mime::LINEEND)`: Create and return the
+  array of headers for the current `Part`.
+- `getHeaders($EOL = Zend\Mime\Mime::LINEEND)`: Return the headers for the
+  current `Part` as a string.

mkdocs.yml

@@ -0,0 +1,12 @@
+docs_dir: doc/book
+site_dir: doc/html
+pages:
+    - index.md
+    - Intro: intro.md
+    - Reference:
+        - Messages: message.md
+        - Parts: part.md
+site_name: zend-mime
+site_description: zend-mime
+repo_url: 'https://github.com/zendframework/zend-mime'
+copyright: 'Copyright (c) 2016 <a href="http://www.zend.com/">Zend Technologies USA Inc.</a>'