PHPackages                             sunaoka/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. sunaoka/holidays

ActiveLibrary[Utility & Helpers](/categories/utility)

sunaoka/holidays
================

Holiday calculation library

v1.6.3(1mo ago)21.8k↑18.8%MITPHPPHP ^5.5 || ^7.0 || ^8.0CI passing

Since Jan 27Pushed 1mo agoCompare

[ Source](https://github.com/sunaoka/holidays)[ Packagist](https://packagist.org/packages/sunaoka/holidays)[ RSS](/packages/sunaoka-holidays/feed)WikiDiscussions develop Synced today

READMEChangelogDependencies (8)Versions (58)Used By (0)

Holiday calculation library for PHP
===================================

[](#holiday-calculation-library-for-php)

[![Latest](https://camo.githubusercontent.com/169d9a1865d9a42ff9dad431f051202ff7afc4f53e3a4c0f32f66ba208d25db8/68747470733a2f2f706f7365722e707567782e6f72672f73756e616f6b612f686f6c69646179732f76)](https://packagist.org/packages/sunaoka/holidays)[![License](https://camo.githubusercontent.com/761e72b0a6df710683154264863cb629c95c3ac7ce3c4c2b3902e94c23742c06/68747470733a2f2f706f7365722e707567782e6f72672f73756e616f6b612f686f6c69646179732f6c6963656e7365)](https://packagist.org/packages/sunaoka/holidays)[![PHP](https://camo.githubusercontent.com/94adf362190e0499931ba2497319197d685c825137ccb93c37a8a5882162e227/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f73756e616f6b612f686f6c6964617973)](composer.json)[![Test](https://github.com/sunaoka/holidays/actions/workflows/test.yml/badge.svg)](https://github.com/sunaoka/holidays/actions/workflows/test.yml)[![codecov](https://camo.githubusercontent.com/b47d6b9435a3412c2246c019bda741ab4e0ade38148720dfd791885fc0b7be70/68747470733a2f2f636f6465636f762e696f2f67682f73756e616f6b612f686f6c69646179732f6272616e63682f646576656c6f702f67726170682f62616467652e737667)](https://codecov.io/gh/sunaoka/holidays)

---

Supported Countries
-------------------

[](#supported-countries)

CountryCode🇨🇳 China`CN`🇩🇪 Germany`DE`🇫🇷 France`FR`🇬🇧 United Kingdom`GB`🇭🇰 Hong Kong`HK`🇮🇩 Indonesia`ID`🇮🇹 Italy`IT`🇯🇵 Japan`JP`🇰🇷 Korea`KR`🇱🇺 Luxembourg`LU`🇸🇬 Singapore`SG`🇹🇼 Taiwan`TW`🇺🇸 United States of America`US`Installation
------------

[](#installation)

```
composer require sunaoka/holidays
```

Basic Usage
-----------

[](#basic-usage)

### Finds whether a date is a holiday

[](#finds-whether-a-date-is-a-holiday)

```
use Sunaoka\Holidays\Holidays;

// Is January 1, 2021 a holiday in the United States (US)?
$holidays = new Holidays('US');
$holidays->isHoliday('2021-01-01');
// => true
```

### Returns a list of holidays

[](#returns-a-list-of-holidays)

```
use Sunaoka\Holidays\Holidays;

// Returns United States (US) Holidays in 2021
$holidays = new Holidays('US');
$holidays->getHolidays(2021);
// =>
// array(36) {
//   [0] =>
//   class Sunaoka\Holidays\Holiday#1 (4) {
//     protected $name =>
//     string(14) "New Year's Day"
//     public $date =>
//     string(26) "2021-01-01 00:00:00.000000"
//     public $timezone_type =>
//     int(3)
//     public $timezone =>
//     string(3) "UTC"
//   }
//   [1] =>
//   class Sunaoka\Holidays\Holiday#2 (4) {
//     protected $name =>
//     string(26) "Martin Luther King Jr. Day"
//     public $date =>
//     string(26) "2021-01-18 00:00:00.000000"
//     public $timezone_type =>
//     int(3)
//     public $timezone =>
//     string(3) "UTC"
//   }
//     :
//     :
//     :
//   [35] =>
//   class Sunaoka\Holidays\Holiday#36 (4) {
//     protected $name =>
//     string(14) "New Year's Eve"
//     public $date =>
//     string(26) "2021-12-31 00:00:00.000000"
//     public $timezone_type =>
//     int(3)
//     public $timezone =>
//     string(3) "UTC"
//   }
```

### Returns holidays for a given date range

[](#returns-holidays-for-a-given-date-range)

```
use Sunaoka\Holidays\Holidays;

// Return United States (US) holidays from 2021-01-01 to 2021-01-07
$holidays = new Holidays('US');
$holidays->between(date('2021-01-01'), date('2021-01-07'));
// array(1) {
//   [0] =>
//   class Sunaoka\Holidays\Holiday#1 (4) {
//     protected $name =>
//     string(14) "New Year's Day"
//     public $date =>
//     string(26) "2021-01-01 00:00:00.000000"
//     public $timezone_type =>
//     int(3)
//     public $timezone =>
//     string(3) "UTC"
//   }
// }
```

### Add custom holiday

[](#add-custom-holiday)

```
use Sunaoka\Holidays\Holidays;

// Add 2021-05-05 as my birthday
$holidays = new Holidays('US');
$holidays->addHoliday(new Holiday('2021-05-05', 'My Birthday 🎉'));

$holidays->isHoliday('2021-05-05');
// => true
```

### Update holiday data to latest

[](#update-holiday-data-to-latest)

```
php ./vendor/bin/holiday-update
```

### Remove unused country holidays

[](#remove-unused-country-holidays)

To avoid shipping unused country holidays, you can run the `Sunaoka\\Holidays\\Task\\Composer::removeHolidays` task and specify the services you want to keep in `composer.json`:

```
{
    "require": {
      "sunaoka/holidays": "^1.1"
    },
    "scripts": {
        "pre-autoload-dump": [
            "Sunaoka\\Holidays\\Task\\Composer::removeHolidays"
        ]
    },
    "extra": {
        "sunaoka/holidays": [
            "jp",
            "us"
        ]
    }
}
```

In this example, when running `composer update` or `composer install`, all holidays except Japan (`jp`) and United States of America (`us`) will be removed.

###  Health Score

51

—

FairBetter than 95% of packages

Maintenance92

Actively maintained with recent releases

Popularity22

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity68

Established project with proven stability

 Bus Factor1

Top contributor holds 99.7% 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 ~29 days

Recently: every ~87 days

Total

55

Last Release

39d ago

PHP version history (2 changes)v1.0.0PHP >=5.6

v1.0.20PHP ^5.5 || ^7.0 || ^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/aab0eef8c17cb4a1d856c457224642bdf29adf5255e2f9db84e1c192f78ef272?d=identicon)[sunaoka](/maintainers/sunaoka)

---

Top Contributors

[![sunaoka](https://avatars.githubusercontent.com/u/105845?v=4)](https://github.com/sunaoka "sunaoka (311 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (1 commits)")

---

Tags

holidayphp

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/sunaoka-holidays/health.svg)

```
[![Health](https://phpackages.com/badges/sunaoka-holidays/health.svg)](https://phpackages.com/packages/sunaoka-holidays)
```

###  Alternatives

[symfony/ux-cropperjs

Cropper.js integration for Symfony

19346.6k3](/packages/symfony-ux-cropperjs)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)