README

hirehq/laravel-bank-holidays adds UK-aware Carbon macros for working day calculations in Laravel applications, using the official GOV.UK bank holiday feed.

Features

• Carbon macros for moving forward and backward by working day
• Predicate helpers for working days and bank holidays
• GOV.UK bank holiday feed integration with long-lived caching
• Support for england-and-wales, scotland, and northern-ireland
• Laravel package auto-discovery with publishable configuration

Installation

composer require hirehq/laravel-bank-holidays

Publish Configuration

php artisan vendor:publish --tag=bank-holidays-config

This publishes config/bank_holidays.php to your application.

Configuration

return [
    'division' => 'england-and-wales',
    'cache_days' => 31,
    'timezone' => null,
];

• division: england-and-wales, scotland, or northern-ireland
• cache_days: feed cache lifetime in days
• timezone: optional override; falls back to app.timezone_display, then app.timezone

The package always uses the official GOV.UK bank holiday endpoint over HTTPS and validates the response structure before caching it.

Compatibility

Usage

use Carbon\CarbonImmutable;

$date = CarbonImmutable::parse('2025-05-23');

$next = $date->addWorkingDay();
$previous = $date->subWorkingDay();

$isWorkingDay = $date->isWorkingDay();
$isBankHoliday = $date->isBankHoliday();

The package evaluates weekends and the configured UK bank holiday division when resolving working days.

Testing

From the package directory:

composer install
composer test
composer refactor

Contributing

Please review CONTRIBUTING.md before opening a pull request.

Security

Please report vulnerabilities according to SECURITY.md. Sensitive security reports can be sent to security@hirehq.co.uk.