sann4ez/laravel-holidays

Laravel package to get national and public holidays with multi-driver support

1.2.1 2025-08-11 06:49 UTC

Requires

• php: ^8.1
• illuminate/contracts: ^9.0|^10.0|^11.0|^12.0
• illuminate/support: ^9.0|^10.0|^11.0|^12.0

MIT

• Kyrychuk Olexandr

• calendar
• laravel
• laravel package
• holidays
• working days
• holidayapi
• holiday api
• calendarific
• public holidays
• national holidays
• date utils
• non-working days
• sann4ez
• multi-driver
• holiday provider
• apininjas

README

Laravel package to get holidays with multi-driver support

Installation

1️⃣ Require this package using Composer:

composer require sann4ez/laravel-holidays

2️⃣ Publish the package resources:

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

🔧 Default Configuration

Here’s the default config file for reference:

<?php

return [
    'default_country' => env('HOLIDAY_DEFAULT_COUNTRY', 'UA'),

    'driver' => env('HOLIDAY_DRIVER', 'calendarific'),

    'drivers' => [
        'calendarific' => \Sann4ez\Holidays\Drivers\Calendarific::class,
        'apininjas' => \Sann4ez\Holidays\Drivers\ApiNinjas::class,              // У безкоштовному плані не можна вказувати рік, по дефолту поточний
        'holidayapi' => \Sann4ez\Holidays\Drivers\HolidayApi::class,            // Немає поточного року у безкоштовному плані
        'elevenholidays' => \Sann4ez\Holidays\Drivers\ElevenHolidays::class,
    ],

    'calendarific' => [
        'token' => env('CALENDARFIC_TOKEN', ''),
    ],

    'apininjas' => [
        'token' => env('APININJAS_TOKEN', ''),
    ],

    'holidayapi' => [
        'token' => env('HOLIDAYAPI_TOKEN', ''),
    ],

    'elevenholidays' => [
        'token' => env('ELEVENHOLIDAYS_TOKEN', ''),
    ],
];

Usage

📝 Get holidays for a year

use Sann4ez\Holidays\Facades\Holidays;

$holidays = Holidays::get();

or

use Sann4ez\Holidays\Facades\Holidays;

$holidays = Holidays::get(['country' => 'UA', 'year' => 2025], 'calendarific');

🧐 Check if a date is a holiday or weekend

use Carbon\Carbon;
use Sann4ez\Holidays\Facades\Holidays;

// Check only holidays
$isHoliday = Holidays::is(Carbon::parse('2025-01-07'));

// Check holidays and weekends
$isHolidayOrWeekend = Holidays::is(Carbon::parse('2025-01-05'), weekend: true);

// With specific driver
$isHoliday = Holidays::is(Carbon::parse('2025-01-07'), drivers: 'calendarific');

// With multiple drivers (fallback logic)
$isHoliday = Holidays::is(Carbon::parse('2025-01-07'), drivers: ['calendarific', 'holidayapi']);