README

A Laravel Nepali date converter for Bikram Sambat (BS) ↔ Gregorian (AD), with Carbon-like formatting, Nepali/English month names, and a user-editable dataset.

This package is built so your application uses a local dataset file in storage/ (not inside vendor/).
That means your app can patch/update the calendar data manually at any time — without updating the package — and your changes won’t be overwritten by composer update.

Highlights

• ✅ Convert BS → AD and AD → BS
• ✅ Flexible inputs for both directions (ints, arrays, strings, Carbon, DateTime, BsDate)
• ✅ Dataset is user‑editable at storage/app/bsad/bsad.json
  • No vendor edits required
  • Composer updates won’t overwrite your dataset
• ✅ Carbon‑like formatting
  • NepaliDateConverter::format('Y F d, l', 'np', true)
• ✅ Output in English or Nepali (month names + weekday names)
• ✅ Optional Nepali digits output
• ✅ Clean API designed to be easy to extend (more tokens/locales later)

Requirements

• PHP 8.1+
• Laravel 9 / 10 / 11 / 12
• nesbot/carbon ^2 | ^3

Installation (Packagist)

composer require nobelzsushank/nepali-date-converter

Publish config + dataset:

php artisan vendor:publish --tag=bsad-config
php artisan vendor:publish --tag=bsad-data

This creates:

• config/bsad.php
• storage/app/bsad/bsad.json ✅ (ACTIVE dataset file used at runtime)

Configuration

config/bsad.php options:

• data_path – where the app reads the dataset
  Default: storage/app/bsad/bsad.json
• update_url – dataset URL used by bs:update-data (optional)
• backup_on_update – keep backups when updating (default: true)
• locale – default locale: en or np
• nepali_digits – output digits in Nepali (true/false)

Example .env (optional updater):

BSAD_UPDATE_URL=https://example.com/bsad.json

How dataset updates work (no vendor edits)

Your app reads BS month‑day data from:

storage/app/bsad/bsad.json

So if you need to fix/extend the calendar (e.g., the package author hasn’t updated data yet), you can:

• edit storage/app/bsad/bsad.json manually, or
• point bsad.data_path to another file you manage.

✅ These changes stay in your app — Composer updates do not touch your storage/ files.

Point to a custom dataset file (optional)

In config/bsad.php:

'data_path' => storage_path('app/bsad/custom-bsad.json'),

Quick Start

AD → BS (including today)

use NobelzSushank\Bsad\Facades\NepaliDateConverter;

$bsToday = NepaliDateConverter::adToBs(now('Asia/Kathmandu'));

echo (string) $bsToday;   // "2082-11-12" (example)
echo $bsToday->year;      // 2082
echo $bsToday->month;     // 11
echo $bsToday->day;       // 12

BS → AD

use NobelzSushank\Bsad\Facades\NepaliDateConverter;

$ad = NepaliDateConverter::bsToAd(2082, 11, 14);     // CarbonImmutable
echo $ad->toDateString();             // 2026-02-26

echo NepaliDateConverter::bsToAdDateString(2082, 11, 14); // 2026-02-26

⚠️ Blade tip: BS date strings must be quoted
NepaliDateConverter::bsToAd(2082-11-14) is math in PHP. Use '2082-11-14'.

Flexible Inputs (All Supported)

BS → AD: bsToAd(...)

All of these are supported:

1) Integers (classic)

NepaliDateConverter::bsToAd(2082, 11, 14);
NepaliDateConverter::bsToAdDateString(2082, 11, 14);

2) String “YYYY-MM-DD” (also accepts /, ., spaces)

NepaliDateConverter::bsToAd('2082-11-14')->toDateString();
NepaliDateConverter::bsToAd('2082/11/14')->toDateString();
NepaliDateConverter::bsToAd('2082.11.14')->toDateString();
NepaliDateConverter::bsToAd('2082 11 14')->toDateString();

3) List array

NepaliDateConverter::bsToAd([2082, 11, 14])->toDateString();

4) Associative array

