dipesh / nepali-date
The Nepali Date package is designed for working with the Nepali calendar. It provides functionality for converting dates between the English (AD) and Nepali (BS) calendars, along with a wide range of methods for handling and manipulating Nepali dates. This comprehensive tool facilitates seamless int
Requires
- php: >=8.4
- dipesh/date: ^1.0
Requires (Dev)
- laravel/pint: ^1.17
- pestphp/pest: ^3.8
- phpstan/phpstan: ^2.3
- phpunit/phpunit: ^11.3
- rector/rector: ^2.6
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Nepali (BS) calendar dates for PHP (>= 8.4). Convert between English (AD) and Nepali (BS) calendars, format dates in English or Devanagari, compare and manipulate dates, and plug in custom calendars.
Installation
composer require dipesh/nepali-date
Quick Start
use Dipesh\NepaliDate\NepaliDate; $date = NepaliDate::make('2081-04-25'); echo $date->format('Y F d g l'); // 2081 Shrawan 25 Gate Sukrabar $date->setLang('np')->format('Y F d g l'); // २०८१ साउन २५ गते शुक्रबार
Creating Instances
use Dipesh\NepaliDate\NepaliDate; // Current date $date = NepaliDate::now(); // From a BS date string (flexible separators: / - .) $date = NepaliDate::make('2081/04/25'); $date = new NepaliDate('2081-04-25'); // From an AD (Gregorian) date $date = NepaliDate::fromADDate('2024/08/08'); // Immutable: create a new date from an existing one $other = $date->create('2082/01/01'); // Immutable: switch language $np = $date->setLang('np'); $np = $date->setLang(new \Dipesh\Date\lang\Nepali);
Date Conversion
// BS → AD (returns an EnDate, an immutable \DateTime subclass) $ad = $date->toAd(); echo $ad->format('Y-m-d'); // AD → BS $nepali = NepaliDate::fromADDate('2024/08/08'); echo $nepali->format('Y/m/d');
Date Components
All component accessors return language-aware formatted values:
$date = NepaliDate::make('2081/04/25'); $date->year(); // "2081" $date->month('m'); // "04" $date->month('F'); // "Shrawan" $date->day(); // "25" $date->weekDay('w'); // "6" $date->weekDay('D'); // "Sukra" $date->weekDay('l'); // "Sukrabar"
Raw integer values are available via getters (useful for calculations):
$date->getYear(); // 2081 $date->getMonth(); // 4 $date->getDay(); // 25 $date->getWeekDay(); // 6 $date->getDate(); // "2081/04/25"
Manipulation
All manipulation methods return new instances — the original is unchanged.
$date = NepaliDate::make('2081/04/24'); $future = $date->addDays(4); // 2081/04/28 $past = $date->subDays(4); // 2081/04/20 // In-place mutation (only on NepaliDate) $date->setUp('2082/01/01');
Comparison
$a = NepaliDate::make('2081/04/24'); $b = NepaliDate::make('2081/04/25'); $a->isEqual($b); // false $a->isGreaterThan($b); // false $a->isLessThan($b); // true $a->diffDays($b); // 1
Anniversary
isAnniversary() reports whether a date marks the anniversary of another — i.e. same month and day, regardless of year. A date is therefore its own anniversary. Omit the argument to compare against today's date (NepaliDate::now()).
$today = NepaliDate::make('2082/04/25'); $today->isAnniversary('2081/04/25'); // true (same month + day) $today->isAnniversary('2081/05/25'); // false (different month) $today->isAnniversary('2081/04/26'); // false (different day) // No argument → compare against today (NepaliDate::now()) NepaliDate::now()->isAnniversary(); // true (today is its own anniversary) NepaliDate::make('2081/04/25')->isAnniversary(); // true only when today is month 04, day 25
isBirthday() is an alias for isAnniversary() — a birthday is just the anniversary of a birth date. It accepts the same optional argument.
$baby = NepaliDate::make('2081/04/25'); $baby->isBirthday('2082/04/25'); // true $baby->isBirthday(); // true only when today is month 04, day 25
Formatting
| Character | Description | Example |
|---|---|---|
Y |
Year (4-digit) | 2081 |
m |
Month (numeric, zero-padded) | 04 |
M |
Month (short name) | (empty for English) |
F |
Month (full name) | Shrawan |
d |
Day (zero-padded) | 25 |
w |
Weekday (numeric, 1=Sun–7=Sat) | 6 |
D |
Weekday (short name) | Sukra |
l |
Weekday (full name) | Sukrabar |
g |
Half-moon indicator | Gate / गते |
$date->format('Y/m/d'); // 2081/04/25 $date->format('Y F d g l'); // 2081 Shrawan 25 Gate Sukrabar $date->format('Y-m-d', 'np'); // २०८१-०४-२५ (temporary language override) $date->setLang('np')->format('Y F d g l'); // २०८१ साउन २५ गते शुक्रबार
Calendar DataSet
By default the package uses the packaged Nepali calendar (BS 2000–2090). Pass a custom DataSet to work with a different calendar.
Custom DataSet
Each year row is 12 month day-counts (29–32). Base dates anchor AD ↔ BS conversion.
use Dipesh\NepaliDate\DataSet; use Dipesh\NepaliDate\NepaliDate; $dataSet = DataSet::make( [ 2000 => [31, 32, 31, 32, 31, 30, 30, 30, 29, 30, 29, 31], 2001 => [31, 31, 32, 31, 31, 31, 30, 29, 30, 29, 30, 30], ], '1944/01/01', // base AD date '2000/09/17', // equivalent BS date ); $date = NepaliDate::make('2000/09/17', $dataSet); echo $date->toAd()->format('Y-m-d'); // 1944-01-01
Building incrementally
$dataSet = DataSet::make() ->addRow(2000, [31, 32, 31, 32, 31, 30, 30, 30, 29, 30, 29, 31]) ->append(2001, [31, 31, 32, 31, 31, 31, 30, 29, 30, 29, 30, 30]);
Extending DataSet
Ship a reusable custom calendar by extending DataSet:
use Dipesh\NepaliDate\DataSet; class TinyDataSet extends DataSet { public function __construct(array $rows = [], ?string $baseEnglishDate = null, ?string $equivalentNepaliDate = null) { parent::__construct( $rows ?: [2000 => [30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30]], $baseEnglishDate ?? '2000/01/01', $equivalentNepaliDate ?? '2000/01/01', ); } } $dataSet = TinyDataSet::make(); // late-static-bound $date = NepaliDate::make('2000/02/01', $dataSet);
DataSets are iterable and serializable:
foreach ($dataSet as $year => $monthDays) { /* ... */ } $restored = unserialize(serialize($dataSet));
Testing
Tests use Pest. Run the full suite:
composer test # or vendor/bin/pest tests --colors
Run code style checks with Pint:
composer lint
Recommended Package for Full Calendar System
For a complete calendar system with events, navigation, and more, see dipesh/calendar:
composer require dipesh/calendar
License
Nepali Date is open source under the MIT license.