Download the PHP package laragear/rut without Composer

Rut

Tools to parse, validate and generate Chilean RUT in Laravel.

Keep this package free

Your support allows me to keep this package free, up-to-date and maintainable. Alternatively, you can spread the word on social media.

Requirements

• Laravel 11 or later

Installation

Fire up Composer and require it into your project:

Creating a RUT

To create a RUT from an already valid source, instance a Rut object with the numbers and the verification digit, separately.

Otherwise, you may want to use parse() to create it from a single string. It will try its best to create a RUT instance from what is given, or throw an InvalidRutException if the string doesn't have the necessary characters to create a RUT.

RUT Types

Officially, there are six types of RUT. To differentiate between them, you have access to is...() methods.

Additionally, you have access to the isPermanent() method, which checks if the RUT is below 100.000.000.

[!IMPORTANT]

This package considers RUT as valid when between 100.000 and 200.000.000, inclusive. Most (if not all) people using 99.999 or lower RUT numbers are deceased.

Generating RUTs

The package comes with a convenient RUT Generator facade to create thousands or millions of random RUTs using fluid methods.

The make() method generates a Collection of 15 Rut by default, but you can set any number you want. Alternatively, you can use makeOne() to create just one random Rut.

You can use as...() to make a given type of RUTs.

If you plan to create several millions of RUTs, there is a high change you will come with duplicates. To avoid collisions, use the unique() method in exchange for a small performance hit to remove duplicates.

Serialization

By default, all Rut instances are serialized into text using a strict format, which includes thousands separators and hyphen to separate the RUT number from the RUT verification digit.

