Search by

dipesh / nepali-date

dipeshpokhrel

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

Package info

github.com/pokhreldipesh/nepalidate

pkg:composer/dipesh/nepali-date

Statistics

Installs: 657

Dependents: 1

Suggesters: 0

Stars: 4

Open Issues: 0

3.0.2 2026-11-10 03:46 UTC

README

Version

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.