The swiftmailer fork

[alquerci]

"Main purpose", meaning "reason for being" or "reason to be".

As a contributor, in order to avoid wasting time on things that do not contribute to the main purpose of this repository.

A visible purpose can help focus on the most important and vital issues.
The main purpose may be well visible, to avoid any confusion.

[thirsch]

For me, the main purpose is to fix deprecations and make this lib running under upcoming php versions as long as it's feasible with small adjustments. For 8.2 and 8.3 everything is already done and no further work needed.

Personally, I'm not sure, if phpcs and other steps are really necessary, as I think it's better to use the time to migrate to symfony/mailer or any other actively maintained mailing solution.

What do you think about the main purpose, @alquerci, @thePanz, @connorhu?

[connorhu]

Deprecation fixing.

https://symfony.com/blog/the-end-of-swiftmailer

“Migrating from Swiftmailer to Symfony Mailer is a relatively easy task as the concepts are the same between the two projects.”

We should start work on this.

[alquerci]

To reformulate with my words.

Main purpose: "Supports same PHP versions as latest FriendsOfSymfony1/symfony1"

In practice: For each PHP version, the test suite must pass. Where a deprecation will fail, the build.

If test suite pass, there is nothing to do.

[thePanz]

To reformulate with my words.

Main purpose: "Supports same PHP versions as latest FriendsOfSymfony1/symfony1"

In practice: For each PHP version, the test suite must pass. Where a deprecation will fail, the build.

If test suite pass, there is nothing to do.

We should formulate it differently, without a reference to SF1.

We should mention:

• which versions of PHP do we support?
• what do we do with BC breaks?
• what about new features?
• what about bugfixes in the original code? (Should we create issues from the legacy tracker to GitHub?)

This should be a discussion , not an issue IMO

[mentalstring]

I went ahead and converted this into a discussion, hope that's alright with everyone.

For me, the main purpose is to fix deprecations and make this lib running under upcoming php versions as long as it's feasible with small adjustments. For 8.2 and 8.3 everything is already done and no further work needed.

Personally, I'm not sure, if phpcs and other steps are really necessary, as I think it's better to use the time to migrate to symfony/mailer or any other actively maintained mailing solution.

Those are my thoughts too. Mainly, fix deprecations and support newer PHP versions.

In that context, I think the phpcs changeset was perhaps unnecessary, making it a bit harder for others to check what actually changed in this fork with little to gain – I suppose it can make it easier to work with the codebase in the future, but (personally) I would not do much work on this fork, unless required by newer PHP versions and such.

• what about new features?

I lean towards not having any new features in it.

[connorhu]

Migration guide? Realworld examples? Compatibility methods (such as from(), to() subject() etc)?
I don't think we need to think about amazingly complicated things as new features.

How this:

$message = (new Swift_Message('Wonderful Subject'))
  ->setFrom(['john@doe.com' => 'John Doe'])
  ->setTo(['receiver@domain.org', 'other@domain.org' => 'A name'])
  ->setBody('Here is the message itself')
  ;

becomes this:

$email = (new Email())
            ->from('hello@example.com')
            ->to('you@example.com')
            ->subject('Time for Symfony Mailer!')
            ->text('Sending emails is fun again!')
            ->html('<p>See Twig integration for better HTML integration!</p>');

[mentalstring]

Migration guide? Realworld examples?

A migration path, if necessary, sure. Not sure what what you mean by real world examples – do you mean add to the documentation?

Compatibility methods (such as from(), to() subject() etc)?

Wouldn't oppose to this if the point is shortening the gap to eventually replace it with symfony/mailer, although I'm not sure how close we could get. I have a different suggestion on this, but I'll post it on a different reply.

[mentalstring]

“Migrating from Swiftmailer to Symfony Mailer is a relatively easy task as the concepts are the same between the two projects.”

We should start work on this.

In the context of symfony1, I'm wondering if it would be feasible to implement an alternative mailer class (that could be switched to in factories.yml) based on symfony/mailer, while keeping the current sfMailer based on Swiftmailer as is, available for those who can't or prefer not to switch.

The new mailer class would essentially implement most methods of the sfMailer class, but translating them into symfony/mailer way of doing things.

I think the main hurdle would be the spool delivery strategy feature but, imho, could be skipped in this mailer class as I don't think it's a feature widely used and those relying on that specifically can still stick with sfMailer+swiftmailer.

For those trying to be become less dependent on symfony1 and slowly move towards the current Symfony (or just multiple components), I think this could be a step in that direction.

