diff --git a/README.md b/README.md index cf8c9c9..37235e8 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,6 @@ -# A package to create customizable mail templates in Filament +# Mail Templates for Filament -## - -This is where your description should go. Limit it to a paragraph or two. Consider adding a small example. +A package to quickly create customizable mail templates in Filament ## Installation @@ -12,65 +10,12 @@ You can install the package via composer: composer require codedor/filament-mail-templates ``` -You can publish and run the migrations with: - -```bash -php artisan vendor:publish --tag="filament-mail-templates-migrations" -php artisan migrate -``` - You can publish the config file with: ```bash php artisan vendor:publish --tag="filament-mail-templates-config" ``` -This is the contents of the published config file: - -```php -return [ -]; -``` - -Optionally, you can publish the views using - -```bash -php artisan vendor:publish --tag="filament-mail-templates-views" -``` - -## Usage - -```php -$filamentMailTemplates = new Codedor\FilamentMailTemplates(); -echo $filamentMailTemplates->echoPhrase('Hello, Codedor!'); -``` - ## Documentation For the full documentation, check [here](./docs/index.md). - -## Testing - -```bash -vendor/bin/pest -``` - -## Changelog - -Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. - -## Upgrading - -Please see [UPGRADING](UPGRADING.md) for more information on how to upgrade to a new version. - -## Contributing - -Please see [CONTRIBUTING](CONTRIBUTING.md) for details. - -## Security Vulnerabilities - -If you discover any security-related issues, please email info@codedor.be instead of using the issue tracker. - -## License - -The MIT License (MIT). Please see [License File](LICENSE.md) for more information. diff --git a/docs/index.md b/docs/index.md index b897499..c27b87b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,144 @@ -# A package to create customizable mail templates in Filament +# Mail Templates for Filament -## Introduction +A package to quickly create customizable mail templates in Filament ## Installation + +You can install the package via composer: + +```bash +composer require codedor/filament-mail-templates +``` + +## Defining Mail Templates + +When adding mail templates there are a few things to do, first you'll need to add the `Codedor\FilamentMailTemplates\Models\Traits\HasMails` trait models that you want to have mail templates. + +```php +namespace App\Models; + +use Codedor\FilamentMailTemplates\Models\Traits\HasMails; +use Illuminate\Database\Eloquent\Model; + +class Inquiry extends Model +{ + use HasMails; +} +``` + +After doing this, you'll also need to define what fields you want to be able to use in the mail template. To do this you'll need to define the fields in the `getMailVariables` method. + +The keys in this array will be the variables that show up in the mail template as labels, and the values will be the values that will be used in the mail template, when sent. + +```php +namespace App\Models; + +use Codedor\FilamentMailTemplates\Models\Traits\HasMails; +use Illuminate\Database\Eloquent\Model; + +class Inquiry extends Model +{ + use HasMails; + + public function getMailVariables(): array + { + return [ + 'first name' => $this->first_name, + 'last name' => $this->last_name, + 'e-mail' => $this->email, + 'message body' => $this->message, + 'inquiry type' => $this->inquiryType?->working_title, + ]; + } + + public function inquiryType() + { + return $this->belongsTo(InquiryType::class); + } +} +``` + +Lastly, you need to define the actual mail template. To do this you'll need to add the following to any Provider in your project: + +```php +use App\Models; +use Illuminate\Support\ServiceProvider; + +class AppServiceProvider extends ServiceProvider +{ + public function boot(): void + { + Models\Inquiry::registerMail('inquiry-admin') + ->description('Send an email to the admin when a new inquiry is made'); + + Models\Inquiry::registerMail('inquiry-user') + ->view('mail.inquiry-new') + ->description('Send an email to the user when a new inquiry is made'); + } +} +``` + +The `registerMail` method takes a string as the first argument, this is the name/identifier of the mail template and should be kebabcase. A description can be given as well, this is optional but will provide the admin additional information about the mail template in the Filament resource. + +## Saving the Mail Templates + +When you are done defining your templates, run the following command: + +```bash +php artisan filament-mail-templates:create +``` + +This will loop over all your defined mail templates and create them in the database. It is recommended that you add this command in your deployment process, so that the mail templates are always up to date. + +## Sending Mail Templates from the front-end + +After filling in all data in the CMS, you can get the mail object in the front-end by using the `mail` method of the model. For example, this contact form: + +```php +class ContactForm extends Component +{ + public array $fields = []; + + public function submit() + { + $this->validate(); + + /** @var Inquiry $inquiry */ + $inquiry = Inquiry::create($this->fields); + + Mail::send($inquiry->mail('inquiry-admin')->to($inquiry->inquiryType?->to_email)); + Mail::send($inquiry->mail('inquiry-user')->to($inquiry->email)); + } +} +``` + +This example will send a mail to the admin and the user. + +The `mail` method returns a Laravel Mailable object, so you can use all the methods that are available on that object. + +## Customizing Mail Templates + +The config file comes with the following: + +```php +return [ + 'default' => [ + 'view' => 'filament-mail-templates::mail.template', + 'to_email' => null, + ], + 'navigation' => [ + 'templates' => [ + 'icon' => 'heroicon-o-inbox', + 'group' => 'Mails', + 'shown' => true, + ], + 'history' => [ + 'icon' => 'heroicon-o-mail', + 'group' => 'Mails', + 'shown' => true, + ], + ], +]; +``` + +Here you can define some default values and customize the navigation icon/groups of the resources. The `shown` key can be used to hide the resource from the navigation completely. diff --git a/src/Console/Commands/CreateMailTemplates.php b/src/Console/Commands/CreateMailTemplates.php index b5a7e92..7dc25db 100644 --- a/src/Console/Commands/CreateMailTemplates.php +++ b/src/Console/Commands/CreateMailTemplates.php @@ -4,7 +4,7 @@ use Codedor\FilamentMailTemplates\Facades\MailTemplateCollection; use Codedor\FilamentMailTemplates\Models\MailTemplate; -use Codedor\FilamentMailTemplates\RegisteringMailTemplate; +use Codedor\FilamentMailTemplates\MailTemplateBuilder; use Illuminate\Console\Command; class CreateMailTemplates extends Command @@ -15,9 +15,9 @@ class CreateMailTemplates extends Command public function handle(): void { - MailTemplateCollection::each(function (RegisteringMailTemplate $template) { + MailTemplateCollection::each(function (MailTemplateBuilder $builder) { MailTemplate::updateOrCreate([ - 'identifier' => $template->getIdentifier(), + 'identifier' => $builder->getIdentifier(), ]); }); } diff --git a/src/Filament/MailTemplateResource.php b/src/Filament/MailTemplateResource.php index bab56ce..e4325ce 100644 --- a/src/Filament/MailTemplateResource.php +++ b/src/Filament/MailTemplateResource.php @@ -63,6 +63,7 @@ public static function form(Form $form): Form ->content(fn (Model $record) => $record->description), Repeater::make('to_email') + ->helperText('If left empty, the sites default e-mail will be used.') ->label('Target e-mails') ->schema([ Grid::make()->schema([ diff --git a/src/Mail/MailableTemplate.php b/src/Mail/MailableTemplate.php index b41df87..27c3f8f 100644 --- a/src/Mail/MailableTemplate.php +++ b/src/Mail/MailableTemplate.php @@ -4,7 +4,7 @@ use Codedor\FilamentMailTemplates\Models\MailHistory; use Codedor\FilamentMailTemplates\Models\MailTemplate; -use Codedor\FilamentMailTemplates\RegisteringMailTemplate; +use Codedor\FilamentMailTemplates\MailTemplateBuilder; use Illuminate\Bus\Queueable; use Illuminate\Database\Eloquent\Model; use Illuminate\Mail\Mailable; @@ -21,12 +21,12 @@ class MailableTemplate extends Mailable public MailTemplate $template; public function __construct( - public RegisteringMailTemplate $registeredTemplate, + public MailTemplateBuilder $builder, public Model $item, string $locale, public bool $isPreview = false, ) { - $this->template = $registeredTemplate->getTemplateModel(); + $this->template = $builder->getTemplateModel(); $this->locale($locale); } @@ -53,7 +53,7 @@ public function content(): Content $body = nl2br($this->parseVariables($this->template->body)); return new Content( - view: $this->registeredTemplate->getView(), + view: $this->builder->getView(), with: [ 'item' => $this->item, 'body' => new HtmlString($body), diff --git a/src/RegisteringMailTemplate.php b/src/MailTemplateBuilder.php similarity index 98% rename from src/RegisteringMailTemplate.php rename to src/MailTemplateBuilder.php index 427f857..405610b 100644 --- a/src/RegisteringMailTemplate.php +++ b/src/MailTemplateBuilder.php @@ -5,7 +5,7 @@ use Codedor\FilamentMailTemplates\Mail\MailableTemplate; use Codedor\FilamentMailTemplates\Models\MailTemplate; -class RegisteringMailTemplate +class MailTemplateBuilder { public null|string $locale = null; diff --git a/src/MailTemplateCollection.php b/src/MailTemplateCollection.php index a761082..1480999 100644 --- a/src/MailTemplateCollection.php +++ b/src/MailTemplateCollection.php @@ -6,15 +6,15 @@ class MailTemplateCollection extends Collection { - public function addTemplate(RegisteringMailTemplate $template): self + public function addTemplate(MailTemplateBuilder $builder): self { - return $this->add($template); + return $this->add($builder); } - public function getTemplate(string $identifier): RegisteringMailTemplate + public function getTemplate(string $identifier): MailTemplateBuilder { - return $this->first(function (RegisteringMailTemplate $template) use ($identifier) { - return $template->getIdentifier() === $identifier; + return $this->first(function (MailTemplateBuilder $builder) use ($identifier) { + return $builder->getIdentifier() === $identifier; }); } } diff --git a/src/Models/MailTemplate.php b/src/Models/MailTemplate.php index c71a832..311a838 100644 --- a/src/Models/MailTemplate.php +++ b/src/Models/MailTemplate.php @@ -3,7 +3,7 @@ namespace Codedor\FilamentMailTemplates\Models; use Codedor\FilamentMailTemplates\Facades\MailTemplateCollection; -use Codedor\FilamentMailTemplates\RegisteringMailTemplate; +use Codedor\FilamentMailTemplates\MailTemplateBuilder; use Illuminate\Database\Eloquent\Model; use Illuminate\Support\Collection; use Spatie\Translatable\HasTranslations; @@ -32,7 +32,7 @@ class MailTemplate extends Model 'to_email' => 'array', ]; - public function getMailTemplate(): RegisteringMailTemplate + public function getMailTemplate(): MailTemplateBuilder { return MailTemplateCollection::getTemplate($this->identifier); } diff --git a/src/Models/Traits/HasMails.php b/src/Models/Traits/HasMails.php index df2e077..f229d4b 100644 --- a/src/Models/Traits/HasMails.php +++ b/src/Models/Traits/HasMails.php @@ -4,7 +4,7 @@ use Codedor\FilamentMailTemplates\Facades\MailTemplateCollection; use Codedor\FilamentMailTemplates\Mail\MailableTemplate; -use Codedor\FilamentMailTemplates\RegisteringMailTemplate; +use Codedor\FilamentMailTemplates\MailTemplateBuilder; trait HasMails { @@ -20,13 +20,13 @@ public function mail(string $identifier, null|string $locale = null): MailableTe return new MailableTemplate($template, $this, $locale); } - public static function registerMail($identifier): RegisteringMailTemplate + public static function registerMail($identifier): MailTemplateBuilder { - $template = RegisteringMailTemplate::make($identifier, self::class); + $builder = MailTemplateBuilder::make($identifier, self::class); - MailTemplateCollection::addTemplate($template); + MailTemplateCollection::addTemplate($builder); - return $template; + return $builder; } public function getMailVariables(): array