Smtp Mailer Bundle Laravel Package

Getting Started

At 0.0.x this package is pre-1.0 and the 0.0.2 release carries no changelog beyond a compare link, so treat the whole API surface as provisional until you've read the diff yourself.

1. Pin it exactly. composer require tourze/smtp-mailer-bundle:0.0.2 — do not use a ^0.0 constraint, since 0.0.x bumps may change signatures without notice.
2. Read the source before the docs. Start with composer.json (to see what it requires and how it autoloads), then the bundle/extension class and its Configuration definition. In a Symfony-style bundle the extension class is where the real defaults live; that is the authoritative behaviour, not the README.
3. Check what actually gets registered. Because this is packaged as a bundle, the natural assumption is Symfony-style registration. In a Laravel app, confirm whether a ServiceProvider or extra.laravel.providers entry is present. If not, you'll be wiring it manually (see Gotchas).
4. First real use case: a single SMTP transport. Configure one mailer with a DSN such as smtp://user:[email protected]:587, send a Mailable through Mail::to(...)->send(...), and verify delivery before touching anything else. The value of this package is concentrated almost entirely in transport/config wiring — prove that path works end to end first.

If that minimal path doesn't work within an hour, stop and evaluate whether Laravel's built-in Symfony Mailer transports already cover your need (they usually do).

Implementation Patterns

Configuration via DSN, not scattered options. Keep credentials in config/mail.php fed from .env, and express the transport as a single DSN string. This is the pattern the underlying SMTP transport expects and it makes staging/production swaps trivial:

'smtp_custom' => [
    'transport' => 'smtp',
    'host' => env('MAIL_HOST'),
    'port' => env('MAIL_PORT', 587),
    'encryption' => env('MAIL_ENCRYPTION', 'tls'),
    'username' => env('MAIL_USERNAME'),
    'password' => env('MAIL_PASSWORD'),
],

Multiple named mailers. If the package resolves a transport per mailer name, declare two or three mailers (transactional, bulk/ESP, internal relay) and select at send time with Mail::mailer('bulk')->to(...). This is the cleanest way to route without spreading conditionals through your app.

Queued mailables from day one. SMTP handshakes are the slowest part of a request. Make every non-trivial mailable ShouldQueue and set a dedicated mail queue so slow SMTP retries don't starve your job workers.

Test seam: Mail::fake() locally, Mailpit/MailHog in CI. Fake for assertions in feature tests; a real SMTP sink for integration tests so encoding, TLS, and auth problems surface before production.

Wrap it behind a small adapter. Because 0.0.x is volatile, isolate usage in one class (a MailDispatcher or similar) so a future version bump touches one file rather than thirty call sites.

Verify with a command. Add an artisan command or php artisan tinker snippet that sends a bare message. Keeping that reproducible saves hours when config drifts.

Gotchas and Tips

• The 0.0.2 changelog is empty. Before upgrading, run git diff 0.0.1..0.0.2 (or browse the compare URL) against vendor/. An undocumented bump in a 0.0.x package is the highest-risk kind.
• "Bundle" ≠ Laravel package. Don't assume auto-discovery. If php artisan about / the vendor list doesn't show it, register the service provider manually in config/app.php (or bootstrap/providers.php on Laravel 11+) and re-run php artisan config:clear.
• Stale config cache is the #1 false alarm. After changing mail settings, always php artisan config:clear (and queue:restart for workers). A "credentials wrong" error is frequently a cached config.
• Port/encryption mismatch. 587 is STARTTLS (tls), 465 is implicit TLS (ssl), 25 is generally blocked by cloud providers. Getting this wrong produces timeouts that look like network failures.
• Don't forget MAIL_FROM_ADDRESS. Some SMTP relays reject mail without a matching envelope sender even when the From header is set.
• Debug at the SMTP level, not the framework level. When things fail, drop to a raw connection test (e.g. openssl s_client -connect host:587 -starttls smtp) to separate network/TLS/auth problems from Laravel wiring problems. Laravel's transport exceptions often hide the underlying SMTP response code in getPrevious().
• Extension point to prefer: swap the transport binding rather than forking the package. Bind your own Mailer/TransportInterface implementation in a service provider — that keeps your code upgrade-safe when 0.0.3 lands.
• Treat this as a thin convenience layer. Everything this package does can typically be expressed with Laravel's native smtp mailer config. Adopt it only where it demonstrably saves you work, and have a two-line rollback to stock config ready.