README

RUT工具库

一个用于创建、操作和生成智利RUTs或RUNs的完整库。

此包允许您

• 创建一个RUT对象，以便方便地存储RUT信息。
• 验证、清理和修正RUTs。
• 生成随机RUTs，方式灵活。

虽然这个包可以作为您项目的“开火即走”工具，但请确保阅读文档，以免重复。

要求

此包只需要PHP 7.3及以后的版本。

它可能在旧版本上也能运行，但它将仅支持活跃的PHP版本。

可选：了解el weón weón weón的含义。

安装

只需运行Composer并将它引入到您的项目中

composer require darkghosthunter/rut-utils

如果您在项目中没有Composer，您应该感到羞愧只需安装它。

用法

• 什么是RUT或RUN？
• 创建RUT
• 检索RUT
• 生成RUTs
• 辅助工具
• 回调
• 序列化
• 全局辅助工具

什么是RUT或RUN？

RUT（或RUN对人们来说）是一串数字，用于识别个人或公司。它们对每个人都是唯一的，并且永远不会重新分配给个人，因此RUT的注册总是增长的。

RUT由一个随机数字组成，如18.765.432，以及一个校验数字，这是对该数字应用数学算法(Modulo 11)的结果。这个校验数字在0到9之间，或是一个K。最后，你得到这个

18.765.432-1

这种识别信息是智利公司的可靠选择。它允许将一个账户与一个个人（人或公司）关联起来，并且可以通过其他服务中用户可能拥有的其他数据进行交叉引用。

RUTs和RUNs之间的区别是什么？RUT用于识别个人或公司税，RUN用于识别个人。对于这两种情况，它们实际上是相同的。

创建RUT

有两种方法可以创建RUT：严格的手动实例化和使用make()静态辅助工具。

手动实例化

使用手动实例化允许您通过给定的数字和校验数字快速创建RUT。例如，来自数据库或其他可信来源的数据。

<?php 

use DarkGhostHunter\RutUtils\Rut;

// Create a RUT using its numbers and verification digit separately.
$rutA = new Rut('14328145', 0); 

// ...even if the RUT is malformed 
$rutB = new Rut(10000, 'foo'); 

虽然这是一种非常好的方法来获取有效的RUT，但您可能想使用make()静态辅助工具来创建Rut实例。

<?php 

use DarkGhostHunter\RutUtils\Rut;

// Create a RUT using its numbers and verification digit separately.
$rutA = Rut::make('14328145', 0);

// You can also use a whole string.
$rutB = Rut::make('14.328.145-0');

// And even malformed ones with invalid characters
$rutC = Rut::make('asdwdasd14.32.814.5-0');

静态辅助工具将自动清理字符串并为您解析数字和校验数字，因此您不必这样做。

如果生成的RUT是不规则的或无效的，将返回null而不是Rut实例，您可以使用它来快速设置代码中的流程控制。

<?php 

use DarkGhostHunter\RutUtils\Rut;

$malformed = Rut::make('not-a-rut');

if (!$malformed) {
    echo 'This RUT is bad!';
}

make()方法接受一个值或可调用对象，当RUT是不规则的或无效时将返回。

<?php 

use DarkGhostHunter\RutUtils\Rut;

$validA = Rut::make('14328145', 0, 'this is valid');
echo $validA; // "14.328.145-0"

$validB = Rut::make('14.328.145-0', function () {
    return 'also valid'; 
});
echo $validB; // "14.328.145-0"

$invalid = Rut::make('18.765.432-1', null, 'this is invalid');
echo $invalid; // "this is invalid"

或者，您可能想使用makeOrThrow()在尝试创建不规则或无效的RUT时抛出异常。

<?php 

use DarkGhostHunter\RutUtils\Rut;

$validA = Rut::makeOrThrow('18.765.432', 1);

// [!] [InvalidRutException]

创建多个RUTs

使用循环来生成多个RUT（统一社会信用代码）可能比较繁琐。相反，可以使用many()静态方法。该方法会自动从最终数组中过滤掉格式不正确的RUT。

<?php

use DarkGhostHunter\RutUtils\Rut;

// Create multiple RUTs
$rutsA = Rut::many('14.328.145-0', '14.328.145-0');

// Or issue an array of multiple RUTs
$rutsB = Rut::many([
    '14.328.145-0',
    '7976228-8',
    ['14.328.145', 0]
]);

可以使用manyOrThrow()来返回异常，如果检测到格式不正确或无效的RUT。

