PHPackages                             joaosalless/dates - 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. joaosalless/dates

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

joaosalless/dates
=================

Date library for identification of holidays or commemorative dates (national, state, municipal), automatic calculation of working days and office hours.

1.0.5(6y ago)12904MITPHPPHP >=7.2

Since Jul 29Pushed 6y ago2 watchersCompare

[ Source](https://github.com/joaosalless/dates)[ Packagist](https://packagist.org/packages/joaosalless/dates)[ Docs](https://github.com/joaosalless/dates)[ RSS](/packages/joaosalless-dates/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (6)Dependencies (4)Versions (8)Used By (0)

dates
=====

[](#dates)

[![Software License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](LICENSE.md)

Collaborative Date library for identification of holidays and commemorative dates from countries, states and cities with automatic calculation of business days and office hours.

This library was inspired by the [checkdomain/holiday](https://github.com/checkdomain/Holiday) project, completely rewritten to support holidays and commemorative dates from countries, states and cities with automatic calculation of business days and office hours without having to write a new class for each. Events are loaded from a CSV that may be updated from an collaborative API in the future.

Currently supported countries
-----------------------------

[](#currently-supported-countries)

- 🇧🇷 **BR** Brazil
    - National holidays
    - Estate holidays
    - City holidays
    - Commemorative dates
    - Business days
    - Office hours

Your country, state or city is not supported?
---------------------------------------------

[](#your-country-state-or-city-is-not-supported)

**joaosalless/dates** is open source. If you use this library it would be great to get some support for currently not implemented countries which you are familiar with. Pull requests will be reviewed and merged fast.

Install
-------

[](#install)

Via Composer

```
$ composer require joaosalless/dates
```

Usage
-----

[](#usage)

### Holidays

[](#holidays)

```
$dates = new Joaosalless\Dates\Dates('BR');

// Get only national holidays
$dates->getHolidays('2019-09-07');

// Check if a given date is holiday only national holidays
$dates->isHoliday('2019-09-07');

// Get national and state holidays
$dates->getHolidays(
   '2019-09-07', // Date
   'SP'          // State code
);

// Check if a given date is holiday in national and state holidays
$dates->isHoliday(
   '2019-09-07', // Date
   'SP'          // State code
);

// Get national, state and city holidays
$dates->getHolidays(
   '2019-09-07', // Date
   'SP',         // State code
   '3550308'     // City code
);

// Check if a given date is holiday in national, state and city holidays
$dates->isHoliday(
   '2019-09-07', // Date
   'SP',         // State code
   '3550308'     // City code
);
```

### Commemorative Dates

[](#commemorative-dates)

```
$dates = new Joaosalless\Dates\Dates('BR');

// Get only national commemorative dates
$dates->getCommemorativeDates('2019-09-07');

// Get national and state commemorative dates
$dates->getCommemorativeDates(
   '2019-09-07', // Date
   'SP'          // State code
);

// Get national, state and city commemorative dates
$dates->getCommemorativeDates(
   '2019-09-07', // Date
   'SP',         // State code
   '3550308'     // City code
);
```

### Business days

[](#business-days)

Calculates business days from a start date and a specified number of days

```
// Configure business days and office hours
$config = [
    'week' => [
        'office_hours_start' => '09:00',
        'office_hours_end' => '18:00',
        'check_office_hours' => false,
        'days' => [
            'sun' => [
                'business_day' => false,
            ],
            'mon' => [
                'business_day' => true,
            ],
            'tue' => [
                'business_day' => true,
            ],
            'wed' => [
                'business_day' => false,
            ],
            'thu' => [
                'business_day' => true,
            ],
            'fri' => [
                'business_day' => true,
            ],
            'sat' => [
                'business_day' => true,
                'office_hours_start' => '09:00',
                'office_hours_end' => '14:00',
            ],
        ]
    ]
];

$dates = new Dates('BR', $config);

$dates->calculateBusinessDays(
    10,           // Number of days
    '2019-09-07', // Start date
    'SP',         // Check state holidays
    '3550308',    // Check city holidays
);

$dateTime = new DateTime('2019-07-31 08:23:00');

// Check if given DateTime instance is a business day
$dates->isBusinessDay($dateTime); // Returns bool

// Check if given datetime string is a business day
$dates->isBusinessDay('2019-07-31 08:23:00'); // Returns bool

// Returns \DateTime;
```

### Office hours

[](#office-hours)

Checks if given DateTime instance or datetime string is a office hours

```
$dates = new Joaosalless\Dates\Dates('BR');

$dateTime = new DateTime('2019-07-31 08:23:00');

// Check if given DateTime instance is a office hour
$dates->isOfficeHour($dateTime); // Returns bool

// Check if given string date is office hours
$dates->isOfficeHour('2019-07-31 08:23:00'); // Returns bool
```

Change log
----------

[](#change-log)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Testing
-------

[](#testing)

```
$ composer test
```

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) and [CODE\_OF\_CONDUCT](CODE_OF_CONDUCT.md) for details.

Security
--------

[](#security)

If you discover any security related issues, please email  instead of using the issue tracker.

Credits
-------

[](#credits)

- [João Sales](https://github.com/joaosalless)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

30

—

LowBetter than 64% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity19

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity58

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 ~11 days

Total

6

Last Release

2417d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/5ab78c059784bbe79653eadd91f26cd76e33cd44eb62cadccdbbbed480cd3fe1?d=identicon)[joaosalless](/maintainers/joaosalless)

---

Top Contributors

[![joaosalless](https://avatars.githubusercontent.com/u/6626712?v=4)](https://github.com/joaosalless "joaosalless (14 commits)")

---

Tags

datesholidayswork daysbusiness daysferiadosjoaosallessoffice-hoursdatas comemorativasdias úteishorário de expediente

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/joaosalless-dates/health.svg)

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

###  Alternatives

[simshaun/recurr

PHP library for working with recurrence rules

1.6k15.7M40](/packages/simshaun-recurr)[spatie/holidays

Calculate public holidays

392604.1k1](/packages/spatie-holidays)[geoffreyrose/us-holidays

US Holidays Wrapper for the Carbon DateTime Library.

62717.0k2](/packages/geoffreyrose-us-holidays)[holidayapi/holidayapi-php

Official PHP library for Holiday API

35213.3k1](/packages/holidayapi-holidayapi-php)[jpmurray/laravel-countdown

Provide an easy class easy way to get the time difference between two dates, with an extra bonus trait for eloquent

833.8k](/packages/jpmurray-laravel-countdown)[citco/carbon

This is a wrapper for nesbot/carbon which also calculates which days are British bank holidays (England & Wales only).

17400.1k5](/packages/citco-carbon)

PHPackages © 2026

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