README

Lararut

此软件包集成了 RutUtils 软件包，允许在Laravel项目中操作RUTs。

此外，它还包括6条新规则，方便验证RUT数据。

查看 RutUtils文档，了解创建、生成和验证RUTs的所有可用方法。

重要 此软件包仅验证RUT是否有效，而不验证其是否来自真实人员。如果您需要此类功能，应让您的应用程序与 伪官方API 交互。

要求

• PHP 7.4或8.0
• Laravel 7.x或8.x

检查旧版本以获取旧Laravel版本。

安装

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

composer require darkghosthunter/lararut

验证规则

该软件包包含方便的规则来验证来自前端的RUTs。与先前版本相比，它们更易于使用和理解。

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

php artisan vendor:publish --provider="DarkGhostHunter\Lararut\LararutServiceProvider" --tag="translations"

数据库规则将自动将 K 校验位 数字 规范化以在数据库中搜索。

rut

此检查传入的RUT是否是有效的RUT字符串。它将自动 清除RUT 中的所有内容，除了数字和校验位，然后检查结果RUT是否有效。

<?php

use Illuminate\Support\Facades\Validator;

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

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

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

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

这在用户在RUT输入中按下错误按钮时可能很有用，因此无需要求用户添加连字符或点。之后，您可以使用 Rut::make() 从该输入创建一个新的Rut实例。

<?php

use DarkGhostHunter\RutUtils\Rut;

$rut = Rut::make(request()->input('rut'));

此规则还接受RUTs的 数组。在这种情况下，如果所有RUTs都有效，则 rut 将返回 true，如果至少有一个无效，则返回 false。这在用户在您的应用程序中注册许多人时可能很有用。

<?php

use Illuminate\Support\Facades\Validator;

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

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

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

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

rut_strict

此规则与 rut 类似，但它将验证也使用正确RUT格式的RUTs：带有千位分隔符并在校验位之前有连字符。这允许您在之后绕过任何清理。

由于它不清理值，即使有一个位置不正确的字符或无效字符，它也会返回 false。

<?php

use Illuminate\Support\Facades\Validator;

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

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

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

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

此规则也接受RUTs的 数组。在这种情况下，如果所有RUTs都正确格式化且有效，则 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->fails(); // true

rut_equal

这将检查RUT是否与另一个RUT相等，例如，认证用户的RUT或来自其他数据资源。在验证过程之前，两者都将被清理。

当您需要将RUT与其他外部服务或API进行交叉引用时，这很有用。

<?php

use Illuminate\Support\Facades\Validator;

$validator = Validator::make([
    'rut' => '12343580-K'
], [
    'rut' => 'required|rut_equal:12343580K' 
]);

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

您可以使用RUT的数组进行比较，这可以节省您多次进行rut_equal。在这种情况下，如果所有RUT都有效且彼此相等，则rut_equal将返回true。

<?php

use Illuminate\Support\Facades\Validator;

$validator = Validator::make([
    'rut' => '12.343.580-K'
], [
    'rut' => 'required|rut_equal:12343!580K,12.343.580-K' 
]);

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

如果您需要比较输入中的两个或多个RUT，您最好使用same验证规则。在确认RUT的情况下，使用confirmed验证规则。

rut_exists（数据库）

如果您数据库中有分开的RUT号码和校验位列，您可以使用rut_exists而不是Laravel的exists规则。

为此，您需要设置要查找的表，以及RUT号码列和RUT校验位列，否则规则将猜测列名，通过属性键添加_num和_vd。

<?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->fails(); // true

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

规则将自动将校验位列设置为uppercase，因此即使您在列中管理k为小写也不成问题。

为持久化而拥有RUT号码和校验位列通常是最好的方法。数字可以保存为4字节无符号int，后者为1字节string（1个字符长度）。

要自定义查询，您可以使用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->fails(); // 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->fails(); // true