`

There are three formats available to transform a RUT into a string: strict, basic and raw.

You may change which formatting type to serialize the RUT using one of the convenience methods.

Formatting a RUT can also be done programmatically through the format() method, which accepts a Laragear\Rut\RutFormat enum. If no argument is passed, it will use the default format.

[!TIP]

You can change the global format in the configuration.

Validating a RUT

You should use the included Validation Rules to validate RUTs in your input.

Otherwise, you can manually validate a RUT using isValid() or isInvalid() to check if it's mathematically valid or not, respectively.

Using the validate() method will throw a InvalidRutException if it's invalid.

You can also validate RUT strings directly, or an already separated RUT, by using check() method.

Validation rules

All validation rules messages can be translated. You can add your own translation to these rules by publishing the translation files:

rut rule

This checks if the RUT being passed is a valid RUT string. This automatically cleans the RUT from anything except numbers and the verification digit. Only then it checks if the resulting RUT is mathematically valid.

This may come handy in situations when the user presses a wrong button into an RUT input, so there is no need to ask the user to properly format a RUT. Afterwards, you can use the Request RUT helpers to retrieve the RUT from the Request input or query.

The rule also accepts an array of RUTs. In that case, rut will succeed if all the RUTs are valid. This may come in handy when a user is registering a lot of people into your application.

rut_strict rule

This works the same as rut, but it will validate RUTs that are also using the Strict RUT format: with a thousand separator and a hyphen before the Validation Digit.

It will return false even if there is one misplaced character or an invalid one.

This rule also accepts an array of RUTs. In that case, rut_strict will return true if all the RUTs are properly formatted and valid.

rut_exists database rule

Instead of using Laravel's exists, you can use rut_exists in case your database has separated columns for the RUT Number and Verification Digit.

For this to work you need to set the table to look for, the RUT number column and RUT verification digit column, otherwise the rule will guess the column names by the attribute key and appending _num and _vd, respectively.

This rule automatically validates the RUT before doing the query.

Since this also checks if the RUT is valid (not strict), it will fail if it's not, or the RUT doesn't exist in the database.

To customize the query, you can use the Rule class of Laravel with the method rutExists. Note that you can input the number and verification digit columns, or both, if you don't want to let the rule guess them, as it may incorrectly guess when using a wildcard.

[!TIP]

Database rules will normalize the verification digit as uppercase in the database for search queries.

num_exists database rule

This validation rule checks if only the number of the RUT exists, without taking into account the verification digit. This is handy when the Database has an index in the number of the RUT, thus making this verification blazing fast.

This rule automatically validates the RUT before doing the query.

You can customize the underlying query using the numExists.

rut_unique database rule

This works the same as the rut_exists rule, but instead of checking if the RUT exists in the Database, it will detect if it doesn't. This rule works just like the Laravel's unique rule works.

This rule automatically validates the RUT before doing the query.

You can also exclude a certain ID or records from the Unique validation. For this, you need to use the Rule class.

[!TIP]

Database rules will normalize the verification digit as uppercase in the database for search queries.

[!CAUTION]

You should never pass any user controlled request input into the ignore method. Instead, you should only pass a system generated unique ID such as an auto-incrementing ID or UUID from an Eloquent model instance. Otherwise, your application will be vulnerable to an SQL injection attack.

num_unique database rule

This rule will check only if the number of the RUT doesn't exists already in the database, which is useful for Databases with an index solely on the number of the RUT. This rule also matches the Laravel's unique rule works.

This rule automatically validates the RUT before doing the query.

You can also exclude a certain ID or records from the Unique validation. For this, you need to use the Rule class.

[!TIP]

Database rules will normalize the verification digit in the database for search queries.

[!CAUTION]

You should never pass any user controlled request input into the ignore method. Instead, you should only pass a system generated unique ID such as an auto-incrementing ID or UUID from an Eloquent model instance. Otherwise, your application will be vulnerable to an SQL injection attack.

Database Blueprint helper

If you're creating your database from the ground up, you don't need to manually create the RUT columns. Just use the rut() or rutNullable() helpers in the Blueprint:

[!TIP]

The rutNullable() method creates both Number and Verification Digit columns as nullable.

If you plan to use the RUT Number as an index, which may speed up queries to look for RUTs, you can just index the Number column by fluently adding primary(), index() or unique() depending on your database needs. This is because it has more performance sense to index only the Number rather than the whole RUT.

Request RUT helper

This package includes the rut() macro helper for the Request instance, which retrieves a single RUT from an input or query.

If the input is iterable, like an array or even a Collection instance, you will receive a Collection of Rut instances.

You can also retrieve multiple keys from the Request, which will also return a Collection.

[!IMPORTANT]

It's imperative you validate your input before retrieving RUTs. If there is a malformed RUT, an exception will be thrown.

RUT traits for Eloquent Models

This package contains the HasRut trait to use in Laravel Eloquent Models with tables that have separate RUT Number and RUT Verification digit.

This trait conveniently adds a RUT Scope to a model that has a RUT in its columns, and the rut property which returns a Rut instance.

With that, you will have access to convenient RUT queries shorthands:

[!IMPORTANT]

These RUT queries work over the RUT Number for convenience, as the RUT Verification Digit should be verified only on persistence.

These scopes can be used in your queries easily:

The rut property is dynamically created from the RUT Number and RUT Verification Digit columns, which uses a Cast underneath.

Setting the RUT columns

By convention, the trait uses rut_num and rut_vd as the default columns to retrieve and save the RUT Number and RUT Verification Digit, respectively.

You can easily change it to anything your database is working with for the given Model:

RUT Appended and columns hidden

By default, the rut property is appended, and the underlying columns containing the RUT information are hidden. This enables compatibility with Livewire real-time validation.

To show the underlying RUT columns instead of the RUT string, simply make shouldAppendRut() in the model to return false.

This will effectively return both columns as normal properties.

If you need to make the rut key and the underlying columns visible, you may override the shouldAppendRut() method and return false.

Configuration

This package works flawlessly out of the box, but you may want to change how a Rut is formatted as a string using the global configuration. You can publish it using Artisan:

You will receive the config/rut.php config file like this:

Default RUT Format

By default, RUTs are strictly formatted. This config alters how RUTs are serialized by default as string in your application.

JSON format

For the case of JSON, RUT are cast as a string using the global format when this is null. You can set any format to use when serializing into JSON exclusively.

Alternatively, you can override the configuration by using a callback to create your own JSON format. The callback accepts the Rut instance, and it should return an array or a string to be serialized into JSON. A good place to put this logic is in the boot() method of your AppServiceProvider file.

Verification Digit Case

Since the Verification Digit can be either a single digit or the letter K, it's usually good idea to keep the character case consistent: always work with uppercase or lowercase across all the application.

The Rut instance by default will use uppercase K, but you can change it to lowercase globally by setting this to false. This will affect all Rut instances.

[!TIP]

This doesn't affect database rules, as the verification digit is normalized automatically in the database query.

PhpStorm stubs

For users of PhpStorm, there is a stub file to aid in macro autocompletion for this package. You can publish it using the phpstorm tag:

The file gets published into the .stubs folder of your project. You should point your PhpStorm to these stubs.

Laravel Octane compatibility

• There are no singletons using a stale application instance.
• There are no singletons using a stale config instance.
• There are no singletons using a stale request instance.
• Rut static properties are only written once at boot time from config.

There should be no problems using this package with Laravel Octane.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

License

This specific package version is licensed under the terms of the MIT License, at time of publishing.

Laravel is a Trademark of Taylor Otwell. Copyright © 2011-2025 Laravel LLC.