README

A Laravel package providing easy access to official UK bank holiday data from GOV.UK with intelligent caching and territorial support.

Features

• Fetches data directly from the official GOV.UK bank holidays API
• Intelligent caching with configurable duration
• Support for all UK territories: England & Wales, Scotland, and Northern Ireland
• Clean, Laravel-native API with Facade support
• Blade directive for conditional rendering
• Carbon integration for date handling

Installation

Install the package via Composer:

composer require foxen/laravel-uk-bank-holidays

The package will auto-register its service provider and facade.

Configuration

Publish the configuration file:

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

This will create a config/uk-bank-holidays.php file with the following options:

return [
    // Default territory when none is specified
    'default_territory' => env('UK_BANK_HOLIDAY_TERRITORY', 'england-and-wales'),

    // Cache duration in seconds (default: 24 hours)
    'cache_duration' => env('UK_BANK_HOLIDAY_CACHE', 86400),

    // Cache key prefix
    'cache_key_prefix' => 'uk-bank-holidays',

    // GOV.UK API URL (override for testing)
    'api_url' => env('UK_BANK_HOLIDAY_API', 'https://www.gov.uk/bank-holidays.json'),
];

Usage

Basic Usage

use Foxen\BankHolidays\Facades\BankHolidays;

// Check if a date is a bank holiday
if (BankHolidays::isHoliday('2026-01-01')) {
    echo "It's a bank holiday!";
}

// Check using a Carbon instance
if (BankHolidays::isHoliday(now())) {
    echo "No deliveries today!";
}

Available Territories

• england-and-wales (default)
• scotland
• northern-ireland

// Check a specific territory
BankHolidays::isHoliday('2026-11-30', 'scotland'); // St Andrew's Day - Scotland only

Get All Holidays for a Year

$holidays = BankHolidays::forYear(2026);

foreach ($holidays as $holiday) {
    echo $holiday->title;   // "New Year's Day"
    echo $holiday->date;    // "2026-01-01"
    echo $holiday->notes;   // Additional notes (often empty)
    echo $holiday->bunting; // true/false (decorative flag)
}

// For a specific territory
$scottishHolidays = BankHolidays::forYear(2026, 'scotland');

Get the Next Bank Holiday

// Next holiday from today
$next = BankHolidays::next();
echo $next->title; // "Good Friday"

// Next holiday from a specific date
$next = BankHolidays::next('2026-12-20');
echo $next->title; // "Christmas Day"

// Returns null if no future holidays in data
$next = BankHolidays::next('2030-01-01');

Get Holidays Within a Date Range

// Get all holidays in Q1 2026
$holidays = BankHolidays::between('2026-01-01', '2026-03-31');

// Returns empty collection if no holidays in range
$holidays = BankHolidays::between('2026-02-01', '2026-02-14');

Get Holiday Details for a Specific Date

$holiday = BankHolidays::get('2026-12-25');

if ($holiday) {
    echo $holiday->title; // "Christmas Day"
}

// Returns null if not a holiday
$holiday = BankHolidays::get('2026-01-02'); // null

Clear Cache

// Clear all cached data
BankHolidays::clearCache();

Blade Directive

Use the @bankholiday directive in your Blade templates:

{{-- Check if today is a bank holiday --}}
@bankholiday
    <p>Note: Today is a bank holiday - no deliveries!</p>
@endbankholiday

{{-- Check a specific date --}}
@bankholiday('2026-01-01')
    <p>New Year's Day - Offices closed</p>
@else
    <p>Normal working day</p>
@endbankholiday

{{-- Check with territory --}}
@bankholiday('2026-11-30', 'scotland')
    <p>St Andrew's Day - Scotland only</p>
@endbankholiday

Holiday Object

The Holiday data transfer object has the following properties:

Methods:

• toCarbon() - Returns a Carbon instance of the date
• toArray() - Converts the holiday to an array

Error Handling

The package throws specific exceptions for invalid input:

use Foxen\BankHolidays\Exceptions\InvalidDateException;
use Foxen\BankHolidays\Exceptions\InvalidTerritoryException;
use Foxen\BankHolidays\Exceptions\ApiConnectionException;

try {
    BankHolidays::isHoliday('invalid-date');
} catch (InvalidDateException $e) {
    // Handle invalid date format
}

try {
    BankHolidays::forYear(2026, 'invalid-territory');
} catch (InvalidTerritoryException $e) {
    // Handle invalid territory
}

Testing

composer test

Run tests with coverage:

composer test-coverage

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• MrKareth
• All Contributors

License

The MIT License (MIT). Please see License File for more information.