README

MailTemplator (Easy templates for your emails).

🔥 Introduction :

MailTemplator is lightweight PHP package that helps you create, edit and customize email templates.

📌 Requirements :

• PHP >= 8
• PHPUnit >= 9 (for testing purpose)

🚀 Installation & Use :

    composer require lotfio/mail-templator

⚡ Testing :

    composer test-unit
    composer test-integration

☀️ Static analysis :

    composer psalm

✏️ Usage :

• Create your custom Mail Template in your preferred folder withing your project.
• Mail template class name should ends with Template (MyCustomTemplate, MySecondTemplate).

<?php

namespace MyCustomMilTemplates;

use MailTemplator\Templator;
use MailTemplator\Contracts\TemplateInterface;

final class MyTemplate extends Templator implements TemplateInterface
{
    /**
     * render this template method
     *
     * @param  array|null $variables
     * @return string
     */
    public function render(?array $variables = null): string
    {
        return $this->loadTemplate()->parse($variables);
    }
}

☝️ Available Directives

• @LOGO@, @OPENLINE@, @HEADER@, @CONTENT@, @FOOTER@, @SUBFOOTER@, @POWEREDBY@
• You can customize and update the content of these directives with setters and also with protected properties
• Example :

<?php

namespace MyCustomMilTemplates;

use MailTemplator\Templator;
use MailTemplator\Contracts\TemplateInterface;

final class MyTemplate extends Templator implements TemplateInterface
{
    // you can use a protected property
    protected string $logo = '<img src="https://mysite.com/logo.png">';

    // or a protected setter
    protected function setLogo(): void
    {
      $this->logo = '<img src="https://mysite.com/logo.png">';
    }

    // all other directives can be updated the same way
}

✋ Custom directives

<?php

namespace MyCustomMilTemplates;

use MailTemplator\Templator;
use MailTemplator\Contracts\TemplateInterface;

final class MyTemplate extends Templator implements TemplateInterface
{
    // declare your custom directives
    protected string $content = 'Hello @USERNAME@ how are u ?';
}

• Then you can pass the value with the template setTemplate(new MyTemplate, ['username' => $username])

💪 Custom Static Template

• By default templator uses Free Responsive HTML Email Template
• You can use your custom static template

final class MyTemplate extends Templator implements TemplateInterface
{
    /**
     * render this template method
     *
     * @param  array|null $variables
     * @return string
     */
    public function render(?array $variables = null): string
    {
        return $this->loadTemplate(
          'link/to/your/static/tepmlate.html'
        )->parse($variables);
    }
}

📧 Send mail with Templator

• Send mail with your template
• Email subject will follow Template class name

// your mailer (PHPMailer or swift)
// should implement MailAdapterInterface
$customMailer = new class implements MailTemplator\Contracts\MailAdapterInterface{
  public function send(string $to, string $subject, string $message): bool
  {
     // your mailer send should be wrapped here
     // $subject will be taken from template class name  if no custom subject provided
  }
}

// create an instance of mail class
$mail = new MailTemplator\Mail(
  $customMailer
);

// set your template
$mail->setTemplate(
  new MyCustomMilTemplates\MyTemplate
);

// send mail with the given template
$mail->send('to');

🚀 Laravel Integration

• A recommended directory structure should look like this

• Mail folder

  • Templates folder
  • Customer Mailer (PHPmailer or SwiftMailer)

• Make sure to register your custom mailer to laravel AppServiceProvider

public function register()
{
    // bind custom mailer that implements MailAdapterInterface
    $this->app->bind(MailTemplator\Contracts\MailAdapterInterface::class, function($app){
        return new CustomMailer;
    });
}

• Example usage withing a controller method

public function resetPassword(MailTemplator\Mail $mail)
{
    // send mail
    $mail->setTemplate(
      new App\Mail\Templates\ResetPasswordTemplate
      )->send('email@site.com');
}

🚁 TODO

• Adding database templates support

💻 Contributing

• Thank you for considering to contribute to MailTemplator. All the contribution guidelines are mentioned here.

📃 ChangeLog

• Here you can find the ChangeLog.

🍺 Support the development

• Share MailTemplator and lets get more stars and more contributors.
• If this project helped you reduce time to develop, you can give me a cup of coffee :) : Paypal. 💖

📋 License

• MailTemplator is an open-source software licensed under the MIT license.