Internal Laravel Package

Getting Started

Minimal path to a first send with the Hyvor Relay mail transport:

1. composer require hyvor/relay (or the package name listed in the repo README — check composer.json for the exact vendor/name).
2. Publish the package config if it ships one: php artisan vendor:publish --tag=hyvor-relay-config (tag name may vary; php artisan vendor:publish and pick the Hyvor entry if unsure).
3. Add a mailer entry in config/mail.php pointing at the package transport, and wire matching MAIL_* env vars.
4. Send your first message through the Mail facade:

Mail::to('[email protected]')->send(new WelcomeMail($user));

Where to look first:

• config/mail.php — the mailers array is where the relay driver gets registered.
• The package's service provider (src/*ServiceProvider.php) — confirms the transport/mailer driver name you must use in config.
• The README's "Configuration" and "Cloud vs self-hosted" sections (the 4.1.10 release adds cloud support).

First real use case: transactional email (password resets, receipts, notifications) routed through Hyvor Relay instead of SMTP, so you get relay-level delivery handling without changing your Mailable/Notification code.

Implementation Patterns

Dedicated mailer, default unchanged. Keep smtp/log as the default and add a named relay mailer. This lets you switch per-message with Mail::mailer('relay') or ->mailer('relay') on a Mailable/Notification, and keeps local dev on log.

Cloud vs self-hosted. Since 4.1.10 adds relay cloud, expect a config switch (e.g. HYVOR_RELAY_CLOUD=true or a distinct driver/host). Prefer an explicit relay_cloud mailer entry over branching logic in application code — one mailer for cloud, one for your self-hosted instance, both selectable by name.

Environment-driven config. Standard pattern:

'mailers' => [
    'relay' => [
        'transport' => 'hyvor-relay',
        'host' => env('HYVOR_RELAY_HOST'),
        'port' => env('HYVOR_RELAY_PORT', 587),
        'username' => env('HYVOR_RELAY_USERNAME'),
        'password' => env('HYVOR_RELAY_PASSWORD'),
        'encryption' => env('HYVOR_RELAY_ENCRYPTION', 'tls'),
    ],
],

Exact keys depend on whether the package registers a Symfony transport (host/port/credentials) or a Laravel-native mailer (API key). Confirm against the service provider.

Queue everything user-facing. class WelcomeMail extends Mailable implements ShouldQueue — relay latency and transient failures shouldn't block the request. Pair with Mail::to(...)->queue(...).

Notifications. Add public function via($notifiable) { return ['mail']; } and override ->mailer('relay') in toMail() when you need the relay specifically.

Testing. Mail::fake() and assert on mailables as usual; the transport is irrelevant under fake. For integration checks, point the relay mailer at log in phpunit.xml to avoid hitting the cloud in CI.

Local development. Keep MAIL_MAILER=log in .env, or use a catch-all like Mailpit; only route to relay in staging/production.

Gotchas and Tips

• Config cache. After editing config/mail.php or the package config, run php artisan config:clear (or config:cache in deploy). A stale cached config is the most common "transport not found" cause.
• Driver name mismatch. The transport value must exactly match what the service provider registers. If you see Unsupported mail transport [...], you guessed the driver name — check the provider.
• Service provider registration. If the package isn't auto-discovered (older Laravel or dont-discover), add it to config/app.php. Missing provider = driver never registered.
• Cloud credentials differ from self-hosted. The 4.1.10 cloud feature likely expects a different auth model (API key vs SMTP username/password). Don't reuse self-hosted env values for the cloud mailer.
• Domain verification/DNS. For relay cloud, sender domains usually need SPF/DKIM records set up in the Hyvor dashboard before delivery succeeds. Failures here look like silent bounces, not exceptions — check the relay dashboard logs.
• TLS/port pairing. Port 587 + tls and port 465 + ssl are the usual pairs; mismatches produce handshake errors that read like auth failures.
• Queue workers. After changing mail config or env, php artisan queue:restart. Workers cache config in memory.
• Rate limits and retries. Cloud relays impose sending limits. Use queued mail with $tries/backoff on the job rather than retrying inline.
• Extension points. The package's transport class is usually swappable/bindable; if you need custom headers or logging, wrap the transport or listen to Laravel's MessageSending/MessageSent events rather than forking.
• Version pinning. 4.1.10 is a feature release (cloud), not a patch — read the diff before bumping in production, and pin ^4.1 to avoid surprise minor changes to config keys.

Note: this assessment is based on release metadata (4.1.10, "feat: relay cloud") rather than a full read of the package source. Verify exact package name, config keys, and driver names against composer.json, the README, and the service provider before relying on the snippets above.