Ah, sending mail, the bane of everyone who has ever used the php mail() function for anything remotely non-trivial. There are lots of entries in the \u201chelps you send mail\u201d category in PHP userland:
\nWhile each of these will work with Solar, the new Solar_Mail and Solar_Smtp packages work \u201cnatively\u201d, in that they support automatic configuration, locale and exception inheritance, and so on. Read on for some examples on how to use them.
Here\u2019s a short example on how to build a basic message and set the recipients. In this example, I\u2019ll send a quick note to my old friend Bolivar Shagnasty, and give him both a text and HTML version of the message.
\nNote that the Solar_Mail_Message set*() methods are fluent, so you can chain them together when you find it appropriate. (You can review the full set of Solar_Mail_Message methods if you like.)
$text = <<<TEXT\nThe quick brown fox jumps over the lazy dog.\n\nNow is the time for all good men to come to the aid of their country.\nTEXT;\n\n$html = <<<HTML\n<p>The quick brown fox jumps <em>over</em> the lazy dog.</p>\n\n<p><strong>Now</strong> is the time for all good men\nto come to the aid of their country.</p>\nHTML;\n\n$mail = Solar::factory('Solar_Mail_Message');\n\n$mail->setCharset('utf-8')\n ->setFrom('pmjones@example.com', 'Paul M. Jones')\n ->addTo('boshag@example.com', 'Bolivar Shagnasty')\n ->addCc('nobody@example.net')\n ->setSubject('A Short Test Message')\n ->setText($text)\n ->setHtml($html);\nThat\u2019s pretty easy \u2026 but is it safe?
\nAnything that ends up getting sent as a mail header, including addresses and the subject line, is sanitized against header-injection attacks by removing newlines from the header label and value. Let\u2019s say you want to add a new custom header:
\n$mail = Solar::factory('Solar_Mail_Message');\n$mail->setHeader('X-Custom-Header', \"FoornrnAn evil message\");\nUnder a less-secure system this might cause the header to be sent as:
\nX-Custom-Header: Foo\n\nAn evil message.\nThat\u2019s no good \u2013 somebody just injected their own message into our email.
\nWith Solar_Mail_Message, when the mail gets sent, that header will go out as:
X-Custom-Header: FooAn evil message\nWe strip the newlines in header labels and values automatically, so you should be safe against header injections. (If there are other aspects to securing against header injections I would be happy to hear them.)
\nAdding an attachment to an email is pretty easy; you can use a convenience method to attach a file, or you can build it yourself.
\nConvenience method attachFile():
$file_path = '/path/to/file.pdf';\n$mime_type = 'application/pdf';\n\n// this will automatically set the attachment name\n// to the basename() of the attached file\n$mail = Solar::factory('Solar_Mail_Message');\n$mail->attachFile($file_name, $mime_type);\nOr you can build and add a MIME part yourself with attachPart():
$file_path = '/path/to/file.pdf';\n$mime_type = 'application/pdf';\n\n$part = Solar::factory('Solar_Mail_Message_Part');\n$part->setDisposition('attachment');\n$part->setFilename(basename($file_name));\n$part->setContent(file_get_contents($file_name));\n$part->setType($mime_type);\n\n$mail = Solar::factory('Solar_Mail_Message');\n$mail->attachPart($part);\nNow that we have a message to send, let\u2019s actually get it out there. To send the message, we need to pick what kind of \u201ctransport\u201d we\u2019re going to use, then send the message through that transport.
\nSolar comes with two Solar_Mail_Transport adapters: the Phpmail one, which uses mail() internally, and an SMTP factory-adapter one, which takes a little more setup but is a lot more robust.
Easy one first: the mail()-based adapter.
\n$mail = Solar::factory('Solar_Mail_Message');\n// .. build the message ...\n\n// build a transport and send the message\n$transport = Solar::factory('Solar_Mail_Transport', array(\n 'adapter' => 'Solar_Mail_Transport_Adapter_Phpmail'\n));\n\n$transport->send($mail);\nThe SMTP factory-adapter is a little more complicated, but still not too hard. We need to build an SMTP connection object, then tell the SMTP transport adapter to use it, then send the message.
\n$mail = Solar::factory('Solar_Mail_Message');\n// ...\n\n// build an SMTP connection object\n$smtp = Solar::factory('Solar_Smtp', array(\n 'adapter' => 'Solar_Smtp_Adapter_NoAuth',\n 'host' => 'mail.example.com',\n));\n\n// build a transport and send the message\n$transport = Solar::factory('Solar_Mail_Transport', array(\n 'adapter' => 'Solar_Mail_Transport_Adapter_Smtp',\n 'smtp' => $smtp,\n));\n\n$transport->send($mail);\nThe SMTP connection object is itself a factory, and has adapters for various kinds of authentication:
\n\nLet\u2019s say you always use SMTP with plain authentication when sending a message. You can register the transport objects in your bootstrap file or your Solar_Controller_Page::_setup() method so they are available throughout the application:
// build a Solar_Smtp object\n$smtp = Solar::factory('Solar_Smtp', array(\n 'adapter' => 'Solar_Smtp_Adapter_PlainAuth',\n 'username' => 'pmjones',\n 'password' => 'secret',\n 'host' => 'mail.example.com',\n));\n\n// register it as 'smtp'\nSolar::register('smtp', $smtp);\n\n// build a Solar_Mail_Transport object with the SMTP object injected\n$transport = Solar::factory('Solar_Mail_Transport', array(\n 'adapter' => 'Solar_Mail_Transport_Adapter_Smtp',\n 'smtp' => 'smtp', // uses the registered 'smtp' object\n);\n\n// register the transport as 'mail-transport'\nSolar::register('mail-transport', $transport);\nNow when you create a new mail message, you can tell it that there\u2019s a transport already available, and call send() directly on the message.
\n$mail = Solar::factory('Solar_Mail_Message', array(\n 'transport' => 'mail-transport',\n));\n\n// ... build the message, and then:\n$mail->send();\nFinally, you can take the configuration of the SMTP, transport, and mail objects entirely out of your logic, and put it all in the Solar config file.
\nThen 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, since dependency injection is a core component of Solar.
\nIn your Solar.config.php file:
\n// configure SMTP\n$config['Solar_Smtp'] = array(\n 'adapter' => 'Solar_Smtp_Adapter_PlainAuth',\n 'username' => 'pmjones',\n 'password' => 'secret',\n 'host' => 'mail.example.com',\n);\n\n// configure mail transport\n$config['Solar_Mail_Transport'] = array(\n 'adapter' => 'Solar_Mail_Transport_Adapter_Smtp',\n 'smtp' => 'smtp',\n);\n\n// tell all mail messages to use the registered 'mail-transport'\n$config['Solar_Mail_Message']['transport'] = 'mail-transport';\nThen all you have to do in your setup logic is register class names instead of objects \u2026
\nSolar::register('smtp', 'Solar_Smtp');\nSolar::register('mail-transport', 'Solar_Mail_Transport');\n\u2026 which will cause those objects to be created only at the moment they are first called as depndencies.
\nNow you can send an email message very simply:
\n// create and build a message\n$mail = Solar::factory('Solar_Mail_Message');\n// ...\n\n// send the message; this creates the SMTP and mail-transport objects\n// from the config-file settings, and sends the message trough the\n// registered transport.\n$mail->send();\nUsing 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.
\nThat\u2019s a whirlwind tour of how to send mail in Solar. If you have questions or comments, please feel free to leave them here, or join the Solar mailing list \u2013 we\u2019d love to have you around.
\n" }