hirehq/laravel-bank-holidays

UK bank holiday and working day Carbon macros backed by the GOV.UK bank holiday feed.

v1.0.0 2026-04-02 11:57 UTC

Requires

• php: ^8.2
• illuminate/http: ^11.0|^12.0|^13.0
• illuminate/support: ^11.0|^12.0|^13.0

Requires (Dev)

• driftingly/rector-laravel: ^2.2
• laravel/pint: ^1.24
• orchestra/testbench: ^9.0|^10.0|^11.0
• pestphp/pest: ^3.8
• pestphp/pest-plugin: ^3.0
• rector/rector: ^2.3

MIT

• Hire HQ Software Ltd

• laravel
• carbon
• uk
• working days
• bank holidays

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

Package Version	Laravel	PHP
current	11.x, 12.x, 13.x	8.2, 8.3, 8.4, 8.5

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 [e-mail].