merged branch igorw/swiftmailer-docs (PR #172)

Commits
-------

d4a96c35 [docs] adjust path yet again, to point to /lib/classes
b482107a [docs] add some missing docs for internal swiftmailer services
c4957ef5 [docs] remove unneeded transport and mailer from swiftmailer docs
f210d1ea Merge branch 'master' into swiftmailer-docs
50fddd1c [docs] remove duplicate 'a'
62a31c0f [docs] rewrite usage POST example to not use Swiftmailer
3c92b812 [docs] documentation for SwiftmailerExtension

Discussion
----------

Swiftmailer docs

Finally got round to finishing this one.

* Adds documentation for the SwiftmailerExtension.
* Changes the `POST` example in usage to use `mail()` instead of Swiftmailer.

---------------------------------------------------------------------------

by igorw at 2011/09/18 07:25:43 -0700

Should be complete now.

doc/extensions.rst

@@ -59,6 +59,7 @@ All of these are within the ``Silex\Extension`` namespace.
 * :doc:`DoctrineExtension <extensions/doctrine>`
 * :doc:`MonologExtension <extensions/monolog>`
 * :doc:`SessionExtension <extensions/session>`
+* :doc:`SwiftmailerExtension <extensions/swiftmailer>`
 * :doc:`TwigExtension <extensions/twig>`
 * :doc:`TranslationExtension <extensions/translation>`
 * :doc:`UrlGeneratorExtension <extensions/url_generator>`

doc/extensions/index.rst

@@ -7,6 +7,7 @@ Silex
     doctrine
     monolog
     session
+    swiftmailer
     translation
     twig
     url_generator

doc/extensions/swiftmailer.rst

+SwiftmailerExtension
+====================
+
+The *SwiftmailerExtension* provides a service for sending
+email through the `Swift Mailer <http://swiftmailer.org>`_
+library.
+
+You can use the ``mailer`` service to send messages easily.
+By default, it will attempt to send emails through SMTP.
+
+Parameters
+----------
+
+* **swiftmailer.options**: An array of options for the default
+  SMTP-based configuration.
+
+  The following options can be set:
+
+  * **host**: SMTP hostname, defaults to 'localhost'.
+  * **port**: SMTP port, defaults to 25.
+  * **username**: SMTP username, defaults to an empty string.
+  * **password**: SMTP password, defaults to an empty string.
+  * **encryption**: SMTP encryption, defaults to null.
+  * **auth_mode**: SMTP authentication mode, defaults to null.
+
+* **swiftmailer.class_path** (optional): Path to where the
+  Swift Mailer library is located.
+
+Services
+--------
+
+* **mailer**: The mailer instance.
+
+  Example usage::
+
+    $message = \Swift_Message::newInstance();
+
+    // ...
+
+    $app['mailer']->send($message);
+
+* **swiftmailer.transport**: The transport used for e-mail
+  delivery. Defaults to a ``Swift_Transport_EsmtpTransport``.
+
+* **swiftmailer.transport.buffer**: StreamBuffer used by
+  the transport.
+
+* **swiftmailer.transport.authhandler**: Authentication
+  handler used by the transport. Will try the following
+  by default: CRAM-MD5, login, plaintext.
+
+* **swiftmailer.transport.eventdispatcher**: Internal event
+  dispatcher used by Swiftmailer.
+
+Registering
+-----------
+
+Make sure you place a copy of *Swift Mailer* in the ``vendor/swiftmailer``
+directory. Make sure you point the class path to ``/lib/classes``.
+
+::
+
+    $app->register(new Silex\Extension\SwiftmailerExtension(), array(
+        'swiftmailer.class_path'  => __DIR__.'/vendor/swiftmailer/lib/classes',
+    ));
+
+.. note::
+
+    Swift Mailer is not compiled into the ``silex.phar`` file. You have to
+    add your own copy of Swift Mailer to your application.
+
+Usage
+-----
+
+The Swiftmailer extension provides a ``mailer`` service.
+
+::
+
+    $app->post('/feedback', function () use ($app) {
+        $request = $app['request'];
+
+        $message = \Swift_Message::newInstance()
+            ->setSubject('[YourSite] Feedback')
+            ->setFrom(array('noreply@yoursite.com'))
+            ->setTo(array('feedback@yoursite.com'))
+            ->setBody($request->get('message'));
+
+        $app['mailer']->send($message);
+
+        return new Response('Thank you for your feedback!', 201);
+    });
+
+For more information, check out the `Swift Mailer documentation
+<http://swiftmailer.org>`_.

doc/usage.rst

@@ -142,31 +142,24 @@ Example POST route
 ~~~~~~~~~~~~~~~~~~
 
 POST routes signify the creation of a resource. An example for this is a
-feedback form. We will use `Swift Mailer
-<http://swiftmailer.org/>`_ and assume a copy of it to be present in the
-``vendor/swiftmailer`` directory::
-
-    require_once __DIR__.'/vendor/swiftmailer/lib/swift_required.php';
+feedback form. We will use the ``mail`` function to send an e-mail::
 
     use Symfony\Component\HttpFoundation\Request;
     use Symfony\Component\HttpFoundation\Response;
 
     $app->post('/feedback', function (Request $request) {
-        $message = \Swift_Message::newInstance()
-            ->setSubject('[YourSite] Feedback')
-            ->setFrom(array('noreply@yoursite.com'))
-            ->setTo(array('feedback@yoursite.com'))
-            ->setBody($request->get('message'));
-
-        $transport = \Swift_MailTransport::newInstance();
-        $mailer = \Swift_Mailer::newInstance($transport);
-        $mailer->send($message);
+        $message = $request->get('message');
+        mail('feedback@yoursite.com', '[YourSite] Feedback', $message);
 
         return new Response('Thank you for your feedback!', 201);
     });
 
-It is pretty straight forward. We include the Swift Mailer library,
-set up a message and send that message.
+It is pretty straightforward.
+
+.. note::
+
+    There is a `SwiftmailerExtension <extensions/swiftmailer>` included
+    that you can use instead of ``mail()``.
 
 The current ``request`` is automatically injected by Silex to the Closure
 thanks to the type hinting. It is an instance of `Request
@@ -611,10 +604,10 @@ The exact cause of this issue could not be determined yet.
 ioncube loader bug
 ~~~~~~~~~~~~~~~~~~
 
-Ioncube loader is an extension that can decode PHP encoded file. 
-Unfortunately, old versions (prior to version 4.0.9) are not working well 
+Ioncube loader is an extension that can decode PHP encoded file.
+Unfortunately, old versions (prior to version 4.0.9) are not working well
 with phar archives.
-You must either upgrade Ioncube loader to version 4.0.9 or newer or disable it 
+You must either upgrade Ioncube loader to version 4.0.9 or newer or disable it
 by commenting or removing this line in your php.ini file:
 
 .. code-block:: ini