README

用于解析、验证和生成智利RUT的Laravel工具。

use Laragear\Rut\Rut;

$rut = Rut::parse('18.765.432-1');

if ($rut->isValid()) {
    return 'Your RUT is valid!';
}

保持此包免费

您的支持使我能够保持此包免费、最新和维护。或者，您可以通过 传播信息。

要求

Laravel 10 或更高版本

安装

启动Composer并将它添加到您的项目中

composer require laragear/rut

创建RUT

要从已存在的有效源创建RUT，请分别实例化一个包含数字和校验位的 Rut 对象。

use Laragear\Rut\Rut;

$rut = new Rut(5138171, 8);

否则，您可能想使用 parse() 方法从单个字符串中创建它。它将尽力从给定内容中创建一个RUT实例，如果字符串没有创建RUT所需的字符，将抛出 InvalidRutException。

use Laragear\Rut\Rut;

$rut = Rut::parse('5.138.171-8');

RUT类型

官方上有六种RUT类型。要区分它们，您可以通过访问 is...() 方法。

此外，您还可以通过访问 isPermanent() 方法来检查RUT是否小于100,000,000。

use Laragear\Rut\Rut;

Rut::parse('76.482.465-2')->isPermanent(); // "true"

Rut::parse('76.482.465-2')->isTemporal(); // "false"

重要

此包将RUT视为有效，如果它在100,000至200,000,000之间（含）。大多数（如果不是所有人）使用99,999或更低RUT号码的人已经去世。

生成RUT

此包包含一个方便的RUT Generator 外观，用于使用流式方法创建成千上万或数百万个随机RUT。

make() 方法默认生成一个包含15个 Rut 的 Collection，但您可以设置任何想要的数字。或者，您可以使用 makeOne() 来创建一个随机的 Rut。

use Laragear\Rut\Facades\Generator;

$ruts = Generator::make(10);

$rut = Generator::makeOne();

您可以使用 as...() 来创建特定类型的RUT。

use Laragear\Rut\Facades\Generator;

$people = Generator::asPeople()->make(10);

$companies = Generator::asCompanies()->make(10);

$temporal = Generator::asTemporal()->makeOne();

如果您计划创建数百万个RUT，您可能会遇到重复的情况。为了避免冲突，请使用 unique() 方法，以换取轻微的性能损失来删除重复项。

use Laragear\Rut\Facades\Generator;

$ruts = Generator::unique()->asCompanies()->make(10000000);

序列化

默认情况下，所有 Rut 实例都使用严格的格式序列化为文本。您可以使用三种可用的格式之一使用不同的格式序列化 Rut 实例。

您可以使用 format() 方法与任何 RutFormat 枚举作为参数来将RUT序列化为文本。

use Laragear\Rut\Rut;
use Laragear\Rut\RutFormat;

$rut = Rut::parse('5.138.171-8');

$rut->format();                  // "5.138.171-8"
$rut->format(RutFormat::Strict); // "5.138.171-8"
$rut->format(RutFormat::Basic);  // "5138171-8"
$rut->format(RutFormat::Raw);    // "51381718"

您可以通过全局配置来更改此设置。

验证RUT

您应使用包含的验证规则来验证输入中的RUT。

否则，您可以使用 isValid() 或 isInvalid() 手动验证RUT，分别检查其是否在数学上有效或无效。

use Laragear\Rut\Rut;

$rut = Rut::parse('5.138.171-8');

if ($rut->isValid()) {
    return "The Rut is valid!";
}

使用 validate() 方法，如果它无效，将抛出 InvalidRutException。

use Laragear\Rut\Rut;

Rut::parse('5.138.171-K')->validate(); // InvalidRutException: "The given RUT is invalid."

您还可以使用 check() 方法直接验证RUT字符串，或已分开的RUT。

use Laragear\Rut\Rut;

if (Rut::check('5.138.171-8')) {
    return "This RUT is valid!";
}

if (Rut::check(5138171, '8')) {
    return "This RUT is also valid!";
}

验证规则

