Chilean Bundle Laravel Package

Technical Evaluation

Assessment updated for v3.0.0 (previously written against the 2.x series).

Architecture fit. Still a leaf-level utility package with no persistence, eventing, or framework coupling beyond an optional service provider — but the surface has grown substantially. v3.0.0 spans four distinct concerns: identity validation (RUT, with a new Rut::check(), Rut::random(), RutFormat enum, Stringable/JsonSerializable), money (Clp formatting/parsing, Iva rate constants and of()/add()/net()/fromGross() calculations), contact data (Phone validation plus E.164 and human-readable normalization), and geography (Region and Comuna enums, 16 regions and 346 comunas backed by official CUT codes). That is no longer "a convenience wrapper around a mod-11 checksum" — it is a small Chilean domain library, and it now reaches into Laravel's request and model layers via cl_rut/cl_phone rules, a Rules\Rut object, RutCast, and en/es translations. Addressable surface is still Chile-only, but within that surface it now plausibly replaces several bespoke helpers, not one.

Integration feasibility. Low friction, with one new gate. The floor moved from >=5.4.0 to PHP 8.2+, with Laravel 10+ for the integration layer (tested against 11 and 12); the 2.x series remains available for older stacks. The more consequential change is behavioral: format()/normalize() now throw InvalidFormatException instead of returning false, with quiet() preserving the old falsy contract. Any existing call site that branches on a falsy return is now an unhandled-exception path. vnSeparator() moving from array to string is a bug fix rather than a real migration burden. The new features are straightforward to consume: enums are self-documenting, options() drops directly into select inputs, and the Laravel rules/cast are idiomatic.

Technical risk. Materially reduced from the prior assessment. The maintainer-activity and correctness questions that dominated the 2.x review are largely answered: full declare(strict_types=1), 105 tests / 952 assertions (Pest 3 + Testbench), PHPStan level 8, Pint, a CI matrix across PHP 8.2–8.5 with a lint job, and Dependabot. That is a credible quality posture for a package of this size. Residual risks:

• Bus factor and adoption. Still a single-maintainer project with effectively no downstream dependents — you would remain an early production adopter. The hobby-scale origin signaled by the 2.x metadata is not fully erased by one good release.
• Major-version cadence. 2.x → 3.0 dropped PHP 5/7 and changed exception semantics. Future majors will likely do the same; plan for it rather than being surprised.
• Enum-baked reference data. Region and Comuna ship as generated PHP enums sourced from a SUBDERE spreadsheet. That answers the provenance question, but it means data updates are now coupled to the release cadence — you cannot patch a commune list without a fork or a new tag. Commune and CUT data changes slowly, but it does change.
• New correctness surface. Iva rounding (to the peso), inclusive/exclusive semantics, and any historical rate handling are new logic with financial consequence and no external validation yet. Phone validation on landline formats and +56 variants is the classic source of false negatives.
• Metadata anomaly. The future-dated release timestamp noted previously is still unexplained; it is no longer load-bearing for the decision now that a documented, tested major release exists, but verify the tag and constraints against Packagist before pinning.

Key questions.

1. Is the published tag and its composer.json constraint set (PHP 8.2+, illuminate/support ^10|^11|^12) confirmed on Packagist, and is the release date metadata sane?
2. What is the documented migration contract for 2.x → 3.0 beyond the README upgrade guide — specifically, is every format()/normalize() call site enumerated, and is quiet() a drop-in for the old behavior?
3. Does RutCast validate on set, and what happens on an invalid value — exception, null, or silent passthrough?
4. Is the Comuna/Region generation script committed, and is there a stated policy for regenerating on SUBDERE updates?
5. What rounding mode and rate history does Iva implement, and is there a documented path if the Chilean rate changes?
6. What is the support window for the 2.x series (security-only? end date?), given it is the only option below PHP 8.2?
7. Are the en/es translation strings complete for cl_rut/cl_phone, and are Phone area-code/landline rules backed by fixtures?

Integration Approach

Stack fit. The fit is now broader than "form validation in a Chilean-facing Laravel app." Realistic coverage: RUT validation in onboarding/KYC and FormRequests; RutCast for Eloquent identity storage; Clp/Iva for checkout totals, price display, and invoice line math; Region/Comuna options() for address and shipping forms; Phone for contact capture and normalization to E.164. That makes it viable for checkout and billing surfaces, not just profile edits. It remains a weak fit for polyglot estates where only one service is Chilean-facing, and it is still not a multi-country i18n strategy — it solves Chile, deliberately.

Migration path. Two distinct paths, and they should not be conflated:

• From 2.x: treat this as a real major. Upgrade the PHP runtime to 8.2 first, read the upgrade guide, then grep every format()/normalize() call site and decide per site between quiet() and catching InvalidFormatException. Fix vnSeparator() callers if any exist. Pin ^3.0 and run the full suite; the exception change is the only likely breakage.
• From homegrown helpers: still wrap the compliance-adjacent pieces (RutValidator, IvaCalculator) behind internal contracts so a future fork or swap is a one-file change. The enums are pure data and can be consumed directly — but pin the version, since their contents ship with releases. Where the package now covers ground your bespoke code handled (CLP formatting, phone normalization, IVA), prefer deleting the bespoke code over maintaining both.

