/source/manual/mail/sending.xml

<?xml version="1.0" encoding="UTF-8"?>
<sect1
    xml:id="mail.sending"
    xmlns="http://docbook.org/ns/docbook"
    xmlns:xlink="http://www.w3.org/1999/xlink"
>
	<title>Sending Messages</title>

	<para>
		Now that we have a message to send, let's actually get it out there. To send the message, 
		we need to pick what kind of "transport" we're going to use, then send the message through 
		that transport.
	</para>


	<sect2 xml:id="mail.sending.transport">
        <title>Using a Transport</title>
        <para>
        	Solar comes with two <literal>Solar_Mail_Transport</literal> adapters: the Phpmail one, which uses 
			<link xlink:href="http://php.net/manual/en/function.mail.php">mail()</link> 
			internally, and an SMTP factory-adapter one, which takes a little more setup but is a 
			lot more robust.
        </para>

		<sect3 xml:id="mail.sending.transport.php-mail">
		    <title>The PHP mail() Transport</title>
		    <para>
		    	Easy one first: the mail()-based adapter.
		    </para>
<programlisting language="php"><![CDATA[
<?php
$mail = Solar::factory('Solar_Mail_Message');
// .. build the message ...

// build a transport and send the message
$transport = Solar::factory('Solar_Mail_Transport', array(
    'adapter' => 'Solar_Mail_Transport_Adapter_Phpmail'
));

$transport->send($mail);
?>
]]></programlisting>

		</sect3>

		<sect3 xml:id="mail.sending.transport.solar-smtp">
		    <title>The Solar_Smtp Transport</title>
		    <para>
		    	The SMTP factory-adapter is a little more complicated, but still not too hard. 
				We need to build an <link xlink:href="http://solarphp.com/apidoc/class.Solar_Smtp.Overview">SMTP connection object</link>, 
				then tell the SMTP transport adapter to use it, then send the message.
		    </para>
<programlisting language="php"><![CDATA[
<?php
$mail = Solar::factory('Solar_Mail_Message');
// ...

// build an SMTP connection object
$smtp = Solar::factory('Solar_Smtp', array(
    'adapter' => 'Solar_Smtp_Adapter_NoAuth',
    'host'    => 'mail.example.com',
));

// build a transport and send the message
$transport = Solar::factory('Solar_Mail_Transport', array(
    'adapter' => 'Solar_Mail_Transport_Adapter_Smtp',
    'smtp'    => $smtp,
));

$transport->send($mail);
?>
]]></programlisting>

			<para>
				The SMTP connection object is itself a factory, and has adapters for various kinds of authentication:
				<itemizedlist>
		    		<listitem><para><link xlink:href="http://solarphp.com/apidoc/class.Solar_Smtp_Adapter_NoAuth.Overview">none (the default)</link></para></listitem>
		    		<listitem><para><link xlink:href="http://solarphp.com/apidoc/class.Solar_Smtp_Adapter_PlainAuth.Overview">plain</link></para></listitem>
		    		<listitem><para><link xlink:href="http://solarphp.com/apidoc/class.Solar_Smtp_Adapter_LoginAuth.Overview">login</link></para></listitem>
					<listitem><para><link xlink:href="http://solarphp.com/apidoc/class.Solar_Smtp_Adapter_CramMd5Auth.Overview">CRAM-MD5</link></para></listitem>
		    	</itemizedlist>
			</para>

		</sect3>

    </sect2>

	<sect2 xml:id="mail.sending.transport-di">
        <title>Transport Dependency-Injection</title>
        <para>
        	Instead of building a transport every time you send an email, you can configure a 
			transport for the mail message as a dependency injection. Then the mail message will 
			be able to "send itself" using that injected transport. For <literal>Solar_Mail_Message</literal>, 
			the config key for the transport injection is transport.
        </para>

		<sect3 xml:id="mail.sending.transport-di.config-array">
		    <title>Injecting From Config Array</title>
		    <para>
		    	The easiest way of dependency injection is to pass a config array for the transport. 
				Here's an example of injecting the PHP <link xlink:href="http://php.net/manual/en/function.mail.php">mail()</link> 
				adapter into the mail message.
		    </para>
<programlisting language="php"><![CDATA[
<?php
// create a message object, and inject a transport config
$mail = Solar::factory('Solar_Mail_Message', array(
    'transport' => array(
        'adapter' => 'Solar_Mail_Transport_Adapter_Phpmail',
    )
));

// ... compose the message ...

// now tell the email to "send itself".
// this uses the injected transport.
$mail->send();
?>
]]></programlisting>
			<para>
				Here's a more complex example, using the <literal>Solar_Smtp</literal> factory-adapter transport with plain 
				authentication. Note that the transport itself uses a dependency injection for the 
				<literal>Solar_Smtp</literal> object under the 'smtp' key.
			</para>
