feat: add email adapter DSN parsing

[deepshekhardas]

Add DSN (Data Source Name) parsing support for email adapters, enabling connection configuration via DSN strings.

[greptile-apps]

Greptile Summary

• Adds Email::fromDsn() support for SMTP, SMTPS, Resend, Sendgrid, and Mailgun adapter configuration.
• Adds parsing for SMTP options such as security mode, TLS flags, timeouts, and keepalive.
• Introduces a Messenger failover wrapper that tries multiple adapters in order.
• Expands tests and README examples for DSN-based email configuration and adapter failover.

Confidence Score: 3/5

The DSN parsing additions are mostly covered by focused tests, but the new Messenger failover wrapper needs attention before merge.

The main adapter parsing paths appear well exercised, while array-key handling in Messenger can break valid caller input shapes that PHP arrays commonly allow.

src/Utopia/Messaging/Messenger.php

T-Rex Logs

What T-Rex did

• • Created a focused PHP repro script to exercise Messenger with an Email adapter in zero-indexed, associative, and sparse adapter arrays.
• • Attempted to run the repro, but the environment lacked a PHP binary and runtime tools; PHP, Composer, Docker, and Podman were not available to execute the PHP library repro.
• • Analyzed before/after DSN parsing results using the email-dsn-parsing runner script, confirming the before failure and the after success with adapter creation and input validation.

_{Ran code and verified through T-Rex}

_{Reviews (3): Last reviewed commit: "feat: add email adapter DSN parsing" | Re-trigger Greptile}

[greptile-apps]

The catch block only catches \Exception, so PHP \Error subclasses (\TypeError, \ValueError, \Error, etc.) thrown by an adapter will propagate uncaught and bypass the failover loop entirely. Catching \Throwable instead ensures all adapter-level failures are handled and the next adapter is tried.

Suggested change

	try {
	return $adapter->send($message);
	} catch (\Exception $e) {
	$errors[] = $adapter->getName()
	.' (adapter '
	.($index + 1)
	.'): '
	.$e->getMessage();
	}
	try {
	return $adapter->send($message);
	} catch (\Throwable $e) {
	$errors[] = $adapter->getName()
	.' (adapter '
	.($index + 1)
	.'): '
	.$e->getMessage();
	}

[greptile-apps]

parseIntOption skips range validation when the value is already a PHP int. parse_url returns $parts['port'] as a native integer, so a URL like smtp://host:0 or smtp://host:99999 bypasses the ctype_digit check entirely and passes an invalid port directly to the SMTP constructor. The same zero/overflow gap applies to query-string ports since ctype_digit("0") and ctype_digit("99999") both return true. Adding a positive-integer guard closes this for all call sites (port, timeout, timelimit).

Suggested change

	private static function parseIntOption(mixed $value, string $option): int
	{
	if (\is_int($value)) {
	return $value;
	}
	if (! \is_string($value) || $value === '' || ! \ctype_digit($value)) {
	throw new \InvalidArgumentException('Invalid "'.$option.'" option. Expected integer value.');
	}
	return (int) $value;
	}
	private static function parseIntOption(mixed $value, string $option): int
	{
	if (\is_int($value)) {
	if ($value < 0) {
	throw new \InvalidArgumentException('Invalid "'.$option.'" option. Expected non-negative integer value.');
	}
	return $value;
	}
	if (! \is_string($value) || $value === '' || ! \ctype_digit($value)) {
	throw new \InvalidArgumentException('Invalid "'.$option.'" option. Expected integer value.');
	}
	return (int) $value;
	}

[greptile-apps]

Normalize adapter arrays

Messenger accepts any array of adapters, but later reads $adapters[0]. An associative or sparse array like ['primary' => $adapter] or [1 => $adapter] passes the validation loop and then validateAdapters() tries to call methods on a missing index. Normalizing the array before storing or validating it lets named or sparse adapter lists work consistently.