https://github.com/jayeshmepani/panchang-core
High-precision Vedic Panchang engine for PHP/Laravel with Swiss Ephemeris, festivals, muhurta, eclipses, and raw JSON export.
https://github.com/jayeshmepani/panchang-core
astronomy calendar-api choghadiya eclipse festivals hindu-calendar hora jyotish laravel muhurta nakshatra open-source panchang panchanga php pradosha swiss-ephemeris tithi varjyam vedic-astrology
Last synced: 2 months ago
JSON representation
High-precision Vedic Panchang engine for PHP/Laravel with Swiss Ephemeris, festivals, muhurta, eclipses, and raw JSON export.
- Host: GitHub
- URL: https://github.com/jayeshmepani/panchang-core
- Owner: jayeshmepani
- License: other
- Created: 2026-03-24T20:31:03.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-04T15:56:17.000Z (2 months ago)
- Last Synced: 2026-04-04T18:34:19.171Z (2 months ago)
- Topics: astronomy, calendar-api, choghadiya, eclipse, festivals, hindu-calendar, hora, jyotish, laravel, muhurta, nakshatra, open-source, panchang, panchanga, php, pradosha, swiss-ephemeris, tithi, varjyam, vedic-astrology
- Language: PHP
- Homepage: https://jayeshmepani.github.io/panchang-core/
- Size: 1.1 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Panchang Core
[](https://packagist.org/packages/jayeshmepani/panchang-core)
[](https://packagist.org/packages/jayeshmepani/panchang-core)
[](https://packagist.org/packages/jayeshmepani/panchang-core)
[](https://www.gnu.org/licenses/agpl-3.0.html)
**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 163 festival definitions with tradition/region profiles.
## 🎯 Unique Value Proposition
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 **163 festival definitions** with tradition/region resolution
- ✅ Works **standalone** (no Laravel required)
## Features
- **Complete Panchanga**: Tithi, Vara, Nakṣatra, Yoga, Karaṇa with precise fractions
- **163 festival definitions**: Holikā Dahan, Rāma Navamī, Kṛṣṇa Janmāṣṭamī, Dīpāvalī, Navaratri, Ekādaśī, Swaminarayan Jayantis, 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**: Daylight fivefold division, Sandhya blocks, Nishita, Vijaya, Godhuli, Gowri Panchangam, Kala Vela, Pradosha, Varjyam, Amrita Kaal
- **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
## Installation
```bash
composer require jayeshmepani/panchang-core
```
### Requirements
- **PHP 8.3+** (uses typed constants, readonly classes, enums)
- **Swiss Ephemeris FFI** (`jayeshmepani/swiss-ephemeris-ffi`)
- **Carbon** (`nesbot/carbon`)
- **FFI Extension** (for Swiss Ephemeris)
## Usage
### Standalone Usage
```php
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";
```
### Laravel Usage
```php
env('PANCHANG_EPHE_PATH', __DIR__ . '/../ephe'),
'defaults' => [
'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_',
],
];
```
### Time Output Semantics
- 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.
- `Varjyam` supports multiple windows per day (`window_count`, `windows[]`) and keeps top-level compatibility keys.
- `Pradosha_Kaal` is computed from night-fraction plus Trayodashi overlap and returns both base window and effective overlap window.
- `getDayDetails()` now includes dedicated Karmakala outputs:
- `Daylight_Fivefold_Division`
- `Nishita_Muhurta`
- `Vijaya_Muhurta`
- `Godhuli_Muhurta`
- `Sandhya`
- `Gowri_Panchangam`
- `Kala_Vela`
- `Karmakala_Windows`
### Hindu Calendar Output
- `getDayDetails()` and `getFestivalSnapshot()` now expose a richer `Hindu_Calendar` block.
- Returned keys include:
- `Month_Amanta`
- `Month_Purnimanta`
- `Is_Adhika`
- `Is_Kshaya`
- `Amanta_Index`
- `Purnimanta_Index`
- `PanchangService` resolves month names using exact amavasya-to-amavasya solar transit logic, so final month output can differ from simpler longitude-only month heuristics.
### Raw JSON Exporter
```bash
php panchang_raw_output.php > output.json
```
This exporter writes five top-level sections in one JSON file:
- `meta`: generation timestamp, location, timezone, and config source
- `festivals_2026`: all festival entries for the full year
- `eclipses_2026_2032`: all eclipse entries for 7 years
- `todays_complete_details`: full `getDayDetails()` payload for Bhuj (`Asia/Kolkata`)
- `muhurta_evaluation`: transit-only `getDailyMuhurtaEvaluation()` payload
Notes:
- `todays_complete_details` is intentionally date-sensitive and changes based on the day the script is run.
- `muhurta_evaluation` is transit-only; no natal/person-specific inputs are used.
- Empty arrays such as `Bhadra: []` or `Dharma_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.
### Muhurta APIs
`PanchangService` also exposes higher-level electional helpers:
- `getElectionalSnapshot()`
- `getDailyMuhurtaEvaluation()`
### Festival Catalog Notes
- The canonical source of truth is `FestivalService::FESTIVALS`.
- The current verified catalog contains `163` festival definitions after merging true alias/variant duplicates.
- Festivals that legitimately share the same tithi or civil date remain separate entries when they represent different observances.
### Standalone Configuration
```php
use JayeshMepani\PanchangCore\Panchanga\PanchangService;
// Configure before instantiation
PanchangService::configure(
ephePath: '/path/to/ephe'
);
```
## Supported Festival Definitions (163)
### Solar-Based (Saṅkrānti)
- Makara Saṅkrānti (solar ingress-based; civil date can vary by year/location)
- Viṣṇu Pūjā (Sep 17)
### Tithi-Based (Major)
- 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ā)
### Recurring
- Ekādaśī (twice monthly)
- Pradoṣa (twice monthly)
- Saṅkrānti (monthly)
### Festival Families (Multi-Day)
- **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ṇī)
## Testing
```bash
# Run all tests
composer test
# Check code quality
composer quality
```
## Development
```bash
# Clone repository
git clone https://github.com/jayeshmepani/panchang-core.git
cd panchang-core
# Install dependencies
composer install
# Run tests
composer test
```
## 📊 Calculation Coverage
| 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** | Daylight fivefold division, Sandhya, Nishita, Vijaya, Godhuli, Gowri Panchangam, Kala Vela | ✅ Complete |
| **Festivals** | 163 festival definitions | ✅ Complete |
| **Traditions** | Smarta, Vaishnava, regional | ✅ Complete |
## Full System Requirements
### Core Requirements
- **PHP**: 8.3 or higher
- **Composer**: For package installation
- **FFI Extension**: Required for Swiss Ephemeris FFI
### Dependencies
- **jayeshmepani/swiss-ephemeris-ffi** ^1.0 - Swiss Ephemeris PHP FFI wrapper
- **nesbot/carbon** ^3.0 - Date/time library
## 📚 Documentation
- [Swiss Ephemeris Programmer's Documentation](https://www.astro.com/swisseph/swephprg.htm)
- [Sūrya Siddhānta Translation](https://archive.org/details/suryasiddhantate00sury)
- [Muhūrta Chintāmaṇi Translation](https://archive.org/details/muhurtachintama00vara)
## 🤝 Contributing
Open an issue or pull request on GitHub for bug reports, source audits, or feature additions.
## 📞 Support
- **Issues**: [GitHub Issues](https://github.com/jayeshmepani/panchang-core/issues)
- **Email**: [jayeshmepani777@gmail.com](mailto:jayeshmepani777@gmail.com)
- **Exporter Script**: [`panchang_raw_output.php`](panchang_raw_output.php)
## 💖 Funding
If you find this package helpful, consider sponsoring the development:
[](https://github.com/sponsors/jayeshmepani)
## 📄 License
This repository is licensed under the **GNU Affero General Public License v3.0 (AGPL-3.0)**.
### Swiss Ephemeris Licensing
This core engine utilizes the **Swiss Ephemeris**, which has a dual-licensing model:
1. **Open Source**: Licensed under **GNU AGPLv3**. If you use this package in an open-source project, you must also use AGPLv3.
2. **Commercial**: If you wish to use this package in a closed-source or commercial application, you **MUST** purchase a commercial license from [Astrodienst AG](https://www.astro.com/swisseph/swephprg.htm#licence).
See the [LICENSE](LICENSE) file for the full license text.
## 🙏 Credits
- **[Dieter Koch](https://www.astro.com/swisseph/)** - Swiss Ephemeris C Library Author
- **[Astrodienst AG](https://www.astro.com/)** - 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.