<programlisting language="php"><![CDATA[
<?php
// create a message object, and inject a transport config
$mail = Solar::factory('Solar_Mail_Message', array(
    'transport' => array(
        'adapter' => 'Solar_Mail_Transport_Adapter_Smtp',
        'smtp' => array(
            'adapter'  => 'Solar_Smtp_Adapter_PlainAuth',
            'username' => 'pmjones',
            'password' => 'secret',
            'host'     => 'mail.example.com',
        ),
    )
));

// ... compose the message ...

// now tell the email to "send itself".
// this uses the injected transport.
$mail->send();
?>
]]></programlisting>
			<para>
				This is quite convenient, especially since you can set up those arrays in your config 
				file in advance, making them the default configs each time you create a <literal>Solar_Mail_Message</literal> 
				object. In that case, you can use the class names instead of the full configuration arrays.
			</para>
<programlisting language="php"><![CDATA[
<?php
$config['Solar_Mail_Message'] = array(
    'transport' => 'Solar_Mail_Transport_Adapter_Smtp',
);

$config['Solar_Mail_Transport_Adapter_Smtp'] = array(
    'transport' => 'Solar_Smtp_Adapter_PlainAuth',
);

$config['Solar_Smtp_Adapter_PlainAuth'] = array(
    'adapter'  => 'Solar_Smtp_Adapter_PlainAuth',
    'username' => 'pmjones',
    'password' => 'secret',
    'host'     => 'mail.example.com',
);
?>
]]></programlisting>
			<para>
				Using the config-file-centered process instead of the logic-centered process means 
				that you can have all your settings in one place for use throughout your application. 
				You can even change adapters from the config file without changing any of the 
				mail-sending code, as long as you keep the same registry names.
			</para>
		</sect3>
	
		<sect3 xml:id="mail.sending.transport-di.registry">
		    <title>Injecting From the Registry</title>
		    <para>
		    	The only problem with injection using a config array is that the dependency objects 
				get created anew each time you create a <literal>Solar_Mail_Message</literal>. 
				Sometimes it's better to use registry objects for the dependency, so you don't use 
				up resources re-creating identical objects over and over again.
		    </para>
			
			<para>
				You can register the transport and SMTP objects in your bootstrap file or 
				<link xlink:href="http://solarphp.com/apidoc/class.Solar_Controller_Page._setup"><literal>Solar_Controller_Page::_setup()</literal></link> 
				so they are available throughout the application:
			</para>
<programlisting language="php"><![CDATA[
<?php
// build a Solar_Smtp object
$smtp = Solar::factory('Solar_Smtp', array(
    'adapter'  => 'Solar_Smtp_Adapter_PlainAuth',
    'username' => 'pmjones',
    'password' => 'secret',
    'host'     => 'mail.example.com',
));

// register it as 'smtp'
Solar_Registry::set('smtp', $smtp);

// build a Solar_Mail_Transport object with the SMTP object injected
$transport = Solar::factory('Solar_Mail_Transport', array(
    'adapter' => 'Solar_Mail_Transport_Adapter_Smtp',
    'smtp'    => 'smtp', // uses the registered 'smtp' object
);

// register the transport as 'mail-transport'
Solar_Registry::set('mail-transport', $transport);
?>
]]></programlisting>

		<para>
			Now when you create a new mail message, you can tell it that there's a transport 
			already available, and call <link xlink:href="http://solarphp.com/apidoc/class.Solar_Mail_Message.send">send()</link> 
			directly on the message.
		</para>

<programlisting language="php"><![CDATA[
<?php
$mail = Solar::factory('Solar_Mail_Message', array(
    'transport' => 'mail-transport',
));

// ... build the message, and then:
$mail->send();
?>
]]></programlisting>
		
		<para>
			If you want to, you can put it all of this config information in the Solar config file. 
			Then you can lazy-load the objects from the registry, and they will automatically have 
			all the right settings. The various dependency objects will be lazy-loaded automatically for you.
		</para>
		<para>
			In your Solar.config.php file:
		</para>
<programlisting language="php"><![CDATA[
<?php
// configure SMTP
$config['Solar_Smtp'] = array(
    'adapter'  => 'Solar_Smtp_Adapter_PlainAuth',
    'username' => 'pmjones',
    'password' => 'secret',
    'host'     => 'mail.example.com',
);

// configure mail transport
$config['Solar_Mail_Transport'] = array(
    'adapter' => 'Solar_Mail_Transport_Adapter_Smtp',
    'smtp'    => 'smtp',
);

// tell all mail messages to use the registered 'mail-transport'
$config['Solar_Mail_Message']['transport'] = 'mail-transport';
?>
]]></programlisting>
			<para>
				Then all you have to do in your setup logic is register class names instead of objects ...
			</para>
<programlisting language="php"><![CDATA[
<?php
Solar_Registry::set('smtp', 'Solar_Smtp');
Solar_Registry::set('mail-transport', 'Solar_Mail_Transport');
?>
]]></programlisting>

			<para>
				... which will cause those objects to be created only at the moment they are first 
				called as depndencies, and the same object will be reused every time you pull it from the registry.
			
			</para>
			<para>
				Now you can send an email message very simply:
			</para>
<programlisting language="php"><![CDATA[
<?php
// create and build a message
$mail = Solar::factory('Solar_Mail_Message');
// ...

// send the message; this creates the SMTP and mail-transport objects
// from the config-file settings, and sends the message trough the
// registered transport.
$mail->send();
?>
]]></programlisting>
		</sect3>
	</sect2>
</sect1>