vendor/zendframework/zend-mail/doc/book/transport/smtp-authentication.md

   1 # SMTP Authentication
   2
   3 zend-mail supports the use of SMTP authentication, which can be enabled via
   4 configuration.  The available built-in authentication methods are PLAIN, LOGIN,
   5 and CRAM-MD5, all of which expect 'username' and 'password' values in the
   6 configuration array.
   7
   8 ## Configuration
   9
  10 In order to enable authentication, ou need to specify a "connection class" and
  11 connection configuration when configuring your SMTP transport. The two settings
  12 are briefly covered in the [SMTP transport configuration options](smtp-options.md#configuration-options). Below are more details.
  13
  14 ### connection_class
  15
  16 The connection class should be a fully qualified class name of a
  17 `Zend\Mail\Protocol\Smtp\Auth\*` class or extension, or the short name (name
  18 without leading namespace). zend-mail ships with the following:
  19
  20 - `Zend\Mail\Protocol\Smtp\Auth\Plain`, or `plain`
  21 - `Zend\Mail\Protocol\Smtp\Auth\Login`, or `login`
  22 - `Zend\Mail\Protocol\Smtp\Auth\Crammd5`, or `crammd5`
  23
  24 Custom connection classes must be extensions of `Zend\Mail\Protocol\Smtp`.
  25
  26 ### connection_config
  27
  28 The `connection_config` should be an associative array of options to provide to
  29 the underlying connection class. All shipped connection classes require:
  30
  31 - `username`
  32 - `password`
  33
  34 Optionally, ou may also provide:
  35
  36 - `ssl`: either the value `ssl` or `tls`.
  37 - `port`: if using something other than the default port for the protocol used.
  38   Port 25 is the default used for non-SSL connections, 465 for SSL, and 587 for
  39   TLS.
  40 - `use_complete_quit`: configuring whether or not an SMTP transport should
  41   issue a `QUIT` at `__destruct()` and/or end of script execution. Useful in
  42   long-running scripts against [SMTP servers that implements a reuse time limit](#smtp-transport-usage-for-servers-with-reuse-time-limit).
  43
  44 ## Examples
  45
  46 ### SMTP Transport Usage with PLAIN AUTH
  47
  48 ```php
  49 use Zend\Mail\Transport\Smtp as SmtpTransport;
  50 use Zend\Mail\Transport\SmtpOptions;
  51
  52 // Setup SMTP transport using PLAIN authentication
  53 $transport = new SmtpTransport();
  54 $options   = new SmtpOptions([
  55     'name'              => 'localhost.localdomain',
  56     'host'              => '127.0.0.1',
  57     'connection_class'  => 'plain',
  58     'connection_config' => [
  59         'username' => 'user',
  60         'password' => 'pass',
  61     ],
  62 ]);
  63 $transport->setOptions($options);
  64 ```
  65
  66 ### SMTP Transport Usage with LOGIN AUTH
  67
  68 ```php
  69 use Zend\Mail\Transport\Smtp as SmtpTransport;
  70 use Zend\Mail\Transport\SmtpOptions;
  71
  72 // Setup SMTP transport using LOGIN authentication
  73 $transport = new SmtpTransport();
  74 $options   = new SmtpOptions([
  75     'name'              => 'localhost.localdomain',
  76     'host'              => '127.0.0.1',
  77     'connection_class'  => 'login',
  78     'connection_config' => [
  79         'username' => 'user',
  80         'password' => 'pass',
  81     ],
  82 ]);
  83 $transport->setOptions($options);
  84 ```
  85
  86 ### SMTP Transport Usage with CRAM-MD5 AUTH
  87
  88 ```php
  89 use Zend\Mail\Transport\Smtp as SmtpTransport;
  90 use Zend\Mail\Transport\SmtpOptions;
  91
  92 // Setup SMTP transport using CRAM-MD5 authentication
  93 $transport = new SmtpTransport();
  94 $options   = new SmtpOptions([
  95     'name'              => 'localhost.localdomain',
  96     'host'              => '127.0.0.1',
  97     'connection_class'  => 'crammd5',
  98     'connection_config' => [
  99         'username' => 'user',
 100         'password' => 'pass',
 101     ],
 102 ]);
 103 $transport->setOptions($options);
 104 ```
 105
 106 ### SMTP Transport Usage with PLAIN AUTH over TLS
 107
 108 ```php
 109 use Zend\Mail\Transport\Smtp as SmtpTransport;
 110 use Zend\Mail\Transport\SmtpOptions;
 111
 112 // Setup SMTP transport using PLAIN authentication over TLS
 113 $transport = new SmtpTransport();
 114 $options   = new SmtpOptions([
 115     'name'              => 'example.com',
 116     'host'              => '127.0.0.1',
 117     'port'              => 587,
 118     // Notice port change for TLS is 587
 119     'connection_class'  => 'plain',
 120     'connection_config' => [
 121         'username' => 'user',
 122         'password' => 'pass',
 123         'ssl'      => 'tls',
 124     ],
 125 ]);
 126 $transport->setOptions($options);
 127 ```
 128
 129 ### SMTP Transport Usage for servers with reuse time limit
 130
 131 By default, every `Zend\Mail\Protocol\Smtp\*` class tries to disconnect from
 132 the STMP server by sending a `QUIT` command and expecting a `221` (_Service
 133 closing transmission channel_) response code.  This is done automatically at
 134 object destruction (via the `__destruct()` method), and can generate errors
 135 with SMTP servers like [Posftix](http://www.postfix.org/postconf.5.html#smtp_connection_reuse_time_limit)
 136 that implement a reuse time limit:
 137
 138 ```php
 139 // [...]
 140 $transport->send($message);
 141
 142 var_dump('E-mail sent');
 143 sleep(305);
 144 var_dump('Soon to exit...');
 145 exit;
 146
 147 // E-mail sent
 148 // Soon to exit...
 149 // Notice: fwrite(): send of 6 bytes failed with errno=32 Broken pipe in ./zend-mail/src/Protocol/AbstractProtocol.php on line 255
 150 // Fatal error: Uncaught Zend\Mail\Protocol\Exception\RuntimeException: Could not read from 127.0.0.1 in ./zend-mail/src/Protocol/AbstractProtocol.php:301
 151 ```
 152
 153 To avoid this error, you can configure any `Zend\Mail\Protocol\Smtp\*` instance
 154 to close the connection with the SMTP server without the `QUIT` command:
 155
 156 ```php
 157 use Zend\Mail\Transport\Smtp as SmtpTransport;
 158 use Zend\Mail\Transport\SmtpOptions;
 159
 160 // Setup SMTP transport to exit without the `QUIT` command
 161 $transport = new SmtpTransport();
 162 $options   = new SmtpOptions([
 163     'name'              => 'localhost.localdomain',
 164     'host'              => '127.0.0.1',
 165     'connection_class'  => 'plain',
 166     'connection_config' => [
 167         'username'          => 'user',
 168         'password'          => 'pass',
 169         'use_complete_quit' => false,
 170     ],
 171 ]);
 172 $transport->setOptions($options);
 173 ```
 174
 175 > ### NOTE: recreate old connection
 176 >
 177 > The flag described above aims to avoid errors that you cannot manage from PHP.
 178 >
 179 > If you deal with SMTP servers that exhibit this behavior from within
 180 > long-running scripts, you will need to:
 181 >
 182 > 1. Trace the time elapsed since the creation of the connection.
 183 > 1. Close and reopen the connection if the elapsed time exceeds the reuse
 184 >    time limit
 185 >
 186 > As an example, you can perform these steps by applying a proxy class that
 187 > wraps the real `Zend\Mail\Protocol\Smtp\*` instance to track the construction
 188 > time, and then close and open the connection when needed.