Thoughts?

[connorhu]

Attach is a problem:
https://github.com/symfony/symfony1-docs/blob/master/gentle-introduction/en/11-Emails.markdown#the-flexible-way
Direct swiftmailer call is a problem:
https://github.com/symfony/symfony1-docs/blob/master/gentle-introduction/en/11-Emails.markdown#the-powerful-way

I've started writing a documentation that goes through method by method, and describes what a swiftmailer invocation of a given method looks like in symfony/mailer.
This is probably the kind of depth that can be implemented in a rector and that can transform.
Once this migration description is done (the developer knows which method to actually rewrite to what), "only" the exception changes and spool migration are left.

Migration Cheatsheet

SWM: class Swift_Message
SYM: class Email

Constants

SWM: Swift_Message::PRIPRITY_HIGHEST = 1;
SYM: Email::PRIORITY_HIGHEST = 1;

SWM: Swift_Message::PRIPRITY_HIGH = 2;
SYM: Email::PRIORITY_HIGH = 2;

SWM: Swift_Message::PRIPRITY_NORMAL = 3;
SYM: Email::PRIORITY_NORMAL = 3;

SWM: Swift_Message::PRIPRITY_LOW = 4;
SYM: Email::PRIORITY_LOW = 4;

SWM: Swift_Message::PRIPRITY_LOWEST = 5;
SYM: Email::PRIORITY_LOWEST = 5;

Methods

SWM: public function __construct($subject = null, $body = null, $contentType = null, $charset = null)
SYM: public function __construct(?Headers $headers = null, ?AbstractPart $body = null)

To, Cc, Bcc

SWM: public function setTo($addresses, $name = null)
SYM: public function to(Address|string ...$addresses): static
SWM: public function setCc($addresses, $name = null)
SYM: public function cc(Address|string ...$addresses): static
SWM: public function setBcc($addresses, $name = null)
SYM: public function bcc(Address|string ...$addresses): static

use Symfony\Component\Mime\Address;

->setTo('address')
->to('address')
->to(new Address('address'))

->setTo('address', $name)
->to(new Address('address', 'name'))
->to('name <address>')
->to(Address::create('name <address>'))

->setTo([
  'address1' => 'name1',
  'address2' => 'name2',
])
->to([
  new Address('address', 'name'),
  new Address('address', 'name'),
])

Body

SWM: public function setBody(string $body, $contentType = null, $charset = null)
SYM: public function text($body, string $charset = 'utf-8'): static
SYM: public function html($body, string $charset = 'utf-8'): static

->setBody('Text Body')
->text('Text Body')

->setBody('Text Body', null, 'iso8859-2')
->text('Text Body', 'iso8859-2')

->setBody('My <em>amazing</em> body', 'text/html', 'iso8859-2')
->html('My <em>amazing</em> body', 'iso8859-2')

[mentalstring]

Attach is a problem: https://github.com/symfony/symfony1-docs/blob/master/gentle-introduction/en/11-Emails.markdown#the-flexible-way Direct swiftmailer call is a problem: https://github.com/symfony/symfony1-docs/blob/master/gentle-introduction/en/11-Emails.markdown#the-powerful-way

The reference in the documentation would remain true as anyone can still use the default sfMailer and it would work as per the docs. However, the existence of (an optional) alternative symfony/mailer based mailer class could be mentioned/documented on the WHATS_NEW.md where what to be aware of could be mentioned (e.g. no spooling and the need to replace any direct use of Swift_* class), for those would like to switch to it.

That said, yes, a rector approach could automate some things, but wouldn't that approach be forcing people into using the symfony/mailer mailer class? Or, do you mean to provide a console task to do some of the required changes only for those who would want to switch deliberately to an alternative mailer class?

[connorhu]

I have in mind a solution that first replaces the Swift_Message class with something like this:
\FriendsOfSymfony1\MailerWrapper\Message
A Message class (if it is possible) that implements exactly the same methods as swiftmailer. Inside, our wrapper solution wraps to symfony/mailer.
This would make it possible to implement the migration in a project with only one class renaming (even if only as a test). From there, you can move on to symfony/mailer.
If a migration guide can be so detailed that "If you wrote it this way before, write it this way after this" and it can be useful, then the wrapper can be skipped. I'm not sure what we win with a wrapper.

What can't be skipped and is another issue is the mailing "framework implementation". Does the "new" mailer solution really need to be swift compatible? Does it need all spool? What does modern symfony framework add to symfony/mailer? Can we provide that (even 100% compatible)? Is BC allowed?