检索RUT

由于无法知道您的应用程序如何与RUT交互，您可以方便地将Rut对象视为数组、对象或字符串。

<?php

use DarkGhostHunter\RutUtils\Rut;

// Let's create first the RUT:
$rut = Rut::make(14328145, 0);

// Return the RUT as a string
echo $rut; // 14.328.145-0

// You can get number or verification digit as an array
echo $rut['num']; // 14328145
echo $rut['vd']; // 0

// ...or as an object
echo $rut->num; // 14328145
echo $rut->vd; // 0

出于安全原因，您不能在实例中设置num和vd。

小写或大写K

RUT可以包含作为校验位的K字符。当创建RUT时，Rut对象不区分小写k或大写K，但默认情况下总是存储为大写。

您可以使用allUppercase()或allLowercase()方法来更改所有Rut实例的行为

<?php

use DarkGhostHunter\RutUtils\Rut;

Rut::allLowercase();

echo Rut::make('12343580', 'K')->vd; // "k"

Rut::allUppercase();

echo Rut::make('12343580', 'K')->vd; // "K"

此外，您可以通过使用uppercase()和lowercase()来更改单个实例的配置。

<?php

use DarkGhostHunter\RutUtils\Rut;

$rut = Rut::make('12343580', 'K');

$rut->lowercase();

echo $rut->vd; // "K"

$rut->uppercase();

echo $rut->vd; // "k"

当您的数据源管理小写k且您需要严格的比较以存储或标准化时，这可能会很有用。

生成RUTs

有时，创建一个RUT用于即时使用很有用，通常用于测试目的，例如播种和模拟。

您可以使用RutGenerator类并使用方法来构建您想要的RUT生成方式。方法是流式的，这意味着，您可以在使用generate()方法之前连续使用它们。

<?php

use DarkGhostHunter\RutUtils\RutGenerator;

$rut = RutGenerator::make()->generate();

echo $rut; // "7.976.228-8" 

默认模式为普通人创建RUT，范围在1,000,000至50,000,000之间。您可以使用forCompany()方法，该方法将结果随机变化在50,000,000至100,000,000之间。

<?php

use DarkGhostHunter\RutUtils\RutGenerator;

echo $rut = RutGenerator::make()->asPerson()->generate();
// "15.846.327-K"

echo $company = RutGenerator::make()->asCompany()->generate();
// "54.029.467-4"

当然，一个可能不够。您可以在这些方法中添加一个参数，指定您想要生成的RUT数量。结果将以数组的形式返回。

<?php

use DarkGhostHunter\RutUtils\RutGenerator;

$peopleRuts = RutGenerator::make()->asPerson()->generate(10);
$companyRuts = RutGenerator::make()->asCompany()->generate(35);

如果您需要它们作为原始字符串而不是Rut实例，这在生成数千个实例且对内存使用要求严格时非常好，请使用asBasic()和asRaw()方法。

这将输出类似22605071K的随机字符串。

<?php

use DarkGhostHunter\RutUtils\RutGenerator;

$raw = RutGenerator::make()->asRaw()->generate(10);
$basic = RutGenerator::make()->asBasic()->generate(20);
$strict = RutGenerator::make()->asStrict()->generate(30);

生成随机唯一的RUT

如果您需要创建超过数千个RUT而不存在重复的风险，请使用withoutDuplicates()方法。

<?php

use DarkGhostHunter\RutUtils\RutGenerator;

$ruts = RutGenerator::make()->withoutDuplicates()->generate(100000);

调用之间的唯一结果

您可能有一个自定义播种器在您的应用程序中，它可能会每次都调用generate()，从而增加每次生成的碰撞风险。别担心！使用generateStatic()，您将保证在整个应用程序生命周期中获取唯一的结果。

<?php

use DarkGhostHunter\RutUtils\RutGenerator;

$users = [
    ['name' => 'John'],
    ['name' => 'Clara'],
    ['name' => 'Mark'],
    // ... and other 99.997 records
];

$seeder = function ($user) {
    return array_merge($user, [
        'rut' => RutGenerator::make()->generateStatic()
    ]);
};

// Call the seeder
foreach ($users as $key => $user) {
    $users[$key] = $seeder($user);
}

// Flush the static array for the next seeder call
RutGenerator::make()->flushStatic();

辅助工具

您可以使用RutHelper类快速操作和检查字符串，它包含您可以使用的大量便利的静态方法。

