PHPackages geoffreyrose/useful-dates-us-holidays - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. geoffreyrose/useful-dates-us-holidays ActiveLibrary[Utility & Helpers](/categories/utility) geoffreyrose/useful-dates-us-holidays ===================================== Useful Dates - US Holidays Extension v1.1.0(2mo ago)124↓93.3%MITPHPPHP ^8.4CI passing Since Dec 11Pushed 1mo agoCompare [ Source](https://github.com/geoffreyrose/useful-dates-us-holidays)[ Packagist](https://packagist.org/packages/geoffreyrose/useful-dates-us-holidays)[ GitHub Sponsors](https://github.com/geoffreyrose)[ RSS](/packages/geoffreyrose-useful-dates-us-holidays/feed)WikiDiscussions main Synced today READMEChangelog (2)Dependencies (7)Versions (4)Used By (0) [![Latest Stable Version](https://camo.githubusercontent.com/7b0bd76b2fe5d37197efa705895866fad1eb0eea323bca7e0c66475ef871228e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f67656f6666726579726f73652f75736566756c2d64617465732d75732d686f6c69646179733f7374796c653d666c61742d737175617265)](https://packagist.org/packages/geoffreyrose/useful-dates-us-holidays)[![Test Status](https://camo.githubusercontent.com/952c21d7190aee2c27a70d427109d2a487a3f3f59bf2be434a9c4e98c330ee2e/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f67656f6666726579726f73652f75736566756c2d64617465732d75732d686f6c69646179732f74657374732e796d6c3f6272616e63683d6d61696e267374796c653d666c61742d737175617265266c6162656c3d7465737473)](https://github.com/geoffreyrose/useful-dates-us-holidays/actions?query=branch%3Amain)[![Code Coverage](https://camo.githubusercontent.com/02ae2a7eab0cf5715d37f65e00cc9471a3449a8321ea94136b03002a48e9cf12/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f67682f67656f6666726579726f73652f75736566756c2d64617465732d75732d686f6c69646179732f6d61696e3f7374796c653d666c61742d737175617265)](https://app.codecov.io/gh/geoffreyrose/useful-dates-us-holidays/branch/main)[![License](https://camo.githubusercontent.com/80012b302c32900a37f8fc488b1f18c8d6b4efc7686c524823ee2c2bb4ee851c/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f67656f6666726579726f73652f75736566756c2d64617465732d75732d686f6c69646179733f7374796c653d666c61742d737175617265)](https://github.com/geoffreyrose/useful-dates-us-holidays/blob/main/LICENSE) US Holidays Extension For Useful Dates ====================================== [](#us-holidays-extension-for-useful-dates) Adds 42 US holidays to use with [Useful Dates](https://github.com/geoffreyrose/useful-dates). This is the next evolution of [geoffreyrose/us-holidays](https://github.com/geoffreyrose/us-holidays) but for my date package Useful Dates. ### Requirements [](#requirements) - PHP 8.4+ - [Useful Dates](https://github.com/geoffreyrose/useful-dates) ### Supported Holidays [](#supported-holidays) - April Fool's Day - Armed Forces Day - Ash Wednesday - Black Friday - Christmas Day - Christmas Eve - Cinco de Mayo - Columbus Day - Cyber Monday - Daylight Saving (End) - Daylight Saving (Start) - Earth Day - Easter - Father's Day - Flag Day - Good Friday - Groundhog Day - Halloween - Hanukkah - Independence Day - Indigenous Peoples' Day - Juneteenth - Kwanzaa - Labor Day - Martin Luther King Jr. Day - Memorial Day - Mother's Day - New Year's Day - New Year's Eve - Orthodox Easter - Palm Sunday - Passover - Patriot Day - Pearl Harbor Remembrance Day - Presidents' Day - Rosh Hashanah - St. Patrick's Day - Tax Day - Thanksgiving - Valentine's Day - Veterans Day - Yom Kippur Optionally, you can also include the "observed" holidays. **Observed Holidays** are when the Federal Holiday falls on a Saturday it is observed on the previous day (Friday) or when it falls on a Sunday it is observed on the next day (Monday). - Christmas Day (Observed) - Independence Day (Observed) - Juneteenth (Observed) - New Year's Day (Observed) - Veterans Day (Observed) ### Usage [](#usage) #### Installation [](#installation) ``` composer require geoffreyrose/useful-dates-us-holidays ``` ### Basic Usage [](#basic-usage) ``` use UsefulDates\UsefulDates; ... $usefulDates = new UsefulDates; $usefulDates = $usefulDates->setDate(\Carbon\Carbon::create(2000, 4, 1)) $usefulDates->addExtension(\UsefulDatesUsHolidays\UsefulDatesUsHolidaysExtension::class); $myDates = $usefulDates->getUsefulDatesInDays(100); // Or // $myDates = $usefulDates->getUsefulDatesByYear() // Uses current year set in UsefulDates with setDate(); // $myDates = $usefulDates->getUsefulDatesByYear(2026); // $myDates = $usefulDates->getUsefulDatesInYears(2); foreach ($myDates as $myDate) { echo $myDate->name . ' -- ' . $myDate->usefulDate()->format('F n, Y') . ' -- Days Away: ' . $myDate->daysAway(); } ``` To include observed holidays, use the `include_observed` option. ``` use UsefulDates\UsefulDates; ... $usefulDates = new UsefulDates; $usefulDates = $usefulDates->setDate(\Carbon\Carbon::now()); $usefulDates->addExtension(\UsefulDatesUsHolidays\UsefulDatesUsHolidaysExtension::class, [ 'include_observed' => true ]); $myDates = $usefulDates->getUsefulDatesByYear(2026); ``` ### Additional Methods [](#additional-methods) This extension adds two helper methods to check if a date is a bank or federal holiday: #### isBankHoliday(): bool [](#isbankholiday-bool) Check if the current date is a Bank Holiday and the day it is observed on. **Bank Holiday Rules:** - If the holiday falls on Sunday, it is observed the next day (Monday) - Bank holidays that fall on Saturday are NOT observed on the previous Friday - Only applies to holidays that can fall Monday - Friday - Holidays that always fall on weekends are not considered bank holidays **Returns:** - `true` if the date is a bank holiday - `false` if the date is not a bank holiday **Example:** ``` $usefulDates = new UsefulDates; $usefulDates = $usefulDates->setDate(\Carbon\Carbon::parse('2026-01-01')); // New Year's Day (Thursday) $usefulDates->addExtension(\UsefulDatesUsHolidays\UsefulDatesUsHolidaysExtension::class); if ($usefulDates->isBankHoliday()) { echo "Banks are closed today!"; } ``` #### isFederalHoliday(): bool [](#isfederalholiday-bool) Check if the current date is a Federal Holiday and the day it is observed on. **Federal Holiday Rules:** - If the holiday falls on Saturday, it is observed the previous day (Friday) - If the holiday falls on Sunday, it is observed the next day (Monday) - Only applies Monday - Friday - Holidays that always fall on weekends are not considered federal holidays **Returns:** - `true` if the date is a federal holiday - `false` if the date is not a federal holiday **Example:** ``` $usefulDates = new UsefulDates; $usefulDates = $usefulDates->setDate(\Carbon\Carbon::parse('2026-07-03')); // July 4th observed (Friday) $usefulDates->addExtension(\UsefulDatesUsHolidays\UsefulDatesUsHolidaysExtension::class); if ($usefulDates->isFederalHoliday()) { echo "Federal offices are closed today!"; } ``` ### Getting Holiday Information [](#getting-holiday-information) You can retrieve holiday information for specific dates: ``` $usefulDates = new UsefulDates; $usefulDates = $usefulDates->setDate(\Carbon\Carbon::parse('2026-12-25')); $usefulDates->addExtension(\UsefulDatesUsHolidays\UsefulDatesUsHolidaysExtension::class); $dates = $usefulDates->getUsefulDate(); foreach ($dates as $date) { echo $date->name; // "Christmas Day" } ``` Or get all holidays for a year: ``` $usefulDates = new UsefulDates; $usefulDates = $usefulDates->setDate(\Carbon\Carbon::now()); $usefulDates->addExtension(\UsefulDatesUsHolidays\UsefulDatesUsHolidaysExtension::class); $holidays2026 = $usefulDates->getUsefulDatesByYear(2026); ``` ### Holiday Properties [](#holiday-properties) Each holiday object includes the following properties: - `name` - The official name of the holiday - `is_bank_holiday` - Boolean indicating if it's a bank holiday - `is_federal_holiday` - Boolean indicating if it's a federal holiday - `bank_holiday_start_year` - The year the holiday became a bank holiday (if applicable) - `bank_holiday_end_year` - The year the holiday ceased being a bank holiday (if applicable) - `federal_holiday_start_year` - The year the holiday became a federal holiday (if applicable) - `federal_holiday_end_year` - The year the holiday ceased being a federal holiday (if applicable) **Example:** ``` $usefulDates = new UsefulDates; $usefulDates = $usefulDates->setDate(\Carbon\Carbon::parse('2026-01-19')); $usefulDates->addExtension(\UsefulDatesUsHolidays\UsefulDatesUsHolidaysExtension::class); $dates = $usefulDates->getUsefulDate(); foreach ($dates as $date) { echo $date->name; // "Martin Luther King Jr. Day" echo $date->is_federal_holiday; // true echo $date->federal_holiday_start_year; // 1986 } ``` ### Development [](#development) ### Linting [](#linting) ``` ./vendor/bin/pint ``` ### Static Analysis [](#static-analysis) ``` ./vendor/bin/phpstan analyse src --memory-limit 2G ``` ### Testing [](#testing) ``` ./vendor/bin/pest ./vendor/bin/pest --coverage-html coverage herd coverage ./vendor/bin/pest --coverage-html coverage ``` ### Health Score 42 — FairBetter than 88% of packages Maintenance89 Actively maintained with recent releases Popularity9 Limited adoption so far Community6 Small or concentrated contributor base Maturity55 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~138 days Total 2 Last Release 66d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/3210702?v=4)[Geoffrey Rose](/maintainers/geoffreyrose)[@geoffreyrose](https://github.com/geoffreyrose) --- Top Contributors [![geoffreyrose](https://avatars.githubusercontent.com/u/3210702?v=4)](https://github.com/geoffreyrose "geoffreyrose (35 commits)") --- Tags phplaravelcarbonUS HolidaysUseful Dates ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/geoffreyrose-useful-dates-us-holidays/health.svg) ``` [![Health](https://phpackages.com/badges/geoffreyrose-useful-dates-us-holidays/health.svg)](https://phpackages.com/packages/geoffreyrose-useful-dates-us-holidays) ``` ### Alternatives [kylekatarnls/laravel-carbon-2 Carbon 2 adapter for Laravel 631.2M1](/packages/kylekatarnls-laravel-carbon-2)[amranidev/laracombee Recommendation system for laravel 11538.8k1](/packages/amranidev-laracombee)[yieldstudio/tailwind-merge-php Merge Tailwind CSS classes without style conflicts 4975.4k1](/packages/yieldstudio-tailwind-merge-php)[wujunze/money-wrapper MoneyPHP Wrapper 103.8k](/packages/wujunze-money-wrapper) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)