README

本包由centagon维护

在Laravel中使用优化的二进制UUID

使用常规UUID作为主键肯定会很慢。

此包通过存储略微调整的二进制版本的UUID来解决这个问题。您可以在此处了解有关存储机制的更多信息：[http://mysqlserverteam.com/storing-uuid-values-in-mysql-tables/](http://mysqlserverteam.com/storing-uuid-values-in-mysql-tables/)

该包可以生成优化的UUID版本。它还提供了方便的模型作用域，可以轻松检索使用二进制UUID的模型。

想测试系统上的性能提升吗？没问题，我们已包括基准测试。

该包目前仅支持MySQL和SQLite。

安装

您可以通过Composer安装此包

composer require spatie/laravel-binary-uuid

使用方法

为了让模型使用优化的UUID，您必须在表中添加一个uuid字段作为主字段。

Schema::create('table_name', function (Blueprint $table) {
    $table->uuid('uuid');
    $table->primary('uuid');
});

为了让模型使用编码的UUID（即使用UUID作为主键），您必须让模型使用Spatie\BinaryUuid\HasBinaryUuid特质。

use Illuminate\Database\Eloquent\Model;
use Spatie\BinaryUuid\HasBinaryUuid;

class TestModel extends Model
{
    use HasBinaryUuid;
}

如果您不喜欢主键名称uuid，可以手动指定getKeyName方法。别忘了将$incrementing设置为false。

use Illuminate\Database\Eloquent\Model;
use Spatie\BinaryUuid\HasBinaryUuid;

class TestModel extends Model
{
    use HasBinaryUuid;

    public $incrementing = false;
    
    public function getKeyName()
    {
        return 'custom_uuid';
    }
}

如果您尝试将具有二进制属性的模型转换为JSON，您会看到错误。通过在您的模型上声明$uuidAttributes，您将告诉包在转换为数组时将那些UUID转换为文本。这也为每个uuid属性添加了一个动态访问器。

use Illuminate\Database\Eloquent\Model;
use Spatie\BinaryUuid\HasBinaryUuid;

class TestModel extends Model
{
    use HasBinaryUuid;
    
    /**
     * The suffix for the uuid text attribute 
     * by default this is '_text'
     * 
     * @var
     */
    protected $uuidSuffix = '_str';
    
    /**
     * The binary UUID attributes that should be converted to text.
     *
     * @var array
     */
    protected $uuids = [
        'country_uuid' // foreign or related key
    ];
}

在您的JSON中，您将看到uuid和country_uuid以它们的文本表示形式。如果您还使用复合主键，上面的方法也足够好了。只需在$uuids数组中包含您的键或覆盖您的模型上的getKeyName()方法，并返回键的数组作为复合主键。您还可以自定义UUID文本属性后缀名称。在上面的代码中，它不是'_text'，而是'_str'。

您的模型中的$uuids数组定义了在检索时转换为UUID字符串并在写入数据库时转换为二进制的字段。您不需要在模型中的$casts数组中定义这些字段。

关于uuid蓝图方法的说明

Laravel目前不允许添加新的蓝图方法，这些方法可以开箱即用。因此，我们决定覆盖uuid的行为，这将创建一个BINARY列而不是一个CHAR(36)列。

在某些情况下，Laravel生成的代码也将使用uuid，但不支持我们的二进制实现。一个例子是数据库通知。为了使这些通知工作，您必须将那些通知迁移的迁移更改为其使用CHAR(36)。

// $table->uuid('id')->primary();

$table->char('id', 36)->primary();

创建模型

模型的UUID将在保存时自动生成。

$model = MyModel::create();

dump($model->uuid); // b"\x11þ╩ÓB#(ªë\x1FîàÉ\x1EÝ." 

获取可读UUID

UUID仅在数据库中以二进制形式存储。但是，您可以使用文本版本，例如用于URL生成。

$model = MyModel::create();

dump($model->uuid_text); // "6dae40fa-cae0-11e7-80b6-8c85901eed2e" 

在创建模型之前，如果您想设置一个特定的UUID，这也是可能的。

不过，您可能永远不会想这样做。

$model = new MyModel();

$model->uuid_text = $uuid;

$model->save();

查询模型

查询数据库的最优方式

$uuid = 'ff8683dc-cadd-11e7-9547-8c85901eed2e'; // UUID from eg. the URL.

$model = MyModel::withUuid($uuid)->first();

withUuid作用域将自动将UUID字符串编码以查询数据库。手动方法可能如下所示。

$model = MyModel::where('uuid', MyModel::encodeUuid($uuid))->first();

您也可以使用withUuid作用域查询多个UUID。

$models = MyModel::withUuid([
    'ff8683dc-cadd-11e7-9547-8c85901eed2e',
    'ff8683ab-cadd-11e7-9547-8c85900eed2t',
])->get();

注意：1.3.0版本添加了使用UUID字符串查找数据的简化语法。

$uuid = 'ff8683dc-cadd-11e7-9547-8c85901eed2e'; // UUID from eg. the URL.

$model = MyModel::find($uuid);  

$model = MyModel::findOrFail($uuid);

1.3.0版本查询多个UUID。

$uuids = [
    'ff8683dc-cadd-11e7-9547-8c85901eed2e',
    'ff8683ab-cadd-11e7-9547-8c85900eed2t',
];

$model = MyModel::findMany($uuids);

查询关系

您也可以使用withUuid作用域通过指定要查询的字段来查询关系字段。

$models = MyModel::withUuid('ff8683dc-cadd-11e7-9547-8c85901eed2e', 'relation_field')->get();

$models = MyModel::withUuid([
    'ff8683dc-cadd-11e7-9547-8c85901eed2e',
    'ff8683ab-cadd-11e7-9547-8c85900eed2t',
], 'relation_field')->get();

运行基准测试

该包包含基准测试，证明以调整后的二进制形式存储UUID确实具有更好的性能。

在运行测试之前，您应该设置一个MySQL数据库并在phpunit.xml.dist中指定连接配置。

要运行测试，请执行此命令。

phpunit -d memory_limit=-1 --testsuite=benchmarks

运行基准测试可能需要几分钟。您将有机会喝几杯咖啡！

在测试运行时，平均结果将在终端输出。测试完成后，您将在测试文件夹中找到CSV格式的单个查询统计信息。

您可以使用这些数据进一步调查UUID在本地计算机上的性能。

以下是我们在机器上运行的基准测试的一些结果。

正常ID、二进制UUID和优化UUID方法的比较。在大型数据集上，优化UUID表现优于其他方法。

测试

composer test

变更日志

有关最近更改的更多信息，请参阅变更日志。

贡献

有关详细信息，请参阅贡献指南。

安全

如果您发现任何安全相关的问题，请通过电子邮件freek@spatie.be联系，而不是使用问题跟踪器。

明信片软件

您可以使用此包，但如果它进入了您的生产环境，我们非常感激您从家乡寄给我们一张明信片，并说明您正在使用我们的哪个包。

我们的地址是：Spatie，Samberstraat 69D，2060 安特卫普，比利时。

我们将所有收到的明信片发布在我们的公司网站上。

致谢

• Brent Roose
• 所有贡献者

支持我们

Spatie是一家位于比利时安特卫普的网络设计公司。您可以在我们的网站上找到所有开源项目的概述这里。

您的业务是否依赖于我们的贡献？联系并支持我们在Patreon。所有承诺都将用于分配人力进行维护和开发新功能。

许可证

MIT许可证（MIT）。有关更多信息，请参阅许可证文件。