Yasumi Laravel Package

Technical Evaluation

Architecture fit

Yasumi is a pure-PHP, calculation-driven holiday library with no database, no external API, and no runtime service dependency. That makes it a low-ceremony fit for a Laravel monolith or modular monolith: it is a library you call in-process, not an integration you operate. For teams that already need business-calendar logic — SLA clocks, payroll cutoffs, billing cycles, shipping dispatch, scheduling, accruals, "next business day" — this replaces brittle hand-maintained holiday tables and ad-hoc if ($month === 12) logic with a maintained, tested rule engine.

The provider model (one class per country/region) is the right abstraction for multi-tenant and multi-geography products. Holiday type filters (Official, Observed, Bank, Seasonal, Other) are the most strategically useful feature: most products conflate "is it a public holiday" with "is the office closed" and "does the bank settle," and those are genuinely different questions. Time zone awareness and global translations mean the library can serve localized UX without a separate i18n pipeline for holiday names.

Integration feasibility

High. composer require azuyalabs/yasumi on PHP 8.2+, PSR-4 autoloading, PSR-12, MIT license, semver 2.x line. No Laravel service provider is shipped, which is fine — the correct pattern is a thin internal adapter (a singleton service plus a config file for default country/locale) rather than calling Yasumi::create() from controllers and jobs. Expect roughly one to three days of engineering for the adapter, caching, and test fixtures; the library itself is not the cost.

Technical risk

• Correctness risk is the dominant risk, and it is jurisdictional, not technical. The changelog is dense with substantive corrections: Belgium's Easter/Pentecost not being official, Scotland's Easter Monday not being a bank holiday, Mexico holidays reclassified as observance, Germany's Pentecost rules varying by state, Portugal's Corpus Christi, Czech Christmas Eve, Ukraine 2021–2023 changes. This is a healthy sign of maintenance, but it also tells you the library's holiday semantics change in ways that can silently move dates in your product. Any downstream financial or contractual calculation needs an owner who validates rules, not just bumps versions.
• Key-based lookups are a stability liability. The unreleased changelog renames Queen's Birthday → Monarch's Birthday, adds HolidayNotFoundException for unknown keys, and adds key validation to removeHoliday. If you persist or expose holiday keys, treat them as internal and map them to your own stable identifiers.
• Regional granularity is uneven. Some countries expose states/provinces (Canada, Germany, Spain, Australia), others are national-only. If your product sells into sub-national markets, coverage must be inventoried per market rather than assumed.
• Historical and forward bounds. Providers encode establishment/abolition years. Retroactive reporting and multi-year forecasts will hit boundaries; test both directions.
• PHP 8.2 floor. If any Laravel app or queue worker in the fleet is below 8.2, this is a hard blocker until upgraded.
• Metadata anomaly. The Dependents: 0 figure conflicts with 1,106 stars and an active multi-year changelog; likely a Packagist metric artifact, but verify real-world adoption before treating the package as strategic. The 2026-09-30 last-release date is also a data-quality flag worth confirming against the actual releases page.

Key questions

1. Which jurisdictions and sub-national regions must we support at launch, and in which languages?
2. Do we need Observed vs Official vs Bank distinction, or only "office closed"?
3. What is the required date range — forward forecasts only, or historical backfill for reporting?
4. Which downstream systems are financially or contractually sensitive to a wrong date?
5. Who owns legal verification of holiday rules per market, and on what cadence?
6. What is our minimum PHP version across all apps and workers?

Integration Approach

Stack fit

Native Laravel/Lumen fit at the Composer layer; no framework coupling to fight. The library uses DateTime/DateTimeImmutable and implements ArrayIterator, so it composes cleanly with Laravel's scheduler, queue payloads, and Carbon-based domain code — with the caveat that you should normalize at the adapter boundary rather than mixing Carbon and raw DateTime deep in domain logic.

Migration path

