Chilean Bundle Laravel Package

Product Decisions This Supports

• Chile market entry and checkout readiness: RUT validation (cl_rut, Rules\Rut, RutCast) for signup, checkout, billing profiles, and account updates. Now paired with Phone (E.164 normalization, mobile/landline detection) so the same dependency covers contact-data quality for SMS/WhatsApp verification and delivery, not just tax IDs.
• Address and delivery-market scope: Region and Comuna enums (16 regions, 346 comunas with official CUT codes) make a Chile-specific address model a realistic near-term feature rather than a bespoke data-maintenance project. This is the biggest change to the roadmap conversation: the package now supports shipping/delivery coverage decisions, regional segmentation, and checkout address selects.
• Pricing and tax-display decisions: Iva (RATE, of(), add(), net(), fromGross()) plus Clp formatting lets product standardize how prices are shown and converted gross/net in Chile. This supports decisions about consumer-facing price display (Chilean consumer norms around IVA-inclusive pricing) — but as a display and arithmetic aid, not as a tax authority.
• Build vs. buy: Adopt for commodity localization primitives (RUT, phone, region/comuna, CLP, IVA math). The v3 scope strengthens the buy case: building and maintaining a CUT-coded comuna dataset plus RUT/phone edge cases in-house is now clearly non-strategic engineering. Only build if requirements are unusual or the dependency can't be owned.
• Scope control (still essential): The package is a localization/validation toolkit, not a tax-compliance or e-invoicing solution. Tax calculation policy, SII integration, document emission, filing, and regulatory guarantees remain separate product/legal workstreams. The presence of Iva will tempt stakeholders to assume "tax is handled" — explicitly pre-empt that.
• Platform dependency decision (new): v3 requires PHP 8.2+ and Laravel 10+. Adoption is now gated on a runtime upgrade decision. Teams staying on PHP 5.x/7.x must pin ^2.2, which forks the team onto a legacy series and splits validation behavior across services.
• Upgrade/change-management decision (new): format()/normalize() now throw InvalidFormatException instead of returning false. Any existing caller relying on silent failure changes behavior in production paths. Treat the 2.x → 3.x move as a scheduled change with a code audit, not a patch bump.
• Prioritization input: Still an enabler, not a differentiator — but the blast radius of "enablement" has widened from RUT fields to addresses, phone, and price display. Worth pulling forward if Chile is on the near-term roadmap and any of those three are also blocking conversion or support load.
• Success metrics to track: Form completion rate, invalid-RUT rejection rate, invoice/billing rejection rate, billing-support tickets, time-to-launch for Chile flows — plus new: address-completion rate and comuna-mismatch errors, phone verification/delivery success rate, price-display and rounding discrepancy reports.

When to Consider This Package

• Consider it when: You are building a Laravel 10+/PHP 8.2+ product for Chilean users and need low-cost, MIT-licensed handling of RUT, phone, region/comuna, CLP formatting, and IVA arithmetic in forms, onboarding, billing, and checkout.
• Stronger fit than before for: MVPs and mid-stage Chile localization, because v3 ships declare(strict_types=1), PHPStan level 8, 105 tests / 952 assertions, a PHP 8.2–8.5 CI matrix, Laravel validation rules with es/en translations, an Eloquent cast, and Dependabot. That is materially better engineering hygiene than the prior assessment reflected.
• Adoption criteria: PHP 8.2+/Laravel 10+ runtime, ability to pin a version, integration tests around accepted/rejected values (including the new exception-throwing behavior), and wrapping behind an internal interface (validator, address provider, price formatter) so it can be swapped or forked.
• Data-governance criterion (new): Comuna/region data is generated from an external source (SUBDERE spreadsheet). Assign an owner to re-generate or verify that dataset on a schedule, and confirm you're comfortable with the CUT codes as your address key.
• Runtime gating: If you cannot move to PHP 8.2+, you are on ^2.2 — a legacy series with no Iva/Clp/Phone/Region/Comuna, and different error semantics. Decide deliberately rather than by default.
• Look elsewhere when: You need official tax calculation, electronic invoicing, SII integration, regulatory certification, enterprise SLAs, or a vendor-backed compliance guarantee. Iva and Clp do not change this.
• Look elsewhere or build in-house when: Validation rules must be contractually guaranteed by a vendor, security review rejects small community packages, or you need multi-country tax localization or a maintained tax engine. Also when your requirements demand full Chilean address normalization/geocoding beyond static region/comuna lookup.
• Adoption-signal caveat: The release improves internal quality but does not by itself prove external adoption (the prior 99-star/zero-dependents signal is unaddressed by release notes). Keep the fork/vendor fallback and avoid treating it as mission-critical infrastructure without an exit plan.

How to Pitch It (Stakeholders)

• For executives: This is still a small, MIT-licensed utility, but v3 is a real capability upgrade: it now covers Chilean tax-ID validation, phone numbers, the full region/comuna address structure, and peso/VAT formatting and arithmetic. It can accelerate Chile launch work across signup, checkout, billing, and delivery — cheaply and without strategic lock-in. It is not a compliance platform and does not replace legal/tax review.
• For engineering: v3.0.0 is a breaking major: PHP 8.2+ and Laravel 10+ required; format()/normalize() throw InvalidFormatException outside quiet() mode; vnSeparator() signature fixed. Pin the version, audit existing call sites for the new exception behavior, add tests, wire the new cl_rut/cl_phone rules and RutCast, and keep address/comuna data refresh owned. Wrap in adapters (validator, address provider, price formatter) so the dependency stays replaceable. Teams on older PHP stay pinned to ^2.2 — track that as tech debt.
• For product: Beyond RUT fields, this unblocks Chile-specific address selects, phone capture/normalization, and consistent CLP/IVA price display — so it now touches checkout conversion, delivery coverage, and pricing presentation, not just form validation. Measure conversion, address-completion, phone-deliverability, and invoice-error impact. Keep scope on localization primitives; tax policy, filing, and SII stay outside.
• Risk framing: Quality signals improved (typed code, static analysis, real test suite, active CI, Dependabot) which lowers maintenance risk; external adoption evidence and vendor backing are still absent, and the major version requires migration work. Mitigate with source review, version pinning, internal tests, an adapter boundary, and a fork/vendor fallback. Approve a time-boxed upgrade spike plus an in-house fallback so the Chile roadmap isn't blocked by a single small dependency or a runtime upgrade.