Laravel Brazil Holidays Laravel Package

Product Decisions This Supports

• Feature-level: business-day math for Brazil. isHoliday, isBusinessDay, and addBusinessDays are the primitives behind the dates users actually care about — invoice/boleto due dates, subscription renewal and dunning retries, D+n delivery ETAs, SLA clocks on support tickets, contract interest and late-fee accrual, and payroll/payment cutoffs. Deciding to standardize these calculations on one library rather than letting each squad hand-roll its own holiday table is a real platform decision.
• Build vs. buy. Replaces an in-house table of Brazilian dates that someone has to remember to update every time legislation moves. The 1.0.0 note that Consciência Negra (Nov 20) is included from 2024 is exactly the kind of change that silently breaks a homegrown list — this package treats legislation-following as the vendor's job, not ours.
• Correct defaulting of optional days. Carnival and Corpus Christi are exposed as opt-in, which matches reality: they are pontos facultativos, not statutory national holidays. That lets PM decide per-surface whether to honor them (customer-facing ETA: probably yes; contractual due-date math: probably no). Getting this wrong is a support-ticket and compliance problem, not a cosmetic one.
• Roadmap / market localization. A credible Brazil localization story needs date correctness as table stakes. This unblocks Brazil-specific billing, logistics, and finance roadmap items without a research spike.
• Configuration over code for regional coverage. State and municipal holidays via config means product can localize per-region (e.g., São Paulo vs. Rio customers) without engineering releases — useful for regional pricing, regional SLAs, or per-tenant holiday calendars in multi-tenant setups.

When to Consider This Package

Adopt when most of the following hold:

• You ship a Laravel/PHP product with Brazilian customers, employees, or counterparties, and any user-visible date is computed as "N business days."
• You want a small, focused dependency rather than a general-purpose holiday library, and you're content to own the state/municipal holiday lists yourself (they're config, so accuracy is on us).
• You need optional-day granularity — the ability to treat Carnival/Corpus Christi as working days or not, per feature.
• You run minimal container images, where the pure-PHP Easter calculation avoids depending on the calendar extension.
• You're replacing a hardcoded holiday table that has already gone stale, or is likely to.

Look elsewhere when:

• You need multi-country or broad international holiday coverage — a dedicated international holiday library is the better fit; this package is Brazil-scoped by design.
• You need financial-market conventions (ANBIMA/B3 settlement calendars, bank holidays, "following business day" / modified-following adjustments for securities or FX). Holiday data alone doesn't express those rules.
• You need holiday data as a maintained service (API/DB with authoritative state and municipal coverage). Config-driven municipal lists mean we curate and review them, and a wrong municipal date produces a wrong due date.
• You're not on Laravel, or you need holidays for many years ahead with guaranteed legislative tracking — for a 1.0.0 package, pin the version and wrap it behind our own interface so a future swap is cheap.
• Due dates are contractually fixed (e.g., a regulator or counterparty defines the calendar). Then the calendar is a business rule to encode explicitly, not a library default.

Two adoption cautions worth writing into the ticket: this is a 1.0.0 initial release — treat the API as unstable and put a thin adapter in front of it; and confirm the package's default set (which holidays are on, whether optional days are off) matches our contractual definitions before it touches money.

How to Pitch It (Stakeholders)

For executives: We operate in Brazil, and a lot of what we show customers — payment due dates, delivery estimates, support SLAs — is counted in business days. Today that logic is either duplicated across teams or based on a holiday list someone maintains by hand. This package gives us one accurate, low-cost source of truth for Brazilian holidays, including the 2024 addition of Consciência Negra, which is precisely the sort of legislative change a hand-maintained list misses. It's a small, single-purpose dependency that reduces a quiet class of operational and compliance errors — wrong due dates, missed SLAs, misquoted delivery windows — and it unblocks Brazil-specific billing and logistics work on the roadmap. Risk is low and contained: it's a young 1.0.0 release, so we'll pin the version and keep it behind our own interface.

For engineering: Drop-in Laravel package: isHoliday, isBusinessDay, addBusinessDays, national holidays computed per year, Carnival/Corpus Christi opt-in (they're optional days, not statutory), and state/municipal extras via config. Easter is computed in pure PHP, so no dependency on the calendar extension — safe for slim images. Action items: (1) pin to 1.0.x and wrap it in a single internal service so we can swap implementations later; (2) the config-driven regional holiday lists are ours to own and review — treat them as data with an owner and a review cadence; (3) verify the default holiday set against our contractual definitions before using it for invoicing or interest accrual.