使用 Referenceable 为模型定制参考号

在许多 web 应用中，为模型生成唯一的参考号是一项常见要求。无论是在构建需要订单号的电子商务平台、需要发票参考号的发票系统，还是需要可跟踪标识符的应用，管理参考号生成都可能很快变得复杂。

Referenceable 是 Mohamed Said 创建的 Laravel 包，它通过允许生成具有灵活格式和全面配置选项的可定制模型参考号来帮助解决这一挑战。

主要特性

• 多生成策略：可随机、序列和基于模板生成参考
• 高可配置性：前缀、后缀、分隔符等的广泛配置选项
• 模板系统：使用占位符如 {YEAR}、{MONTH}、{SEQ}、{RANDOM}，以处理复杂格式
• 序列编号: 使用重置选项自增序号(daily, monthly, yearly)
• 验证与确认：内置参考验证和唯一性检查
• 碰撞处理：自动碰撞检测和解决
• 多租户支持：租户感知参考生成
• Artisan 命令：用于管理和维护的综合 CLI 工具
• 性能优化：缓存、批处理和数据库事务

示例

假设我们有一个系统，允许用户在大学提交状态信请求。我们可以创建一个迁移，其中包含一个字段来存储我们的参考号：

Schema::create('status_letters', function (Blueprint $table) {
    $table->id();
    $table->string('reference_number')->unique()->index();
    // other table columns for our status letters...
    $table->timestamps();
});

然后，我们创建一个模型，并指定如何创建我们的参考号：

use MohamedSaid\Referenceable\Traits\HasReference;
 
class StatusLetter extends Model
{
    use HasReference;
 
    protected $referenceColumn = 'reference_number';
    protected $referenceStrategy = 'template';
    protected $referenceTemplate = [
        'format' => '{PREFIX}-{YEAR}{MONTH}{SEQ}',
        'sequence_length' => 4,
    ];
    protected $referencePrefix = 'STL';
    // Will generate: STL-2025090001, STL-2025090002...
}

除了 template 策略，你也可以使用 random 策略：

protected $referenceStrategy = 'random';
protected $referencePrefix = 'STL';
protected $referenceLength = 6;
protected $referenceCase = 'upper';
 
// Will generate: STL-A12BC3

或者使用 sequential 策略：

protected $referenceStrategy = 'sequential';
protected $referencePrefix = 'STL';
protected $referenceSequential = [
    'start' => 1000,
    'min_digits' => 4,
    'reset_frequency' => 'monthly', // never, daily, monthly, yearly
];
 
// Will generate: STL-001000, STL-001001, STL-001002...

配置引用也可以在 config/referenceable.php 中全局完成，而不是基于每个模型。

Referenceable 提供了许多方法和模型范围。其中一些是：

// Manually generate without saving it
$reference = $statusLetter->generateReference();
 
// Check if your model has a reference
if ($statusLetter->hasReference()) {
    echo "Reference Number: " . $statusLetter->reference;
}
 
// Find an item by its reference number
$statusLetter = StatusLetter::findByReference('STL-2025090001');
 
// Find references starting with prefix
$lettersThisMonth = StatusLetter::referenceStartsWith('STL-202509')->get();

不必再纠结于 Laravel 中混乱的参考号生成了—— Referenceable 包只需几行配置即可为你提供专业的订单号、发票 ID 和跟踪代码。

通过 Composer 安装此软件包并运行 install 命令，尝试一下：

composer require eg-mohamed/referenceable
php artisan referenceable:install

GitHub 仓库：https://github.com/EG-Mohamed/Referenceable