
本文详解如何在 Laravel 中正确使用队列(Queue)批量发送带 PDF 附件的邮件,涵盖模型、Mailable、Job 及控制器的协同配置,并重点指出 get() 缺失导致队列不触发的关键错误。
本文详解如何在 laravel 中正确使用队列(queue)批量发送带 pdf 附件的邮件,涵盖模型、mailable、job 及控制器的协同配置,并重点指出 `get()` 缺失导致队列不触发的关键错误。
在 Laravel 中通过队列异步发送批量邮件是提升应用响应性能和可靠性的标准实践。但初学者常因细微疏漏(如查询构建器未执行)导致队列任务“静默失败”——看似调用了 dispatch(),实则任务根本未写入数据库队列表,php artisan queue:listen 自然无任何输出,数据库 jobs 表也为空。
✅ 正确流程:从查询到投递的完整链路
核心问题在于控制器中 $letters 的获取方式:
// ❌ 错误:$letters 是 Builder 实例,未执行查询,foreach 实际遍历空结果
$letters = AcceptLetter::where('email', '!=', null)->where('passport_number','!=','0');
foreach($letters as $letter){ ... } // 不会执行任何迭代!
// ✅ 正确:必须显式调用 ->get() 获取 Eloquent 集合
$letters = AcceptLetter::where('email', '!=', null)
->where('passport_number', '!=', '0')
->get(); // ← 关键修复!
foreach ($letters as $letter) {
QueueJob::dispatch($letter); // 此时才真正将任务推入队列
}
? 提示:Laravel 的查询构造器(Query Builder)是惰性执行的,
where()等方法仅构建 SQL 条件,get()、first()、count()等才是触发实际数据库查询的操作。
? Mailable 类优化建议
你定义的 TopluKabulMektubu 类整体结构合理,但有两点关键优化:
-
PDF 路径安全性检查:避免因
public_path($letter->pdf)中$letter->pdf为空或路径非法导致附件失败:public function build() { $pdfPath = public_path($this->letter->pdf); if (!file_exists($pdfPath)) { \Log::warning("PDF not found for letter #{$this->letter->id}: {$this->letter->pdf}"); // 可选择抛出异常或跳过附件 } return $this->subject('Mail Title') ->view('emails.topluKabulSon') ->attach($pdfPath, [ 'as' => 'AcceptanceLetter.pdf', 'mime' => 'application/pdf', ]); } -
避免
$this->letter在build()中重复赋值:SerializesModels已确保模型可序列化,直接使用$this->letter即可,无需额外变量。
Laravel Cloud下载Laravel Cloud(cloud.laravel.com)。此技能用于处理所有 Laravel Cloud 请求,包括搜索和读取数据。只要任务涉及 Laravel Cloud,即使用此技能。
⚙️ Job 类设计精简版
你的 QueueJob 类可进一步简化(移除冗余注释与保护属性),并增强健壮性:
<?php namespace App\Jobs;
use App\Models\AcceptLetter;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
class SendAcceptanceLetter implements ShouldQueue
{
use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
public function __construct(public AcceptLetter $letter) // PHP 8+ 属性提升,更清晰
{
//
}
public function handle()
{
try {
$this->letter->sendAcceptanceLetter();
} catch (\Exception $e) {
\Log::error("Failed to send acceptance letter #{$this->letter->id}", [
'exception' => $e->getMessage(),
'trace' => $e->getTraceAsString()
]);
// 可选:标记失败状态或触发告警
}
}
}
✅ 命名建议:将
QueueJob改为语义明确的SendAcceptanceLetter,符合 Laravel 社区惯例。
? 测试与验证步骤
完成代码修复后,按顺序执行以下操作验证:
-
确保队列驱动为
database(.env):QUEUE_CONNECTION=database
-
创建并迁移队列表:
php artisan queue:table php artisan migrate
-
启动队列监听器(另开终端):
php artisan queue:listen
-
访问测试路由
/topluDeneme,观察终端是否打印Processing jobs...及任务日志。 -
检查数据库
jobs表 是否新增记录;成功执行后记录将被删除,失败任务进入failed_jobs表。
⚠️ 注意事项总结
-
永远记得
get()/cursor():Eloquent 查询必须显式执行才能获得数据。 -
附件路径务必存在且可读:
public_path()返回的是绝对路径,确保$letter->pdf存储的是相对public/的子路径(如pdf/letter_123.pdf)。 -
邮箱字段有效性校验:在
sendAcceptanceLetter()中增加if (!$this->email) return;避免向空地址发信。 -
避免在
handle()中直接调用模型方法修改状态:你的sendAcceptanceLetter()内部已更新$this->email_send,但若队列失败重试,可能造成状态错乱。推荐改为在handle()中统一处理状态更新,或使用数据库事务保证一致性。
遵循以上规范,即可稳定、高效地实现 Laravel 批量邮件队列投递。