1. Inventory the current state. Grep for hardcoded holiday arrays, isHoliday-style helpers, holiday database tables, and inline date math. Most Laravel codebases have two or three divergent implementations; consolidating them is usually the largest source of value.
2. Build a domain adapter, not a facade to the vendor. A BusinessCalendar service with methods like holidaysFor(string $region, int $year), isHoliday(Carbon $date, string $region), nextBusinessDay(), and addBusinessDays(). Keep the vendor type out of your public surface so the library remains replaceable.
3. Establish a golden dataset before cutover. For each launch market and year, snapshot expected holiday names and dates into fixtures and assert against them. This becomes your regression gate for every future version bump and the mechanism by which a legal-rule change is caught rather than discovered by a customer.
4. Dual-run. Run the new adapter in parallel with legacy logic in shadow mode for one or two reporting cycles, logging divergences. Divergences are almost always in the legacy code — but not always.
5. Cut over by consumer, not by module. Start with low-stakes consumers (UI display, calendar widgets), then scheduler/notification logic, then financially sensitive paths.

Compatibility

Straightforward Composer resolution. Pin with a caret constraint on the 2.x line and treat minor bumps as reviewable changes, not auto-merge — the changelog demonstrates that minor releases ship behavioral corrections. Register Dependabot/Renovate with a dedicated reviewer for this package. Ship a config/business-calendar.php for default provider, locale, timezone, and allowed holiday types per tenant, and resolve per-tenant overrides through config or a settings table rather than code.

Sequencing

Adapter and caching layer → golden dataset and test harness → low-stakes consumer cutover → shadow-run on business-day math → financially sensitive consumers → remove legacy holiday tables. Do not start with payroll or billing; the adapter's API will still be moving.

Caching

Holiday computation is cheap but not free, and results are immutable once calculated for a given provider + year + locale. Use Cache::remember keyed on provider:region:year:locale:types, warm the current and next year via a scheduled command, and avoid per-request instantiation inside hot loops. Cardinality is tenants × regions × years × locales — modest, but size it explicitly for multi-tenant deployments.

Operational Impact

Maintenance

No infrastructure, no database, no service to page on. The recurring cost is dependency hygiene plus the human judgment required to validate holiday rules. Budget a named owner for the holiday data domain; without one, version bumps become a coin flip on whether a legal correction silently shifts a customer's billing date. Version bumps should be paired with the golden-dataset diff, which reduces the review to "what changed and is the change correct" rather than a code read.

Support

Support load shifts from "why is this date wrong" engineering tickets to product/legal clarification tickets, which is a better allocation. Two exceptions deserve runbooks: tenants reporting a missing regional holiday (usually a coverage question, sometimes a genuine rule gap that should be filed upstream), and tenants reporting an unexpected observed/substitute holiday (usually a type-filter misconfiguration). Provide a support-facing view of "which holidays are active for this tenant" to cut diagnosis time.

Scaling

Effectively free. In-process computation, small memory footprint, no I/O, no rate limits, no third-party availability dependency. It scales linearly with request volume without a new bottleneck. The only scaling consideration is cache cardinality and cold-start cost on cache flush — a scheduled warm job handles both. Contrast this favorably against holiday SaaS APIs, which introduce a network hop, a rate limit, an availability SLA, and a per-request cost into what is fundamentally a deterministic calculation.

Failure modes

• Unknown holiday key → HolidayNotFoundException after the recent change. Wrap key lookups; never let a vendor exception surface as a 500.
• Unknown or unsupported provider/region → exception at instantiation. Validate tenant region config at write time, not read time.
• Silent rule drift on upgrade → the highest-severity mode. Mitigated only by the golden dataset and manual review of jurisdictional changes.
• Type-filter misuse → holiday present but excluded, or vice versa; produces plausible-looking wrong answers rather than errors.
• Out-of-range years → some holidays legitimately do not exist before their establishment year; nulls are correct behavior, not bugs. Callers must handle null.
• Locale fallback gaps → holiday names may fall back to a default language for uncovered locales; verify per-market rather than assuming full translation coverage.
• Timezone edges → a holiday computed in a provider timezone compared against a UTC-stored timestamp can land on the wrong day. Normalize to the business timezone at the boundary.

Ramp-up

Very low for engineers — the README example is genuinely quick-start, documentation is hosted, and the API surface is small. The real ramp-up is domain education: teaching the team the difference between official, observed, and bank holidays, and why "is it a holiday" is not a boolean question. That is a half-day of context for the team and a much longer tail for whoever owns the golden dataset. Overall this is a low-risk, high-leverage adoption — the decision hinges less on the library's engineering quality, which is visibly solid, and more on whether we have the discipline to own holiday-rule correctness as a product concern.