您可以使用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->fails(); // true

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->fails(); // true

您还可以使用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->fails(); // true

[警告] 您永远不应将任何受用户控制的请求输入传递给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->fails(); // true

您还可以使用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->fails(); // true

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

数据库蓝图助手

如果您从头开始创建数据库，则无需手动创建RUT列。只需在蓝图中使用rut()或rutNullable()助手。

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

Schema::create('company', function (Blueprint $table) {
    $table->rutNullable();
    
    // ...
});

rutNullable()方法会创建可空的数字和校验位列。

如果您计划将数字用作索引，这可能有助于加快查找RUT的查询速度，您只需通过流畅地添加primary()、index()或unique()（根据您的数据库需求）来对数字列进行索引。这是因为仅对数字进行索引比对整个RUT进行索引更有意义。

RUT模型特质

此包包含两个特质：HasRut和RoutesRut。

要使用这些特质，请确保您的模型在单独的列中保存RUT数字和RUT校验位。

HasRut

此特质方便地为具有RUT列的模型添加RUT作用域和返回Rut实例的rut属性。

<?php

namespace App\Models;

use DarkGhostHunter\Lararut\HasRut;
use Illuminate\Foundation\Auth\User as Authenticatable;

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

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

• findRut()：通过给定的RUT查找记录。
• findManyRut()：通过给定的RUTs查找多个记录。
• findRutOrFail()：通过RUT查找记录或失败。
• findRutOrNew()：通过RUT查找记录或创建一个新记录。
• whereRut()：创建一个WHERE子句，其中RUT数字等于已发行的数字。
• orWhereRut()：创建一个OR WHERE子句，其中RUT数字等于已发行的数字。

这些RUT查询通过RUT数字进行，以方便起见，因为RUT校验位应在持久化时进行验证。

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 = 'digit_rut';
    
    // ...    
}

RoutesRut

您可以使用RoutesRut特质来重写Eloquent模型的resolveRouteBinding()方法，以查找其RUT，如果标识字段是rut。

确保您还添加了HasRut特质，因为它将使用添加的查询作用域。

use DarkGhostHunter\Lararut\HasRut;
use DarkGhostHunter\Lararut\RoutesRut;

class User extends Authenticatable
{
    use HasRut;
    use RoutesRut;
}

然后，您将能够在路由中通过指定rut作为用于从数据库检索模型实例的字段名称来使用路由模型绑定。

Route::get('usuario/{user:rut}', function (User $user) {
    return $user;
});

如果RUT无效，则找不到模型，因此在路由绑定时无需验证RUT。

Rut集合

此包在使用many()和manyOrThrow()时注册了一个回调，以检索作为Laravel集合的RUT数组。

$ruts = Rut::many([
    '15500342-1',
    '7276742-K'
]);

echo $ruts->first(); // "15.500.342-1"

助手

本软件包包含全局助手代码文件 rut()，允许你在代码的任何位置创建Rut实例，或者在未提供任何参数的情况下创建Rut生成器。

<?php

namespace App\Http\Listeners;

use Illuminate\Auth\Events\Lockout;
use App\Notifications\ProbablyForgotHisPassword;
use App\Notifications\SupportReadyToHelp;
use App\Models\User;

class LogFailedAttempt
{
    /**
     * Handle the event.
     *
     * @param  Lockout  $event
     * @return void
     */
    public function handle(Lockout $event)
    {
        // Get the RUT from the request input
        $rut = rut($event->request->input('rut'));
        
        // If the user who tried exists in the database, notify him.
        if ($user = User::where('rut_num', $rut->num)->first()) {
            $user->notify(new ProbablyForgotHisPassword());
        }
    }
    
    /**
     * Creates many RUTs. 
     * 
     * @return array|\DarkGhostHunter\RutUtils\Rut
     */
    public function generateRuts()
    {
        return rut()->generate(100);
    }
}

授权

本软件包遵循MIT授权协议。