• cleanRut
• separateRut
• validate
• validateStrict
• filter
• rectify
• isPerson
• isCompany
• isEqual
• getVd

cleanRut

清除RUT字符串中的无效字符。此外，您可以设置是否希望将K校验字符设置为大小写。

<?php

use DarkGhostHunter\RutUtils\RutHelper;

echo RutHelper::cleanRut('f@a18765432@@7'); // "187654327"
echo RutHelper::cleanRut('18.290.743-K', false); // "18290743k"

separateRut

清理并分离字符串为数字和校验位数组。

<?php

use DarkGhostHunter\RutUtils\RutHelper;

RutHelper::separateRut('18.290.743-K', false);

// array(2) [
//    0 => 18290743,
//    1 => 'k',
// ]

validate

检查发放的RUT是否有效。

如果有多个RUT，则如果所有RUT都有效，则返回true，如果至少有一个无效，则返回false。

<?php

use DarkGhostHunter\RutUtils\RutHelper;

echo RutHelper::validate('14328145-0'); // true
echo RutHelper::validate('14.328.145-0', '12343580-K'); // true
echo RutHelper::validate(143281450); // true
echo RutHelper::validate('not-a-rut'); // false
echo RutHelper::validate(['14.328.145-0', '12343580-K', 'foo']); // false

或者，您可以使用Rut对象本身。

<?php

use DarkGhostHunter\RutUtils\Rut;

// Cleans the rut, and validate it 
echo Rut::make('14328145-0')->isValid(); // true
echo Rut::make('94.328.145-0')->isValid(); // false
echo Rut::make('cleanthis14328145-0-andthistoo')->isValid(); // true

validateStrict

您可以严格验证RUT。传递的RUT值必须是带有千位分隔符和位于RUT校验位之前连字符的字符串。

如果有多个RUT，则如果所有RUT都有效，则返回true，如果至少有一个无效，则返回false。

<?php

use DarkGhostHunter\RutUtils\RutHelper;

// Receive the raw string, and strictly validate it
echo RutHelper::validateStrict('14328145-0'); // false
echo RutHelper::validateStrict('14.328.145-0', '12343580-K'); // false
echo RutHelper::validateStrict(143281450); // false
echo RutHelper::validateStrict('not-a-rut'); // false
echo RutHelper::validateStrict(143281450, 'not-a-rut'); // false
echo RutHelper::validateStrict('14.328.1!45-0'); // false

filter

过滤RUT数组，返回仅包含有效RUT的数组。

<?php

use DarkGhostHunter\RutUtils\RutHelper;

// Filter only the valid ruts, and leave the invalid out of the result.
$rutsA = RutHelper::filter(
    '14328145-0', 
    '12343580-K', 
    '94.328.145-0', 
    'not-a-rut'
);

var_dump($rutsA);

// array(1) {
//     [0] => 14328145-0
//     [1] => 12343580-K
// } 

$rutsB = RutHelper::filter([
    '14328145-0',
    '12343580-K',
    '94.328.145-0',
    'not-a-rut'
]);

var_dump($rutsB);

// array(1) {
//     [0] => 14328145-0
//     [1] => 12343580-K
// } 

rectify

接收只有RUT号码，并返回包含相应校验位的有效Rut实例。

<?php

use DarkGhostHunter\RutUtils\RutHelper;

$rut = RutHelper::rectify('18765432');

echo $rut->num; // "18765432"
echo $rut->vd; // "7"

如果您传递整个RUT，您可能得到一个带有附加校验位的新的RUT。确保您只传递RUT号码。

isPerson

检查RUT是否小于50,000,000，通常用于普通人。

<?php

use DarkGhostHunter\RutUtils\RutHelper;

echo RutHelper::isPerson('22605071-k'); // true

您也可以在Rut实例内部使用isPerson()辅助工具。

<?php

use DarkGhostHunter\RutUtils\RutHelper;

echo RutHelper::make('22605071-k')->isPerson(); // true

isCompany

检查RUT是否超过或等于50,000,000，这些通常用于公司。

<?php

use DarkGhostHunter\RutUtils\RutHelper;

echo RutHelper::isCompany('50000000-7'); // true

您还可以在Rut实例内使用isCompany()辅助函数。

<?php

use DarkGhostHunter\RutUtils\RutHelper;

echo RutHelper::make('50000000-7')->isCompany(); // true

isEqual

返回两个或更多RUT是否相等，无论这些格式如何，即使这些无效。

<?php