Compatibility. PHP 8.2+ is the hard gate; verify no other pinned dependency caps below it, and run composer why-not against your target Laravel before committing. Conflict risk is minimal — it is a leaf dependency with no transitive baggage — so the concern remains the opposite (a future abandonment), addressed by pinning plus a fork contingency. If you have existing RUT data in mixed formats, decide the RutCast storage format once and backfill deliberately; changing it later is a data migration.

Sequencing.

1. Verify the tag, constraints, and release metadata on Packagist; confirm the CI matrix is green on the tag you intend to pin.
2. Runtime prerequisite: PHP 8.2+ and Laravel 10+ in the target service; otherwise stay on 2.x and defer.
3. Build a fixture set of known-valid and known-invalid RUTs (K, leading zeros, short/long, formatted vs. raw) and assert output parity with your current validator before replacing anything — including exception-vs-false behavior.
4. Wrap Rut and Iva behind internal contracts, add to CI, and migrate call sites. Audit every format()/normalize() caller in the same pass.
5. Roll out Clp and Phone to non-critical surfaces (display formatting, profile edits) and validate Phone against real Chilean contact data before enabling it as a gate.
6. Extend to billing/IVA only after independently verifying rounding and rate semantics against SII expectations — this is the highest-consequence new code.
7. Validate the Comuna CUT codes and region mappings against your existing address data before using them for fiscal or shipping addresses.
8. Adopt RutCast last, with a backfill plan and a rollback path.

Operational Impact

Maintenance. Meaningfully better than the 2.x posture. Strict types, a real test suite, PHPStan level 8, and Dependabot directly address the framework/PHP drift that was the previous top concern — you now have evidence the package tracks Laravel 11/12 and PHP 8.5. The remaining cost is major-version upgrades: 2.x → 3.0 changed the PHP floor and exception semantics, and the next major likely will too. Budget a review at each Laravel/PHP major and keep the fork option live; the code surface is small enough that a fork or in-house reimplementation remains measured in hours to days, which is why the dependency is still low-regret.

Support. Community-only, no vendor, no SLA. The upgrade guide, translations, and test suite reduce the "read the source" tax considerably, and the exception contract is now explicit rather than incidental. Two things to pin down for planning: the support window for the 2.x series (it is your fallback if the PHP 8.2 floor is a blocker) and the maintainer's responsiveness to issues on 3.x. Acceptable for this class of utility; still require a documented fallback if it becomes load-bearing for compliance-critical invoicing.

Scaling. Negligible. Pure computation, no I/O, no network calls, no caching concerns. Enum lookups (fromName(), inRegion()) are in-memory and the 346-case Comuna enum is trivial in footprint. Rut::random() is a test/seed helper, not a production hot path. Not a throughput or latency consideration at any realistic volume.

Failure modes.

• Uncaught InvalidFormatException on upgrade — the highest-probability new failure. Any format()/normalize() call site that assumed false now returns a 500 on malformed user input. Caught only by auditing every call site or exercising the failure path in tests.
• Stale Comuna/Region data — now a dependency-upgrade problem rather than a config change. Blast radius is moderate (shipping/fiscal addresses, dropdowns) and resolution is blocked until a release or a fork.
• IVA rounding or rate defects — financial and compliance exposure; no external validation of the semantics yet.
• Phone false negatives — rejecting valid landline or +56 variants creates contact-capture friction; mitigate with real-world fixtures.
• RutCast storage-format mismatch — silently inconsistent identity records; hard to detect after the fact, easy to prevent with a one-time format decision and backfill.
• False negatives / false positives on RUT — unchanged in nature, but the package now has 952 assertions behind the algorithm, so the residual risk is your integration, not the checksum.
• Abandonment — lower probability than before, still non-zero. Mitigated by the wrapper and fork contingency, not by assuming maintenance continues.
• Framework drift — substantially mitigated by Dependabot and the CI matrix; treat a red or absent CI run on a target tag as a stop signal.

Ramp-up. Low. A mid-level PHP developer integrates RUT and CLP in well under a day; the enums are self-documenting and the Laravel rules and cast are idiomatic. Additional effort worth budgeting: roughly half a day for the 2.x → 3.0 exception audit, and a day for IVA semantics verification plus RutCast migration design if you go near billing. Documentation beyond the README and upgrade guide is likely still thin, so plan for source-reading on edge cases.

Revised recommendation. Move from conditional to adopt, with gates. v3.0.0 resolves the two objections that drove the earlier caution — maintainer activity and test coverage — and it expands the package from a nicety into something that can retire real bespoke code. The gates are narrow and checkable: confirm the PHP 8.2+/Laravel 10+ floor fits the target service, audit the format()/normalize() exception change before upgrading, verify IVA math independently before it touches invoices, and treat the Comuna/Region enum data as a versioned artifact to be revalidated on upgrade. Keep the internal interface and fork readiness — not because the package looks fragile now, but because single-maintainer dependencies earn that posture permanently.