[C2] Sorting out mailer params

[ywarnier]

In C2 git right now (pre-alpha3) there's a little mess regarding MAILER settings.

In C1, almost all mail-related settings were kept in app/config/mail.conf.php, to the exception of the noreply_email_address setting which was kept in the settings_current table.

This allowed e-mail settings to be "hidden" to beginner Chamilo admins who could possibly break the configuration by changing it from the web interface. However, I think it is reasonnable to consider that beginner Chamilo admins have a better level of digitalization than 10 years ago and that screwing e-mail settings, in the end, is a recoverable error. Even more so if you have a way to test your configuration before you save it.

At this moment, in what will become Chamilo 2, we have added an e-mail sending configuration section in the Chamilo install wizard, which either just asks for a name and e-mail (in case of "mail" or "sendmail" being used locally on the server) or, for SMTP, the email/name/host/port/authentication/user/pass/security/charset/replyto/debug and a test button.

In .env, we currently have:

###> symfony/mailer ###
MAILER='' # (mail/sendmail/smtp)
SMTP_HOST=''
SMTP_PORT=''
SMTP_AUTH=''
SMTP_USER=''
SMTP_PASS=''
SMTP_SECURE='' # 0/1
SMTP_CHARSET=''
SMTP_UNIQUE_REPLY_TO='true'
SMTP_DEBUG='' # 0/1

MAILER_DSN='://:@:'
MAILER_FROM_EMAIL=''
MAILER_FROM_NAME=''
###< symfony/mailer ###

We need at least a MAILER_DSN in .env, otherwise Symfony will get upset, but the other settings are not needed there.

There is also (separately, in 1.11) a notion of "unique_sender" which goes with a name and an e-mail and that we want to drop and set to true by default (there's no point in trying to fake sending each e-mail from the e-mail address of the person having sent the mail).

Additionnally, in the settings table, we have:

• smtp_from_email
• noreply_email_address
• possibly smtp_from_name

Changes needed

No setting should remain in .env, except for the MAILER_DSN. The MAILER_DSN will hold a default value, set during the installation and to satisfy Symfony, but the real MAILER_DSN will be read from the settings.variable='mailer_dsn' setting. This DB setting will also be set at installation (a copy of the MAILER_DSN in .env) but will then be editable by the admin in the platform settings. In this case, the mailer_dsn setting from the database then takes priority and always overrides the MAILER_DSN from .env. This is done through a custom transport factory in the Chamilo code.

Defining the DSN correctly removes the need for the following fields, as the DSN contains them:

• MAILER
• SMTP_HOST
• SMTP_PORT
• SMTP_AUTH
• SMTP_USER
• SMTP_PASS
• SMTP_SECURE

During installation, the DSN field also replaces all the related fields.

Other settings should be added to the database. Here is a table explaining the types of changes required.

Name in C1	Old name in C2	New (variable in settings)	Description	Language term	Language term description
$platform_email['SMTP_MAILER']	MAILER	mailer_dsn	The DSN	Mail DSN	The DSN fully includes all parameters needed to connect to the mail service. You can learn more at %s. Here are a few examples of supported DSN syntaxes: %s
$platform_email['SMTP_HOST']	SMTP_HOST	mailer_dsn	-	-	-
$platform_email['SMTP_PORT']	SMTP_PORT	mailer_dsn	-	-	-
$platform_email['SMTP_AUTH']	SMTP_AUTH	mailer_dsn	-	-	-
$platform_email['SMTP_USER']	SMTP_USER	mailer_dsn	-	-	-
$platform_email['SMTP_PASS']	SMTP_PASS	mailer_dsn	-	-	-
$platform_email['SMTP_SECURE']	SMTP_SECURE	mailer_dsn	defaults to '' but could be tls/ssl	-	-
$platform_email['SMTP_FROM_EMAIL']	MAILER_FROM_EMAIL	mailer_from_email	An e-mail address (if empty, uses the admin's e-mail from the form in the install wizard but stores it into this variable)	Mail: 'From' address	The e-mail address from which e-mails will be sent when the platform sends an e-mail, also used as 'reply-to' header. We recommend using a 'no-reply' e-mail address here, to avoid excessive filling of an e-mail box. The support e-mail address defined in the Platform section should be used to contact you, but replying to automatic notifications should not be encouraged.
$platform_email['SMTP_FROM_NAME']	MAILER_FROM_NAME	mailer_from_name	A name of person/team sending the mail.	Mail: 'From' name	The name that appears as the sender (next to the From e-mail address) when the platform sends an e-mail.
$platform_email['SMTP_CHARSET']	SMTP_CHARSET	mailer_mails_charset	Not in install wizard, only in admin section	Mail: character set	In case you need to define the charset to use when sending those e-mails. Leave empty if you're not sure.
$platform_email['SMTP_UNIQUE_REPLY_TO']	SMTP_UNIQUE_REPLY_TO	-	Remove setting	-	-
$platform_email['SMTP_DEBUG']	SMTP_DEBUG	mailer_debug_enable	Not in the install wizard, only in admin section	Mail: Debug	Select whether you want to enable the e-mail sending debug logs. These will give you more information on what is happening when connecting to the mail service, but are not elegant and might break page design. Only use when there is not user activity.
$platform_email['EXCLUDE_JSON']	-	mailer_exclude_json	-	Mail: Avoid using JSON	Some e-mail clients do not understand the descriptive LD+JSON format, showing it as a loose JSON string to the final user. If this is your case, you might want to set the variable below to 'false' to disable this header.
$platform_email['DKIM*']	-	mailer_dkim	This doesn't have to be migrated from 1.11. Its use is exceptional	Mail: DKIM headers	Enter a JSON array of your DKIM configuration settings (see example).
$platform_email['XOAUTH2_*]	-	mailer_xoauth2	-	Mail: XOAuth2 options	If you use some XOAuth2-based e-mail service, use this setting in JSON to save your specific configuration (see example) and select XOAuth2 in the mail service setting.

If possible, those settings should be migrated from 1.11.x to 2.0 by forming the DSN and writing it both in .env and in settings, and migrating the other settings.

The mailer_dkim setting must be attached to a settings_value_template record that gives the following array:

{
    'enable' => 1,
    'selector' => 'chamilo',
    'domain' => 'mydomain.com',
    'private_key_string' => ''
    'private_key' => '',
    'passphrase' => ''

The mailer_xoauth2 setting must be attached to a settings_value_template record that gives the following array:

{
    'method' => false,
    'url_authorize' => 'https://provider.example/oauth2/auth',
    'url_access_token' => 'https://provider.example/token',
    'url_resource_owner_details' => 'https://provider.example/userinfo',
    'scopes' => '',
    'client_id' => '',
    'client_secret' => '',
    'refresh_token' => ''
}