Merge branch 'hotfix/54'

Close #54

Author: weierophinney

doc/book/zend.mail.file.options.md

@@ -0,0 +1,92 @@
+# Zend\\Mail\\Transport\\FileOptions
+
+## Overview
+
+This document details the various options available to the `Zend\Mail\Transport\File` mail
+transport.
+
+## Quick Start
+
+```php
+use Zend\Mail\Transport\File as FileTransport;
+use Zend\Mail\Transport\FileOptions;
+
+// Setup File transport
+$transport = new FileTransport();
+$options   = new FileOptions(array(
+    'path'              => 'data/mail/',
+    'callback'  => function (FileTransport $transport) {
+        return 'Message_' . microtime(true) . '_' . mt_rand() . '.txt';
+    },
+));
+$transport->setOptions($options);
+```
+
+## Configuration Options
+
+**path**  
+The path under which mail files will be written.
+
+<!-- -->
+
+**callback**  
+A PHP callable to be invoked in order to generate a unique name for a message file. By default, the
+following is used:
+
+```php
+function (Zend\Mail\FileTransport $transport) {
+    return 'ZendMail_' . time() . '_' . mt_rand() . '.tmp';
+}
+```
+
+## Available Methods
+
+`Zend\Mail\Transport\FileOptions` extends `Zend\Stdlib\AbstractOptions`, and inherits all
+functionality from that class; this includes property overloading. Additionally, the following
+explicit setters and getters are provided.
+
+**setPath**  
+`setPath(string $path)`
+
+Set the path under which mail files will be written.
+
+Implements fluent interface.
+
+<!-- -->
+
+**getPath**  
+`getPath()`
+
+Get the path under which mail files will be written.
+
+Returns string
+
+<!-- -->
+
+**setCallback**  
+`setCallback(Callable $callback)`
+
+Set the callback used to generate unique filenames for messages.
+
+Implements fluent interface.
+
+<!-- -->
+
+**getCallback**  
+`getCallback()`
+
+Get the callback used to generate unique filenames for messages.
+
+Returns PHP callable argument.
+
+<!-- -->
+
+**\_\_construct**  
+`__construct(null|array|Traversable $config)`
+
+Initialize the object. Allows passing a PHP array or `Traversable` object with which to populate the
+instance.
+
+## Examples
+
+Please see the \[Quick Start\](zend.mail.file-options.quick-start) for examples.

doc/book/zend.mail.introduction.md

@@ -0,0 +1,92 @@
+# Introduction to Zend\\Mail
+
+## Getting started
+
+`Zend\Mail` provides generalized functionality to compose and send both text and *MIME*-compliant
+multipart email messages. Mail can be sent with `Zend\Mail` via the `Mail\Transport\Sendmail`,
+`Mail\Transport\Smtp` or the `Mail\Transport\File` transport. Of course, you can also implement your
+own transport by implementing the `Mail\Transport\TransportInterface`.
+
+### Simple email with Zend\\Mail
+
+A simple email consists of one or more recipients, a subject, a body and a sender. To send such a
+mail using `Zend\Mail\Transport\Sendmail`, do the following:
+
+```php
+use Zend\Mail;
+
+$mail = new Mail\Message();
+$mail->setBody('This is the text of the email.');
+$mail->setFrom('[email protected]', 'Sender\'s name');
+$mail->addTo('[email protected]', 'Name of recipient');
+$mail->setSubject('TestSubject');
+
+$transport = new Mail\Transport\Sendmail();
+$transport->send($mail);
+```
+
+> ## Note
+#### Minimum definitions
+In order to send an email using `Zend\Mail` you have to specify at least one recipient as well as a
+message body. Please note that each Transport may require additional parameters to be set.
+
+For most mail attributes there are "get" methods to read the information stored in the message
+object. for further details, please refer to the *API* documentation.
+
+You also can use most methods of the `Mail\Message` object with a convenient fluent interface.
+
+```php
+use Zend\Mail;
+
+$mail = new Mail\Message();
+$mail->setBody('This is the text of the mail.')
+     ->setFrom('[email protected]', 'Some Sender')
+     ->addTo('[email protected]', 'Some Recipient')
+     ->setSubject('TestSubject');
+```
+
+## Configuring the default sendmail transport
+
+The most simple to use transport is the `Mail\Transport\Sendmail` transport class. It is essentially
+a wrapper to the *PHP* [mail()](http://php.net/mail) function. If you wish to pass additional
+parameters to the [mail()](http://php.net/mail) function, simply create a new transport instance and
+pass your parameters to the constructor.
+
+### Passing additional parameters
+
+This example shows how to change the Return-Path of the [mail()](http://php.net/mail) function.
+
+```php
+use Zend\Mail;
+
+$mail = new Mail\Message();
+$mail->setBody('This is the text of the email.');
+$mail->setFrom('[email protected]', 'Dolf');
+$mail->addTo('[email protected]', 'Matthew');
+$mail->setSubject('TestSubject');
+
+$transport = new Mail\Transport\Sendmail('[email protected]');
+$transport->send($mail);
+```
+
+> ## Note
+#### Safe mode restrictions
+Supplying additional parameters to the transport will cause the [mail()](http://php.net/mail)
+function to fail if *PHP* is running in safe mode.
+
+> ## Note
+#### Choosing your transport wisely
+Although the sendmail transport is the transport that requires only minimal configuration, it may
+not be suitable for your production environment. This is because emails sent using the sendmail
+transport will be more often delivered to SPAM-boxes. This can partly be remedied by using the
+\[SMTP Transport\](zend.mail.transport.quick-start.smtp-usage) combined with an SMTP server that has
+an overall good reputation. Additionally, techniques such as SPF and DKIM may be employed to ensure
+even more email messages are delivered as should.
+
+> ## Warning
+#### Sendmail Transport and Windows
+As the *PHP* manual states the `mail()` function has different behaviour on Windows and on \*nix
+based systems. Using the Sendmail Transport on Windows will not work in combination with `addBcc()`.
+The `mail()` function will sent to the BCC recipient such that all the other recipients can see him
+as recipient!
+Therefore if you want to use BCC on a windows server, use the SMTP transport for sending!