README

A Laravel-friendly Bikram Sambat (BS) date package for converting, formatting, and manipulating Nepali dates.

Built with Carbon compatibility and a simple, developer-friendly API.

Features

AD ↔ BS date conversion
Create BS dates
Get today's Nepali date
Nepali month names
Nepali weekday names
Date formatting
Human-readable dates
Carbon conversion
Date arithmetic
Date comparison
Difference between dates
JSON serialization
Helper functions
Laravel service container integration
PSR-4 autoloading

Requirements

PHP ^8.2
Laravel 11.x or 12.x
Carbon ^3.0

Installation

Install the package via Composer:

composer require paradox/nepali-date

The Laravel service provider is automatically registered through Laravel package discovery.

Usage

Import

use Paradox\NepaliDate\NepaliDate;

You can resolve the package through Laravel's service container:

$nepaliDate = app(NepaliDate::class);

Alternatively, use dependency injection:

use Paradox\NepaliDate\NepaliDate;

class ExampleController
{
    public function index(NepaliDate $nepaliDate)
    {
        //
    }
}

Dependency injection is recommended when using the package inside controllers, services, jobs, and other Laravel classes.

Convert AD to BS

$nepaliDate = app(NepaliDate::class);

$date = $nepaliDate->parse('2026-07-31');

echo $date->format();
// 2083-04-15

echo $date->readable();
// 15 श्रावण 2083

You can also use:

$date = $nepaliDate->adToBs('2026-07-31');

Create a BS Date

$nepaliDate = app(NepaliDate::class);

$date = $nepaliDate->create(
    2083,
    4,
    15
);

echo $date->format();

// 2083-04-15

The arguments are:

year, month, day

For example:

$nepaliDate->create(2083, 4, 15);

creates:

2083-04-15

Get Today's Nepali Date

$nepaliDate = app(NepaliDate::class);

$date = $nepaliDate->today();

echo $date->format();

You can also use:

$date = $nepaliDate->now();

`today()` vs `now()`

Both return the current Nepali date.

$nepaliDate->today();
$nepaliDate->now();

Access Date Components

$nepaliDate = app(NepaliDate::class);

$date = $nepaliDate->parse('2026-07-31');

echo $date->year();
// 2083

echo $date->month();
// 4

echo $date->day();
// 15

Nepali Month Name

echo $date->monthName();

// श्रावण

You can also retrieve a month name directly:

echo $nepaliDate->monthName(4);

// श्रावण

Weekday

Get the full Nepali weekday name:

echo $date->weekName();

// शुक्रबार

You can also retrieve a weekday directly:

echo $nepaliDate->weekName(6);

Short Weekday

echo $date->shortWeek();

// शुक्र

Or:

echo $nepaliDate->shortWeek(6);

Day of Week

The package provides both standard and ISO weekday numbers.

$date->dayOfWeek();

Returns:

0 - 6

ISO weekday:

$date->dayOfWeekIso();

Returns:

1 - 7

Date Formatting

The default format is:

echo $date->format();

// 2083-04-15

You can specify a custom separator:

echo $date->format('/');

// 2083/04/15

Human-Readable Date

echo $date->readable();

// 15 श्रावण 2083

Convert BS to AD

Create a BS date:

$nepaliDate = app(NepaliDate::class);

$date = $nepaliDate->create(
    2083,
    4,
    15
);

Convert it to Carbon:

$carbon = $date->toCarbon();

echo $carbon->format('Y-m-d');

// 2026-07-31

You can also use the converter directly through the main API:

$englishDate = $nepaliDate->bsToAd(
    2083,
    4,
    15
);

Convert to Carbon

Every NepaliDate object can be converted to Carbon:

$date = $nepaliDate->create(
    2083,
    4,
    15
);

$carbon = $date->toCarbon();

You can then use Carbon functionality:

echo $carbon->format('Y-m-d');

Result:

2026-07-31

Convert to Array

$array = $date->toArray();