所有验证规则消息都可以翻译。您可以通过发布翻译文件来为这些规则添加自己的翻译。

php artisan vendor:publish --provider="Laragear\Rut\RutServiceProvider" --tag="translations"

`rut` 规则

此规则检查传递的RUT是否为有效的RUT字符串。这会自动 清除RUT 中的任何内容，除了数字和校验位。然后它检查生成的RUT是否在数学上有效。

<?php

use Illuminate\Support\Facades\Validator;

$validator = Validator::make([
    'rut' => '14328145-0'
], [
    'rut' => 'rut'
]);

echo $validator->passes(); // true

$validator = Validator::make([
    'rut' => '65.00!!!390XXXX2'
], [
    'rut' => 'rut'
]);

echo $validator->passes(); // true

当用户错误地按下 RUT 输入中的按钮时，这可能很有用，因此无需要求用户正确格式化 RUT。之后，您可以使用请求 RUT 辅助工具从请求输入或查询中检索 RUT。

此规则也接受 RUT 的 数组。在这种情况下，如果所有 RUT 都有效，则 rut 将成功。当用户需要将许多人注册到您的应用程序时，这可能会很有用。

<?php

use Illuminate\Support\Facades\Validator;

$validator = Validator::make([
    'rut' => ['14328145-0', '12.343.580-K', 'thisisnotarut']
], [
    'rut' => 'rut'
]);

echo $validator->passes(); // false

$validator = Validator::make([
    'rut' => ['14328145-0', '12.343.580-K', '20881410-9']
], [
    'rut' => 'rut'
]);

echo $validator->passes(); // true

`rut_strict` 规则

它与 rut 的工作方式相同，但它将验证也使用严格 RUT 格式的 RUT：带有千位分隔符并在验证位之前带有连字符。

即使有一个字符放错位置或无效，它也会返回 false。

<?php

use Illuminate\Support\Facades\Validator;

$validator = Validator::make([
    'rut' => '14.328.145-0'
], [
    'rut' => 'rut_strict'
]);

echo $validator->passes(); // true

$validator = Validator::make([
    'rut' => '1.4328.145-0'
], [
    'rut' => 'rut_strict'
]);

echo $validator->passes(); // false

此规则也接受 RUT 的 数组。在这种情况下，如果所有 RUT 都正确格式化且有效，则 rut_strict 将返回 true。

<?php

use Illuminate\Support\Facades\Validator;

$validator = Validator::make([
    'rut' => ['1.4328.145-0', '12.343.580-K']
], [
    'rut.*' => 'required|rut_strict',
]);

echo $validator->paases(); // false

`rut_exists` 数据库规则

除了使用 Laravel 的 exists 外，如果您数据库中 RUT 号码和验证位分开存储，则可以使用 rut_exists。

为此，您需要设置要查找的表、RUT 号码 列和 RUT 验证位 列，否则规则将根据属性键猜测列名，分别附加 _num 和 _vd。

此规则在查询之前自动验证 RUT。

<?php

use Illuminate\Support\Facades\Validator;

$validator = Validator::make([
    'rut' => '12.343.580-K'
], [
    'rut' => 'required|rut_exists:mysql.users,rut_num,rut_vd'
]);

echo $validator->passes(); // false

由于这也检查 RUT 是否有效（非严格），如果它不是或 RUT 不在数据库中，则将失败。

要自定义查询，您可以使用 Laravel 的 Rule 类和 rutExists 方法。请注意，您可以输入数字和验证位列，或两者都输入，如果您不想让规则猜测它们，因为它可能在使用通配符时猜测错误。

<?php

use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rule;

$validator = Validator::make([
    'rut' => [
        'rut_1' => '12.343.580-K',
        'rut_2' => '13.871.792-5',
    ],
], [
    'rut' => [
        'required',
        Rule::rutExists('mysql.users', 'rut_num', 'rut_vd')->where('account_id', 1),
    ]
]);

echo $validator->passes(); // true

技巧

数据库规则将验证位规范化为数据库中的大写字母，以便进行搜索查询。

