Documentation

SMTP Mailer

HexPHP leverages PHPMailer under the hood to provide an incredibly lean, easy-to-use mailer system tied directly into your application's Core Layout and Components system.

SMTP Configuration

Configure your application environment to successfully connect to an SMTP server. This requires adjusting `MAIL_*` keys in your root .env file. By default, it connects to Mailhog / Mailtrap on localhost:1025.

# SMTP Mail Settings in .env
MAIL_HOST=smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=your_username
MAIL_PASSWORD=your_password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=system@hexphp.test
MAIL_FROM_NAME="HexPHP Framework"

Creating Email Templates

Say goodbye to hardcoded HTML string concatinations inside variables. You can build Hex emails EXACTLY like you build Hex web pages!

Hex templates are parsed from app/Components/emails/*.php. An example welcome.php template is already placed there for you.

The Base Email Layout

Your individual view templates don't require inline CSS resets or <body> HTML wrappers. After resolving variables into your specific component string, the Mailer automatically injects them securely into your global email wrapper frame located at app/Layout/Email.php. This layout also includes an embedded inline logo (public/img/logo.svg) at the top of the email as an attached inline graphic to prevent email clients from blocking external images!

Testing via CLI

You can rapidly test your email components and SMTP configuration using the built-in hex CLI command.

# php hex email:send [template_name] [email_address]
php hex email:send welcome hello@example.com

Sending Mail

Once you've constructed a template inside the emails directory, you can trigger it anywhere inside your codebase statically using \App\Core\Mail::send. All variable array keys are natively converted into scope boundaries to be accessible directly inside the email template!

<?php
use App\Core\Mail;

// This will utilize app/Components/emails/welcome.php
Mail::send(
    'newuser@example.com', 
    'Welcome to HexPHP!', 
    'welcome', 
    ['name' => 'John Doe']
);

Newsletter & Unsubscribe System

HexPHP includes a native Regex Routing system that makes capturing dynamic variables straight from your URLs trivial. Out of the box, we have wired up a dedicated NewsletterSubscriber model featuring secure, hashed token tracking.

If you wish to place an unsubscribe link at the bottom of standard emails, simply pass an $unsubscribe_link string into the variables array of Mail::send(). The core Email.php layout will detect it and automatically append an Unsubscribe footer.

<?php
use App\Models\NewsletterSubscriber;
use App\Core\Env;
use App\Core\Mail;

$token = NewsletterSubscriber::generateToken();
$link = Env::get("APP_URL") . "/unsubscribe/$token";

// This naturally populates the $unsubscribe_link inside app/Layout/Email.php
Mail::send("subscriber@example.com", "Weekly Digest", "newsletter", [
    "unsubscribe_link" => $link
]);