Nepali Date Laravel Package

Product Decisions This Supports

• Market-entry scoping for Nepal. Any product touching Nepali users needs Bikram Sambat dates on invoices, receipts, tax filings (IRD), payroll, school admissions, land records, and government forms. This package answers "how much work is BS support?" before you commit a quarter to it.
• Build vs. buy on calendar data. BS↔AD conversion is not an algorithm problem — it's a lookup-table problem. BS month lengths are irregular and change year to year, so the real asset is a maintained data table plus formatting. This package lets you buy that data instead of owning it.
• Depth-of-localization decision. It separates a cosmetic Nepal launch (render an extra date string next to the AD date) from a deep one (dual-calendar storage, BS date pickers, BS-aligned reporting periods, Shrawan 1 fiscal-year boundaries, Asia/Kathmandu time at UTC+5:45). That distinction drives the roadmap and the staffing estimate.
• Feature candidates it unblocks: BS/AD date pickers, dual-calendar display on documents, DOB capture and validation, fiscal-year reporting aligned to the Nepali calendar, BS-dated notifications/SMS, HR leave calendars, and billing cycles that follow BS months.
• Vendor/roadmap risk input. With 5 stars, 0 dependents, and a single maintainer, the decision this informs is less "adopt or not" and more "adopt behind an abstraction, or budget for a fork."

When to Consider This Package

Consider it when:

• You are on PHP/Laravel, shipping to Nepali users, and need three things only: AD↔BS conversion, BS formatting, and framework glue.
• The BS surface is bounded — display, capture, and date arithmetic on a known year range — not a full calendaring engine.
• You can absorb a low-adoption dependency: pin the version, vendor or fork the calendar data, and wrap it behind your own interface so a swap is a day of work, not a sprint.

Validate before you commit (these are the real diligence questions):

• Supported year range, and how month-length data gets corrected when it does.
• Whether it handles Asia/Kathmandu's +5:45 offset and timezone-aware instants, or only naive dates.
• Laravel and Carbon version compatibility; whether it plays with CarbonImmutable and framework validation rules.
• Test coverage on year boundaries, leap-month edge cases, and historical dates — ask for a golden-file comparison against an official Nepal calendar source.

Look elsewhere when:

• BS dates are load-bearing — payroll, tax, statutory filings. A single-maintainer package with no dependents and no field validation is not the right foundation for a compliance surface; buy from a vendor or build a thin internal service over a vetted dataset.
• You need recurring events in BS, multi-language calendars, or high-volume conversion throughput.
• You are not on PHP. The domain need is real; this artifact is not the answer.
• Procurement requires an active maintainer community, security review, or an SLA. Five stars and zero dependents won't clear that bar.

How to Pitch It (Stakeholders)

To executives: Nepal is a real market with a real localization gate — users and regulators expect Bikram Sambat dates, and BS months don't map cleanly onto the Gregorian calendar. This package is a cheap way to size that work: MIT-licensed, actively released, and it covers conversion, formatting, and Laravel integration. The risk isn't cost, it's maintenance — it's a small, single-maintainer project. Recommendation: fund a short spike, not a commitment, and keep an exit path.

To engineering: Treat it as an adapter, not a dependency. Isolate it behind an internal DateConverter interface so the library is swappable, pin the version, vendor the calendar data table so upstream drift can't silently change historical dates, and build golden-file tests against an authoritative Nepal calendar source before it touches anything financial. Recent releases are encouraging; the missing signal is field usage, so our own test suite has to do that job.