Swiftmailer Twig Bundle Laravel Package

Getting Started

1. Install and pin the version. composer require <vendor>/<package>:^1.1. v1.1 pulls in SwiftMailer 6 and therefore requires Symfony 3.3+ components — check composer why symfony/* before upgrading an existing app, since a stale Symfony 2.8/3.2 lock will block the install.
2. Publish config if the package ships any. php artisan vendor:publish --provider="<Vendor>\<Package>\<Package>ServiceProvider" — the mail transport settings usually land in config/mail.php or a package-specific config/<package>.php.
3. Look first at the service provider and the transport class. That's where the package binds itself into Laravel's mailer (Mail::extend() / Mail::mailer() or a MailManager override). Read the transport's send() method before anything else — it tells you exactly which SwiftMailer objects you're dealing with.
4. First use case: wire up the driver, then send through the normal Laravel API rather than the package API:

   // .env
   MAIL_DRIVER=<package-driver>
   

   Mail::to($user)->send(new WelcomeMail($user));
   

   If that works, the transport is bound correctly and everything else is plain Laravel mail.

v1.1 upgrade note: run composer update <vendor>/<package> and immediately php artisan config:clear && php artisan queue:restart. The SwiftMailer 6 jump is the only change in this release, but it is a major-version dependency bump, so treat it as a potentially breaking upgrade (see Gotchas).

Implementation Patterns

• Prefer Mailables over raw Mail::send. The package is a transport concern; message construction should stay in app/Mail/*. This keeps you insulated if a future v1.x moves off SwiftMailer (SwiftMailer was deprecated in favour of Symfony Mailer, so expect that eventually).
• Register custom transports through Laravel, not through Swift. If you need to add or swap a transport, use the framework's extension point:

  Mail::extend('mydriver', function (array $config) {
      return new MyTransport(...);
  });
  

  Doing it in a service provider's boot() keeps it testable and avoids mutating Swift_Mailer after the fact.
• Queue long-running sends. Mail::to($user)->queue(new WelcomeMail($user)) moves the Swift transport call onto the worker. This matters more for SMTP/API transports than for log/array, and it's the single biggest reliability win for bulk sends.
• Use multiple mailers for split traffic (transactional vs. bulk) rather than swapping the default driver at runtime. Define a second entry in config/mail.php and call Mail::mailer('bulk')->to(...).
• Testing: Mail::fake() short-circuits the transport entirely — great for asserting assertSent/assertQueued, useless for validating the package's credentials or connection. Pair it with a small integration test that sends one real message to a sink (Mailtrap, log driver, or a local SMTP catcher).
• Plugins and events (SwiftMailer 6 style). If you register Swift plugins (logger, anti-flood, decorator), attach them to the Swift_Mailer instance the package exposes — typically via a container binding or an event listener that runs after the mailer is resolved. Prefer namespaced classes (Swift\Mailer, Swift\Plugins\LoggerPlugin) in new code.
• Watch the envelope. Set ->from() in the Mailable's build() and let the package/config supply the default; mixing MAIL_FROM_ADDRESS with a Mailable-level from is the most common cause of "mail sends but looks wrong in Gmail".

Gotchas and Tips

• SwiftMailer 6 namespacing. v1.1 upgrades to SwiftMailer 6, which introduced namespaced classes (Swift\Message, Swift\Transport\...) while keeping Swift_* underscore aliases as a compatibility layer. Any package code, plugin, or app listener that type-hints Swift_Message should still work, but check every Swift_* reference in your own code and in third-party mail plugins — the underscore names are deprecated in SwiftMailer 6 and were removed in 7, so this is your chance to migrate.
• PHP and Symfony floor raised. SwiftMailer 6 requires PHP 7.0+; Symfony 3.3 components are pulled in transitively. If you're on PHP 5.6 or a locked Symfony 2.8, the v1.1 update will fail to resolve — that's a hard stop, not a warning. Run composer update --with-dependencies for the mail-related packages in one pass.
• Symfony 3.3 event/dispatcher changes. SwiftMailer 6 delegates more to Symfony's EventDispatcher. If you had custom listeners on Swift_Events_SendEvent or similar, re-verify they're still firing after the upgrade; silently-dropped listeners are the classic symptom.
• config:clear after touching mail config. config/mail.php is cached; a stale cache will happily keep using the old transport name while you debug a "driver not found" error. php artisan config:clear is step one for any mail problem.
• Mail::fake() hides transport breakage. Tests pass, production throws Connection could not be established with host. Keep one non-faked smoke test per mailer.
• Failures are often swallowed. Exceptions from the transport may be caught and logged rather than rethrown, depending on how the driver is wired. Always check storage/logs/laravel.log before assuming "it sent".
• Queued mail uses a serialized Mailable. If your Mailable holds a Swift object or a closure (e.g. a withSwiftMessage() callback that captures $this), serialization can fail on the worker. Test with QUEUE_DRIVER=sync first, then a real queue connection.
• Extension points to know: Mail::extend() (custom transport), Mail::mailer() (named config), withSwiftMessage() (final message tweaks — headers, attachments, custom headers), and the package's own service provider bindings for the Swift_Mailer singleton.
• Deprecation horizon. SwiftMailer itself is end-of-life; Laravel moved to Symfony Mailer in 6.x. This v1.1 is a maintenance-release bridge, not a long-term bet — avoid writing new code that depends directly on Swift_* internals so the eventual Symfony Mailer migration is a transport swap, not a rewrite.