diff --git a/docs/EMAIL_TEMPLATES.md b/docs/EMAIL_TEMPLATES.md new file mode 100644 index 0000000..fdfd8b4 --- /dev/null +++ b/docs/EMAIL_TEMPLATES.md @@ -0,0 +1,525 @@ +# Email Templates + +The CMS uses a template-based email system powered by **PHPMailer** and the `Email\Sender` service. All email templates are editable PHP files located in `resources/views/emails/`. + +## Quick Start + +### 1. Configure Email Settings + +Copy the example configuration: +```bash +cp resources/config/email.yaml.example resources/config/email.yaml +``` + +Edit `resources/config/email.yaml`: +```yaml +email: + test_mode: true # Enable for development + driver: mail # or 'smtp' for production + from_address: noreply@yourdomain.com + from_name: Your Site Name +``` + +### 2. Customize Email Templates + +Templates are in `resources/views/emails/`. Edit them like any PHP file: + +```php +// resources/views/emails/welcome.php +
Hi = htmlspecialchars($Username) ?>,
+Welcome to = htmlspecialchars($SiteName) ?>!
+``` + +### 3. Test in Development + +With `test_mode: true`, emails are logged instead of sent: +``` +[INFO] TEST MODE - Email not sent +[INFO] To: newuser@example.com +[INFO] Subject: Welcome to My Site! +[INFO] Body: Hi John, Welcome to My Site... +``` + +## Available Templates + +### welcome.php +**Sent when**: A new user is created +**Triggered by**: `SendWelcomeEmailListener` (listens to `user.created` event) +**Variables available**: +- `$Username` - The new user's username +- `$SiteName` - Site name from settings +- `$SiteUrl` - Site URL from settings + +**Customization ideas**: +- Add your logo (use absolute URL: `https://yoursite.com/logo.png`) +- Change gradient colors in header +- Modify greeting message +- Add onboarding steps +- Include social media links +- Add help/support contact info + +### password-reset.php +**Sent when**: A user requests a password reset +**Triggered by**: `PasswordResetManager::requestReset()` (via forgot password form) +**Variables available**: +- `$ResetLink` - The password reset URL with token +- `$ExpirationMinutes` - Token expiration time in minutes (default: 60) +- `$SiteName` - Site name from settings + +**Customization ideas**: +- Change gradient colors in header to match your brand +- Modify the security notice styling +- Add your logo +- Include support contact information +- Customize expiration warning message +- Add additional security tips + +## Email Configuration + +### Drivers + +**mail** (default) +- Uses PHP's `mail()` function +- Requires server to have mail configured +- Works on most shared hosting +- May have deliverability issues + +**sendmail** +- Uses sendmail binary +- Available on Linux/Mac servers +- Better than `mail()` for deliverability + +**smtp** (recommended for production) +- Uses SMTP server (Gmail, SendGrid, Mailgun, etc.) +- Best deliverability +- Requires SMTP credentials + +### SMTP Configuration Examples + +#### Gmail +```yaml +email: + driver: smtp + host: smtp.gmail.com + port: 587 + username: your-email@gmail.com + password: your-app-password # NOT your regular Gmail password! + encryption: tls + from_address: your-email@gmail.com + from_name: Your Site Name +``` + +**Important**: Use an [App Password](https://support.google.com/accounts/answer/185833), not your regular password! + +#### SendGrid +```yaml +email: + driver: smtp + host: smtp.sendgrid.net + port: 587 + username: apikey + password: SG.your-sendgrid-api-key-here + encryption: tls + from_address: noreply@yourdomain.com + from_name: Your Site Name +``` + +#### Mailgun +```yaml +email: + driver: smtp + host: smtp.mailgun.org + port: 587 + username: postmaster@yourdomain.com + password: your-mailgun-smtp-password + encryption: tls + from_address: noreply@yourdomain.com + from_name: Your Site Name +``` + +### Test Mode + +Enable test mode during development to log emails instead of sending: + +```yaml +email: + test_mode: true +``` + +Emails will be logged with full details: +``` +[INFO] TEST MODE - Email not sent +[INFO] To: test@example.com +[INFO] Subject: Welcome! +[INFO] Body: Hi John, Welcome to... +``` + +## Customizing Templates + +### Basic Customization + +Templates are standard PHP files with variables. Edit them directly: + +```php +// resources/views/emails/welcome.php + + + + + + + + +Hey = htmlspecialchars($Username) ?>! 👋
+ + +Thanks for signing up! We're excited to have you.
+ + + + Get Started Now + + + +``` + +### Adding Images + +Use absolute URLs for images (relative paths don't work in emails): + +```php + +
+
+
+
+```
+
+### Inline CSS
+
+Always use inline CSS or `
+
+
+
+```
+
+### Variables and Logic
+
+Templates support full PHP:
+
+```php
+
+
+ You've earned a bonus!
+ + + + +Year: = date('Y') ?>
+URL: = htmlspecialchars($SiteUrl) ?>
+``` + +### Email-Safe HTML + +Follow these best practices: + +1. **Use tables for layout** (not divs) for better email client support +2. **Inline CSS** - Styles must be inline or in ` + + +Hi = htmlspecialchars($Username) ?>,
+= htmlspecialchars($Message) ?>
+