`num_exists` 数据库规则

此验证规则检查 RUT 的号码是否存在，而不考虑验证位。当数据库在 RUT 号码上有索引时，这很方便，从而使此验证非常快速。

此规则在查询之前自动验证 RUT。

<?php

use Illuminate\Support\Facades\Validator;

$validator = Validator::make([
    'rut' => '12.343.580-K'
], [
    'rut' => 'required|num_exists:mysql.users,rut_num' 
]);

echo $validator->passes(); // false

您可以使用 numExists 自定义底层查询。

<?php

use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rule;

$validator = Validator::make([
    'rut' => '12.343.580-K',
], [
    'rut' => [
        'required',
        Rule::numExists('mysql.users', 'rut_num')->where('account_id', 1),
    ]
]);

echo $validator->passes(); // false

`rut_unique` 数据库规则

这与 rut_exists 规则的工作方式相同，但它将检测 RUT 是否不存在于数据库中，而不是检查 RUT 是否存在。此规则的工作方式与 Laravel 的 unique 规则相同。

此规则在查询之前自动验证 RUT。

<?php

use Illuminate\Support\Facades\Validator;

$validator = Validator::make([
    'rut' => '12.343.580-K'
], [
    'rut' => 'required|rut_unique:mysql.users,rut_num,rut_vd' 
]);

echo $validator->passes(); // false

您还可以使用 Rule 类排除特定 ID 或记录的唯一验证。为此，您需要使用 Rule 类。

<?php

use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rule;

$validator = Validator::make([
    'rut' => '12.343.580-K',
], [
    'rut' => [
        'required',
        Rule::rutUnique('mysql.users', 'rut_num')->ignore(request()->user()),
    ]
]);

echo $validator->passes(); // false

技巧

数据库规则将验证位规范化为数据库中的大写字母，以便进行搜索查询。

注意

您永远不应该将任何用户控制的请求输入传递给 ignore 方法。相反，您应该只传递系统生成的唯一 ID，例如来自 Eloquent 模型实例的自动递增 ID 或 UUID。否则，您的应用程序将容易受到 SQL 注入攻击。

`num_unique` 数据库规则

此规则将仅检查 RUT 的号码是否已在数据库中存在，这对于仅在 RUT 号码上具有索引的数据库很有用。此规则也与 Laravel 的 unique 规则的工作方式相同。

此规则在查询之前自动验证 RUT。

<?php

use Illuminate\Support\Facades\Validator;

$validator = Validator::make([
    'rut' => '12.343.580-K'
], [
    'rut' => 'required|num_unique:mysql.users,rut_num' 
]);

echo $validator->passes(); // false

您还可以使用 Rule 类排除特定 ID 或记录的唯一验证。为此，您需要使用 Rule 类。

<?php

use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rule;

$validator = Validator::make([
    'rut' => '12.343.580-K',
], [
    'rut' => [
        'required',
        Rule::numUnique('mysql.users')->ignore(request()->user()->id),
    ]
]);

echo $validator->passes(); // false

技巧

数据库规则将验证位在数据库中规范化，以便进行搜索查询。

注意

数据库蓝图助手

如果您从头开始创建数据库，您不需要手动创建RUT列。只需在Blueprint中使用rut()或rutNullable()辅助函数。

Schema::create('users', function (Blueprint $table) {
    // $table->unsignedInteger('rut_num');
    // $table->char('rut_vd', 1);
    
    $table->rut();
    
    // ...
});

Schema::create('company', function (Blueprint $table) {
    // $table->unsignedInteger('rut_num')->nullable();
    // $table->char('rut_vd', 1)->nullable();
    
    $table->rutNullable();
    
    // ...
});

技巧

rutNullable()方法创建同时数字和校验位列，均可为空。

如果您计划将RUT号码用作索引，这可能可以加快查找RUT的查询速度，您只需通过流畅地添加primary()、index()或unique()来索引数字列，具体取决于您的数据库需求。这是因为仅索引数字比整个RUT索引有更好的性能。

