Authentic Vedic Panchanga calculation engine with Swiss Ephemeris precision for PHP 8.3+.
This package provides high-precision calculations for Vedic Panchanga elements (Tithi, Vara, Nakṣatra, Yoga, Karaṇa), Muhūrta, Chogadiya, Hora, Karmakala windows, and 237 festival definitions with tradition/region profiles.
Key characteristics:
- ✅ Uses Swiss Ephemeris FFI for maximum astronomical precision
- ✅ Implements classical Indian algorithms from authentic texts
- ✅ Uses IEEE 754 double precision throughout the calculation pipeline
- ✅ Supports 237 festival definitions with tradition/region resolution
- ✅ Works standalone (no Laravel required)
- Complete Panchanga: Tithi, Vara, Nakṣatra, Yoga, Karaṇa with precise fractions
- 237 festival definitions: Holikā Dahan, Rāma Navamī, Kṛṣṇa Janmāṣṭamī, Dīpāvalī, Navaratri, Ekādaśī, Swaminarayan Jayantis, regional observances, etc.
- Festival Families: Multi-day celebrations (Holi, Diwali, Navaratri) with proper orchestration
- Muhūrta Calculations: Abhijit, Brahma Muhūrta, Rahu Kāla, Gulika, Yamaganda, Dur Muhūrta
- Time Determination: Chogadiya, Hora, Prahara, Lagna table, Bhadra/Vishti Karana detection with classical Mukha/Puchha subdivision
- Karmakala Outputs: Rahu Kāla/Gulika/Yamaganda, daylight fivefold division, Prahara, Sandhya blocks, Nishita, Vijaya, Godhuli, Gowri Panchangam, Kala Vela, Pradosha, Varjyam, Amrita Kaal
- Localization: English, Hindi, and Gujarati output via
PANCHANG_LOCALE/locale - Calendar Type Support: Amanta and Purnimanta month representation via
PANCHANG_CALENDAR_TYPE/calendar_type - Tradition Profiles: Smarta, Vaishnava, North, South, Bengal, Maharashtra, Tamil
- Classical Accuracy: Based on Sūrya Siddhānta, Muhūrta Chintāmaṇi, Nirṇaya Sindhu
composer require jayeshmepani/panchang-core- PHP 8.3+ (uses typed constants, readonly classes, enums)
- Swiss Ephemeris FFI (
jayeshmepani/swiss-ephemeris-ffi) - Carbon (
nesbot/carbon) - FFI Extension
- Swiss Ephemeris Data Files
The core engine relies on the PHP FFI (Foreign Function Interface) extension to communicate with the Swiss Ephemeris C library. This has been a foundational architectural requirement since the first version of the library to ensure maximum astronomical precision.
# Install PHP FFI
sudo apt install php8.3-ffi
# Or for PHP 8.4
sudo apt install php8.4-ffisudo dnf install php-ffi
# or
sudo yum install php-ffi# PHP from Homebrew includes FFI by default
brew install [email protected]FFI is included with PHP 8.3+ for Windows. You just need to enable it in your php.ini.
The FFI extension must be explicitly enabled. Add or uncomment the following in your php.ini:
extension=ffi
ffi.enable=1Note
ffi.enable=1 is required for CLI usage. For web server usage (FPM/Apache), you may need to set ffi.enable=preload for better security and performance.
php -r "echo extension_loaded('ffi') ? 'FFI loaded\n' : 'FFI not loaded\n';"
php -r "echo ini_get('ffi.enable') ? 'FFI enabled\n' : 'FFI not enabled\n';"The package requires .se1 data files for high-precision astronomical calculations.
- Download: You can download the verified ephemeris files from Swiss-Ephemeris-PHP Releases.
- Setup: Place these files in a directory (e.g.,
/path/to/ephe) and configure the path in your.envorconfig/panchang.php:
PANCHANG_EPHE_PATH=/absolute/path/to/ephe<?php
require 'vendor/autoload.php';
use JayeshMepani\PanchangCore\Panchanga\PanchangService;
use JayeshMepani\PanchangCore\Astronomy\AstronomyService;
use JayeshMepani\PanchangCore\Astronomy\SunService;
use JayeshMepani\PanchangCore\Panchanga\PanchangaEngine;
use JayeshMepani\PanchangCore\Panchanga\MuhurtaService;
use JayeshMepani\PanchangCore\Festivals\FestivalService;
use JayeshMepani\PanchangCore\Festivals\FestivalRuleEngine;
use JayeshMepani\PanchangCore\Festivals\Utils\BhadraEngine;
use SwissEph\FFI\SwissEphFFI;
use Carbon\CarbonImmutable;
// Initialize services
$sweph = new SwissEphFFI();
$ruleEngine = new FestivalRuleEngine();
$panchang = new PanchangService(
$sweph,
new SunService($sweph),
new AstronomyService($sweph),
new PanchangaEngine(),
new MuhurtaService(),
new FestivalService($ruleEngine),
new BhadraEngine()
);
// Calculate panchanga for a specific date/location
$date = CarbonImmutable::parse('2026-03-24');
$details = $panchang->getDayDetails(
date: $date,
lat: 23.2472446,
lon: 69.668339,
tz: 'Asia/Kolkata'
);
// Access panchanga elements
echo "Tithi: " . $details['Tithi']['name'] . " (" . $details['Tithi']['paksha'] . ")\n";
echo "Nakshatra: " . $details['Nakshatra']['name'] . " (Pada " . $details['Nakshatra']['pada'] . ")\n";
echo "Yoga: " . $details['Yoga']['name'] . "\n";
echo "Karana: " . $details['Karana']['name'] . "\n";
echo "Vara: " . $details['Vara']['name'] . "\n";<?php
use JayeshMepani\PanchangCore\Facades\Panchang;
use Carbon\CarbonImmutable;
// Calculate panchanga
$details = Panchang::getDayDetails(
date: CarbonImmutable::parse('2026-03-24'),
lat: 23.2472446,
lon: 69.668339,
tz: 'Asia/Kolkata'
);
// Festivals are included in day details
$festivals = $details['Festivals'];
// Full daily Muhurta evaluation (no manual field extraction required)
$muhurta = Panchang::getDailyMuhurtaEvaluation(
date: CarbonImmutable::parse('2026-03-24'),
lat: 23.2472446,
lon: 69.668339,
tz: 'Asia/Kolkata'
);
// Get month-wise calendar summary (ideal for grid views)
$calendar = Panchang::getMonthCalendar(
year: 2026,
month: 4,
lat: 23.2472446,
lon: 69.668339,
tz: 'Asia/Kolkata'
);OutputGeneratorService (for programmatic JSON payload assembly):
generateFestivals(
int $year,
float $lat,
float $lon,
string $tz,
float $elevation = 0.0,
CalendarType|string $calendarType = CalendarType::Amanta,
): array
generateEclipses(
int $startYear,
int $endYear,
float $lat,
float $lon,
string $tz,
): array
generateTodayPanchang(
float $lat,
float $lon,
string $tz,
float $elevation = 0.0,
CalendarType|string $calendarType = CalendarType::Amanta,
): array
generateAll(
int $festivalYear,
int $eclipseStartYear,
int $eclipseEndYear,
float $lat,
float $lon,
string $tz,
float $elevation = 0.0,
CalendarType|string $calendarType = CalendarType::Amanta,
): arrayCliBootstrap (for standalone script bootstrap and service wiring):
CliBootstrap::init(string $baseDir): void
CliBootstrap::makePanchangService(): PanchangService
CliBootstrap::makeEclipseService(): EclipseService
CliBootstrap::makeOutputGenerator(PanchangService $panchang): OutputGeneratorServiceThis package implements algorithms from authentic Sanskrit texts with verified formulas.
Important: This is a source-integrity map, not a manuscript-critical proof. The codebase mixes:
- Direct Panchang/Jyotisha conventions (widely standard)
- Package rule mappings attributed to traditional literature
- Regional or published almanac conventions
- Modern secondary references
- Legacy/heuristic helpers
For complete details, see docs/TRADITIONAL_TEXT_SOURCES.md.
| Source | Implementation |
|---|---|
| Sūrya Siddhānta 1.29 | Tithi calculation (30 lunar days, 12° each) |
| Sūrya Siddhānta 8.1 | Nakṣatra calculation (27 lunar mansions, 13°20' each) |
| Sūrya Siddhānta 3.1-3 | Yoga calculation (27 combinations, 13°20' Sun-Moon sum) |
| Muhūrta Chintāmaṇi Chapter 2 | Karana calculation (11 half lunar days, 6° each) |
| Sūrya Siddhānta 1.10-1.11 | Muhūrta, Ghaṭikā, Pala time units |
| Source | Implementation |
|---|---|
| Muhūrta Chintāmaṇi | Universal bad tithis, Vara-Tithi Yogas |
| Bṛhat Saṃhitā | Muhurta rules, Samvatsara, Ritu |
| Māyamata | Vāstu muhurta guidance |
| Vaikhānasa Āgama | Āgama-based muhurta guidance |
| Aśvalāyana Gṛhya Sūtra | Gṛhya-sūtra muhurta guidance |
| Muhūrta Mārtaṇḍa | Advanced muhurta calculations |
| Gargiya Jyotisha | Rikta Tithi dosha |
| Source | Implementation |
|---|---|
| Nirṇaya Sindhu | Festival timing, Bhadra rules |
| Muhūrta Chintāmaṇi | Aruṇodaya, Pradoṣa, Ekadashi handling |
| Hari Bhakti Vilāsa | Vaishnava Ekadashi rules |
| Source | Implementation |
|---|---|
| Tamil Gowri/Pambu Panchangam | Gowri Panchangam (8-part day/night division) |
| Sarāvalī | Kala Vela rules (Rahu, Gulika, Yamaghantaka) |
| Aṣṭāṅga Hṛdaya | Brahma Muhurta timing |
| Charaka Saṃhitā | Muhurta concepts |
| Manusmṛti | Brahma Muhurta for Vedic study |
| Sandhyāvandanam Tradition | Sandhya windows (living tradition) |
| Source | Implementation |
|---|---|
| Swiss Ephemeris | Planetary longitudes, Ayanāṃśa, Vara |
| KP System | Varjyam (Visha Ghati) calculation |
| Ernst Wilhelm's Classical Muhurta | Bhadra subdivisions |
- ❌ Every package rule is 1:1 from a single primary text
- ❌ All regional or sectarian variants are covered
- ❌ Modern almanac conventions are identical across traditions
- ❌ Independent verification against critical Sanskrit editions
All calculations use:
- IEEE 754 double precision (53-bit significand)
- No intermediate rounding (lossless calculations)
- Binary search convergence (80 iterations, 1e-24 JD precision)
The core engine utilizes the Swiss Ephemeris (SwissEph) for maximum astronomical precision.
| Mode | Date Range | Precision | Requirement |
|---|---|---|---|
| High Precision | 13,201 BCE to 17,191 CE | 0.001 arcsec | .se1 Data Files |
| Standard (Moshier) | 3,000 BCE to 3,000 CE | 0.1 arcsec | Built-in (Automatic) |
- Planetary/Solar: 0.001 arcsec with DE431 files.
- Lunar: 3 arcsec (Moshier) / 0.001 arcsec (DE431).
- Asteroids: Main asteroids covered 5401 BCE to 5399 CE.
Ephemeris data is split into 600-year files:
- CE (AD) Dates: Files prefixed with
sepl_orsemo_(e.g.,sepl_18.se1for 1800-2400 CE). - BCE (BC) Dates: Files prefixed with
seplmorsemom. - Asteroids: Files prefixed with
se00orse0j.
For any authentic Hindu Panchanga (Tithi, Vara, Nakshatra, Yoga, Karana), Lahiri (Chitra Paksha) is the absolute mandatory legal and religious standard in India.
The panchang-core engine is permanently locked to Lahiri to ensure 100% calculation integrity. Support for alternative Ayanamsas (Raman, KP, Fagan) has been intentionally removed to prevent "wrong" dates for festivals and Nakshatras.
Publish the config file:
php artisan vendor:publish --provider="JayeshMepani\PanchangCore\PanchangServiceProvider" --tag="panchang-config"Edit config/panchang.php:
return [
'ephe_path' => env('PANCHANG_EPHE_PATH', __DIR__ . '/../ephe'),
'defaults' => [
'locale' => env('PANCHANG_LOCALE', 'en'), // en, hi, gu
'calendar_type' => env('PANCHANG_CALENDAR_TYPE', 'amanta'), // amanta, purnimanta
'measurement_system' => 'indian_metric',
'date_time_format' => 'indian_12h',
'time_notation' => '12h',
'coordinate_format' => 'decimal',
'angle_unit' => 'degree',
'duration_format' => 'mixed',
],
'festivals' => [
'default_tradition' => 'Smarta',
'default_region' => 'North',
'supported_traditions' => ['Smarta', 'Vaishnava'],
'supported_regions' => ['North', 'South', 'Bengal', 'Maharashtra', 'Tamil', 'Gujarat'],
],
'cache' => [
'enabled' => true,
'ttl' => 86400,
'prefix' => 'panchang_',
],
];- All time-like fields now include date-qualified companions as
*_iso(example:varjyam_start_iso). - Panchang day context is
sunrise -> next sunrise; times earlier than sunrise are dated to the next civil date. Varjyamsupports multiple windows per day (window_count,windows[]) and keeps top-level compatibility keys.Pradosha_Kaalis computed from night-fraction plus Trayodashi overlap and returns both base window and effective overlap window.getDayDetails()now includes dedicated Karmakala outputs:Rahu_Kaal_Gulika_YamagandaAbhijit_MuhurtaPrahara_Full_DayDaylight_Fivefold_DivisionBrahma_MuhurtaDur_Muhurta_Full_DayNishita_MuhurtaVijaya_MuhurtaGodhuli_MuhurtaSandhyaGowri_PanchangamKala_VelaKarmakala_WindowsVarjyamAmrita_KaalPradosha_Kaal
getDayDetails()andgetFestivalSnapshot()now expose a richerHindu_Calendarblock.- Returned keys include:
Month_AmantaMonth_PurnimantaIs_AdhikaIs_KshayaAmanta_IndexPurnimanta_Index
PanchangServiceresolves month names using exact amavasya-to-amavasya solar transit logic, so final month output can differ from simpler longitude-only month heuristics.
Resolved festival objects include both localized display fields and calculation-basis metadata:
- Display fields:
name,description,deity,fasting,regions,aliases - Rule metadata:
calculation_basis.type,basis,tithi,paksha,month,solar_rashi,nakshatra,fixed_date,weekday,karmakala_type,adhika,relative_day - Resolver metadata:
resolution.standard_date,resolution.observance_date,resolution.is_tithi_vriddhi,resolution.is_tithi_kshaya,resolution.target_tithi_start_jd,resolution.target_tithi_end_jd, andrules_applied - Human-facing metadata has localized companion fields such as
basis_name,paksha_name,month.name,karmakala_type_name, andwinning_reason_name
The festival calculation_basis.month block follows the active calendar type only:
{
"calendar_type": "amanta",
"value": "Chaitra",
"name": "ચૈત્ર"
}For PANCHANG_CALENDAR_TYPE=purnimanta, the same field returns the purnimanta rule month only. It does not emit both amanta and purnimanta month names in a single localized output.
Use this when you want the complete all-in-one package output in a single JSON file:
php scripts/panchang_raw_output.php > output.jsonThis exporter writes five top-level sections in one JSON file:
meta: generation timestamp, location, timezone, and config sourcefestivals_2026: all festival entries for the full yeareclipses_2026_2032: all eclipse entries for 7 yearstodays_complete_details: fullgetDayDetails()payload for Bhuj (Asia/Kolkata)muhurta_evaluation: transit-onlygetDailyMuhurtaEvaluation()payload
Notes:
todays_complete_detailsis intentionally date-sensitive and changes based on the day the script is run.muhurta_evaluationis transit-only; no natal/person-specific inputs are used.- Empty arrays such as
Bhadra: []orDharma_Sindhu: []are valid outputs when no matching window exists for that Panchang day. - Saṅkrānti festivals are assigned by civil-date ingress tagging (00:00-24:00 local day), so pre-sunrise ingress stays on the same calendar date.
The scripts/ directory contains standalone exporters for common validation and integration workflows:
php scripts/panchang_today.php
php scripts/panchang_month_output.php 2026 4 > month_2026_04.json
php scripts/panchang_eclipses.php 2026 2032
php scripts/panchang_festivals.php 2026Notes:
panchang_today.phpwritestoday_panchang.jsonautomatically and prints status text only. It does not emit raw JSON to stdout and does not accept a custom output filename.panchang_month_output.phpprints JSON to stdout only; choose the output filename with shell redirection, e.g.> month_2026_04.json.panchang_eclipses.phpwriteseclipses_YYYY_YYYY.jsonautomatically and prints status text only. It does not emit raw JSON to stdout and does not accept a custom output filename.panchang_festivals.phpwritesfestivals_YYYY.jsonautomatically and prints status lines only; do not redirect its stdout as if it were raw JSON.panchang_raw_output.phpprints the complete all-in-one JSON to stdout only; choose the output filename with shell redirection, e.g.> output.json.- Use
PANCHANG_LOCALE=en|hi|guandPANCHANG_CALENDAR_TYPE=amanta|purnimantato generate localized/calendar-type variants.
To generate into a dedicated directory, redirect only stdout-based scripts and move implicit-output files after generation:
cd scripts
dir="output/amanta/gu"
mkdir -p "$dir"
PANCHANG_CALENDAR_TYPE=amanta PANCHANG_LOCALE=gu php panchang_today.php > /tmp/today.log
mv -f today_panchang.json "$dir/today.json"
PANCHANG_CALENDAR_TYPE=amanta PANCHANG_LOCALE=gu php panchang_festivals.php 2026 > /tmp/festivals.log
mv -f festivals_2026.json "$dir/festivals_2026.json"
PANCHANG_CALENDAR_TYPE=amanta PANCHANG_LOCALE=gu php panchang_month_output.php 2026 4 > "$dir/month_2026_04.json"
PANCHANG_CALENDAR_TYPE=amanta PANCHANG_LOCALE=gu php panchang_eclipses.php 2026 2032 > /tmp/eclipses.log
mv -f eclipses_2026_2032.json "$dir/eclipses_2026_2032.json"PanchangService also exposes higher-level electional helpers:
getElectionalSnapshot()getDailyMuhurtaEvaluation()
- The canonical source of truth is
FestivalService::FESTIVALS. - The current verified catalog contains
237festival definitions (FestivalService::FESTIVALS). - Festivals that legitimately share the same tithi or civil date remain separate entries when they represent different observances.
- Use
PanchangService::getFestivalYearCalendar()for complete year-wide festival output. It performs package-side date iteration, relativeday_afterfestival handling, adjacent duplicate consolidation, and yearly single-observance consolidation for configured exceptions. FestivalService::getFestivalsForYear()is intentionally disabled;FestivalServiceowns the catalog/rule payloads, whilePanchangServiceowns location-aware Panchang orchestration.
use JayeshMepani\PanchangCore\Panchanga\PanchangService;
// Configure before instantiation
PanchangService::configure(
ephePath: '/path/to/ephe'
);- Makara Saṅkrānti (solar ingress-based; civil date can vary by year/location)
- Viṣṇu Pūjā (Sep 17)
- Vasanta Pañcamī (Māgha Śukla Pañcamī)
- Mahā Śivarātri (Māgha Kṛṣṇa Chaturdaśī)
- Holikā Dahan (Phālguna Śukla Pūrṇimā)
- Rāma Navamī (Chaitra Śukla Navamī)
- Kṛṣṇa Janmāṣṭamī (Bhādrapada Kṛṣṇa Aṣṭamī)
- Gaṇeśa Chaturthī (Bhādrapada Śukla Chaturthī)
- Dīpāvalī (Kārttika Kṛṣṇa Amāvāsyā)
- Ekādaśī (twice monthly)
- Pradoṣa (twice monthly)
- Saṅkrānti (monthly)
- Holi: Holikā Dahan → Dhuleti
- Diwali: Dhanteras → Naraka Chaturdaśī → Lakṣmī Pūjā → Govardhan Pūjā → Bhai Dūj
- Janmāṣṭamī: Smarta (Aṣṭamī at sunrise) vs Vaishnava (Aṣṭamī + Niśīta + Rohiṇī)
# Run all tests
composer test
# Check code quality
composer quality# Clone repository
git clone https://github.com/jayeshmepani/panchang-core.git
cd panchang-core
# Install dependencies
composer install
# Run tests
composer test| Category | Elements | Status |
|---|---|---|
| Panchanga | Tithi, Vara, Nakṣatra, Yoga, Karaṇa | ✅ Complete |
| Muhūrta | 30 Muhūrtas (15 day + 15 night), Abhijit, Brahma, Dur Muhūrta | ✅ Complete |
| Kāla Nirṇaya | Chogadiya, Hora, Rahu Kāla, Gulika, Yamaganda, Bhadra | ✅ Complete |
| Karmakala | Rahu Kāla/Gulika/Yamaganda, daylight fivefold division, Prahara, Sandhya, Nishita, Vijaya, Godhuli, Gowri Panchangam, Kala Vela, Pradosha, Varjyam, Amrita Kaal | ✅ Complete |
| Festivals | 237 festival definitions | ✅ Complete |
| Traditions | Smarta, Vaishnava, regional | ✅ Complete |
- PHP: 8.3 or higher
- Composer: For package installation
- FFI Extension: Required for Swiss Ephemeris FFI
- jayeshmepani/swiss-ephemeris-ffi ^1.0 - Swiss Ephemeris PHP FFI wrapper
- nesbot/carbon ^3.0 - Date/time library
- Swiss Ephemeris Programmer's Documentation
- Sūrya Siddhānta Translation
- Muhūrta Chintāmaṇi Translation
Open an issue or pull request on GitHub for bug reports, source audits, or feature additions.
- Issues: GitHub Issues
- Email: [email protected]
- Exporter Script:
scripts/panchang_raw_output.php
If you find this package helpful, consider sponsoring the development:
This repository is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).
This core engine utilizes the Swiss Ephemeris, which has a dual-licensing model:
- Open Source: Licensed under GNU AGPLv3. If you use this package in an open-source project, you must also use AGPLv3.
- Commercial: If you wish to use this package in a closed-source or commercial application, you MUST purchase a commercial license from Astrodienst AG.
See the LICENSE file for the full license text.
- Dieter Koch - Swiss Ephemeris C Library Author
- Astrodienst AG - Swiss Ephemeris Maintainers
- Classical Texts: Sūrya Siddhānta, Muhūrta Chintāmaṇi, Nirṇaya Sindhu, Dharma Sindhu
Built for Vedic astrology and astronomy workflows.