Delivery Calculator Laravel Package

Product Decisions This Supports

• Build vs. buy for calendar logic. Holiday/business-day math looks trivial and never is: regional variants, observed-day shifts, one-off government declarations, and half-day rules. This package offloads that maintenance to a dependency so your team ships product logic instead of an ever-growing calendar table.
• Feature scoping for date-sensitive promises. Anything user-facing that says "3 business days," "next working day," or "excluding holidays" — delivery estimates, SLA countdowns, trial and billing period ends, support response targets — can be quoted honestly rather than approximated with weekday-only math.
• Roadmap expansion into new markets. Because holiday data is region-keyed, launching in an additional country becomes a configuration task rather than an engineering project. This is the strongest argument for putting multi-region date logic on the roadmap earlier than it would otherwise be justifiable.
• Risk reduction on compliance-adjacent surfaces. Payroll cutoffs, interest accrual, statutory filing deadlines, and contract notice periods all depend on correct working-day calculation. Correctness here is a legal/financial exposure question, not a UX nicety.
• The v1.1.3 caching change specifically. Holiday lookups were previously a per-request cost, which quietly discouraged using them in hot paths (list rendering, quote calculations, bulk back-office jobs). Caching removes that performance tax, so PMs can now approve features that evaluate business days per row or per user without budgeting for a caching layer of their own or accepting latency regressions.

When to Consider This Package

Adopt when most of the following hold:

• You are already on Laravel/PHP and want holiday logic expressed idiomatically rather than bolted on as a service call or a hand-maintained config file.
• Date arithmetic appears in more than one feature area — the value scales with reuse, and a single one-off is often better served by a hardcoded array.
• You operate in, or plan to enter, multiple holiday regions, including sub-national ones, where maintaining the data yourself is a recurring annual obligation.
• Your requirements are business-day arithmetic (add/skip working days, "is this a working day," count between dates) rather than exchange trading calendars, lunar calendars, or shift-level scheduling.
• You can tolerate data freshness as a dependency concern: statutory holidays change, occasionally at short notice, so you need a policy for upgrading and a fallback when a jurisdiction is missing or stale.

Look elsewhere when:

• You need holiday data as a first-class API product with guaranteed SLAs and versioned data feeds rather than a library you upgrade on your own cadence.
• Your domain is financial market calendars (trading half-days, settlement schedules) or workforce shift scheduling, which demand far richer semantics than public holidays.
• You are not on Laravel, or you need the same logic in a second runtime — a library-level solution will fragment your source of truth.
• You need guaranteed historical accuracy for years past; verify coverage explicitly before committing, since libraries vary widely here.
• Your only requirement is "is today a holiday in one country." A static config file is cheaper than a dependency.

How to Pitch It (Stakeholders)

For executives: We currently encode holiday and working-day logic ourselves in a few places, which costs us a small amount of engineering time every year and creates real exposure anywhere we promise a date to a customer or a regulator. This package replaces that homegrown logic with a maintained, region-aware implementation. The new caching release removes the main reason we were avoiding it in high-traffic screens, so adopting it is now a low-risk consolidation rather than a performance trade-off. The return is not a headline feature; it is reduced recurring maintenance, cleaner expansion into new markets, and fewer date-related defects in billing, SLAs, and compliance workflows.

For engineering: A Laravel-native holiday calendar with per-region data, providing working-day checks and date arithmetic. v1.1.3 adds caching of holiday lookups, which is the change that makes it safe to call in loops, list rendering, and batch jobs. Key diligence items before adoption: confirm jurisdiction coverage for the regions we actually serve (including historical years), define an upgrade cadence so holiday data stays current, and specify a fallback path when a region or year isn't covered — a silently missing holiday is worse than an obviously missing one. Low integration cost, low coupling; the main long-term obligation is keeping the version current.

Recommendation: Proceed to a short spike — integrate behind a thin internal interface so the dependency is swappable, verify coverage against our served regions, and measure lookup cost in our heaviest date-sensitive path. Treat as an adopt-and-standardize candidate rather than a one-off utility.