Email Configuration Fails Due to Leading Whitespace in Database Settings

[EB-TNAP]

Current Behavior

Bug Report: Email Configuration Fails Due to Leading Whitespace in Database Settings

Summary

Flarum's email configuration can fail silently when database settings contain leading or trailing whitespace characters in the mail_host field. This causes DNS resolution failures with misleading error messages, making the issue difficult to diagnose.

Environment

• Flarum Version: 1.x
• PHP Version: 8.x
• Database: MySQL/MariaDB
• Mail Driver: SMTP
• Server: Ubuntu 22.04.5 LTS

Bug Description

When configuring SMTP email settings through the Flarum admin panel, if whitespace is accidentally added to the hostname field, it gets stored in the database with the whitespace intact. This causes email sending to fail with DNS resolution errors.

Symptoms

• "Send Test Mail" button fails in admin panel
• Error logs show: Connection could not be established with host mail.example.com (note the extra space)
• DNS lookup errors: getaddrinfo for mail.example.com failed: Name or service not known
• Direct SMTP tests outside Flarum work perfectly with the same credentials

Root Cause

1. Flarum admin panel allows whitespace to be saved in email configuration fields
2. Database settings override config.php settings
3. The whitespace is passed directly to SwiftMailer without trimming
4. SwiftMailer attempts DNS resolution on a hostname with whitespace, which fails

Reproduction Steps

1. Go to Admin Panel → Email Configuration
2. Configure SMTP settings with intentional leading/trailing space in hostname field (e.g., " mail.example.com")
3. Save configuration
4. Click "Send Test Mail"
5. Observe DNS resolution failure in logs

Database Investigation

Query to check for the issue:

SELECT `key`, value FROM your_prefix_settings WHERE `key` = 'mail_host';

In our case, the database contained:

"mail_host" = " mail.privateemail.com"

Notice the leading space character.

Current Workaround

Fix via direct database update:

php -r "
\$config = require 'config.php';
\$pdo = new PDO('mysql:host=' . \$config['database']['host'] . ';dbname=' . \$config['database']['database'], \$config['database']['username'], \$config['database']['password']);
\$stmt = \$pdo->prepare('UPDATE ' . \$config['database']['prefix'] . 'settings SET value = TRIM(value) WHERE \`key\` = ?');
\$stmt->execute(['mail_host']);
"

Suggested Fixes

1. Frontend Validation (Immediate)

Add JavaScript validation to trim whitespace in email configuration form fields before submission.

2. Backend Sanitization (Recommended)

Implement server-side trimming of email configuration values before database storage:

// In the email settings save handler
$mailHost = trim($request->get('mail_host'));

3. Database Migration (Comprehensive)

Add a migration to clean up existing installations:

// Migration to clean up existing whitespace in mail settings
$mailSettings = ['mail_host', 'mail_username', 'mail_from'];
foreach ($mailSettings as $setting) {
    DB::table('settings')
        ->where('key', $setting)
        ->update(['value' => DB::raw('TRIM(value)')]);
}

4. Improved Error Messaging

Enhance error messages to specifically mention hostname resolution issues and suggest checking for whitespace.

Impact

• Severity: Medium - Breaks core email functionality
• Frequency: Uncommon but difficult to diagnose when it occurs
• User Experience: Poor - Misleading error messages lead to extensive troubleshooting

Additional Notes

This issue is particularly problematic because:

1. The error message doesn't clearly indicate whitespace as the cause
2. External SMTP tests work fine, leading to confusion about server configuration
3. config.php changes don't resolve the issue since database settings take precedence
4. Users may spend hours troubleshooting server/DNS/firewall issues unnecessarily

Testing Verification

After implementing the fix, email functionality should be tested with:

• Leading spaces in hostname
• Trailing spaces in hostname
• Mixed whitespace characters (tabs, etc.)
• All email configuration fields (host, username, from address)

---

Contact Information: Available for follow-up questions or testing proposed fixes.

Related Files:

• vendor/flarum/core/src/Api/Controller/SendTestMailController.php
• Admin panel email configuration form
• Database settings table

Steps to Reproduce

Steps to reproduce are shown above.

Expected Behavior

Hopefully this issue can be fixed. It is solved for me. Maybe it can be fixed for someone else

Screenshots

No response

Environment

• Flarum version: x.y.z
• Website URL: http://example.com
• Webserver: [e.g. apache, nginx]
• Hosting environment: [e.g. shared, vps]
• PHP version: x.y.z
• Browser: [e.g. chrome 67, safari 11]

Output of php flarum info

Output of "php flarum info", run this in terminal in your Flarum directory.

Possible Solution

No response

Additional Context

No response

[imorland]

Fix will be included in the upcoming 1.8.11 release