feature #19 [Documentation] Extracted from Sylius/Sylius repository ()

This PR was merged into the 1.5-dev branch.

Discussion
----------



Commits
-------

1bf0c37 sylius mailer bundle exported to md
110add1 changed menu display names, improved php code

README.md

@@ -18,7 +18,7 @@ Sylius is an Open Source eCommerce solution built from decoupled components with
 Documentation
 -------------
 
-Documentation is available on [**docs.sylius.com**](http://docs.sylius.com/en/latest/components_and_bundles/bundles/SyliusMailerBundle/index.html).
+[Documentation is available in the *docs* folder.](docs/index.md)
 
 Contributing
 ------------

docs/configuration.md

@@ -0,0 +1,30 @@
+# Configuration reference
+
+```yaml
+sylius_mailer:
+      sender_adapter: sylius.email_sender.adapter.swiftmailer # Adapter for sending e-mails.
+      renderer_adapter: sylius.email_renderer.adapter.twig # Adapter for rendering e-mails.
+      sender:
+          name: # Required - default sender name.
+          address: # Required - default sender e-mail address.
+      templates: # Your templates available for selection in backend!
+          label1: Template path 1
+          label2: Template path 2
+          label3: Template path 3
+      emails:
+          your_email:
+              subject: Subject of your email
+              template: App:Email:yourEmail.html.twig
+              enabled: true/false
+              sender:
+                 name: Custom name
+                 address: Custom sender address for this e-mail
+          your_another_email:
+              subject: Subject of your another email
+              template: App:Email:yourAnotherEmail.html.twig
+              enabled: true/false
+              sender:
+                 name: Custom name
+                 address: Custom sender address for this e-mail
+```
+**[Go back to the documentation's index](index.md)**

docs/index.md

@@ -0,0 +1,20 @@
+# SyliusMailerBundle
+
+Sending customizable e-mails has never been easier in Symfony.
+
+You can configure different e-mail types in the YAML or in database. (and use YAML as fallback)
+This allows you to send out e-mails with one simple method call, providing an unique code and data.
+
+The bundle supports adapters, by default e-mails are rendered using Twig and sent via Swiftmailer, but you can easily implement your own adapter and delegate the whole operation to external API.
+
+This bundle provides easy integration of the [Sylius mailer component](https://docs.sylius.com/en/latest/components_and_bundles/components/Mailer/index.html)
+with any Symfony full-stack application.
+
+* [Installation](installation.md)
+* [Your First Email](your_first_email.md)
+* [Using Custom Adapter](using_custom_adapter.md)
+* [Configuration reference](configuration.md)
+
+## Learn more
+
+* [Emails in the Sylius platform](https://docs.sylius.com/en/latest/book/architecture/emails.html) - concept documentation

docs/installation.md

@@ -0,0 +1,48 @@
+# Installation
+
+We assume you're familiar with [Composer](http://packagist.org), a dependency manager for PHP.
+Use the following command to add the bundle to your `composer.json` and download the package.
+
+If you have [Composer installed globally](http://getcomposer.org/doc/00-intro.md#globally).
+
+```bash
+composer require sylius/mailer-bundle
+```
+Otherwise you have to download .phar file.
+
+```bash
+curl -sS https://getcomposer.org/installer | php
+php composer.phar require sylius/mailer-bundle
+```
+# Adding required bundles to the kernel
+
+You need to enable the bundle inside the kernel.
+
+```php
+// config/bundles.php
+
+return [
+    new winzou\Bundle\StateMachineBundle\winzouStateMachineBundle(),
+    new FOS\RestBundle\FOSRestBundle(),
+    new JMS\SerializerBundle\JMSSerializerBundle($this),
+    new Stof\DoctrineExtensionsBundle\StofDoctrineExtensionsBundle(),
+    new WhiteOctober\PagerfantaBundle\WhiteOctoberPagerfantaBundle(),
+
+    new Sylius\Bundle\MailerBundle\SyliusMailerBundle(),
+];
+```
+# Container configuration
+
+Put this configuration inside your ``config/packages/sylius_mailer.yaml``.
+
+```yaml
+sylius_mailer:
+    sender:
+        name: My website
+        address: no-reply@my-website.com
+```
+
+Congratulations! The bundle is now installed and ready to use.
+
+**[Go back to the documentation's index](index.md)**
+

docs/using_custom_adapter.md

@@ -0,0 +1,41 @@
+# Using Custom Adapter
+
+There are certain use cases, where you do not want to send the e-mail from your app, but delegate the task to an external API.
+
+It is really simple with Adapters system!
+
+## Implement Your Adapter
+
+Create your adapter class and add your custom logic for sending:
+
+```php
+namespace App\Mailer\Adapter;
+
+use Sylius\Component\Mailer\Sender\Adapter\AbstractAdapter;
+use Sylius\Component\Mailer\Model\EmailInterface;
+use Sylius\Component\Mailer\Renderer\RenderedEmail;
+
+class CustomAdapter extends AbstractAdapter
+{
+    public function send(array $recipients, $senderAddress, $senderName, RenderedEmail $renderedEmail, EmailInterface $email, array $data)
+    {
+        // Your custom logic.
+    }
+}
+```
+## Register And Configure New Adapter In Container
+
+In your ``config/packages/sylius_mailer.yaml`` file, add your adapter definition and configure the mailer to use it.
+
+```yaml
+services:
+    app.email_sender.adapter.custom:
+        parent: sylius.email_sender.adapter.abstract
+        class: App\Mailer\Adapter\CustomAdapter
+
+sylius_mailer:
+    sender_adapter: app.email_sender.adapter.custom
+```
+That's it! Your new adapter will be used to send out e-mails. You can do whatever you want there!
+
+**[Go back to the documentation's index](index.md)**

docs/your_first_email.md

@@ -0,0 +1,96 @@
+# Your First Email
+
+Let's say you want to send a notification to the website team when someone submits a new position to your movie catalog website!
+
+You can do it in few simple steps:
+
+## Configure Your E-Mail
+
+
+In your ``config/packages/sylius_mailer.yaml``, under ``sylius_mailer`` you should configure the email:
+
+```yaml
+# config/packages/sylius_mailer.yaml
+
+sylius_mailer:
+    sender:
+        name: Movie Database Example
+        address: no-reply@movie-database-example.com
+    emails:
+        movie_added_notification:
+            subject: A new movie {{ movie.title }} has been submitted
+            template: "Email/movieAddedNotification.html.twig"
+```
+That's it! Your unique code is "movie_added_notification". Now, let's create the template.
+
+## Creating Your Template
+
+In your ``templates/Email/movieAddedNotification.html.twig`` put the following Twig code:
+
+```twig
+{% block subject %}
+    A new movie {{ movie.title }} has been submitted
+{% endblock %}
+
+{% block body %}
+    Hello Movie Database Example!
+
+    A new movie has been submitted for review to your database.
+
+    Title: {{ movie.title }}
+    Added by {{ user.name }}
+
+    Please review it and accept or reject!
+{% endblock %}
+```
+That should be enough!
+
+## Sending The E-Mail
+
+The service responsible for sending an e-mail has id ``sylius.email_sender``. All you need to do is retrieve it from the container or inject to a listener:
+
+```php
+namespace App\Controller;
+
+use Symfony\Component\HttpFoundation\Request;
+
+class MovieController
+{
+    public function submitAction(Request $request)
+    {
+        // Your code.
+
+        $this->get('sylius.email_sender')->send('movie_added_notification', ['team@website.com'], ['movie' => $movie, 'user' => $this->getUser()]);
+    }
+}
+```
+Listener example:
+
+```php
+namespace App\Controller;
+
+use App\Event\MovieCreatedEvent;
+use Sylius\Component\Mailer\Sender\SenderInterface;
+
+class MovieNotificationListener
+{
+    private $sender;
+
+    public function __construct(SenderInterface $sender)
+    {
+        $this->sender = $sender;
+    }
+
+    public function onMovieCreation(MovieCreatedEvent $event)
+    {
+        $movie = $event->getMovie();
+        $user = $event->getUser();
+
+        $this->sender->send('movie_added_notification', ['team@website.com'], ['movie' => $movie, 'user' => $user]);
+    }
+}
+```
+
+We recommend using events approach, but you can send e-mails from anywhere in your application. Enjoy!
+
+**[Go back to the documentation's index](index.md)**