Download the PHP package cmixin/business-day without Composer

business-day

Carbon mixin to handle business days

Professionally supported nesbot/carbon is now available

Install

Usage

First load the mixin in some global bootstrap place of your app:

Try in the live editor%3B%0A%0ABusinessDay%3A%3Aenable(%27Carbon%5CCarbon%27%2C%20%24baseList%2C%20%24additionalHolidays)%3B%0A%0A%24date%20%3D%20Carbon%3A%3Aparse(%272019-12-25%27)%3B%0A%0Aif%20(%24date-%3EisHoliday())%20%7B%0A%20%20%24name%20%3D%20%24date-%3EgetHolidayName()%3B%0A%20%20echo%20%22December%2025th%20is%20an%20holiday%20in%202019%20as%20it%27s%20%24name%5Cn%22%3B%0A%7D%20else%20%7B%0A%20%20echo%20%22December%2025th%20is%20not%20an%20holiday%20in%202019.%5Cn%22%3B%0A%7D%0A%0A%24date%20%3D%20Carbon%3A%3Aparse(%272019-04-16%27)%3B%0A%0Aif%20(%24date-%3EisHoliday())%20%7B%0A%20%20%24id%20%3D%20%24date-%3EgetHolidayId()%3B%0A%20%20echo%20%22April%2016th%20is%20an%20holiday%20in%202019%20as%20it%27s%20%24id%5Cn%22%3B%0A%7D%20else%20%7B%0A%20%20echo%20%22April%2016th%20is%20not%20an%20holiday%20in%202019.%5Cn%22%3B%0A%7D%0A%0A%24date%20%3D%20Carbon%3A%3Aparse(%272020-04-16%27)%3B%0A%0Aif%20(%24date-%3EisHoliday())%20%7B%0A%20%20%24id%20%3D%20%24date-%3EgetHolidayId()%3B%0A%20%20echo%20%22April%2016th%20is%20an%20holiday%20in%202020%20as%20it%27s%20%24id%5Cn%22%3B%0A%7D%20else%20%7B%0A%20%20echo%20%22April%2016th%20is%20not%20an%20holiday%20in%202020.%5Cn%22%3B%0A%7D%0A)

Business days methods are now available on any Carbon instance used anywhere later.

You can also just enable methods on Carbon then set region/holidays later:

Configure holidays

You can set different holidays lists for different regions (to handle different countries, enterprises, etc.)

We provide 356 regional holidays lists of 143 countries that work out of the box in src/Cmixin/Holidays.

And you can easily customize them and add your own lists.

A holidays list file is a PHP file that return an array, each item of the array represent a holiday of the year.

It can be a fixed date such as '12-25' for Christmas, a expression starting with = like 'third Monday of January' or a closure that will calculate the date for the given year.

Expressions support any format the PHP DateTime constructor supports such as:

• second Wednesday of July
• 03-01 - 3 days

And we add a lot of syntaxical sugar:

• = easter 3 (Easter + 3 days)
• = Friday before 01-01 (before/after)
• = 01-01 if Saturday then next Monday and if Sunday,Monday then next Tuesday (multiple conditions)
• = 01-01 if weekend then next Monday (weekend = Saturday or Sunday)
• = 01-01 substitute (substitute = shift the day to the next day that is not Saturday, Sunday or an other holiday, it means if you have both 01-01 substitute and 01-02 substitute, you're sure to get the 2 holidays not during the weekend in the right order no matter the days it falls)
• = orthodox -2 (2 days before Orthodox Easter)
• = julian 12-25 (Julian calendar)
• = 02-05 on Monday holiday only if this is a Monday.
• = 02-05 not on Monday not an holiday if this is a Monday.
• = 02-05 on even years even years only.
• = 02-05 on every 5 years since 1999 if year is 1999, 2004, 2009, 2014, etc.

setHolidaysRegion / getHolidaysRegion

To select the set of holidays of a region, use:

This will select our national preset for USA (only holidays common to all states).

Before selecting a region the list of holidays is empty so isHoliday will return false for any date.

getYearHolidays

Get the holiday dates list for a given year:

It will output:

Try in the live editor%20%7B%0A%20%20%20%20echo%20%24holiday->getHolidayName().%27%3A%20%27.%24holiday->format(%27l%2C%20F%20j%2C%20Y%27)."%5Cn"%3B%0A%7D)

getHolidays

This method allow you to get the holiday list for a given region passed in argument, if no argument given the list for the current selected region is returned.

setHolidays

It's how you can set your own holidays lists:

You can also pass deep array to setHolidays to set in the same call holidays dates and either observed flags, names (in different languages) or both:

addHolidays

While setHolidays replace the whole holidays list for a given region, addHolidays append holidays to the current list.

As for setHolidays, addHolidays handle deep arrays using date, observed and name keys.

resetHolidays

Reset all holidays and region previously set.

isHoliday

Returns true if the date (Carbon instance) is a holiday (in the list of the selected region), false else.

getHolidayId

Same as isHoliday but returns a string id for the given holiday, so you can target specific holidays.

getHolidayName

Returns the name of the holiday in the current locale (or English by default) or false if the day is not a holiday.

Note: be aware, region has no effect to the holiday language name since some regions have multiple languages. So to get french names of the french holidays, you need both Carbon::setHolidaysRegion('fr-national') and Carbon::setLocale('fr_FR'), the first for the holiday calendar, the second for the language.

setHolidayName

Wanna rename a holiday name in a particular language? No problem:

It also allows you to name an additional holiday you added manually and you can specify multiple languages using array:

isBusinessDay

