- How do I install geoffreyrose/us-holidays in a Laravel app?
- Install it with Composer using composer require geoffreyrose/us-holidays. Laravel package auto-discovery registers the service provider and facade alias, so no manual registration is normally required. The package needs no database, queue, or external service, which keeps setup to a single dependency. If a config file is shipped, publish it so you can control which holidays your application honors.
- Which Laravel and PHP versions does us-holidays support?
- The package is intended for Laravel 9 through 12 on PHP 8.1 or newer, with Carbon 2 or 3, but you should confirm the exact constraints in its composer.json before adopting it. Check that the release you install has CI covering the Laravel and PHP versions you actually run. Because the library extends Carbon, pinning both Carbon and the package version is the safest way to avoid a surprise transitive update.
- How do I check whether a date is a US holiday and get its name?
- The package adds holiday awareness on top of Carbon and exposes a Laravel facade, so the usual pattern is to pass a Carbon instance to the facade and receive a boolean plus the matching holiday name. Read the README for the exact method names in the release you install, since a thin wrapper like this can rename helpers between versions. Wrap the calls in your own small service class so any future API change is contained to one place in your codebase.
- What are the 42 US holidays included, and can I restrict which ones count?
- A set that large almost certainly mixes federal legal holidays such as New Year's Day, Juneteenth, and Thanksgiving with cultural observances such as Valentine's Day, Halloween, and Easter. That matters because a holiday for a retail calendar is not the same as a holiday for a bank or a federal contractor. Read the source or config to get the definitive list, then enable only the subset that matches your written business definition. Do not assume the full set is appropriate for billing, SLA, or payroll logic.
- How does the package handle observed holidays that fall on a weekend?
- Observed-date shifting typically moves a Saturday holiday to the preceding Friday and a Sunday holiday to the following Monday, with a New Year's Day edge case that can shift observance into the prior calendar year. These rules are a real correctness surface, so verify how the current release models them and whether the behavior is configurable. Write your own tests around year boundaries and weekend cases before relying on the output for money or deadlines. Date libraries tend to fail by returning a plausible wrong boolean rather than throwing an exception.
- How do I add my own custom holidays?
- The package provides a mechanism for registering custom holidays alongside the built-in US set, which is useful for company shutdown days or state-specific dates. Determine from the README and source whether registration is config-driven or must happen at runtime per request, because that changes how you wire it into a long-running worker or an Octane process. Keep your custom list in application config rather than scatter it through controllers, and cover it with tests so a package upgrade cannot silently drop your dates.
- Is geoffreyrose/us-holidays compatible with Carbon 3?
- Because the package extends Carbon's API, it inherits Carbon's major-version churn, and Carbon 3 changed behavior and signatures in places. Confirm that the package version you install explicitly declares support for the Carbon major you are on, then pin it in composer.json. A transitive Composer update on Carbon is the most likely way this dependency breaks in production. Running your holiday tests in CI after any dependency bump is the cheapest safeguard.
- Can I use this package for business-day calculations like next business day or due dates?
- The package's scope is holiday awareness, not a full business-day calendar, so treat it as a predicate you compose with rather than a scheduling engine. Confirm whether the current release exposes any next-business-day helper, and if not, combine its holiday check with Carbon's weekday arithmetic in your own service. This is a good fit for invoicing cycles, SLA deadlines, payroll cutoffs, and notification suppression as long as you own the business-day rules. It does not model bank, NYSE, or early-close calendars, so those requirements need a different source.
- What timezone does the holiday check use for today?
- The library does not own timezone storage, so the answer depends on the Carbon instance or application timezone you pass in. Always supply an explicit timezone rather than relying on server-local time, especially if you run workers across regions or process dates near midnight. Decide in writing whether your product's holiday definition follows a user's local date, the company's operating timezone, or UTC, and test that boundary. Getting this wrong shows up as an off-by-one-day holiday result rather than an error.
- Is this package actively maintained, and what is the risk of it being abandoned?
- It is a small, single-maintainer library with a modest star count, which is acceptable for a pure-computation dependency but not something to depend on blindly for contractual correctness. The blast radius of abandonment is limited because the code is forkable and the holiday rules are well understood. Mitigate by wrapping the facade, keeping your own tests around observed-date edge cases, and pinning the version. If holiday accuracy is business critical, budget for maintaining a fork or your own holiday table.