Example:

[
    'year' => 2083,
    'month' => 4,
    'day' => 15,
    'formatted' => '2083-04-15',
    'readable' => '15 श्रावण 2083',
    'month_name' => 'श्रावण',
    'week_name' => 'शुक्रबार',
    'short_week' => 'शुक्र',
    'ad_date' => '2026-07-31',
]

JSON Serialization

NepaliDate implements JsonSerializable.

Therefore, you can use:

return response()->json($date);

Or:

$json = json_encode($date);

The resulting JSON contains the date information:

{
  "year": 2083,
  "month": 4,
  "day": 15,
  "formatted": "2083-04-15",
  "readable": "15 श्रावण 2083",
  "month_name": "श्रावण",
  "week_name": "शुक्रबार",
  "short_week": "शुक्र",
  "ad_date": "2026-07-31"
}

Date Manipulation

Add Days

$newDate = $date->addDays(10);

Subtract Days

$newDate = $date->subDays(5);

Add One Day

$newDate = $date->addDay();

Subtract One Day

$newDate = $date->subDay();

Add Months

$newDate = $date->addMonths(2);

Subtract Months

$newDate = $date->subMonths(1);

Add One Month

$newDate = $date->addMonth();

Subtract One Month

$newDate = $date->subMonth();

Add Years

$newDate = $date->addYears(1);

Subtract Years

$newDate = $date->subYears(1);

Add One Year

$newDate = $date->addYear();

Subtract One Year

$newDate = $date->subYear();

Date Comparison

Equals

$date1 = $nepaliDate->create(
    2083,
    4,
    15
);

$date2 = $nepaliDate->create(
    2083,
    4,
    15
);

$date1->equals($date2);

// true

Before

$date1->isBefore($date2);

// true / false

After

$date1->isAfter($date2);

// true / false

Between

$date = $nepaliDate->create(
    2083,
    4,
    15
);

$start = $nepaliDate->create(
    2083,
    4,
    1
);

$end = $nepaliDate->create(
    2083,
    4,
    30
);

$date->between(
    $start,
    $end
);

// true

You can also control whether the boundaries are inclusive:

$date->between(
    $start,
    $end,
    false
);

Difference in Days

$date1 = $nepaliDate->create(
    2083,
    4,
    15
);

$date2 = $nepaliDate->create(
    2083,
    4,
    20
);

$difference = $date1->diffInDays($date2);

// 5

Helper Functions

The package also provides helper functions when the helper file is loaded.

AD to BS

ad_to_bs('2026-07-31');

BS to AD

bs_to_ad(
    2083,
    4,
    15
);

Nepali Month

nepali_month(4);

Nepali Weekday

nepali_week(6);

Short Nepali Weekday

nepali_short_week(6);

Complete Example

use Paradox\NepaliDate\NepaliDate;

class ExampleController
{
    public function index(NepaliDate $nepaliDate)
    {
        $date = $nepaliDate->parse(
            '2026-07-31'
        );

        echo $date->format();
        // 2083-04-15

        echo $date->monthName();
        // श्रावण

        echo $date->weekName();
        // शुक्रबार

        echo $date->readable();
        // 15 श्रावण 2083

        echo $date
            ->toCarbon()
            ->format('Y-m-d');

        // 2026-07-31
    }
}

Laravel Service Container

The package registers NepaliDate with Laravel's service container.

You can resolve it manually:

$nepaliDate = app(
    \Paradox\NepaliDate\NepaliDate::class
);

Or inject it into your class:

use Paradox\NepaliDate\NepaliDate;

public function index(NepaliDate $nepaliDate)
{
    $date = $nepaliDate->today();

    return $date->format();
}

Testing

The package includes PHPUnit tests.

Run the test suite from the package root:

vendor/bin/phpunit

On Windows PowerShell:

.\vendor\bin\phpunit

License

This package is open-sourced software licensed under the MIT license.

parad0x / nepali-date

Package info

Security

Statistics