README

NepaliDate is a dependency-free PHP library for working with the Nepali calendar (Bikram Sambat / BS) — the calendar of Nepal. It converts between AD (Gregorian) and BS, formats, parses, compares, and manipulates Nepali dates with a fluent, Carbon-inspired API, and ships first-class Laravel support (Eloquent casts, validation rules, and Blade directives).

Whether you're building a Nepali government portal, a Nepal-based e-commerce app, a school/attendance system, or just need accurate AD ⇄ BS date conversion in PHP, NepaliDate gives you a complete, tested toolkit instead of hand-rolled conversion math.

✨ Features

🕒 Full Nepali (BS) date and time support — not just year/month/day conversion
🗓 Simple, accurate conversion between AD and BS
🔁 Both mutable (NepaliDate) and immutable (NepaliDateImmutable) variants
➕ Add, subtract, and snap dates by year, month, day, hour, minute, or second
🌐 Built-in Nepali (np) and English (en) locales, with full customization support
🔢 Format dates with date()-style tokens, or use predefined format constants
🔍 Rich comparison API — isToday(), isWeekend(), between(), and more
🧩 Laravel-ready: Eloquent casts, form validation rules, and Blade directives out of the box
🔤 Standalone NepaliNumbers utility for digit, currency, and word conversion

📦 Installation

Install via Composer:

composer require rohanadhikari/nepali-date

No other setup is required for plain PHP. In Laravel, the service provider is auto-discovered — see Laravel Integration.

🚀 Quick Start

use RohanAdhikari\NepaliDate\NepaliDate;
use RohanAdhikari\NepaliDate\NepaliDateImmutable;

// Current Nepali date and time
$now = NepaliDate::now();

// Parse a natural-language notation and manipulate it
$date = NepaliDate::fromNotation('tomorrow');
$date->addDays(5);

// Convert to Gregorian (AD)
$adDate = $date->toAd();

// Format it
echo $date->format(NepaliDate::FORMAT_DATETIME_24_FULL);
// e.g. 2082-06-30 14:45:22

// Immutable variant — every mutation returns a new instance
$immutableNow = NepaliDateImmutable::now();
$newDate = $immutableNow->addDays(10); // original is unchanged

Note

Predefined format constants are listed in Constants.

Using in plain PHP (no framework)

require __DIR__ . '/vendor/autoload.php';

use RohanAdhikari\NepaliDate\NepaliDate;

$now = NepaliDate::now();
echo $now->format(NepaliDate::FORMAT_DATETIME_24_FULL);

$ad = new DateTime('now', new DateTimeZone('Asia/Kathmandu'));
echo NepaliDate::fromAd($ad)->format(NepaliDate::FORMAT_DATE_YMD);

Make sure the path to vendor/autoload.php is correct relative to your script — Composer is the recommended way to load the package.

📖 Documentation

The core README covers the essentials; everything else lives in docs/, organized by topic (Carbon-style) so you only read what you need:

Guide	Covers
Initialization	`now()`, `fromAd()`, `fromNotation()`, `fromTimestamp()`, direct construction
Formatting	Format tokens, examples, locale-aware output
Parsing	`parse()`, `createFromFormat()`, custom parse patterns
Arithmetic & Shifting	Add/subtract units, month overflow control, diff, timezone/week shifting
Getters	Year, time, day, month, timezone, and locale-based accessors
Setters	Basic, unit-based, and combined setters
Boundaries	`startOf()`/`endOf()` for day, week, month, quarter, year, decade...
Comparison	`eq()`, `between()`, `isToday()`, `isWeekend()`, and other state checks
Constants	Weekday, month, locale, and format constants
Locale Customization	Customizing month/weekday names per locale
Macros	Adding custom methods at runtime
Nepali Numbers	Digit, currency, and word conversion utilities
Calendar	Low-level BS/AD calendar math and lookup tables
Exceptions	What can be thrown, and how to guard against it
Laravel Integration	Eloquent casts, validation rules, Blade directives

🌐 Locale

Available locales: en and np.

$date = NepaliDate::now();
$date->setLocale(NepaliDate::NEPALI); // or ->locale('np')

echo $date->format(NepaliDate::FORMAT_DATETIME_24);
// Example Output: २०८२-०६-३१ २१:३४

$date->resetLocale();

Note

Set a global default for every new instance with NepaliDate::defaultLocale(NepaliDate::NEPALI). See Locale Customization to change the underlying month/weekday names.

Laravel Integration

Casts, form validation rules, and Blade directives (@nepaliDate, @nepaliNow, @nepaliWeekend, ...) are all included and auto-registered — see the Laravel Integration Guide for the full reference.

use RohanAdhikari\NepaliDate\Laravel\Casts\ADAsNepaliDate;

class Post extends Model
{
    protected function casts(): array
    {
        return ['published_at' => ADAsNepaliDate::class];
    }
}

<p>Published: @nepaliDate($post->published_at, 'l, F j, Y')</p>

🧪 Testing

composer test      # Run the Pest test suite
composer analyse    # Run PHPStan static analysis
composer format      # Run Laravel Pint

🤝 Contributing

Contributions are welcome and will be fully credited. Please read the Contributing Guide before opening an issue or pull request.

🔒 Security

If you discover a security vulnerability, please see SECURITY.md for responsible disclosure instructions instead of using the public issue tracker.

📄 License

The MIT License (MIT). See LICENSE.md for details.

rohanadhikari / nepali-date

Maintainers

Package info

Fund package maintenance!

Statistics

Security