fix(mail): correct markdown generation and HTML content rendering

docs/en/components/mail.md

@@ -76,14 +76,17 @@ sending, which is useful in development.
 
 ## Creating a Mailable
 
-With `hyperf/devtool` installed, generate a view-based mailable or use `--markdown` to also create a
-Markdown template:
+With `hyperf/devtool` installed, generate a view-based mailable or use `--markdown` to generate a
+mailable that references a Markdown view:
 
 ```shell
 php bin/hyperf.php gen:mail TestMail
 php bin/hyperf.php gen:mail TestMail --markdown
 ```
 
+`--markdown` (or `-m`) is a flag and takes no value. For `TestMail`, the generated class references
+`mail.test-mail`; create that Blade template separately in your configured view directory.
+
 `Envelope` defines addresses, subject, tags, metadata, and Symfony message callbacks. `Content`
 accepts `view` (or its `html` alias), `text`, `markdown`, `htmlString`, and `with`. Public properties
 declared by your mailable are also exposed to the view.
@@ -130,6 +133,18 @@ Attachments can also be created with `Attachment::fromData()`, `fromStorage()`,
 `fromStorageDisk()`. A reusable attachable object may implement
 `FriendsOfHyperf\Mail\Contract\Attachable`.
 
+For pre-rendered HTML, return `Content(htmlString: ...)` from your mailable. The HTML is used
+directly without rendering a Blade view:
+
+```php
+use FriendsOfHyperf\Mail\Mailable\Content;
+
+public function content(): Content
+{
+    return new Content(htmlString: '<h1>Hello</h1><p>Mail body</p>');
+}
+```
+
 ## Sending Mail
 
 `Mail::mailer()` selects a configured mailer; omitting its argument uses `mail.default`. The

docs/zh-cn/components/mail.md

@@ -72,13 +72,16 @@ mailer 专属的 `from`、`reply_to`、`to` 或 `return_path` 会覆盖对应全
 
 ## 创建 Mailable
 
-安装 `hyperf/devtool` 后，可生成基于视图的 mailable；使用 `--markdown` 会同时创建 Markdown 模板：
+安装 `hyperf/devtool` 后，可生成基于视图的 mailable；使用 `--markdown` 会生成引用 Markdown 视图的邮件类：
 
 ```shell
 php bin/hyperf.php gen:mail TestMail
 php bin/hyperf.php gen:mail TestMail --markdown
 ```
 
+`--markdown`（或 `-m`）是无需传值的开关。对于 `TestMail`，生成的类引用 `mail.test-mail`；
+请在配置的视图目录中另行创建对应的 Blade 模板。
+
 `Envelope` 定义地址、主题、标签、元数据和 Symfony 消息回调。`Content` 接受 `view`（或其 `html`
 别名）、`text`、`markdown`、`htmlString` 和 `with`。mailable 中声明的 public 属性也会暴露给视图。
 
@@ -123,6 +126,18 @@ class TestMail extends Mailable
 附件还可通过 `Attachment::fromData()`、`fromStorage()` 或 `fromStorageDisk()` 创建。可复用的附件
 对象可以实现 `FriendsOfHyperf\Mail\Contract\Attachable`。
 
+对于已渲染的 HTML，可在 mailable 中返回 `Content(htmlString: ...)`。HTML 将直接作为邮件正文，
+无需渲染 Blade 视图：
+
+```php
+use FriendsOfHyperf\Mail\Mailable\Content;
+
+public function content(): Content
+{
+    return new Content(htmlString: '<h1>Hello</h1><p>Mail body</p>');
+}
+```
+
 ## 发送邮件
 
 `Mail::mailer()` 选择已配置的 mailer；省略参数时使用 `mail.default`。`to()`、`cc()` 和 `bcc()`

docs/zh-hk/components/mail.md

@@ -72,13 +72,16 @@ mailer 專屬的 `from`、`reply_to`、`to` 或 `return_path` 會覆蓋對應全
 
 ## 創建 Mailable
 
-安裝 `hyperf/devtool` 後，可生成基於視圖的 mailable；使用 `--markdown` 會同時創建 Markdown 模板：
+安裝 `hyperf/devtool` 後，可生成基於視圖的 mailable；使用 `--markdown` 會生成引用 Markdown 視圖的郵件類：
 
 ```shell
 php bin/hyperf.php gen:mail TestMail
 php bin/hyperf.php gen:mail TestMail --markdown
 ```
 
