Laravel Brazil Holidays Laravel Package

Getting Started

• Install with composer require (package name per Packagist listing) and, if a config file ships, publish it with php artisan vendor:publish --tag=config (or the package's published tag) so the state/municipal holiday lists and the Carnival/Corpus Christi toggles live in config/. Commit that file.
• Look first at the generated config/*.php file and the package's facade/service entry point. That pair tells you everything you need: which municipality/state is active, whether Carnival and Corpus Christi count as holidays, and which methods (isHoliday, isBusinessDay, addBusinessDays) are exposed.
• First use case: gate a business-day SLA. In a controller or job, resolve the package from the container, call isBusinessDay($date) for the current timestamp, and use it to decide whether to dispatch a notification or queue it for the next working day. This is the fastest "did it do what I expect?" smoke test against a known date.

Implementation Patterns

• SLA and deadline math. Use addBusinessDays($date, $n) rather than chaining ->addWeekdays() on Carbon. The package knows about national holidays (and any state/municipal ones you configured), so ticket due dates, delivery estimates, and invoice cutoffs stay correct across holidays. Wrap this in a small BusinessDays helper or a custom cast so the logic is reused instead of sprinkled across controllers.
• Config as the source of truth for locale. Set the state (UF) and, if relevant, the municipality once at application level, then let all callers use the same instance. For multi-tenant apps, override the config per tenant at resolution time (e.g. a scoped instance or a wrapper that passes the tenant's UF/municipality) rather than mutating global config at runtime.
• Year-scoped queries. When rendering calendars, dashboards, or holiday lookups for a date range, iterate years and cache the holiday list per [year, state, municipality, carnival/corpus flags] key. This makes expensive calls cheap and keeps the results consistent for the whole request.
• Combining with Carbon. The package operates on dates, not moments. Normalise incoming Carbon instances to the start of day in the app timezone (typically America/Sao_Paulo) before calling isHoliday/isBusinessDay, and keep the original time when you need to display it. Store business-date computations as date columns, not datetime.
• Integration points. Good places to wire it in: form request validation (reject dates that aren't business days), model accessors for "next business day", scheduled task guards (if ($this->holidays->isBusinessDay(now())) { ... }), and reporting queries for working-day counts.
• Testing. Freeze time with Carbon::setTestNow() against known dates (e.g. a fixed Carnival year, 1 Jan, 7 Sep) so your assertions don't drift. Add a small fixture test that confirms Consciência Negra is treated as a holiday only from 2024 onward — that's the edge most likely to bite in historical reporting.

Gotchas and Tips

• Carnival and Corpus Christi are optional, not national statutory holidays. Don't assume defaults. Explicitly set both toggles in config and document which behaviour your business rules rely on — otherwise a config publish/regenerate can silently change SLA calculations.
• Consciência Negra starts in 2024. Any calculation spanning earlier years must not treat 20 November as a holiday. If you compute historical business-day counts, verify the year boundary explicitly; this is the most likely source of off-by-one errors in backdated reports.
• State/municipal holidays are a config maintenance burden. They change with local legislation and by year. Keep the list reviewed on a schedule, and prefer IBGE/UF keys over free-text names so lookups don't break on typos or accents.
• addBusinessDays semantics. Confirm whether the start date is counted and what happens when it lands on a holiday or weekend. Write one test that pins the behaviour, then build your SLA helper on top of it — do not re-derive the rule elsewhere.
• Timezone drift. isBusinessDay(now()) depends on the app timezone. If you run jobs in UTC but serve Brazilian users, convert to local time first; otherwise late-evening UTC timestamps will resolve to the wrong calendar day.
• Config caching in production. After editing holiday config, run php artisan config:clear (and re-cache). A stale cached config is the usual cause of "the package says today isn't a holiday" in production while it's correct locally.
• Pure-PHP Easter calculation. It avoids the ext-calendar dependency, which is good for portability, but validate it once against a few known Easter dates and rely on the package's own holiday derivation rather than reimplementing it. If you need movable feasts beyond Carnival/Corpus Christi, that's your extension point.
• Caching invalidation. If you cache per-year results, include all config inputs (state, municipality, carnival, corpus) in the cache key; a missed dimension leads to one tenant seeing another's holidays.