Laravel Chile

Thoughtful tools for Chilean applications.

Strict RUT values, an offline official CUT catalog with native territory enums, and exact CLP/IVA arithmetic, with Laravel validation rules and Eloquent casts. Small immutable domain objects, explicit failures, and no runtime HTTP.

Installation

Install the 0.1 release line from Packagist in a compatible Laravel application:

composer require "geolize-studio/laravel-chile:^0.1"

0.1.0 is the first public release. During 0.x, APIs may change in a minor release; the ^0.1 constraint stays below 0.2.0. Review the changelog before upgrading and commit your application's Composer lock file. No custom Composer repository is required.

For package development from a source checkout:

composer install
composer check
composer test:automation
php examples/quickstart.php

Quickstart

use GeolizeStudio\Chile\Clp;
use GeolizeStudio\Chile\Comuna;
use GeolizeStudio\Chile\Iva;
use GeolizeStudio\Chile\RoundingMode;
use GeolizeStudio\Chile\Rut;
use GeolizeStudio\Chile\Territory;

$rut = Rut::parse('12.345.678-5');
$rut->toString(); // '12345678-5'
$rut->format();   // '12.345.678-5'
Rut::tryParse('12.345.678-9'); // null: incorrect DV

$territory = app(Territory::class); // Automatically registered, lazily loaded.
$territory->comuna('01101')->name; // 'Iquique'; CUT codes stay strings.
$place = $territory->resolveComuna('Ñuñoa');
$place->match?->code; // '13120'; inspect status before accepting uncertain input.

Comuna::Nunoa->value; // '13120'
Comuna::Nunoa->label(); // 'Ñuñoa'
Comuna::Nunoa->province(); // Province::Santiago
Comuna::Nunoa->region(); // Region::Metropolitana

$price = Iva::standard()->fromNet(
    Clp::fromPesos(10_000),
    RoundingMode::HalfAwayFromZero,
);
$price->tax->pesos();   // 1900
$price->gross->pesos(); // 11900
Clp::tryParse('1.234,56'); // null: fractional pesos are rejected.

The executable quickstart asserts these results. Outside Laravel, use Territory::loadDefault() and reuse the returned instance. No configuration publishing, database migration, or facade is required.

Laravel integration

use GeolizeStudio\Chile\{Clp, Comuna, Iva, Region, Rut};
use GeolizeStudio\Chile\Laravel\Rules\ClpRule;
use GeolizeStudio\Chile\Laravel\Rules\RutRule;
use Illuminate\Validation\Rule;

// Request validation:
$rules = [
    'rut' => ['nullable', new RutRule],
    'amount' => ['required', new ClpRule],
    'comuna_code' => ['required', 'string', Rule::enum(Comuna::class)],
];

// Return these entries from an Eloquent model's casts() method:
$casts = [
    'rut' => Rut::class,
    'amount' => Clp::class,
    'iva_rate' => Iva::class,
    'comuna_code' => Comuna::class,
];

// CUT-to-label pairs for selects:
Comuna::options(region: Region::Metropolitana);

Use string columns for RUT and CUT, a signed BIGINT for pesos, and a JSON column for IVA's exact ratio: {"numerator":19,"denominator":100}. Rut, Clp, and Iva work directly as casts; territory enums use Laravel's built-in enum casting. Explicit RutCast, ClpCast, and IvaCast classes are also available.

Casts preserve null and reject malformed writes and historical values. Reading a legacy presentation does not silently rewrite it on the next save. An IVA rate does not determine tax applicability, and separate territory casts do not validate their parent relationship. See the Eloquent guide for schema examples, serialization, and failure behavior, and territory enums for hierarchy helpers and select options.

Contracts and limits

Territory ships the hash-pinned SUBDERE CUT_2018_v04 snapshot: 16 regions, 56 provinces, and 346 comunas. Official names and codes are retained, with source and legal references in the manifest. The final territorial review accepted its CUT/hierarchy scope after checking the legal record and comparing official INE/DPA products. Differences in official presentation names are documented; the package does not supply boundary geometry. Source observations can open draft review PRs; they never silently adopt data, merge changes, or publish releases.

Compatibility and verification

Requires 64-bit PHP 8.3+, intl, mbstring, and Laravel/Illuminate 12.24+ or 13. The local and GitHub-hosted matrices passed all 12 PHP 8.3–8.5 / Laravel 12–13 combinations with minimum eligible and current dependencies, plus all six clean production-consumer combinations. See verification evidence for exact revisions, versions, and the scope of each check.

Documentation

• RUT grammar, errors, and integration
• Territorial catalog, resolution, and maintenance
• CLP, IVA, rounding, and overflow
• Native territory enums and select options
• Eloquent casts, schemas, and serialization
• Developer experience
• Engineering references and adoption decisions
• Agent discovery and adoption
• Verification evidence and release checklist
• Contributing, changelog, and security
• Artwork references

Coding agents

Maintainers: read AGENTS.md. Consumers: use the versioned skill and Boost guideline. Resources follow Laravel Boost's third-party package layout. Installation and update were exercised with Boost 2.10.4 in a disposable Codex consumer; see the evidence.

The skill can also be installed deliberately in a client's documented skill location. Composer does not install it globally or change agent settings. This repository's .agents/skills/chile-development alias points to the canonical bundled resource. llms.txt is an optional navigation index, not a guarantee of indexing or recommendation.

Language and license

Documentation, code, errors, examples, and agent guidance are English. Chilean terminology and official names retain their correct spelling. Code is MIT licensed; source-document and artwork terms are described separately in their provenance documents.