rahax/iranian-holidays

Laravel package for Iranian official holidays and working-day adjustments, sourced from time.ir.

v1.0.0 2026-07-21 12:28 UTC

Requires

• php: ^8.2
• illuminate/bus: ^11.0|^12.0
• illuminate/console: ^11.0|^12.0
• illuminate/database: ^11.0|^12.0
• illuminate/http: ^11.0|^12.0
• illuminate/queue: ^11.0|^12.0
• illuminate/support: ^11.0|^12.0
• morilog/jalali: ^3.0

Requires (Dev)

• orchestra/testbench: ^9.0|^10.0
• pestphp/pest: ^3.0|^4.0
• pestphp/pest-plugin-laravel: ^3.0|^4.0

MIT

• raha

Published on Packagist.org on 2026-07-21 12:59 UTC

README

Laravel package for Iranian official holidays and working-day adjustments. Holidays are fetched from time.ir and stored as holiday-only rows.

Requirements

• PHP 8.2+
• Laravel 11 or 12

Installation

composer require rahax/iranian-holidays

Publish the config (optional) and run migrations:

php artisan vendor:publish --tag=iranian-holidays-config
php artisan migrate

Fill holidays

php artisan iranian-holidays:fill --years=5 --sync

Without --sync, a queued job is dispatched.

Prune old holidays

php artisan iranian-holidays:prune --sync

Schedule weekly prune in your app's routes/console.php:

use Illuminate\Support\Facades\Schedule;

Schedule::command('iranian-holidays:prune')->weeklyOn(0, '04:00');

Working-day service

use Morilog\Jalali\Jalalian;
use Rahax\IranianHolidays\Services\IranianHolidayService;

$service = app(IranianHolidayService::class);

$date = new Jalalian(1404, 1, 1);

$service->isOfficialHoliday($date);
$service->isNonWorkingDay($date); // Thursday, Friday, or official holiday
$service->adjustToWorkingDay($date); // advances to the next working day

Non-working days are Thursday, Friday, and any date present in iranian_holidays.

Configuration

Env	Purpose
IRANIAN_HOLIDAYS_TIME_IR_API_KEY	Override the bundled time.ir public client key (only needed if it rotates)
IRANIAN_HOLIDAYS_API_BASE_URL	Default https://api.time.ir
IRANIAN_HOLIDAYS_LOCALE	Default fa
IRANIAN_HOLIDAYS_TIMEOUT	HTTP timeout in seconds
IRANIAN_HOLIDAYS_FILL_QUEUE	Queue name for fill job
IRANIAN_HOLIDAYS_PRUNE_QUEUE	Queue name for prune job

Schema

Table iranian_holidays:

• gregorian_date (unique) — write source of truth
• jalali_date (Y-m-d, unique) — filled automatically from Gregorian on save

Only holiday days are stored; presence of a row means that day is an official holiday.

License

MIT