Run composer require phpexperts/workday-planner
Imagine that you have to schedule a task to run every workday in your country over a given time period.
In order to do this, you first have to figure out what the workdays are, and the weekends. Simple enough, right? But then you remember: "Hey, what about Christmas? and all those other holidays?"
So you dutifully go about detecting those, too. Only to have your clients complaining on the Monday after the Fourth of July. Because, you see, at least in the United States, holidays that occur on Saturdays are observed on the previous Friday, while holidays that occur on Sundays are observed on the next Monday.
With this package, all of these technicalities are handled for you. You give it a date range, and it will dutifully spit out the workdays, keeping in mind both the actual and observed U.S. national holidays common to most employers.
use PHPExperts\WorkdayPlanner\WorkdayDetector;
function isWorkday($dateString) {
$isWorkday = WorkdayDetector::isWorkday(new \DateTime($dateString));
$isOrIsnt = $isWorkday ? 'is' : 'is not';
echo "$dateString $isOrIsnt a work day.\n";
}
// Is Friday, 10 August 2018, a workday?
isWorkday('10 August 2018'); // Workday
isWorkday('11 August 2018'); // Weekend
isWorkday('25 December 2018'); // Fixed holiday
isWorkday('22 November 2018'); // Floating holiday
/* Output:
10 August 2018 is a work day.
11 August 2018 is not a work day.
25 December 2018 is not a work day.
22 November 2018 is not a work day.
*/Some holidays are based upon a certain day of the month, instead of a fixed date. These are called "floating holidays".
The date spec looks like this for Thanksgiving Day:
{
"name": "Thanksgiving Day",
"type": "day",
"when": "fourth Thursday of November"
}Examples:
WorkdayDetector::isWorkday(new \DateTime('2018-11-22')); // false; Thanksgiving Day
WorkdayDetector::isWorkday(new \DateTime('2019-11-28')); // false; Thanksgiving Day
echo (new HolidayDetector()) // 2018-11-22
->getHoliday('Thanksgiving Day')
->format('Y-m-d');
echo (new HolidayDetector()) // 2018-11-28
->changeYear(2019)
->getHoliday('Thanksgiving Day')
->format('Y-m-d'); // The Fourth of July occurs on a Sunday in 2021, so the following Monday is not
// a workday.
use PHPExperts\WorkdayPlanner\WorkdayPlanner;
$planner = new WorkdayPlanner(new \DateTime('2021-07-01'), new \DateTime('2021-07-06'));
echo json_encode(
$planner->getWorkdays(),
JSON_PRETTY_PRINT
);
/* Output:
[
"2021-07-01",
"2021-07-02",
"2021-07-06"
]
*/ $detector = new HolidayDetector();
var_dump([
$detector->isHoliday('2021-07-04'), // The actual holiday.
$detector->isHoliday('2021-07-05'), // The observed holiday
]);
$detector = new HolidayDetector();
$detector->changeYear(2021);
print_r([
'actual' => $detector->getHoliday('Independence Day')->format('l jS \of F Y'),
'observed' => $detector->getHoliday('Independence Day (Observed)')->format('l jS \of F Y'),
]);
/* Output:
array(2) {
[0] => bool(true)
[1] => bool(true)
}
Array
(
[actual] => Sunday 4th of July 2021
[observed] => Monday 5th of July 2021
)
*/There are several ways to access the workdays.
The Workday Planner can be accessed like an array, or as an iterator, or you can just get a simple array of all the workday dates.
$planner = new WorkdayPlanner(new \DateTime('2021-07-01'), new \DateTime('2021-07-06'));
echo json_encode(
$planner->getWorkdays(),
JSON_PRETTY_PRINT
);
/* Output:
[
"2021-07-01",
"2021-07-02",
"2021-07-06"
]
*/ $planner = new WorkdayPlanner(new \DateTime('2021-07-01'), new \DateTime('2021-07-06'));
/** @var \DateTime $workday */
foreach ($planner as $workday) {
// ...
} $planner = new WorkdayPlanner(new \DateTime('2021-07-01'), new \DateTime('2021-07-06'));
// Is it a workday?
if (isset($planner['2021-07-01'])) {
echo "Yes, it is.\n";
}
else {
echo "No, it is not.\n";
}
// Since '2021-07-01' is the first day in the range, it is equal to $planner[0].
echo ($planner[0] === $planner['2021-07-01']) ? 'Strictly equal!' : 'Not equal.';
/* Output:
Yes, it is.
Strictly equal!
*/Workdays can be manually removed, per your policies:
$planner = new WorkdayPlanner(new \DateTime('2021-07-01'), new \DateTime('2021-07-06'));
unset($planner['2021-07-01']);
// Is it a workday?
if (isset($planner['2021-07-01'])) {
echo "Yes, it is.\n";
}
else {
echo "No, it is not.\n";
}
/* Output:
No, it is not.
*/The project currently has 100% code coverage via unit tests.
Here is the behavior documentation, generated by PHPUnit's testdox:
- Can parse fixed holiday dates
- Can parse floating holiday dates
- Can determine if a date is a holiday
- Shows error for unimplemented country
- Shows error for invalid data
- Shows error for invalid holiday spec
- Properly handles unknown holidays
- Will report friday as the observed day for saturday holidays
- Will report friday as the observed day for sunday holidays
- Can determine if a date is a workday
- Will create a date range of workdays
- Will properly offset saturday holidays
- Will properly offset sunday holidays
- Can iterate through each date
- The number of workdays is countable
- Can access dates via the array operator with a numeric index
- Can access dates via the array operator with a date index
- Can use numeric isset on a workday
- Can use date isset on a workday
- Can remove a work day via unset
- Properly handles a start date later than the end date
- Properly handles a start date equal to the end date
- Properly handles invalid dates
- Wont allow manually adding workdays
Created by Theodore R. Smith theodore@phpexperts.pro, mostly in one day.
A PHP Experts, Inc., project.