Schema::create('users', function (Blueprint $table) {
    // $table->unsignedInteger('rut_num')->primary();
    // $table->char('rut_vd', 1);

    $table->rut()->primary();
    
    // ...
});

RUT请求辅助函数

此包包括用于Request实例的rut()宏辅助函数，可以从输入或查询中检索单个RUT。

use Illuminate\Http\Request;

public function show(Request $request)
{
    $request->validate([
        'person' => 'required|rut'
    ]);
    
    $rut = $request->rut('person');
    
    // ...
}

如果输入是可迭代的，如array或甚至是Collection实例，您将收到一个包含Rut实例的Collection。

$request->validate([
    'people'   => 'required|array',
    'people.*' => 'rut'
]);

$ruts = $request->rut('people');

您还可以从请求中检索多个键，这将返回一个Collection。

$request->validate([
    'mom'        => 'required|rut',
    'dad'        => 'required|rut',
    'children'   => 'required|array'
    'children.*' => 'required|rut',
]);

$parents = $request->rut('mom', 'dad'); // Or $request->rut(['mom', 'dad']);
$children = $request->rut('children');

重要

在检索RUT之前验证输入是至关重要的。如果存在格式不正确的RUT，将抛出异常。

Eloquent模型RUT特性

此包包含用于Laravel Eloquent模型的HasRut特性，适用于具有单独RUT号码和RUT校验位的表的模型。

该特性方便地为具有RUT列的模型添加RUT范围，并提供一个返回Rut实例的rut属性。

<?php

namespace App\Models;

use Laragear\Rut\HasRut;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use HasRut;
    
    // ...
}

这样，您将能够访问方便的RUT查询简写

重要

这些RUT查询为了方便起见，在RUT号码上操作，因为RUT校验位应该在持久化时才验证。

这些范围可以轻松地用于您的查询中

use App\Models\User;

$user = User::whereRut('20490006-K')->where('is_active', true)->find();

rut属性是由RUT号码和RUT校验位列动态创建的，其下面使用了一个转换。

echo $user->rut; // "20490006-K"

设置RUT列

按照惯例，该特性使用rut_num和rut_vd作为默认列来检索和保存RUT号码和RUT校验位。

您可以轻松将其更改为模型所使用的任何内容

class User extends Authenticatable
{
    use HasRut;
    
    protected const RUT_NUM = 'numero_rut';
    protected const RUT_VD = 'digito_rut';
    
    // ...    
}

RUT附加和列隐藏

默认情况下，rut属性是附加的，包含RUT信息的底层列是隐藏的。这使它与Livewire实时验证兼容。

{
    "id": 1,
    "name": "Taylor",
    "email": "taylor@laravel.com",
    "rut": "16.887.941-5"
}

要显示底层RUT列而不是RUT字符串，只需在模型中将shouldAppendRut()返回为false。

/**
 * If the `rut` key should be appended, and hide the underlying RUT columns.
 *
 * @return bool
 */
public function shouldAppendRut(): bool
{
    return false;
}

这将有效地将两个列作为正常属性返回。

{
    "id": 1,
    "name": "Taylor",
    "email": "taylor@laravel.com",
    "rut_num": 16887941,
    "rut_vd": "5"
}

如果您需要使rut键和底层列可见，您可以重写shouldAppendRut()方法并返回false。

public function shouldAppendRut(): bool
{
   $this->append('rut');

   return false;
}

配置

此包开箱即用，但您可能希望更改Rut作为字符串格式化的方式，这可以通过全局配置来完成。您可以使用Artisan发布它

php artisan vendor:publish --provider="Laragear\Rut\RutServiceProvider" --tag="config"

您将收到类似这样的config/rut.php配置文件

use Laragear\Rut\RutFormat;

return [
    'format' => RutFormat::Strict,
    'json_format' => null,
    'uppercase' => true,
];

默认RUT格式

use Laragear\Rut\RutFormat;

return [
    'format' => RutFormat::DEFAULT,
];

默认情况下，RUT是严格格式化的。此配置改变了RUT在应用程序全局范围内作为字符串序列化的方式。

