PHPackages freshwork/chilean-bundle - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Validation & Sanitization](/categories/validation) 4. / 5. freshwork/chilean-bundle ActiveLibrary[Validation & Sanitization](/categories/validation) freshwork/chilean-bundle ======================== A PHP composer package with Chilean validations, common variables, etc. (RUT, IVA, ETC). Ready for Laravel. Grande chile ctm :) v3.0.0(1mo ago)98212.3k↓38.4%11[1 issues](https://github.com/freshworkstudio/ChileanBundle/issues)3MITPHPPHP ^8.2CI passing Since Aug 7Pushed 1mo ago7 watchersCompare [ Source](https://github.com/freshworkstudio/ChileanBundle)[ Packagist](https://packagist.org/packages/freshwork/chilean-bundle)[ RSS](/packages/freshwork-chilean-bundle/feed)WikiDiscussions main Synced 2w ago READMEChangelog (3)Dependencies (7)Versions (22)Used By (3) [![Chilean Bundle — PHP utilities for Chile: RUT, IVA, CLP, Phones, Regions](https://private-user-images.githubusercontent.com/1103494/620359446-8848dc2e-dc62-4ad5-847c-502568b8e0ca.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3ODU1MTgxNTQsIm5iZiI6MTc4NTUxNzg1NCwicGF0aCI6Ii8xMTAzNDk0LzYyMDM1OTQ0Ni04ODQ4ZGMyZS1kYzYyLTRhZDUtODQ3Yy01MDI1NjhiOGUwY2EucG5nP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI2MDczMSUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNjA3MzFUMTcxMDU0WiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9ZTJlNWUxNmYyZGM5OTc2YTZlYWZlMTAyYTVjMDQwYzhkY2U4ZDdkMWViZTJlOTI5NTE0ZTc2NGE5ZWU5OWJiYiZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QmcmVzcG9uc2UtY29udGVudC10eXBlPWltYWdlJTJGcG5nIn0.zfDNMjI1lS8T0jXhJnuQYgyTDLG5pYz0V_pVxONb9rI)](https://private-user-images.githubusercontent.com/1103494/620359446-8848dc2e-dc62-4ad5-847c-502568b8e0ca.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3ODU1MTgxNTQsIm5iZiI6MTc4NTUxNzg1NCwicGF0aCI6Ii8xMTAzNDk0LzYyMDM1OTQ0Ni04ODQ4ZGMyZS1kYzYyLTRhZDUtODQ3Yy01MDI1NjhiOGUwY2EucG5nP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI2MDczMSUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNjA3MzFUMTcxMDU0WiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9ZTJlNWUxNmYyZGM5OTc2YTZlYWZlMTAyYTVjMDQwYzhkY2U4ZDdkMWViZTJlOTI5NTE0ZTc2NGE5ZWU5OWJiYiZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QmcmVzcG9uc2UtY29udGVudC10eXBlPWltYWdlJTJGcG5nIn0.zfDNMjI1lS8T0jXhJnuQYgyTDLG5pYz0V_pVxONb9rI) Chilean Bundle ============== [](#chilean-bundle) [![Tests](https://github.com/freshworkstudio/ChileanBundle/actions/workflows/run-tests.yml/badge.svg)](https://github.com/freshworkstudio/ChileanBundle/actions/workflows/run-tests.yml)[![Latest Version on Packagist](https://camo.githubusercontent.com/c0451b3fca996af0f3eeef33e253c157c2647ca04113602d2a46e6b3b4fa0aec/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6672657368776f726b2f6368696c65616e2d62756e646c652e737667)](https://packagist.org/packages/freshwork/chilean-bundle)[![Total Downloads](https://camo.githubusercontent.com/cc1cd138c5ee5411240385b0401a539a4abeba607f530a21b7279c0b307a8eb8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6672657368776f726b2f6368696c65616e2d62756e646c652e737667)](https://packagist.org/packages/freshwork/chilean-bundle)[![License](https://camo.githubusercontent.com/d4697372e4ce2c0a7087164d6c099bc8e911f195e41827e251635048d8728a75/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6672657368776f726b2f6368696c65616e2d62756e646c652e737667)](LICENSE) A PHP composer package with Chilean validations, formatters and utilities. Viva Chile Mier... ``` use Freshwork\ChileanBundle\{Rut, Iva, Clp, Phone, Region}; Rut::check('12.345.678-5'); // true Iva::add(10000); // 11900 Clp::format(1234567); // '$1.234.567' Phone::check('+56 9 8765 4321'); // true Region::Metropolitana->capital(); // 'Santiago' ``` This package includes --------------------- [](#this-package-includes) FeatureClassDescription**R.U.T.**`Rut`Validation, formatting, parsing and generation of Chilean RUTs**I.V.A.**`Iva`Chilean VAT (19%) constants and calculations**Pesos (CLP)**`Clp`Format and parse Chilean peso amounts**Phones**`Phone`Validate, normalize and format Chilean phone numbers**Regions**`Region`Enum with the 16 regions of Chile (names, numerals, capitals)**Comunas**`Comuna`Enum with the 346 comunas backed by their official CUT code**Laravel**—`cl_rut` / `cl_phone` validation rules, Rule object, Facade and Eloquent castRequirements ------------ [](#requirements) - PHP 8.2+ - Laravel 10+ (optional, only for the Laravel integration — the test suite runs against Laravel 11 and 12) > Using PHP 5.x/7.x or an older Laravel? Stick with `freshwork/chilean-bundle:^2.2` — the legacy 2.x series supports PHP 5.4+. Installation ------------ [](#installation) ``` composer require freshwork/chilean-bundle ``` If you're using Laravel, the package supports Auto-Discovery, so you're done. If you're not using Laravel, just use the classes directly — they have no dependencies. --- R.U.T. ------ [](#rut) ### The Basics [](#the-basics) ``` use Freshwork\ChileanBundle\Rut; Rut::parse('11.111.111-1')->validate(); // true Rut::check('11.111.111-1'); // true (never throws) $rut = new Rut('11.111.111', '1'); $rut->validate(); // true ``` ### `parse()` [](#parse) The recommended way of creating a `Rut`. It automatically separates the verification number (dígito verificador) from the rest of the number, and escapes dots, dashes and spaces. ``` Rut::parse('11.111.111-1')->validate(); // true Rut::parse('12.345.678-5')->validate(); // true Rut::parse('123456785')->validate(); // true Rut::parse('1.23.45.6.7.8-5')->validate(); // true ``` ### `check()` [](#check) The quickest way to know if a string is a valid RUT. It never throws exceptions. ``` Rut::check('12.345.678-5'); // true Rut::check('12.345.678-9'); // false Rut::check('not-a-rut'); // false ``` ### `validate()` / `isValid()` [](#validate--isvalid) `validate()` is an alias of `isValid()`. If the RUT is well-formed but the verification number is wrong, it returns `false`: ``` Rut::parse('12.345.678-9')->validate(); // false ``` If the RUT has an invalid **format**, it throws `Freshwork\ChileanBundle\Exceptions\InvalidFormatException`: ``` Rut::parse('12.3k5.6L8-9')->validate(); // throws InvalidFormatException Rut::set('12.345.678')->validate(); // throws: no verification number set ``` #### Quiet mode [](#quiet-mode) Use `quiet()` to return `false` instead of throwing. Re-enable exceptions with `use_exceptions()`. ``` Rut::parse('12.3k5.6L8-9')->quiet()->validate(); // false, no exception ``` ### `format()` & `normalize()` [](#format--normalize) ``` use Freshwork\ChileanBundle\RutFormat; Rut::parse('123456785')->format(); // '12.345.678-5' Rut::parse('123456785')->format(RutFormat::Complete); // '12.345.678-5' Rut::parse('123456785')->format(RutFormat::WithDash); // '12345678-5' Rut::parse('123456785')->format(RutFormat::Escaped); // '123456785' // normalize() is an alias of format(RutFormat::Escaped) — ideal for storing in a database Rut::parse('12.345.678-5')->normalize(); // '123456785' ``` The legacy `Rut::FORMAT_*` int constants still work. On an invalid RUT, `format()` throws an `InvalidFormatException` (or returns `false` in quiet mode). ### `calculateVerificationNumber()` & `fix()` [](#calculateverificationnumber--fix) ``` Rut::set('12.345.678')->calculateVerificationNumber(); // '5' Rut::parse('12.345.678-9')->fix()->format(); // '12.345.678-5' (vn corrected) Rut::set('12345678')->fix()->validate(); // true ``` ### `random()` [](#random) Generates a random valid RUT. Useful for seeders, factories and tests. ``` Rut::random(); // e.g. 17.062.139-5 Rut::random(5000000, 30000000); // custom range ``` ### Getters, setters & serialization [](#getters-setters--serialization) ``` Rut::parse('12.345.678-5')->number(); // '12345678' Rut::parse('12.345.678-5')->vn(); // '5' Rut::parse('12.345.678-5')->toArray(); // ['12345678', '5'] (string) Rut::parse('123456785'); // '12.345.678-5' (Stringable) json_encode(['rut' => Rut::parse('123456785')]); // {"rut":"12.345.678-5"} (JsonSerializable) ``` --- I.V.A. ------ [](#iva) Chilean VAT helpers. All amounts are rounded to the nearest peso (CLP has no decimals). ``` use Freshwork\ChileanBundle\Iva; Iva::RATE; // 0.19 Iva::PERCENTAGE; // 19 Iva::of(10000); // 1900 — IVA for a net amount Iva::add(10000); // 11900 — gross (net + IVA) Iva::net(11900); // 10000 — net from a gross amount Iva::fromGross(11900); // 1900 — IVA contained in a gross amount ``` --- Pesos (CLP) ----------- [](#pesos-clp) ``` use Freshwork\ChileanBundle\Clp; Clp::format(1234567); // '$1.234.567' Clp::format(-1234567); // '-$1.234.567' Clp::format(1234567, symbol: false); // '1.234.567' Clp::parse('$1.234.567'); // 1234567 Clp::parse('-$1.234'); // -1234 ``` --- Phones ------ [](#phones) Chilean phone numbers have 9 national digits: mobiles start with `9`, landlines with `2`–`7` (area code included). ``` use Freshwork\ChileanBundle\Phone; Phone::check('+56 9 8765 4321'); // true Phone::check('09-8765 4321'); // true Phone::check('12345678'); // false $phone = Phone::parse('09 8765 4321'); $phone->isValid(); // true $phone->isMobile(); // true $phone->isLandline(); // false $phone->number(); // '987654321' (normalized national number) $phone->e164(); // '+56987654321' $phone->format(); // '+56 9 8765 4321' (string) $phone; // '+56 9 8765 4321' ``` --- Regions ------- [](#regions) An enum with the 16 regions of Chile, backed by their official region number. ``` use Freshwork\ChileanBundle\Region; Region::Metropolitana->value; // 13 Region::Metropolitana->officialName(); // 'Región Metropolitana de Santiago' Region::Metropolitana->romanNumeral(); // 'RM' Region::Metropolitana->capital(); // 'Santiago' Region::from(9); // Region::Araucania Region::cases(); // all 16 regions Region::northToSouth(); // regions in geographic order Region::options(); // [15 => 'Región de Arica y Parinacota', ...] ready for selects ``` --- Comunas ------- [](#comunas) An enum with the 346 comunas of Chile, backed by their official territorial code (Código Único Territorial — CUT, [SUBDERE](https://www.subdere.gov.cl)). The first digits of the code are the region number, so every comuna knows its region. ``` use Freshwork\ChileanBundle\Comuna; use Freshwork\ChileanBundle\Region; Comuna::Santiago->value; // 13101 Comuna::Santiago->code(); // '13101' (zero-padded official format, e.g. '01101' for Iquique) Comuna::Nunoa->officialName(); // 'Ñuñoa' Comuna::Nunoa->region(); // Region::Metropolitana Comuna::from(16101); // Comuna::Chillan Comuna::fromName('ñuñoa'); // Comuna::Nunoa (case and accent insensitive) Comuna::inRegion(Region::Nuble); // the 21 comunas of Ñuble Region::Metropolitana->comunas(); // the 52 comunas of the RM Comuna::options(); // [1101 => 'Iquique', ...] ready for selects Comuna::options(Region::Tarapaca); // only Tarapacá's comunas ``` --- Laravel ------- [](#laravel) ### Validation rules [](#validation-rules) ``` $request->validate([ 'rut' => 'required|cl_rut', 'phone' => 'required|cl_phone', ]); ``` Or with a dedicated Rule object: ``` use Freshwork\ChileanBundle\Laravel\Rules\Rut; $request->validate([ 'rut' => ['required', new Rut], ]); ``` Error messages are translated (English and Spanish included). Publish and customize them with: ``` php artisan vendor:publish --tag=chilean-bundle-lang ``` ### Eloquent cast [](#eloquent-cast) Expose a model attribute as a `Rut` object and control how it's stored: ``` use Freshwork\ChileanBundle\Laravel\Casts\RutCast; class Client extends Model { protected function casts(): array { return [ 'rut' => RutCast::class, // stored escaped: 123456785 (recommended) // 'rut' => RutCast::class.':dash', // stored as: 12345678-5 // 'rut' => RutCast::class.':complete', // stored as: 12.345.678-5 ]; } } $client->rut = '12.345.678-5'; $client->rut->format(); // '12.345.678-5' ``` ### Facade [](#facade) ``` use Freshwork\ChileanBundle\Facades\Rut; Rut::check('12.345.678-5'); // true ``` --- Upgrading from 2.x ------------------ [](#upgrading-from-2x) v3.0 is a major release ([full release notes](https://github.com/freshworkstudio/ChileanBundle/releases/tag/v3.0.0)). The core API is unchanged — `parse()`, `set()`, `validate()`, `isValid()`, `fix()`, `join()`, `toArray()` all work exactly as before — but there are a few breaking changes to review. ### Still on PHP 5.x or 7.x? Stay on 2.x [](#still-on-php-5x-or-7x-stay-on-2x) The **legacy 2.x series remains available and compatible with PHP 5.4+** (and older Laravel versions). It's not going anywhere — if you can't upgrade PHP yet, just pin the previous major: ``` composer require freshwork/chilean-bundle:^2.2 ``` ### 1. PHP 8.2+ (and Laravel 10+) required [](#1-php-82-and-laravel-10-required) v3 uses modern PHP features (enums, strict types, first-class match expressions). The Laravel integration (validation rules, cast, facade) relies on contracts introduced in Laravel 10; the test suite runs against Laravel 11 and 12. ### 2. `format()` and `normalize()` now throw on invalid RUTs [](#2-format-and-normalize-now-throw-on-invalid-ruts) In 2.x they silently returned `false` even with exceptions enabled — which also made `(string) $rut` fatal on PHP 8. Now they behave like `validate()`: ``` // 2.x Rut::parse('123-1')->format(); // false (silently) // 3.x Rut::parse('123-1')->format(); // throws InvalidFormatException Rut::parse('123-1')->quiet()->format(); // false — same behavior as 2.x ``` If you relied on the silent `false`, add `->quiet()` to keep the old behavior. ### 3. `vnSeparator()` now takes a `string` [](#3-vnseparator-now-takes-a-string) The 2.x type hint was `?array` by mistake, which made the method unusable (passing a string threw a `TypeError`). Now it works as documented: ``` Rut::set('12345678', '9')->vnSeparator('·')->join(); // '12345678·9' ``` ### 4. Deprecations (still working, removed in a future major) [](#4-deprecations-still-working-removed-in-a-future-major) DeprecatedUse instead`scape_chars()``escapeChars()``Freshwork\ChileanBundle\Laravel\Facades\Rut``Freshwork\ChileanBundle\Facades\Rut`### What's new in v3 [](#whats-new-in-v3) Besides the modernized [`Rut`](#rut) (with `Rut::check()`, `Rut::random()`, `RutFormat` enum, `Stringable`/`JsonSerializable`), v3 adds [`Iva`](#iva), [`Clp`](#pesos-clp), [`Phone`](#phones), [`Region`](#regions) and [`Comuna`](#comunas), plus the [`cl_rut` / `cl_phone` validation rules and the `Rules\Rut` rule object](#validation-rules) and the [`RutCast` Eloquent cast](#eloquent-cast). --- Testing & code quality -------------------------- [](#testing--code-quality) ``` composer test # Run the test suite (Pest) composer lint # Check code style (Pint) composer analyse # Static analysis (PHPStan) ``` --- Licencia y Postalware --------------------- [](#licencia-y-postalware) Puedes usar este paquete gratuitamente sin ninguna restricción, aunque como está de moda, implementamos una licencia 'Postalware'. Si usas este paquete en producción y te gusta como funciona, agradeceríamos bastante si nos envías una postal de tu ciudad/comuna, una nota de agradecimiento o un súper8. Dirección: Gonzalo De Spirito Providencia 229, Providencia. Chile --- Contributing ------------ [](#contributing) Pull requests are welcome! Please make sure `composer test`, `composer lint` and `composer analyse` pass. You can also contact me at ### Health Score 67 — FairBetter than 99% of packages Maintenance92 Actively maintained with recent releases Popularity49 Moderate usage in the ecosystem Community25 Small or concentrated contributor base Maturity85 Battle-tested with a long release history Bus Factor1 Top contributor holds 86.2% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~229 days Recently: every ~731 days Total 20 Last Release 38d ago Major Versions 0.1.4 → 1.02015-03-03 1.0 → 2.02016-04-14 2.2.0 → v3.0.02026-07-11 PHP version history (2 changes)0.1.0PHP >=5.4.0 v3.0.0PHP ^8.2 ### Community Maintainers ![](https://www.gravatar.com/avatar/954524bc2e96e26c6670b60375e0ed3759db6862e1d2721a074c74f92ef9a070?d=identicon)[gonzunigad](/maintainers/gonzunigad) ![](https://avatars.githubusercontent.com/u/12437201?v=4)[freshwork](/maintainers/freshwork)[@freshwork](https://github.com/freshwork) --- Top Contributors [![gdespirito](https://avatars.githubusercontent.com/u/1103494?v=4)](https://github.com/gdespirito "gdespirito (50 commits)")[![eaguad1337](https://avatars.githubusercontent.com/u/19355144?v=4)](https://github.com/eaguad1337 "eaguad1337 (4 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (2 commits)")[![JoseLuis21](https://avatars.githubusercontent.com/u/7219692?v=4)](https://github.com/JoseLuis21 "JoseLuis21 (2 commits)") --- Tags laravelvalidationrutchiletoolsfreshwork ### Code Quality TestsPest Static AnalysisPHPStan, Rector Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/freshwork-chilean-bundle/health.svg) ``` [![Health](https://phpackages.com/badges/freshwork-chilean-bundle/health.svg)](https://phpackages.com/packages/freshwork-chilean-bundle) ``` ### Alternatives [stuyam/laravel-phone-validator A phone validator for Laravel using the free Twilio phone lookup service. 2862.1k](/packages/stuyam-laravel-phone-validator)[skysplit/laravel5-intl-translation Laravel 5 package for better translation syntax using php-intl extension 10106.7k](/packages/skysplit-laravel5-intl-translation)[pacerit/laravel-polish-validation-rules Simple Polish Validation rules for Laravel and Lumen framework 1454.7k](/packages/pacerit-laravel-polish-validation-rules)[laravel-validation-rules/ip Validate if an ip address is public or private. 1729.7k](/packages/laravel-validation-rules-ip)[cohensive/validation Extra functionality for Laravel 5 Validator. 1413.9k](/packages/cohensive-validation)[fab2s/dt0 Immutable DTOs with bidirectional casting. No framework required. 8x faster than the alternative. 102.6k2](/packages/fab2s-dt0) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)