Skip to content

Reworded the "How to use Gmail" cookbook article #5856

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 5 commits into from
Closed

Reworded the "How to use Gmail" cookbook article #5856

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
afd2305
Reworded the "How to use Gmail" cookbook article
javiereguiluz Nov 3, 2015
ac40aa1
Fixed the doc URL
javiereguiluz Nov 3, 2015
270b203
Implemented all the recommended changes
javiereguiluz Dec 14, 2015
fdef6ea
Fixed YAML syntax issue
javiereguiluz Dec 17, 2015
ec59e77
Last round of reviews
javiereguiluz Dec 18, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 69 additions & 23 deletions cookbook/email/gmail.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,6 @@ During development, instead of using a regular SMTP server to send emails, you
might find using Gmail easier and more practical. The SwiftmailerBundle makes
it really easy.

.. tip::

Instead of using your regular Gmail account, it's of course recommended
that you create a special account.

In the development configuration file, change the ``transport`` setting to
``gmail`` and set the ``username`` and ``password`` to the Google credentials:

Expand Down Expand Up @@ -55,33 +50,84 @@ In the development configuration file, change the ``transport`` setting to
'password' => 'your_gmail_password',
));

You're done!
If you are using the Symfony Standard Edition, it's more convenient to configure
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it's the cookbook, so we can assume they are and we can say "It's more convenient to configure these options in the parameters.yml.dist file:"

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

actually, should be parameters.yml

these options in the ``parameters.yml.dist`` file:

.. tip::
.. code-block:: yaml

If you are using the Symfony Standard Edition, configure the parameters in ``parameters.yml``:
# app/config/parameters.yml.dist
parameters:
# ...
mailer_user: your_gmail_username
mailer_password: your_gmail_password

.. configuration-block::

.. code-block:: yaml

# app/config/parameters.yml
parameters:
# ...
mailer_transport: gmail
mailer_host: ~
mailer_user: your_gmail_username
mailer_password: your_gmail_password
# app/config/config_dev.yml
swiftmailer:
transport: gmail
username: '%mailer_user%'
password: '%mailer_password%'

.. code-block:: xml

<!-- app/config/config_dev.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/swiftmailer
http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">

<!-- ... -->
<swiftmailer:config
transport="gmail"
username="%mailer_user%"
password="%mailer_password%"
/>
</container>

.. code-block:: php

// app/config/config_dev.php
$container->loadFromExtension('swiftmailer', array(
'transport' => 'gmail',
'username' => '%mailer_user%',
'password' => '%mailer_password%',
));

Redefining the Default Configuration Parameters
-----------------------------------------------

The ``gmail`` transport is simply a shortcut that uses the ``smtp`` transport
and sets these options:

============== ==================
Option Value
============== ==================
``encryption`` ``ssl``
``auth_mode`` ``login``
``host`` ``smtp.gmail.com``
============== ==================

If your application uses ``tls`` encryption or ``oauth`` authentication, you
must override the default options by defining the ``encryption`` and ``auth_mode``
parameters.

.. note::
If you are using 2-Step-Verification, you must `generate an App password`_ and
use this as your ``mailer_password`` value.

The ``gmail`` transport is simply a shortcut that uses the ``smtp`` transport
and sets ``encryption``, ``auth_mode`` and ``host`` to work with Gmail.
If your Gmail account uses 2-Step-Verification, you must `generate an App password`_
and use it as the value of the ``mailer_password`` parameter. You must also ensure
that you `allow less secure apps to access your Gmail account`_.

.. note::
.. seealso::

Depending on your Gmail account settings, you may get authentication errors
within your app. If your Gmail account uses 2-Step-Verification, you should
`generate an App password`_ to use for your ``mailer_password`` parameter.
You should also ensure that you `allow less secure apps to access your Gmail account`_.
:doc:`Swiftmailer configuration reference </reference/configuration/swiftmailer>`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would have kept the sentence though:

.. seealso::

    See the :doc:`Swiftmailer configuration reference </reference/configuration/swiftmailer>`
    for more details.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But we can make that change when merging. The PR so far looks ready to me. 👍


.. _`generate an App password`: https://support.google.com/accounts/answer/185833
.. _`allow less secure apps to access your Gmail account`: https://support.google.com/accounts/answer/6010255