+`--markdown`（或 `-m`）是無需傳值的開關。對於 `TestMail`，生成的類引用 `mail.test-mail`；
+請在配置的視圖目錄中另行創建對應的 Blade 模板。
+
 `Envelope` 定義地址、主題、標籤、元數據和 Symfony 消息回調。`Content` 接受 `view`（或其 `html`
 別名）、`text`、`markdown`、`htmlString` 和 `with`。mailable 中聲明的 public 屬性也會暴露給視圖。
 
@@ -123,6 +126,18 @@ class TestMail extends Mailable
 附件還可通過 `Attachment::fromData()`、`fromStorage()` 或 `fromStorageDisk()` 創建。可複用的附件
 對象可以實現 `FriendsOfHyperf\Mail\Contract\Attachable`。
 
+對於已渲染的 HTML，可在 mailable 中返回 `Content(htmlString: ...)`。HTML 將直接作為郵件正文，
+無需渲染 Blade 視圖：
+
+```php
+use FriendsOfHyperf\Mail\Mailable\Content;
+
+public function content(): Content
+{
+    return new Content(htmlString: '<h1>Hello</h1><p>Mail body</p>');
+}
+```
+
 ## 發送郵件
 
 `Mail::mailer()` 選擇已配置的 mailer；省略參數時使用 `mail.default`。`to()`、`cc()` 和 `bcc()`

docs/zh-tw/components/mail.md

@@ -72,13 +72,16 @@ mailer 專屬的 `from`、`reply_to`、`to` 或 `return_path` 會覆蓋對應全
 
 ## 建立 Mailable
 
-安裝 `hyperf/devtool` 後，可生成基於檢視的 mailable；使用 `--markdown` 會同時建立 Markdown 模板：
+安裝 `hyperf/devtool` 後，可生成基於檢視的 mailable；使用 `--markdown` 會生成引用 Markdown 檢視的郵件類：
 
 ```shell
 php bin/hyperf.php gen:mail TestMail
 php bin/hyperf.php gen:mail TestMail --markdown
 ```
 
+`--markdown`（或 `-m`）是無需傳值的開關。對於 `TestMail`，生成的類引用 `mail.test-mail`；
+請在配置的檢視目錄中另行建立對應的 Blade 模板。
+
 `Envelope` 定義地址、主題、標籤、元資料和 Symfony 訊息回撥。`Content` 接受 `view`（或其 `html`
 別名）、`text`、`markdown`、`htmlString` 和 `with`。mailable 中宣告的 public 屬性也會暴露給檢視。
 
@@ -123,6 +126,18 @@ class TestMail extends Mailable
 附件還可透過 `Attachment::fromData()`、`fromStorage()` 或 `fromStorageDisk()` 建立。可複用的附件
 物件可以實現 `FriendsOfHyperf\Mail\Contract\Attachable`。
 
+對於已渲染的 HTML，可在 mailable 中返回 `Content(htmlString: ...)`。HTML 將直接作為郵件正文，
+無需渲染 Blade 檢視：
+
+```php
+use FriendsOfHyperf\Mail\Mailable\Content;
+
+public function content(): Content
+{
+    return new Content(htmlString: '<h1>Hello</h1><p>Mail body</p>');
+}
+```
+
 ## 傳送郵件
 
 `Mail::mailer()` 選擇已配置的 mailer；省略引數時使用 `mail.default`。`to()`、`cc()` 和 `bcc()`

src/mail/README.md

@@ -78,14 +78,17 @@ sending, which is useful in development.
 
 ## Creating a Mailable
 
-With `hyperf/devtool` installed, generate a view-based mailable or use `--markdown` to also create a
-Markdown template:
+With `hyperf/devtool` installed, generate a view-based mailable or use `--markdown` to generate a
+mailable that references a Markdown view:
 
 ```shell
 php bin/hyperf.php gen:mail TestMail
 php bin/hyperf.php gen:mail TestMail --markdown
 ```
 
+`--markdown` (or `-m`) is a flag and takes no value. For `TestMail`, the generated class references
+`mail.test-mail`; create that Blade template separately in your configured view directory.
+
 `Envelope` defines addresses, subject, tags, metadata, and Symfony message callbacks. `Content`
 accepts `view` (or its `html` alias), `text`, `markdown`, `htmlString`, and `with`. Public properties
 declared by your mailable are also exposed to the view.
@@ -132,6 +135,18 @@ Attachments can also be created with `Attachment::fromData()`, `fromStorage()`,
 `fromStorageDisk()`. A reusable attachable object may implement
 `FriendsOfHyperf\Mail\Contract\Attachable`.
 