Returns true if the date (Carbon instance) is nor a week-end day neither a holiday, false else. Week-end days can be configured (see Carbon documentation weekend section).

nextBusinessDay

Add days to the date (Carbon instance) to jump to the next business day (skipping holidays and week-ends).

previousBusinessDay

Sub days to the date (Carbon instance) to jump to the previous business day (skipping holidays and week-ends).

currentOrNextBusinessDay

Returns the current date (Carbon instance) if it's a business day, else add days to jump to the next business day (skipping holidays and week-ends).

currentOrPreviousBusinessDay

Returns the current date (Carbon instance) if it's a business day, else sub days to jump to the previous business day (skipping holidays and week-ends).

addBusinessDays

Add days to the date (Carbon instance) skipping holidays and week-ends.

addBusinessDay

Alias addBusinessDays.

subBusinessDays or subtractBusinessDays

Sub days to the date (Carbon instance) skipping holidays and week-ends.

subBusinessDay or subtractBusinessDay

Alias subBusinessDays.

setObservedHolidaysZone

You can define isolated zones that can observe different holidays lists. By default the zone is "default".

getObservedHolidaysZone

Get the current zone used for observed holidays.

isObservedHoliday

Return true if the current day is an observed holiday (holiday as per the holidays list in use and if it's observed as per the current zone).

observeHoliday

Observe holidays. You can have multiple set of observed days using setObservedHolidaysZone.

observeHolidays

Alias of observeHoliday.

unobserveHoliday

Set holidays as not observed. You can have multiple set of observed days using setObservedHolidaysZone.

unobserveHolidays

Alias of unobserveHoliday.

observeAllHolidays

Remove any previous settings for observed days in the current zone, then make every holidays as observed by default.

unobserveAllHolidays

Remove any previous settings for observed days in the current zone, then make every holidays as not observed by default.

diffInBusinessDays

Get the number of open days between 2 dates.

⚠️ Behavior is different for Carbon 2 and 3:

• Carbon <= 2 returns an absolute number (always positive).
• Carbon >= 3 returns a negative number passed dare is before current date, positive else.

getBusinessDaysInMonth

Get the number of open days in the current/given month.

getMonthBusinessDays

Get an array of Carbon objects for each open day in the current/given month.

isExtraWorkday

Extra work days are days that are worked even if it's during the week-end (so isBusinessDay() returns true for those days). They allow to handle compensation days used in some countries and some business exceptions.

isExtraWorkday returns true if the current day is one for them, false else.

isExtraWorkday is equivalent to isHoliday but for the extra working days list (the without config entry).

getExtraWorkdayId

Get the ID of the current extra work day, or false if it's not an extra workday.

getExtraWorkdayId is equivalent to getHolidayId but for the extra working days list.

getExtraWorkdays

Get the list of the extra workdays of a given region (current region if not specified).

getExtraWorkdays is equivalent to getHolidays but for the extra working days list.

setExtraWorkdays

Set the list of the extra workdays of a given region.

setExtraWorkdays is equivalent to setHolidays but for the extra working days list.

addExtraWorkday

Add an extra workday to the list of a given region.

addExtraWorkday is equivalent to addHoliday but for the extra working days list.

setBusinessDayChecker

Customize the way to determine if a date is a business day or not.

If not set or set to null, the default calculation is:

setHolidayGetter

Customize the way to determine if a date is a holiday and which one it is.

setExtraWorkdayGetter

Customize the way to determine if a date is an extra work day and which one it is.

It's equivalent to setHolidayGetter but for extra work days.

setHolidayDataById

Set an array of data for a given holiday ID.

setHolidayData

Set an array of data for current holiday (does nothing if the current day is not a holiday).

getHolidayDataById

Get stored array of data for a given holiday ID.

getHolidayData

Get stored array of data for current holiday (null if the current day is not a holiday).

getHolidaysAvailableRegions

Get an array of available regions that can be selected.

Laravel

To enable business-day globally in Laravel, set default holidays settings in the config file config/carbon.php (create this file if it does not exist yet):

If you use Laravel but don't plan to use this global config to enable business-day, you may remove it from auto-discovery using:

PHPStan

This library includes a PHPStan extension to provide static analysis support for business day methods when using PHPStan.

The extension automatically provides type information for all business day methods added to Carbon instances, enabling:

• Proper type checking for method parameters and return types
• IDE autocompletion for business day methods
• Static analysis of business day method usage

Enabling the PHPStan Extension

The PHPStan extension is automatically installed when you use PHPStan with this library. If you're using PHPStan Extension Installer (recommended), no manual configuration is needed.

Automatic Installation (Recommended): The extension will be automatically loaded if you have phpstan/extension-installer in your project:

Manual Installation: If you prefer manual configuration, add the extension to your PHPStan configuration file (phpstan.neon or phpstan.neon.dist):

What the Extension Provides

The extension provides complete type information for all business day methods:

Requirements

• PHPStan 1.0.0 or higher
• The extension is automatically available when you install this package with composer require-dev phpstan/phpstan
• No additional dependencies required

Note about timezones

When you set an holidays region, it does not change the timezone, so if January 1st is an holiday, ->isHoliday() returns true from Carbon::parse('2010-01-01 00:00:00.000000) to Carbon::parse('2010-01-01 23:59:59.999999) no matter the timezone you set for those Carbon instance.

If you want to know if it's holiday or business day in somewhere else in the world, you have to convert it:

Contribute

The scope of this library is to provide business date and time utilities to Carbon, if you think of a feature in this scope, feel free to submit a pull-request.

We will also happily merge any holidays file matching an official country, state or region holidays list.

Credits

Based on the work of Christopher "rmblstrp", see Carbon PR #706