Download the PHP package darkghosthunter/rut-utils without Composer

RUT Utilities

A complete library for creating, manipulating and generating chilean RUTs or RUNs.

This package allows you to:

• Create a RUT object to conveniently hold the RUT information.
• Validate, clean and rectify RUTs.
• Generate random RUTs in a flexible manner.

While this package works as a fire-and-forget utility for your project, ensure you read the documentation so you don't repeat yourself.

Requirements

This package only needs PHP 7.3 and later.

It may work on older versions, but it will only support active PHP releases.

Optional: Know what el weón weón weón means.

Installation

Just fire Composer and require it into your project:

If you don't have Composer in your project, you should be ashamed just install it .

Usage

• What is a RUT or RUN?
• Creating a RUT
• Retrieving a RUT
• Generating RUTs
• Helpers
• Make Callbacks
• Serialization
• Global helper

What is a RUT or RUN?

A RUT (or RUN for people) is a string of numbers which identify a person or company. They're unique for each one, and they're never re-assigned to an individual, so the registry of RUTs is always growing.

The RUT its comprised of a random Number, like 18.765.432, and a Verification Digit, which is the result of a mathematical algorithm (Modulo 11) over that number. This Verification Digit vary between 0 and 9, or a K. In the end. you get this:

This identification information is a safe bet for chilean companies. It allows to attach one account to one individual (person or company), and can be cross-referenced with other data the user may have available through other services.

What's the difference between RUTs and RUNs? RUT are meant for identifying a person or company taxes, RUNs are to identify single persons. For both cases, they're practically the same.

Creating a RUT

There are two ways to create a RUT: manual instancing, which is strict, and using the make() static helper.

Manual instancing

Using manual instantiation allows you to create a RUT by the given number and verification digit quickly. For example, with data coming from a Database or any other trustful source.

While this is a very good way to have a rut when knowing it's valid, you may want to use the make() static helper to create a Rut instance.

The static helper will automatically clean the string and parse the number and verification digit for you, so you don't have to.

If the resulting Rut is malformed or invalid, null will be returned instead of a Rut instance, which you can use to quickly set flow control in your code.

The make() method accepts a value or callable that will be returned when the RUT is malformed or invalid.

Alternatively, you may want to use the makeOrThrow() to throw an exception when trying to make a malformed or invalid RUT.

Creating multiple RUTs

It can be cumbersome to do a foreach or for loop to make multiple RUTs. Instead of that, use the many() static method. The method will automatically filter malformed RUTs from the final array.

You can use the manyOrThrow() to return an exception in case a malformed or invalid RUT is detected.

Retrieving a RUT

Since there is no way to know how your application works with RUTs, you can treat the Rut object as an array, object or string for your convenience.

For safety reasons, you cannot set the num and vd in the instance.

Lowercase or Uppercase K

A RUT can have the K character as verification digit. The Rut object doesn't discerns between lowercase k or uppercase K when creating one, but it always stores uppercase as default.

You can change this behaviour for all Rut instances using the allUppercase() or allLowercase() methods:

Additionally, you can change this configuration for a single instance by using uppercase() and lowercase().

This may come in handy when your source of truth manages lowercase k and you need strict comparison for storing, or normalize it.

Generating RUTs

Sometimes it's handy to create a RUT on the fly, usually for testing purposes when seeding and mocking.

You can do that using the RutGenerator class and use the methods to build how you want to generate your RUTs. The methods are fluent, meaning, you can chain them until you use the generate() method.

The default mode makes a RUT for normal people, which are bound between 1.000.000 and 50.000.000. You can use the forCompany() method, which will vary the result randomly between 50.000.000 and 100.000.000.

Of course one may be not enough. You can add a parameter to these methods with the number of RUTs you want to make. The result will be returned as an array.

If for some reason you need them as raw strings instead of Rut instances, which is very good when generating thousands of them on strict memory usage, use the asBasic() and asRaw() method.

This will output the random strings like 22605071K.

Generating random unique RUTs

If you need to create more than thousands of RUTs without the risk of having them duplicated, use the withoutDuplicates() method.

Unique results between calls

You may have a custom seeder in your application that may call generate() every single time, increasing risk of collisions with each generation. Fear not! Using the generateStatic() you are guaranteed to get unique results during a single application lifecycle.

Helpers

You can manipulate and check strings quickly using the RutHelper class, which contains a wide variety of handy static methods you can use.

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

cleanRut

Clears a RUT string from invalid characters. Additionally, you can set if you want the K verification character as uppercase or lowercase.

separateRut

Cleans and separates a string into a number and verification digit array.

validate

Checks if the RUTs issued are valid.

If there are more than one RUT, it will return true if all the RUTs are valid, and false if at least one is invalid.

Alternatively, you can use the Rut object itself.

validateStrict

You can strictly validate a RUT. The RUT value being passed must be a string with thousand separator and hyphen preceding the RUT verification digit.

If there are more than one RUT, it will return true if all the RUTs are valid, and false if at least one is invalid.

filter

Filter an array of RUTs, returning an array of only the valid RUTs.

rectify

Receives only the RUT number and returns a valid Rut instance with the corresponding verification digit.

If you pass down a whole RUT, you may get a new RUT with an appended Verification Digit. Ensure you pass down only the RUT number.

isPerson

Checks if the RUT below 50.000.000, which are usually used for normal people.

You can also use the isPerson() helper inside a Rut instance.

isCompany

Checks if the RUT is over or equal 50.000.000, which are usually used for companies.

You can also use the isCompany() helper inside a Rut instance.

isEqual

Returns if two or more RUTs are equal, independently of how these are formatted, even if these are invalid.

You can also use the isEqual() helper inside a Rut instance.

getVd

Returns the verification digit for a given number.

unpack

Takes an array and, if only one item was issued containing an array, this item contents will be returned to the application.

Callbacks

For convenience, you can register callbacks to be executed after you use many() and manyOrThrow(). For example, you may want to use this to manipulate how the Ruts are handled before these are returned.

You can register a callback using the after() static method. The callable receives the array of RUTs as the come, and must return the result.

If you register multiple callbacks, these will be executed in the order they were registered.

Serialization

Sometimes you may want to store your Rut instance somewhere, or serialize it to JSON, or a string. With this package you're covered from all angles.

Serialize / Unserialize

By default, a Rut instance is serialized as a raw string, which is latter reconstructed quickly by just dividing the string into the number and verification digit:

This is pretty much optimized for low storage and quick instancing. The rest will depend on your serialization engine.

String

There are multiple ways to set the format to use with a Rut instance when is serialized as a string:

• Strict: Default option. Serializes with a thousand separator and hyphen.
• Basic: No thousand separator, only the hyphen.
• Raw: No thousand separator nor hyphen.

These can be set globally using the static methods, and as a per-instance basis using the dynamic calls available in the instance itself.

JSON

By default, when casting to JSON, the result is a string. You can change this to be an array of the number and verification digit using static methods for all instances, or a per-instance case:

Global helper

In version 2.0, all helpers have been killed and now you have only one called rut(). It works as a proxy for Rut::make, but accepts a default in case of invalid ruts. If no parameter is issued, an instance of the Rut Generator is returned.

License

This package is licenced by the MIT License.