+For pre-rendered HTML, return `Content(htmlString: ...)` from your mailable. The HTML is used
+directly without rendering a Blade view:
+
+```php
+use FriendsOfHyperf\Mail\Mailable\Content;
+
+public function content(): Content
+{
+    return new Content(htmlString: '<h1>Hello</h1><p>Mail body</p>');
+}
+```
+
 ## Sending Mail
 
 `Mail::mailer()` selects a configured mailer; omitting its argument uses `mail.default`. The

src/mail/README_CN.md

@@ -74,13 +74,16 @@ mailer 专属的 `from`、`reply_to`、`to` 或 `return_path` 会覆盖对应全
 
 ## 创建 Mailable
 
-安装 `hyperf/devtool` 后，可生成基于视图的 mailable；使用 `--markdown` 会同时创建 Markdown 模板：
+安装 `hyperf/devtool` 后，可生成基于视图的 mailable；使用 `--markdown` 会生成引用 Markdown 视图的邮件类：
 
 ```shell
 php bin/hyperf.php gen:mail TestMail
 php bin/hyperf.php gen:mail TestMail --markdown
 ```
 
+`--markdown`（或 `-m`）是无需传值的开关。对于 `TestMail`，生成的类引用 `mail.test-mail`；
+请在配置的视图目录中另行创建对应的 Blade 模板。
+
 `Envelope` 定义地址、主题、标签、元数据和 Symfony 消息回调。`Content` 接受 `view`（或其 `html`
 别名）、`text`、`markdown`、`htmlString` 和 `with`。mailable 中声明的 public 属性也会暴露给视图。
 
@@ -125,6 +128,18 @@ class TestMail extends Mailable
 附件还可通过 `Attachment::fromData()`、`fromStorage()` 或 `fromStorageDisk()` 创建。可复用的附件
 对象可以实现 `FriendsOfHyperf\Mail\Contract\Attachable`。
 
+对于已渲染的 HTML，可在 mailable 中返回 `Content(htmlString: ...)`。HTML 将直接作为邮件正文，
+无需渲染 Blade 视图：
+
+```php
+use FriendsOfHyperf\Mail\Mailable\Content;
+
+public function content(): Content
+{
+    return new Content(htmlString: '<h1>Hello</h1><p>Mail body</p>');
+}
+```
+
 ## 发送邮件
 
 `Mail::mailer()` 选择已配置的 mailer；省略参数时使用 `mail.default`。`to()`、`cc()` 和 `bcc()`

src/mail/src/Command/MailCommand.php