NepaliDateConverter::bsToAd(['y' => 2082, 'm' => 11, 'd' => 14])->toDateString();
NepaliDateConverter::bsToAd(['year' => 2082, 'month' => 11, 'day' => 14])->toDateString();

5) BsDate object

use NobelzSushank\Bsad\ValueObjects\BsDate;

NepaliDateConverter::bsToAd(new BsDate(2082, 11, 14))->toDateString();

✅ bsToAd() returns a CarbonImmutable in timezone Asia/Kathmandu (from dataset meta).

AD → BS: adToBs(...)

All of these are supported:

1) Any Carbon-parseable string

NepaliDateConverter::adToBs('2026-02-26');                  // -> BsDate
NepaliDateConverter::adToBs('2026-02-26 10:30:00');         // time ignored (startOfDay)
NepaliDateConverter::adToBs('next monday');                 // Carbon parsing rules apply
NepaliDateConverter::adToBsString('2026-02-26');            // -> "YYYY-MM-DD" (BS)

2) Carbon / DateTimeInterface

NepaliDateConverter::adToBs(now('Asia/Kathmandu'));         // 2082-11-14
NepaliDateConverter::adToBs(now()->toImmutable());          // 2082-11-14
NepaliDateConverter::adToBs(new DateTime('2026-02-26'));    // 2082-11-14

3) Integers or arrays

NepaliDateConverter::adToBs(2026, 2, 26);
NepaliDateConverter::adToBs([2026, 2, 26]);
NepaliDateConverter::adToBs(['y' => 2026, 'm' => 2, 'd' => 26]);
NepaliDateConverter::adToBs(['year' => 2026, 'month' => 2, 'day' => 26]);

✅ adToBs() returns a BsDate value object (year, month, day).

Carbon-like Formatting (Nepali + English)

1) Format BS date: BsDate::format(...)

adToBs() returns a BsDate which supports:

$bs = NepaliDateConverter::adToBs(now('Asia/Kathmandu'));

// Nepali month + weekday + Nepali digits
echo $bs->format('Y F d, l', 'np', true);

// English month + weekday
echo $bs->format('Y F d, l', 'en', false);

// Default format
echo $bs->format(); // "YYYY-MM-DD"

2) BS helpers: month/weekday names

$bs = NepaliDateConverter::adToBs(now('Asia/Kathmandu'));

echo $bs->monthName('np');     // e.g. "फाल्गुण"
echo $bs->monthName('en');     // e.g. "Falgun"

echo $bs->weekdayName('np');   // e.g. "बिहीबार"
echo $bs->weekdayName('en');   // e.g. "Thursday"

3) Convert BS back to AD easily

$ad = $bs->toAd();
echo $ad->toDateString();

Carbon Macros (AD side)

Carbon’s built-in format() only accepts one argument, so the package adds macros:

$ad = now('Asia/Kathmandu');

$bs = $ad->toBs(); // -> BsDate

echo $ad->formatBs('Y F d, l', 'np', true);           // AD -> BS -> formatted
echo $ad->formatAdLocalized('Y F d, l', 'np', true);  // AD formatting w/ NP month+weekday + Nepali digits

Supported Format Tokens

The formatter supports these tokens (BS side and AD-localized side):

Escaping is supported: \Y prints literal Y.

Dataset Format (JSON)

Your storage/app/bsad/bsad.json must contain:

{
  "meta": {
    "tz": "Asia/Kathmandu",
    "ad_anchor": "1943-04-14",
    "bs_anchor": { "y": 2000, "m": 1, "d": 1 }
  },
  "years": {
    "2000": [30,32,31,32,31,30,30,30,29,30,29,31]
  }
}

If you see:

BSAD dataset meta.bs_anchor invalid

it means the JSON does not match the expected schema (missing bs_anchor, wrong keys, etc.).

Supported Range

This package is data-driven, so supported years depend on your dataset.

If you try to convert a BS year not present in years, you’ll get:

Unsupported BS year XXXX. Dataset supports YYYY–ZZZZ.

To extend support, update the dataset JSON.

License

MIT — see LICENSE.

Changelog

See CHANGELOG.md.