Nepali Date Laravel Package

Technical Evaluation

Architecture fit. Unchanged and still favorable. The package remains a small, dependency-light, pure-PHP library solving a single bounded problem: Bikram Sambat (BS) ↔ Gregorian (AD) conversion, formatting, and Laravel glue. No I/O, no network calls, no persistence, no domain opinion — it can sit entirely at the presentation/input boundary behind an anti-corruption layer. The critical architectural decision is still where, not whether: store canonical timestamps in UTC/AD in the database and convert only at the edges (form rendering, request validation, API resource serialization, PDF/report generation). Persisting BS strings as the system of record creates sorting, indexing, range-query, and reporting problems no library can fix. Nepal's fixed UTC+05:45 offset (no DST) removes the worst timezone complexity, but the BS day boundary still does not align with UTC midnight, which must be an explicit, documented rule. Nothing in the v2.0-beta note touches this layer.

Integration feasibility. Still a one-line Composer require plus Laravel auto-discovery, with a likely facade alias, config file, and Blade/validation helpers. Blast radius minimal, reversible. What has changed is the version targeting question. The package moved from v1.0.2 to v2.0-beta, and the release note supplies no changelog body — only a compare link. A major-version bump is a semver declaration that breaking changes exist, but the nature of those changes is undocumented. The plausible (unverified) candidates are exactly the categories that dominate our integration risk: PHP constraint raised, illuminate/support range narrowed, Carbon 2 → 3 migration, dropped Laravel majors, namespace/facade rename, or a reworked conversion core. Because the release is tagged beta, the v2 API surface should be treated as unstable until GA.

Technical risk. Ranked, with the new release factored in:

1. Data correctness at the boundaries — unchanged and still the highest-severity item. BS month lengths vary (29–32 days) and are table-driven. Off-by-one-day errors near year edges, out-of-range years, and silent fallback produce plausible but wrong dates on invoices, contracts, and statutory filings. A major-version rewrite of the conversion core is precisely the change most likely to perturb this, and we have no changelog describing whether the table changed.
2. Version-line ambiguity / beta instability — new. v2.0-beta is by definition not a stable target, and we now have two candidate lines (1.x stable, 2.x beta) with no documented delta. Committing to 2.0-beta means adopting an unstable API; committing to 1.0.2 means adopting a line the maintainer is actively superseding. Both are defensible; neither is free.
3. Maintainer/bus factor — slightly improved signal, not resolved. A major release is evidence the maintainer is actively investing, which is genuinely better than a dormant repo. But it is one data point on a single-maintainer project with negligible community and no commercial backing, and an empty changelog body is weak release hygiene — a documentation-quality signal we should weight when estimating our future support burden.
4. API semantics — mutability vs. immutability, Carbon wrapping vs. reimplementation, arithmetic across irregular BS months, Devanagari numeral formatting/parsing. All now more uncertain than at original assessment time, since a major version is where these get renegotiated.
5. Security — still effectively nil attack surface; no meaningful CVE exposure.

Key questions for the maintainer/spike (updated):

• What actually changed in v2? Please publish the changelog body. The compare link is not a substitute; we cannot size an upgrade or a risk decision from a diff link alone.
• What is the 2.0 GA timeline, and is v1.0.2 still receiving fixes (security, table corrections) during the beta period?
• Which line should a new integrator target today — 1.x stable or 2.0-beta? Does the maintainer consider 1.x feature-frozen?
• Did the supported PHP / Laravel / Carbon matrix change between 1.0.2 and 2.0-beta? Specifically: minimum PHP, illuminate/support range, Carbon 2 vs. 3, dropped Laravel majors.
• Did the BS month-length table or its authoritative source change? If so, do 1.x and 2.x produce identical output for the years we care about?
• What is the exact supported BS year range, and what happens outside it — exception or wrong answer?
• Is the date object immutable? Does it expose typed accessors, comparison, and diffing? Any namespace, facade alias, or method-signature renames in 2.0?
• Are Laravel validation rules (nepali_date, bs_date) and Eloquent casts provided, or only formatting helpers?
• Is the maintainer responsive to PRs, and would a fork be necessary?

Integration Approach

Stack fit. Unchanged. Well-suited to a Laravel monolith or API serving the Nepali market: form input validation, model casts for display, Blade directives for localized output, and API resources for dual-calendar responses. Introduce it as an internal CalendarService contract (or our own NepaliDate value object) with the vendor package as the sole implementation — this remains the single most valuable decision here, and it is now more valuable, because it also insulates us from the 1.x → 2.x migration.

Migration path. Phased, with the version decision made explicitly rather than by default:

