Download the PHP package nrngajurel/nepali-calendar without Composer

nrngajurel/nepali-calendar

Bikram Sambat (BS) ⇄ Gregorian (AD) date conversion for PHP, with Laravel Carbon macros that respect a configurable calendar mode. Storage stays AD; only the view layer switches — drop it into any app that needs to show dates in BS, AD, or both.

Contents

• Features
• Datepicker components
• Requirements
• Install
• Carbon macros
• Manager / facade
• Making the mode configurable per tenant / user
• Framework-agnostic converter
• Package layout
• Testing
• Changelog
• Publishing
• Contributing
• Security
• Credits
• License

Features

• Pure PHP converter (NepaliCalendarConverter) — works outside Laravel too.
• Verified against known Nepali New Year dates and round-trip tested across the entire supported range (BS 1970–2100 / AD 1914–2043) with zero drift.
• Calendar mode ('bs' vs 'ad') is resolved through a CalendarModeResolver interface — bind your own for tenant- or user-specific behaviour.
• Throws typed exceptions (InvalidNepaliDateException, UnsupportedDateRangeException) instead of silently returning null.
• Scaffolded to match laravel package (Laravel Installer ≥ v5.31.0) — Pest, Pint, Larastan, and a Testbench workbench sandbox, so it's ready for composer test / composer serve out of the box.

Datepicker components

This package ships three Blade components that wrap nrngajurel/nepali-datepicker-pro (a zero-dependency JS/CSS package, loaded via CDN by default — nothing to npm install or composer require) out of the box. Each renders an <input> using that package's own documented data-nepali-* auto-init contract, so you get a working BS/AD picker with zero JavaScript of your own:

Date Picker

Date Picker	Date Range Picker
Date Time Picker	Month Picker

The picker you show the user (BS, Nepali digits, whatever displayFormat you configure on the JS side) is never assumed to be the value you submit — submit-name injects a hidden field carrying the AD value, exactly like nepali-datepicker-pro's own submitName option. See that package's README for the full JS-side option set (min/max dates, disabled weekdays, presets, locale, etc.) — anything not exposed as a Blade prop below is still reachable by adding your own data-* attribute or calling the JS API directly on the rendered input's id.

Any attribute not listed (class, extra data-*, x-model, etc.) passes straight through to the rendered <input>.

Assets (the CDN <link>/<script> tags plus a single NepaliPicker.autoInit() call) are injected once automatically, no matter how many of the three components appear on a page. If you already bundle nepali-datepicker-pro yourself via npm, publish the config and set datepicker.load_assets to false — the components still render the correct markup, they just skip the CDN tags:

Publish the views if you want to customize the markup:

Requirements

• PHP 8.1+
• Laravel 9, 10, 11, 12, or 13 (via illuminate/contracts + illuminate/support)
• nesbot/carbon ^2.63 or ^3.0

Install

nepali-datepicker-pro itself is a plain npm/JS package — the 3 components above pull it in for you via CDN, so there's nothing extra to install unless you want to bundle it yourself (npm install nepali-datepicker-pro).

Laravel auto-discovers the service provider and the NepaliDate facade. Publish the config if you want to change defaults:

Carbon macros

display() and friends only affect presentation. Keep storing and querying dates in AD — that's what parseDisplay() is for: it takes whatever the user typed (or whatever nepali-datepicker-pro submitted) in the currently active calendar and converts it back to AD before you touch the database.

Manager / facade

For services, jobs, and Artisan commands where a Carbon instance isn't already in scope:

Or inject Nrngajurel\NepaliCalendar\NepaliCalendarManager directly.

Making the mode configurable per tenant / user

The default resolver reads a single config value, which is fine for a single-tenant app. For anything more dynamic, bind your own resolver in your own AppServiceProvider — the package never touches a global helper:

Or implement CalendarModeResolver yourself for anything more involved (caching, request-scoped state, etc.):

Framework-agnostic converter

No Laravel required:

Weekday is 1 (Sunday) .. 7 (Saturday).

Supported range

• AD input: 1914–2043
• BS input: 1970–2100

Dates outside these ranges throw UnsupportedDateRangeException. Structurally invalid dates (e.g. 13/32, Feb 30) throw InvalidNepaliDateException.

Package layout

Scaffolded to match the output of laravel package nrngajurel/nepali-calendar --config --facade --views (Laravel Installer ≥ v5.31.0, using laravel/package-skeleton) — no routes/migrations/translations, since this package doesn't need them:

If you'd rather generate a fresh scaffold yourself and diff it against this repo (e.g. after a future laravel/package-skeleton update), run:

Testing

Or individually:

The test suite includes:

• Round-trip conversion (AD → BS → AD) across the full supported range.
• Regression tests against two independently verified Nepali New Year dates (BS 2081-01-01 = 13 Apr 2024, BS 2083-01-01 = 14 Apr 2026).
• Feature tests for the Carbon macros, the resolver contract (including binding a custom resolver), and the facade.
• Feature tests for all 3 datepicker components: correct data-nepali-* markup, asset dedup across multiple components on one page, and the load_assets config toggle.
• An arch test enforcing strict_types and banning dd()/env()/exit() in package source.

Changelog

See CHANGELOG.md for release history.

Publishing

1. Push this repository to GitHub as nrngajurel/nepali-calendar.
2. Tag a release matching CHANGELOG.md: git tag v1.0.0 && git push --tags.
3. On packagist.org, "Submit" the GitHub repo URL.
4. Enable the Packagist GitHub App (or add the webhook it gives you) so future tags auto-publish without a manual "Update" click.
5. composer require nrngajurel/nepali-calendar then works anywhere.

Contributing

1. Fork and clone the repo.
2. composer install
3. Make your change, with a Pest test covering it.
4. composer test — must pass (Larastan, Pint, Pest) before opening a PR.
5. Open a PR against main. CI (.github/workflows/tests.yml) runs the same matrix across PHP 8.1–8.4 and Testbench ^9–^11.

Security

If you discover a security vulnerability, please email [email protected] instead of opening a public issue.

Credits

• Narayan Gajurel
• Datepicker UI powered by nrngajurel/nepali-datepicker-pro

License

MIT © Narayan Gajurel LICENSE.md.