@@ -32,7 +32,7 @@ public function __construct(
 
     protected function getStub(): string
     {
-        return $this->getConfig()['stub'] ?? ($this->input->getOption('markdown') !== false ? __DIR__ . '/stubs/mail.stub' : __DIR__ . '/stubs/markdown-mail.stub');
+        return $this->getConfig()['stub'] ?? ($this->input->getOption('markdown') ? __DIR__ . '/stubs/markdown-mail.stub' : __DIR__ . '/stubs/mail.stub');
     }
 
     protected function getDefaultNamespace(): string
@@ -81,7 +81,7 @@ protected function getView(): string
     {
         $view = $this->input->getOption('markdown');
 
-        if (! $view) {
+        if (! is_string($view) || $view === '') {
             $name = str_replace('\\', '/', $this->input->getArgument('name'));
 
             $view = 'mail.' . collect(explode('/', $name))
@@ -103,7 +103,7 @@ protected function buildClass(string $name): string
             parent::buildClass($name)
         );
 
-        if ($this->input->getOption('markdown') !== false) {
+        if ($this->input->getOption('markdown')) {
             $class = str_replace(['DummyView', '{{ view }}'], $this->getView(), $class);
         }
 

src/mail/src/Mailer.php

@@ -285,9 +285,9 @@ protected function sendMailable(MailableContract $mailable): ?SentMessage
     /**
      * Parse the given view name or array.
      */
-    protected function parseView(null|Closure|array|string $view): array
+    protected function parseView(null|Closure|Htmlable|HtmlString|array|string $view): array
     {
-        if (is_string($view) || $view instanceof Closure) {
+        if (is_string($view) || $view instanceof Closure || $view instanceof Htmlable || $view instanceof HtmlString) {
             return [$view, null, null];
         }
 
@@ -315,7 +315,7 @@ protected function parseView(null|Closure|array|string $view): array
     /**
      * Add the content to a given message.
      */
-    protected function addContent(Message $message, null|Closure|string $view, null|Closure|string $plain, ?string $raw, array $data = []): void
+    protected function addContent(Message $message, null|Closure|Htmlable|HtmlString|string $view, null|Closure|Htmlable|HtmlString|string $plain, ?string $raw, array $data = []): void
     {
         if (isset($view)) {
             $message->html($this->renderView($view, $data) ?: ' ');
@@ -333,7 +333,7 @@ protected function addContent(Message $message, null|Closure|string $view, null|
     /**
      * Render the given view.
      */
-    protected function renderView(Closure|string $view, array $data): string
+    protected function renderView(Closure|Htmlable|HtmlString|string $view, array $data): string
     {
         $view = value($view, $data);
         if ($view instanceof Htmlable) {

tests/Mail/MailCommandTest.php

@@ -0,0 +1,99 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * This file is part of friendsofhyperf/components.
+ *
+ * @link     https://github.com/friendsofhyperf/components
+ * @document https://github.com/friendsofhyperf/components/blob/main/README.md
+ * @contact  huangdijia@gmail.com
+ */
+
+namespace FriendsOfHyperf\Tests\Mail;
+
+use FriendsOfHyperf\Mail\Command\MailCommand;
+use FriendsOfHyperf\Tests\Concerns\InteractsWithContainer;
+use Hyperf\Config\Config;
+use Hyperf\Contract\ConfigInterface;
+use Hyperf\Support\Filesystem\Filesystem;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\Group;
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\Console\Tester\CommandTester;
+
+/**
+ * @internal
+ */
+#[Group('mail')]
+class MailCommandTest extends TestCase
+{
+    use InteractsWithContainer;
+
+    private string $directory;
+
+    private Filesystem $files;
+
+    private Config $config;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->refreshContainer();
+        $this->config = new Config([]);
+        $this->swap(ConfigInterface::class, $this->config);
+        $this->files = new Filesystem();
+        $this->directory = tempnam(sys_get_temp_dir(), 'mail-command-');
+        unlink($this->directory);
+        $this->files->makeDirectory($this->directory);
+    }
+
+    protected function tearDown(): void
+    {
+        $this->files->deleteDirectory($this->directory);
+        $this->flushContainer();
+        parent::tearDown();
+    }
+
+    #[DataProvider('mailOptions')]
+    public function testGeneratesMailable(string $name, array $options, string $namespace, string $content): void
+    {
+        $tester = new CommandTester(new MailCommand($this->files, $this->config));
+
+        $tester->execute(['name' => $name, '--path' => $this->directory] + $options);
+
+        $tester->assertCommandIsSuccessful();
+        $class = $this->files->get($this->directory . '/WelcomeMail.php');
+        $this->assertStringContainsString('namespace ' . $namespace . ';', $class);
+        $this->assertStringContainsString('class WelcomeMail extends Mailable', $class);
+        $this->assertStringContainsString("subject: 'Welcome Mail'", $class);
+        $this->assertStringContainsString($content, $class);
+        $this->assertStringNotContainsString('{{', $class);
+    }
+
+    public static function mailOptions(): array
+    {
+        return [
+            'view mailable' => ['WelcomeMail', [], 'App\Mail', "view: 'view.name'"],
+            'markdown flag' => ['WelcomeMail', ['--markdown' => true], 'App\Mail', "markdown: 'mail.welcome-mail'"],
+            'short markdown flag' => ['WelcomeMail', ['-m' => true], 'App\Mail', "markdown: 'mail.welcome-mail'"],
+            'slash namespace' => ['Orders/WelcomeMail', ['--markdown' => true], 'App\Mail\Orders', "markdown: 'mail.orders.welcome-mail'"],
+            'backslash namespace' => ['Orders\WelcomeMail', ['--markdown' => true], 'App\Mail\Orders', "markdown: 'mail.orders.welcome-mail'"],
+        ];
+    }
+
+    public function testRespectsConfiguredStub(): void
+    {
+        $stub = $this->directory . '/custom.stub';
+        $this->files->put($stub, '<?php namespace %NAMESPACE%; class %CLASS% { /* custom {{ view }} */ }');
+        $this->config->set('devtool.generator.mail.stub', $stub);
+        $tester = new CommandTester(new MailCommand($this->files, $this->config));
+
+        $tester->execute(['name' => 'WelcomeMail', '--path' => $this->directory, '--markdown' => true]);
+
+        $tester->assertCommandIsSuccessful();
+        $this->assertSame(
+            '<?php namespace App\Mail; class WelcomeMail { /* custom mail.welcome-mail */ }',
+            $this->files->get($this->directory . '/WelcomeMail.php')
+        );
+    }
+}