Azure Mailer Driver Laravel Package

Getting Started

1. Upgrade deliberately. v8.0.0 is a major release, so check your constraint first:

   composer why hafael/azure-mailer-driver
   composer require hafael/azure-mailer-driver:^8.0
   

   Review your app’s Laravel/PHP versions against the package’s new composer.json constraints before rolling out.

2. Look first at config/mail.php and the package README. v8 registers an acs mail transport through Laravel’s native MailManager::extend hook. The canonical driver/transport name is now acs; the legacy azure configuration remains supported for compatibility.

3. Configure a mailer. Add an acs mailer using the credential keys documented by the package, then point MAIL_MAILER=acs at it:

   'mailers' => [
       'acs' => [
           'transport' => 'acs',
           // endpoint / access key / from address per package docs
       ],
   ],
   

   If you already have a working azure mailer from v7, keep it for now and migrate on your own schedule.

4. First use case: send a transactional message through Laravel’s normal Mail API:

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

   The package should be transparent here—you are still using Laravel Mailables, notifications, and queued mail.

5. Clear cached config after changes:

   php artisan config:clear
   

Implementation Patterns

• Use standard Laravel Mailables and notifications. The transport is an implementation detail. Keep mail construction in Mailable/Notification classes and select the mailer via config or Mail::mailer('acs').
• Prefer the new acs mailer name for new code. Treat azure as a compatibility path for existing deployments. This makes future removals of the legacy alias less painful.
• Explicitly select the mailer when you run multiple transports:

  Mail::mailer('acs')->to($user)->send(new ReceiptMail($order));
  

  This is useful when default mail is SMTP but ACS is reserved for production transactional mail.
• Queue outbound mail. Azure Communication Services is a remote API call. Use ShouldQueue on Mailables or Mail::queue() to keep request latency predictable and benefit from Laravel’s retry/failed-job handling.
• Keep credentials in environment/config, not code. Use separate mailers for separate tenants or environments if needed, but define them in config/mail.php so config caching works.
• Use Laravel’s mail events for observability. Listen to MessageSending / MessageSent for logging and correlation IDs rather than wrapping every send call in custom logging.
• Test with Mail::fake() for application behavior. Assert that the right Mailable was sent to the right recipient. Reserve real ACS calls for a small staging smoke test, not the main test suite.
• Rely on the new CI/PHPUnit coverage as upgrade confidence, not as app coverage. v8 adds package-level tests, which helps validate the transport registration and compatibility paths, but your app still needs its own mail configuration tests.

Gotchas and Tips

• Major version bump: v8 modernizes dependencies. Don’t assume a drop-in upgrade from v7 in a legacy Laravel app. Check framework and PHP constraints, then run a staging send before production.
• Transport name mismatch is the most likely config failure. If mail.mailers.acs.transport does not match the name registered by the package, Laravel will throw an “unsupported mail transport” style error. Confirm the exact key in the package README.
• Legacy azure support is a bridge, not a long-term strategy. Existing azure configs should continue to work in v8, but new implementations should use acs. Plan a migration and avoid defining both names unless you intentionally need two mailers.
• Remove duplicate manual provider registration. v8 uses Laravel’s package discovery/native extension hook. If your app manually registered an older service provider or bound a custom transport, remove it to avoid double registration or conflicting transport definitions.
• Beware cached config and long-running workers. After changing mailer config, run php artisan config:clear. For Octane or long-running queue workers, restart workers after config/deployment changes.
• Runtime mailer overrides need care. Laravel caches resolved mailers. If you mutate mail.mailers.acs at runtime, set config before the mailer is first resolved, or purge the resolved mailer.
• ACS-side setup still matters. Verified sender domains, from addresses, and Azure credentials are common sources of 4xx errors. A successful Laravel config does not guarantee the Azure resource is correctly provisioned.
• Queued failures surface in workers. Transport/API errors will appear as failed jobs rather than request-time exceptions. Configure failed_jobs monitoring and retry policies.
• Debug with the simplest possible message first:

  Mail::mailer('acs')->raw('Test', function ($message) {
      $message->to('[email protected]')->subject('ACS test');
  });
  

  This isolates transport/config issues from Mailable rendering issues.
• Extension point: because v8 uses MailManager::extend, the same pattern can be used for other custom transports. Keep custom transport registration in a service provider and avoid colliding with the package’s acs transport name.