1. Version pin decision (same day as spike). Pin to v1.0.2, the line this assessment was written against, and hold there. Do not adopt v2.0-beta for anything in the delivery path. Re-open the decision at 2.0 GA or when the changelog body is published, whichever comes first.
2. Spike (1–2 days): install in a scratch branch, verify the version matrix, and immediately build a golden-file test suite — a few hundred AD↔BS pairs spanning year boundaries, month-end, 29/30/31/32-day months, leap-year interactions, and the UTC+05:45 midnight edge — cross-checked against an authoritative source. Retain this suite; it is the acceptance test for any future 1.x → 2.x move.
3. Pilot module: one low-stakes, read-mostly surface (e.g., displaying a date of birth or a report header in BS alongside AD). Do not start with financial postings or statutory documents.
4. Boundary hardening: validation rules on all BS-accepting forms, the adapter layer, and a written storage policy (AD/UTC canonical, BS presentation-only).
5. Backfill, if applicable: if any existing columns hold BS strings, a one-way migration with a reconciliation report comparing AD-rendered output before and after.
6. Contingency: pre-commit to fork-or-vendor criteria so the decision is not made under incident pressure. Given 1.x may be superseded, also pre-commit to which version we would fork from.

Compatibility. Verify against our current PHP and Laravel LTS targets explicitly. Two distinct checks now: (a) does 1.0.2 conflict with anything in our graph, and (b) does 2.0-beta's constraint graph — which may have moved — force a framework upgrade or block one. Check nesbot/carbon conflicts and facade alias collisions before merging, and confirm neither line pins transitive dependencies in ways that block LTS upgrades. A small library pinning an old illuminate/support is the common and annoying failure mode here, and a major version is where that pin typically moves.

Sequencing. The golden-file suite comes before the pilot, not after. Correctness verification is the gating item; everything else (providers, facades, casts) is trivial. The version-pin decision comes before the spike, because it determines what you are testing.

Operational Impact

Maintenance. Still the dominant operational concern, with a mixed update. Mitigating: an active major release is evidence of a live maintainer, which is better than the dormancy we priced in originally. Aggravating: single maintainer, negligible community, no commercial backing, and a release note that is a bare compare link — which tells us release documentation is not a priority and that we should not expect a clear breaking-change narrative at upgrade time. Assume we may end up owning the code. Budget an internal named owner, mirror the repository, and pin the version explicitly in composer.json (no floating constraints on a 0-dependency, single-maintainer package). Because the conversion data is a static table, treat table updates as a periodic review item — a yearly check against the authoritative calendar source. MIT license makes forking frictionless; state that in the ADR rather than discovering it later.

Support. No commercial support, no SLA, no Stack Overflow corpus. Support burden falls entirely internally: a short runbook covering the storage policy, the out-of-range behavior, the pinned version and the upgrade gate, and the escalation path is worth more than any documentation the package ships — and given the release-note quality, that runbook is now the primary artifact. Ramp-up for a competent Laravel developer is a few hours; the real learning curve is domain knowledge about BS irregularity and which calendar authority the business accepts.

Scaling. A non-issue, unchanged. Conversion is a table lookup and arithmetic — effectively O(1), no memory pressure, no external calls. Only realistic performance note is avoiding per-row instantiation in large exports; bind as a singleton or use static helpers in bulk loops. This package will never be the bottleneck.

Failure modes. In rough order of likelihood and severity:

• Silent wrong dates from table gaps, out-of-range years, or a changed table in 2.x — worst case, because it corrupts downstream records without an error. Mitigation: adapter wraps so out-of-range throws; assertion in the golden-file suite; never mix output from 1.x and 2.x in the same dataset without a reconciliation diff.
• Accidental beta adoption — a developer or dependency resolver pulling v2.0-beta into the tree because the constraint was loose, silently changing date output. Mitigation: explicit exact pin, minimum-stability: stable, and a code-review check on composer.lock diffs for this package.
• Off-by-one-day errors at BS month/year boundaries or near UTC midnight — mitigate with explicit boundary tests and a documented "which day is it" rule.
• Upgrade churn / stranded version line — if 1.x stops receiving fixes while 2.x is in prolonged beta, we sit on an unsupported release. Mitigation: fork contingency plus a mirrored repo, with a defined trigger (e.g., no 1.x fix within 90 days of a known defect).
• Dependency conflict blocking a framework upgrade — mitigate by verifying the constraint graph at adoption time and re-checking each LTS cycle.
• Inconsistent conversion where some code paths call the vendor package directly and others go through the adapter — mitigate by making the adapter the only sanctioned entry point (static analysis rule or review checklist).

Assessment. Adopt conditionally, behind an adapter, pinned to v1.0.2, with a golden-file correctness suite as a hard gate and a documented fork contingency. The v2.0-beta release does not change the architecture or the scaling story — both remain clean — and it modestly improves the maintenance signal by demonstrating an active maintainer. It does, however, add a version-selection decision that did not previously exist and leaves it undocumented: a major bump with no changelog body is a semver claim without evidence, and on a single-maintainer package we should not spend our integration budget reverse-engineering it. Treat 2.0 as not-yet-actionable. Re-open this assessment when the changelog body is published or 2.0 reaches GA, whichever comes first; at that point the golden-file suite is already built and the upgrade is a bounded, testable change rather than a leap.