innonazarene/ph-holiday-calendar

Laravel package that returns Philippine public holidays (from the Official Gazette) for your calendar.

v1.0.3 2026-04-26 12:13 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.0
• illuminate/database: ^10.0|^11.0|^12.0
• illuminate/http: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0
• symfony/css-selector: ^6.0|^7.0
• symfony/dom-crawler: ^6.0|^7.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0
• phpunit/phpunit: ^10.0|^11.0

MIT

• Tom Ramos Pedales

• calendar
• laravel
• philippines
• holidays
• official-gazette

README

A Laravel package that returns Philippine public holidays (from the Official Gazette) in a single API response.

What it returns

{
  "ph_holidays": [
    {
      "date": "2026-04-17",
      "localName": "Biyernes Santo",
      "name": "Good Friday",
      "countryCode": "PH",
      "fixed": false,
      "global": true,
      "types": ["Public"]
    }
  ],
  "activities_list": []
}

activities_list is an array provided manually by the developer. You handle your own database queries and inject the results here!

Installation

composer require innonazarene/ph-holiday-calendar

Auto-discovery registers the service provider and PhHolidayCalendar facade.

Publish config

php artisan vendor:publish --tag=ph-holiday-calendar-config

Usage

Facade

use PhHolidayCalendar\Facades\PhHolidayCalendar;

// 1. Manually query your own database, format it however you want
$myActivities = [
    [
        'id' => 1,
        'title' => 'Personal Vacation',
        'date' => '2026-05-10',
        'type' => 'personal'
    ]
];

// 2. Combined holidays + your manual activities for a month
$data = PhHolidayCalendar::forMonth(year: 2026, month: 5, activitiesList: $myActivities);
// [
//   'ph_holidays'     => [ ... ],
//   'activities_list' => [ ... ]
// ]

// Combined for a full year
$data = PhHolidayCalendar::forYear(year: 2026, activitiesList: $myActivities);

// Holidays only
$holidays = PhHolidayCalendar::holidays(2026);

// Check a specific date
PhHolidayCalendar::isHoliday('2026-12-25');      // true
PhHolidayCalendar::holidayOn('2026-12-25');       // Holiday DTO or null

Dependency injection

use PhHolidayCalendar\PhHolidayCalendar;

class MyService
{
    public function __construct(private PhHolidayCalendar $calendar) {}

    public function getCalendar(): array
    {
        // Inject your custom activities here!
        $myActivities = [];
        return $this->calendar->forMonth(2026, 4, $myActivities);
    }
}

API Routes

Add to routes/api.php:

use App\Http\Controllers\Api\CalendarController;

Route::prefix('calendar')->group(function () {
    Route::get('/',           [CalendarController::class, 'index']);      // holidays + activities
    Route::get('/holidays',   [CalendarController::class, 'holidays']);   // holidays only
    Route::get('/check',      [CalendarController::class, 'check']);      // is date a holiday?
});

See examples/CalendarController.php for the full controller.

Holiday types

types value	Meaning	Pay rule
"Public"	Regular Holiday	100% pay even if absent
"Optional"	Special Non-Working Day	No work, no pay
"WorkDay"	Special Working Day	Normal working day

License

MIT