Extension:SwiftMailer

From MediaWiki.org
Jump to navigation Jump to search
MediaWiki extensions manual
OOjs UI icon advanced.svg
SwiftMailer
Release status: beta
Implementation Hook , Notify
Description Adds a third-party SwiftMailer as an alternate to UserMailer
Author(s) Tony Thomas, Legoktm, Jeff Green (01tonythomastalk)
Latest version 1.1 (2018-09-16)
MediaWiki 1.29+
PHP 5.5.9+
Database changes No
License GNU General Public License 2.0 or later
Download
Translate the SwiftMailer extension if it is available at translatewiki.net
Check usage and version matrix.
Issues Open tasks · Report a bug

The SwiftMailer extension adds a third-party SwiftMailer as an alternate to UserMailer and PHP Pear Mailer

Installation[edit]

  • Download and place the file(s) in a directory called SwiftMailer in your extensions/ folder.
  • Add the following code at the bottom of your LocalSettings.php:
    wfLoadExtension( 'SwiftMailer' );
    
  • Yes Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

To users running MediaWiki 1.29.0 or earlier:

The instructions above describe the new way of installing this extension using wfLoadExtension(). If you need to install this extension on these earlier versions (MediaWiki 1.29.0 and earlier), instead of wfLoadExtension( 'SwiftMailer' );, you need to use:

require_once "$IP/extensions/SwiftMailer/SwiftMailer.php";

Note Note: You will have to run composer update --no-dev in extensions/SwiftMailer/ folder so that composer can pick up the required swiftmailer dependency.

Configuration[edit]

The usual SMTP/direct delivery works well under general conditions, but if your provider needs you to use ssl/tls encryption, edit the following section in your extension.json

1 "config": {
2 	"SMTPAuthenticationMethod": {
3 		"value": "tls" 
4 	}
5 },

It also supports `ssl` as a value as well.


SwiftMailer requires the user to set the following parameters in his wiki's LocalSettings.php

$wgSMTP = array(
      'host'=> "smtp.yoursmtp.org",
      'IDHost'   => "yourhost.org",
      'port'     => 587,
      'auth'     => true,
      'username' => "yourSMTPusername",
      'password' => "yourSMTPpassword"
);

Past Discussions[edit]

SwiftMailer is a serious and well maintained library dedicated to sending email from PHP.

Adding it to core is not some new feature that would be better in an extension. It is a serious improvement to our core handling of email within PHP that replaces our crude UserMailer code.

Our current UserMailer code is ridiculous when you look at it.

By default our UserMailer code will just use php's creaky mail() function. Which has some 'features' like:

  • Unpredictable message headers
  • Lack of feedback regarding delivery failures
  • And this beautiful comment in our codebase:
# PHP's mail() implementation under Windows is somewhat shite, and
# can't handle "Joe Bloggs <joe at bloggs.com>" format email addresses,
# so don't bother generating them

If you want to send email a different way, you could of course instead use $wgSMTP which:

  • First requires you to install PEAR Mail.
    • Who the hell uses PEAR anymore!
    • And don't forget, PEAR is a tool that installs modules globally and is difficult to impossible to use without shell and even admin access.
    •  ;) And this is the hell we put tarball users through, not devs.
  • This PEAR Mail library we're relying on to handle all users who can't use mail() or don't want it's features, here's the dev page:
    • http://pear.php.net/package/Mail
    • Current stable 1.2.0, released in March of 2010
    • Next release, 1.2.1 scheduled release date in January of 2011, never released.
    • ((In other words, the library we're entrusting all our SMTP handling to is practically dead and no longer maintained, Whoops.))
    • Admittedly if you hunt down PEAR Mail's github repo there has been a bit of activity:
      • https://github.com/pear/Mail/commits/trunk
      • But none of this will be installed by pear, it'll only install old code from 2010 missing fixes for a number of bugs in PEAR Mail
      • The majority of changes in 2014 have been minor/trivial things (adding travis builds, whitespace fixes)
      • And, ;) making PEAR Mail installable via Composer *snicker*

And to sprinkle this all off, because mail() and PEAR Mail are so different, half the code in UserMailer::send() is split into two different large code paths, which is a recipe for maintenance headaches.

Using Swift Mailer on the other hand:

  • The library has ample development and maintenance going on: https://github.com/swiftmailer/swiftmailer/commits/master
  • SMTP and mail() are abstracted away into transports, so instead of two large (unmaintained?) code paths we just craft and send an email in one code path, a well maintained library takes care of the difference between transports.
  • In the future we can move away from using mail() and add the ability to use sendmail as a transport directly, without the bugs (in theory I think it would even be possible to try swapping a different transport in place of mail() automatically).
  • All this gets bundled into the tarball directly, so $wgSMTP now works out of the box and doesn't require installation of something that in some situations is impossible to install.