Delivery Calculator Laravel Package

Getting Started

• Install with composer require and, if the package ships one, publish its config: php artisan vendor:publish --tag="holidays-config". The config file is the first place to look after install — it holds the cache settings introduced in v1.1.3.
• Run a single query in tinker to confirm the locale/region wiring works, e.g. resolve holidays for your country and a date range, then dump the results. If you get an empty collection, your region code or locale is wrong far more often than the package is.
• First real use case: replace any hand-rolled if (in_array($date, $hardcodedHolidays)) check with the package's lookup, so business-day maths (SLA timers, invoice due dates, shipping cutoffs) stops being wrong on public holidays.
• Check whether your app is on a Laravel version that has a matching cache driver configured; the new caching behaviour piggybacks on the framework's cache rather than shipping its own store.

Implementation Patterns

• Wrap it in your own service. Don't sprinkle the package facade through controllers and jobs. Create a thin BusinessCalendar (or similar) class that takes a region, exposes isHoliday(Carbon $date) and addBusinessDays(Carbon $date, int $n), and calls the package underneath. That gives you one place to swap regions, add company-specific shutdown days, and later change the package without a repo-wide search.
• Let the new cache do the work on hot paths. Holiday lookups tend to sit inside loops (per-order, per-invoice, per-day-in-a-range). With v1.1.3 caching, repeated queries for the same region/year are cheap, but you should still avoid resolving the same holiday set inside a tight loop — resolve once per job/request and pass it around.
• Pre-warm in a scheduled command. Add a daily or monthly php artisan holidays:warm style command (or a small custom one that iterates your supported regions) so the first request after a cache flush doesn't pay the cost. Good candidates: a Schedule::daily() entry, or a deploy hook step.
• Combine with Carbon business-day helpers carefully. Calculate business days yourself using holiday data rather than assuming addWeekdays() knows about holidays — it doesn't. A small helper that skips weekends and your holiday set is usually 15 lines and removes a whole class of off-by-one bugs.
• Multi-region apps: keep a holidays.regions array in your own config keyed by tenant/country, and resolve the region from the request context rather than hardcoding 'US' in the service.
• Store the derived result, not the holiday. If a date is "the 3rd business day after order", persist the computed due date on the model. Recomputing later against a changed holiday table is a classic source of silently shifting deadlines.

Gotchas and Tips

• Cache invalidation is the big one. With caching on, a corrected holiday (governments do move them — moved observances, one-off national days) won't appear until the TTL expires. Know your TTL, and add an explicit clear step to your deploy or admin tooling: php artisan cache:clear is too blunt, so tag or key-scope the holiday cache if the package allows it.
• Timezone drift. Holiday dates are calendar dates, not instants. Compare using ->toDateString() or start-of-day in the holiday's timezone; comparing a UTC-midnight Carbon to a local-midnight holiday will fail intermittently near DST boundaries.
• Observed vs actual dates. Many regions have both (e.g. a holiday falling on a Sunday observed on Monday). Check which the package returns by default and whether it's configurable — for SLA maths you usually want the observed date.
• Cache store mismatch across environments. If your local dev uses the array driver and production uses Redis, caching bugs only appear in one place. Test the cached path (make the same call twice) rather than assuming.
• Debugging empty results: check region code format (ISO alpha-2 vs subdivisions), the date range boundaries (is between() inclusive?), and whether caching is masking a failed lookup by returning a cached empty array. Flush the specific key when in doubt.
• Extension points: most packages of this type let you add custom holidays or exclude defaults via config or a custom provider. Register company shutdown days there rather than post-processing the returned collection — post-processing tends to get forgotten in one of your five call sites.
• Pin the version range in composer.json at least to ^1.1 so you actually receive the caching fix, and note the version in your README so the next developer knows why holidays appear stale after a data correction.