use DarkGhostHunter\RutUtils\RutHelper;
use Application\Models\User;

$ruts = RutHelper::isEqual(
    'thisisARut12343580-K',
    '12343580-K',
    User::getRutFromDatabase()
);

echo $ruts; // true

您还可以在Rut实例内使用isEqual()辅助函数。

<?php

use DarkGhostHunter\RutUtils\Rut;
use Application\Models\User;

$rut = Rut::make(User::getRutFromDatabase());

echo $rut->isEqual('thisisARut12343580-K', '12343580-k'); // true

getVd

返回给定数字的校验位。

<?php

use DarkGhostHunter\RutUtils\RutHelper;

$vd = RutHelper::getVd(12343580);

echo $vd; // 'K'

解包

接受一个数组，如果只发布了一个包含数组的项，则该项的内容将被返回到应用程序。

<?php

use DarkGhostHunter\RutUtils\RutHelper;

$unpacked = RutHelper::unpack([
    ['12343580K', '22605071-k', 500000007],
]);

echo count($unpacked); // 3

回调

为了方便起见，您可以在使用many()和manyOrThrow()之后注册回调函数。例如，您可能想要在返回之前操作RUT的处理方式。

您可以使用after()静态方法注册回调函数。可调用函数接收RUT数组，并必须返回结果。

<?php

use DarkGhostHunter\RutUtils\Rut;
use DarkGhostHunter\RutUtils\RutHelper;

Rut::after(function ($ruts) {
    
    return array_merge($ruts, [
        'count' => count($ruts),
    ]);
});

$ruts = Rut::many([
    // ...
]);

var_dump($ruts);
// array(100) [
//    // ...
//    'count' => 100,
// ]

如果您注册了多个回调，它们将按注册的顺序执行。

序列化

有时您可能想将Rut实例存储在某个地方，或者将其序列化为JSON，或者字符串。使用此包，您将得到全方位的保障。

序列化/反序列化

默认情况下，Rut实例被序列化为原始字符串，该字符串随后通过仅将字符串分为数字和校验位快速重建。

<?php

use DarkGhostHunter\RutUtils\Rut;

$rut = Rut::make('22605071-k');

echo serialize($rut); // C:28:"DarkGhostHunter\RutUtils\Rut":9:{106663092}

这主要针对低存储和快速实例化进行了优化。其余的将取决于您的序列化引擎。

字符串

有多种方式可以在将Rut实例序列化为字符串时设置要使用的格式

• 严格：默认选项。带有千位分隔符和连字符序列化。
• 基本：不带千位分隔符，只有连字符。
• 原始：不带千位分隔符和连字符。

这些可以通过静态方法全局设置，也可以通过实例本身的动态调用按实例设置。

<?php

use DarkGhostHunter\RutUtils\Rut;

$rut = Rut::make('22605071-k');

Rut::allFormatStrict(); 

echo (string)$rut; // "22.605.071-K"

Rut::allFormatBasic(); 

echo (string)$rut; // "22605071-K"

Rut::allFormatRaw(); 

echo (string)$rut; // "22605071K"

// Per instance
echo $rut->toStrictString(); // "22.605.071-K"
echo $rut->toBasicString(); // "22605071-K"
echo $rut->toRawString(); // "22605071K"

JSON

默认情况下，当转换为JSON时，结果是一个字符串。您可以使用静态方法对所有实例进行更改，或者按实例情况进行更改，使其成为数字和校验位的数组。

<?php

use DarkGhostHunter\RutUtils\Rut;

Rut::allJsonAsArray();

$rut = Rut::make('22605071-k');

echo json_encode($rut); // {"num":"22605071","vd":"K"}

Rut::allJsonAsString();

echo json_encode($rut); // "22.605.071-K"

$rut->jsonAsArray();

echo json_encode($rut); // {"num":"22605071","vd":"K"}

$rut->jsonAsString();

echo json_encode($rut); // "22.605.071-K"

全局辅助工具

在版本2.0中，所有辅助函数都已取消，现在只有一个名为rut()的函数。它作为Rut::make的代理，但在无效RUT的情况下接受默认值。如果没有发布参数，则返回Rut生成器的一个实例。

<?php

$rut = rut('10.666.309-2');

echo $rut; // '10.666.309-2';

$rut = rut('an invalid rut', 'use this!');

echo $rut; // 'use this!'

$rut = rut()->generate();

echo $rut; // '20.750.456-4'

许可

此软件包由MIT许可证许可。