websitesql/mailer

A simple PHP framework for sending emails with PHPMailer and Plates.

Maintainers

Details

github.com/websitesql/mailer

Homepage

Source

Issues

Installs: 2

Dependents: 1

Suggesters: 0

Security: 0

Stars: 0

Watchers: 1

Forks: 0

Open Issues: 0

Type:framework

v1.0.0 2025-04-14 23:02 UTC

Requires

Requires (Dev)

MIT cf122ed83823087758a624ad571d2d5cd29f8389

  • Alan Tiller <alan.woop@alantiller.com>

This package is auto-updated.

Last update: 2025-04-14 23:05:36 UTC

README

A fluent, chainable PHP email library supporting multiple mail drivers (PHP mail, SMTP, log) with HTML/plain text content and template support using League/Plates.

Installation

composer require websitesql/mail

Configuration

The MailProvider class requires an array of configuration options:

$mailConfig = [
    // Required
    'driver' => 'smtp', // Options: 'mail', 'smtp', 'log'
    'from' => 'no-reply@example.com', // Sender email address
    'from_name' => 'My Application', // Sender name
    
    // Required for template support
    'template_path' => __DIR__ . '/templates', // Path to email templates
    
    // Required for SMTP
    'smtp_host' => 'smtp.example.com',
    'smtp_port' => 587, // Common ports: 25, 465, 587
    'smtp_username' => 'username',
    'smtp_password' => 'password',
    
    // Optional
    'debug' => false, // Enable debugging (for SMTP)
];

Basic Usage

The library uses a fluent interface with method chaining:

// Create a mail provider instance
$mailer = new \WebsiteSQL\Mailer\MailProvider($mailConfig);

// Example 1: Send HTML email
$mailer->html('<h1>Hello World</h1><p>This is a test email.</p>')
       ->subject('Test HTML Email')
       ->send('recipient@example.com');

// Example 2: Send plain text email
$mailer->plain('Hello World. This is a test email.')
       ->subject('Test Plain Text Email')
       ->send('recipient@example.com');

// Example 3: Send email with both HTML and plain text
$mailer->html('<h1>Hello World</h1><p>This is a test email.</p>')
       ->plain('Hello World. This is a test email.')
       ->subject('Test Multipart Email')
       ->send('recipient@example.com');

// Example 4: Use a template
$mailer->template('welcome', ['name' => 'John Doe'])
       ->subject('Welcome to Our Site')
       ->send('john.doe@example.com');

API Reference

Constructor

public function __construct(array $options)

Creates a new instance of the MailProvider class.

Parameters:

  • $options (array): Configuration options for the mail provider

Methods

template(string $template, array $data = []): self

Sets the email content using a template.

Parameters:

  • $template (string): Template name (without file extension)
  • $data (array): Data to pass to the template

Returns: Self (for method chaining)

Throws: RuntimeException if template path is not configured or template rendering fails

html(string $html): self

Sets the HTML content of the email.

Parameters:

  • $html (string): HTML content

Returns: Self (for method chaining)

plain(string $text): self

Sets the plain text content of the email.

Parameters:

  • $text (string): Plain text content

Returns: Self (for method chaining)

subject(string $subject): self

Sets the subject of the email.

Parameters:

  • $subject (string): Email subject

Returns: Self (for method chaining)

send(string $to): bool

Sends the email to the specified recipient.

Parameters:

  • $to (string): Email recipient

Returns: Boolean indicating success or failure

Throws: RuntimeException if required fields are not set

Email Drivers

PHP mail()

Uses PHP's built-in mail() function to send emails. Configure with:

$config = [
    'driver' => 'mail',
    'from' => 'sender@example.com',
    'from_name' => 'Sender Name'
];

SMTP

Uses PHPMailer to send emails via SMTP. Configure with:

$config = [
    'driver' => 'smtp',
    'from' => 'sender@example.com',
    'from_name' => 'Sender Name',
    'smtp_host' => 'smtp.example.com',
    'smtp_port' => 587, // 25, 465, or 587
    'smtp_username' => 'username',
    'smtp_password' => 'password',
    'debug' => false // Set to true for debugging
];

Port 465 uses implicit SSL/TLS encryption, while port 587 uses STARTTLS.

Log

Logs emails to the error log instead of sending them. Useful for development and testing. Configure with:

$config = [
    'driver' => 'log'
];

Templates

The library uses League/Plates for templating. Create templates in your template directory:

// templates/welcome.php
<h1>Welcome, <?= $this->e($name) ?>!</h1>
<p>Thank you for registering.</p>

Then use them:

$mailer->template('welcome', ['name' => 'John Doe'])
       ->subject('Welcome')
       ->send('john@example.com');

Exception Handling

The library throws RuntimeException for configuration errors and other issues:

try {
    $mailer->html('<p>Hello</p>')
           ->subject('Test')
           ->send('recipient@example.com');
} catch (RuntimeException $e) {
    // Handle the error
    echo "Error: " . $e->getMessage();
}

Complete Example

// Create configuration
$config = [
    'driver' => 'smtp',
    'from' => 'no-reply@myapp.com',
    'from_name' => 'My Application',
    'template_path' => __DIR__ . '/templates',
    'smtp_host' => 'smtp.myapp.com',
    'smtp_port' => 587,
    'smtp_username' => 'smtp_user',
    'smtp_password' => 'smtp_password'
];

// Create mailer
$mailer = new \WebsiteSQL\Mailer\MailProvider($config);

// Send a welcome email
try {
    $mailer->template('welcome', [
              'username' => 'johndoe',
              'app_name' => 'My Application',
              'login_url' => 'https://myapp.com/login'
           ])
           ->subject('Welcome to My Application')
           ->send('john.doe@example.com');
    
    echo "Email sent successfully!";
} catch (RuntimeException $e) {
    echo "Failed to send email: " . $e->getMessage();
}