Holidays Laravel Package

Product Decisions This Supports

• Feature scoping for anything "business-day aware." Holiday data is the hidden dependency behind delivery estimates, invoice due dates, payroll cutoffs, SLA timers, support staffing, promo calendars, leave/absence workflows, and "next available slot" pickers. This package answers the recurring question — is this date a working day, and what is it called? — without us owning a holiday table.
• Market coverage decisions. Holidays::has() and the country directory give an explicit, checkable coverage matrix. Before committing to a launch market we can ask "do we support its holidays, and at what granularity?" instead of discovering the gap three sprints in.
• Regional granularity as a product tier. Region support (German states, Swiss cantons, Spanish communities, Australian states, etc.) is exactly the kind of detail that separates a demo from a sellable product in EU markets. This lets us price or gate "regional calendars" without new data work.
• Localization without a translation project. Locale-aware holiday names (Holidays::for('be', locale: 'fr')) mean a localized UI with near-zero copy effort — good value per engineering hour.
• Build vs. buy: buy (with a wrapper). The API is trivial; the cost is the data. Maintaining accurate, annually-changing holiday definitions across dozens of countries — including observed-day shifting and Islamic/Chinese/Indian/Nepali calendar tables — is a permanent maintenance tax with no differentiation. MIT licensing plus Composer means near-zero switching cost, so the real decision is "do we wrap it," not "do we marry it."
• Specific leverageable primitives for roadmap items: getUpcoming(n) for notification/reminder features; getInRange() with year/month shorthand for reporting periods; getLongWeekends() for travel, retail, and pricing experiments; isHoliday() for blocking deploys, batch jobs, or outbound comms; HolidayType (national / regional / religious / observed / banked) to let customers filter what counts for them.
• A decision not to make: this is a date calculator, not a compliance system. Payroll, tax, and statutory-leave correctness must remain a policy decision we own and validate, not something we inherit from a community package.

When to Consider This Package

Adopt when:

• The stack is PHP 8.4+ / Laravel and we need holiday awareness in more than one country.
• Coverage checks out for our target markets — verify the countries and regions we actually care about first, since coverage is community-contributed and uneven.
• We need the ergonomics (upcoming, ranges, long weekends, names, isHoliday) and are happy to wrap it behind our own interface.
• We want a fast, cheap spike: composer require spatie/holidays and a snapshot test is an afternoon, not a project.

Look elsewhere or build when:

• Correctness is contractual. Payroll, statutory leave, or anything where a wrong date has legal or financial consequences. There is no SLA here; data is community-maintained via PRs.
• The country or region isn't supported, or is supported but with rules that don't match local law — a real risk with observed-day shifting, which varies by jurisdiction.
• We need far-future or historical dates in lunar-calendar countries. Lookup-table calendars declare a supportedYearRange() (e.g., 2024–2037); multi-year forecasting products will hit that ceiling.
• We need company-specific calendars — shutdown weeks, floating holidays, customer-defined non-working days. That's our data model, not this package's.
• We need business hours, not dates. No timezone/opening-hours logic; that's a separate (and harder) problem.
• PHP version is pinned below 8.4, or the stack isn't PHP.

Risk posture: modest adoption (~400 stars, few declared dependents — notably low for a Spatie package) and the score sits mid-range. Signals in favor: MIT, changelog discipline, tagged releases, snapshot-tested country data, active contributor flow. Signals against: bus factor and data quality rest on volunteers, and country coverage quality will be uneven. Treat it as a good default, not an authoritative source.

How to Pitch It (Stakeholders)

To executives: This is a free, MIT-licensed library that removes a permanent, low-value maintenance chore — keeping holiday calendars accurate across the countries we operate in. It's a small integration, not a platform bet: one Composer dependency, straightforward to replace. It unblocks "business-day aware" features (delivery promises, due dates, SLAs, staffing, localized holiday messaging) and gives us a clear coverage list for deciding which markets we can credibly claim to support. The one caveat to state plainly: it is not a compliance product. We still own the policy calls on payroll and statutory leave.

To engineering: composer require spatie/holidays, immutable Carbon dates, JSON-serializable output, an API that reads well (for(), get(), getInRange(), isHoliday(), getUpcoming(), getLongWeekends()), plus region and locale options. Two real constraints: PHP 8.4+, and country data is community-contributed with snapshot tests, so it's good but not guaranteed. Wrap it in a single CalendarService interface on day one — that caps our exposure and makes a swap a one-day job.

Ask: approve a short spike — validate our top three to five countries (including any region variants and observed-day rules) with snapshot tests, confirm the PHP 8.4 upgrade path, and come back with an adopt/wrap/replace recommendation.