Download the PHP package dev1191/laravel-bs-eloquent without Composer

First-class Bikram Sambat (Nepali Date) Eloquent Casts, Scopes, and Validation for Laravel 10 - 13

A modern, high-performance Laravel package for Bikram Sambat (BS / Nepali Date). It stores standard Gregorian (AD) dates in your database to preserve SQL index performance, while giving you transparent Eloquent casts, scopes, Nepali fiscal year calculations, and a full suite of FormRequest validation rules.

✨ Key Features

• Automatic Eloquent Date Casting (AsBikramSambat): Write BS dates directly ($model->published_at = '2081-01-01') and let the cast automatically convert and store them as Gregorian ('2024-04-14'). When retrieved, you get a rich BsDate object.
• Configurable API / JSON Serialization: Serialize dates as dual ({"ad": "2024-04-14", "bs": "2081-01-01"}), plain bs ("2081-01-01"), ad, or full object details.
• Index-Preserving Eloquent Scopes (HasBikramSambatScopes):
  • whereBs('column', '2081-01-01')
  • whereBsMonth('column', 2081, 1)
  • whereBsYear('column', 2081)
  • whereBsBetween('column', '2081-01-01', '2081-01-31')
  • whereBsFiscalYear('column', '2080/81')
  • whereBsQuarter('column', 2081, 1)
• Built-in Nepal Fiscal Year (Aarthik Barsha): Full support for fiscal years (Shrawan 1 to Ashadh 31/32) and quarterly divisions (Q1-Q4).
• Fluent Date Arithmetic & Period Boundaries: Easily manipulate dates (addBsDays, subBsMonths, startOfBsFiscalYear, endOfBsMonth).
• Carbon Status Checks: Built-in boolean state and comparison methods (isToday(), isYesterday(), isTomorrow(), isPast(), isFuture(), isCurrentMonth(), isCurrentYear(), isSameMonth(), isSameYear()).
• Relative Time Localization (diffForHumans): Natural Nepali and English relative timestamps (e.g., “३ दिन अगाडि”, “२ महिना पछि”, or “3 days ago”).
• Extended Formatting Tokens: Full token mapping mimicking PHP's date() syntax (e.g. l, D, F, M, t, S, Q, x) with Devanagari numerals.
• Validation Rules: Complete suite of Laravel validation rules: bs_date, bs_after, bs_before, bs_fiscal_year.
• Artisan CLI Conversion Tool (php artisan bs:convert): Instant terminal conversion for any BS or AD date directly from the command line, showing Gregorian equivalent, fiscal year, fiscal quarter, and Devanagari output.
• Pure Astronomical Formula Engine: Zero hardcoded calendar arrays or third-party packages. Calculates dates directly from planetary motion, Lahiri Ayanamsa, and solar Sankranti ingress moments.
• Devanagari Numerals & Nepali Month Names: Convert and format seamlessly in Nepali (e.g. २०८१-०१-०१, बैशाख).

📦 Installation

Install the package via Composer:

Publish the configuration file (optional):

The published config/bikram-sambat.php:

🚀 Usage

1. Eloquent Model Casting

Add the cast to your model:

Writing BS Dates:

Reading BS Dates:

2. Eloquent Query Scopes

All queries automatically convert BS boundaries to Gregorian dates so your SQL index remains fast and untouched:

3. FormRequest Validation Rules

Use custom validation rules or standard string rule aliases:

4. Artisan CLI Conversion

Output:

5. Date Manipulation & Carbon Parity (BsDate)

The BsDate object provides Carbon-like fluent operations designed specifically for Bikram Sambat calendar rules:

Fluent Date Arithmetic:

Period Boundaries:

Relative Time Localization (diffForHumans):

Extended Format Tokens:

$date->format($pattern, inDevanagari: false, locale: null) supports standard PHP date() specifiers adapted to BS:

Carbon Status Checks:

5. Artisan CLI Conversion Command

Quickly inspect and convert dates directly from the command line without opening a tinker session:

Sample Output:

🧪 Testing

Run tests with Pest:

🤝 Contributing

Please see CONTRIBUTING.md for detailed guidelines on the Git workflow, branching strategy, testing requirements, and commit conventions.

📄 License

The MIT License (MIT). Please see License File for more information.