JSON格式

use Laragear\Rut\RutFormat;

return [
    'json_format' => null,
];

对于JSON的情况，当此为null时，使用全局格式将RUT转换为字符串。您可以为将RUT序列化为JSON专门设置任何格式。

use Laragear\Rut\Rut;
use Laragear\Rut\RutFormat;

config()->set('rut.format_json', RutFormat::Raw)

Rut::parse('5.138.171-8')->format(); // "5.138.171-8"
Rut::parse('5.138.171-8')->toJson(); // "51381718"

或者，您可以使用回调来覆盖配置以创建自己的JSON格式。回调接受一个Rut实例，并且它应该返回一个array或一个string，以便序列化为JSON。将此逻辑放在AppServiceProvider文件的boot()方法中是一个好地方。

use Laragear\Rut\Rut;

Rut::$jsonFormat = function (Rut $rut) {
    return ['num' => $rut->num, 'vd' => $rut->vd];
}

Rut::parse('5.138.171-8')->toJson(); // "{"num":5138171,"vd":"8"}"

校验位大小写

return [
    'uppercase' => true,
];

由于验证码可以是单个数字或字母 K，通常最好保持大小写一致；在整个应用程序中始终使用大写或小写。

默认情况下，Rut 实例将使用大写 K，但您可以通过将其设置为 false 来全局更改它为小写。这将影响所有 Rut 实例。

use Laragear\Rut\RutFormat;
use Laragear\Rut\Rut;

config()->set('rut.uppercase', false)

$rut = Rut::parse('12351839-K');

$rut->format(); // "12.351.839-k"
$rut->toJson(); // "12.351.839-k"

技巧

这不会影响数据库规则，因为验证码会自动标准化。

PhpStorm 模型

对于 PhpStorm 用户，有一个模型文件来帮助自动补全此包的宏。您可以使用 phpstorm 标签来发布它。

php artisan vendor:publish --provider="Laragear\Rut\RutServiceProvider" --tag="phpstorm"

文件将被发布到您的项目的 .stubs 文件夹。您应该将 PhpStorm 指向这些模型。

Laravel Octane 兼容性

没有使用过时应用程序实例的单例。
没有使用过时配置实例的单例。
没有使用过时请求实例的单例。
Rut 静态属性只在启动时从配置中写入一次。

使用此包与 Laravel Octane 不会有任何问题。

安全性

如果您发现任何与安全相关的问题，请通过电子邮件 darkghosthunter@gmail.com 反馈，而不是使用问题跟踪器。

许可证

此特定包版本在发布时根据 MIT 许可证的条款许可，MIT 许可证。

laragear / rut

维护者

详细信息

README

保持此包免费

要求

安装

创建RUT

RUT类型

生成RUT

序列化

验证RUT

验证规则

`rut` 规则

`rut_strict` 规则

`rut_exists` 数据库规则

`num_exists` 数据库规则

`rut_unique` 数据库规则

`num_unique` 数据库规则

数据库蓝图助手

RUT请求辅助函数

Eloquent模型RUT特性

设置RUT列

RUT附加和列隐藏

配置

默认RUT格式

JSON格式

校验位大小写

PhpStorm 模型

Laravel Octane 兼容性

安全性

许可证

laragear / rut

维护者

详细信息

README

保持此包免费

要求

安装

创建RUT

RUT类型

生成RUT

序列化

验证RUT

验证规则

rut 规则

rut_strict 规则

rut_exists 数据库规则

num_exists 数据库规则

rut_unique 数据库规则

num_unique 数据库规则

数据库蓝图助手

RUT请求辅助函数

Eloquent模型RUT特性

设置RUT列

RUT附加和列隐藏

配置

默认RUT格式

JSON格式

校验位大小写

PhpStorm 模型

Laravel Octane 兼容性

安全性

许可证

`rut` 规则

`rut_strict` 规则

`rut_exists` 数据库规则

`num_exists` 数据库规则

`rut_unique` 数据库规则

`num_unique` 数据库规则