Panchang Core — Advanced Vedic Astrology Engine for PHP

Introduction

Authentic Vedic Panchanga calculation engine with Swiss Ephemeris precision.

Installation

composer require jayeshmepani/panchang-core

Quick Start

<?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\FestivalFamilyOrchestrator;
use JayeshMepani\PanchangCore\Festivals\Utils\BhadraEngine;
use SwissEph\FFI\SwissEphFFI;
use Carbon\CarbonImmutable;

// Initialize services
$sweph = new SwissEphFFI();
$ruleEngine = new FestivalRuleEngine();
$orchestrator = new FestivalFamilyOrchestrator();

$panchang = new PanchangService(
    $sweph,
    new SunService($sweph),
    new AstronomyService($sweph),
    new PanchangaEngine(),
    new MuhurtaService(),
    new FestivalService($ruleEngine, $orchestrator),
    new BhadraEngine()
);

// Calculate panchanga
$date = CarbonImmutable::parse('2026-03-24');
$details = $panchang->getDayDetails(
    date: $date,
    lat: 23.2472446,
    lon: 69.668339,
    tz: 'Asia/Kolkata'
);

echo "Tithi: " . $details['Tithi']['name'] . "\n";
echo "Nakshatra: " . $details['Nakshatra']['name'] . "\n";

Configuration

Global settings and formatting preferences available in config/panchang.php.

Default Calculation Options

The defaultsarray configures formatting representations.

Festival Calculation Settings

The festivalsarray provides defaults for region and tradition if not explicitly supplied.

Nakshatra

Enum: JayeshMepani\PanchangCore\Core\Enums\Nakshatra

use JayeshMepani\PanchangCore\Core\Enums\Nakshatra;

// Get nakshatra from moon longitude
$nakshatra = Nakshatra::fromLongitude(125.3); // Magha

echo $nakshatra->getName();          // "Magha"
echo $nakshatra->getDeity();         // "Pitṛs"
echo $nakshatra->getRulingPlanet(); // "Sun"
echo $nakshatra->getSymbol();       // "Royal Throne"

// Get pada (quarter)
$pada = Nakshatra::getPada(125.3);    // 2
echo "Pada: $pada\n";                // Pada: 2

// Get longitude range
$range = Nakshatra::Ashwini->getLongitudeRange();
echo $range['start'] . "° - " . $range['end'] . "°\n"; // 0° - 13.333°

Tithi

Enum: JayeshMepani\PanchangCore\Core\Enums\Tithi

use JayeshMepani\PanchangCore\Core\Enums\Tithi;

// Get tithi by index (1-30)
$tithi = Tithi::from(12); // Shukla Dwadashi

echo $tithi->getName();            // "Dwadashi"
echo $tithi->getPaksha()->name;    // "Shukla"

// Check paksha
if ($tithi->getPaksha() === Paksha::Shukla) {
    echo "Waxing moon phase\n";
}

// Get normalized index (1-15 for both pakshas)
echo $tithi->getNormalizedIndex(); // 12

Paksha

Enum: JayeshMepani\PanchangCore\Core\Enums\Paksha

Yoga

Enum: JayeshMepani\PanchangCore\Core\Enums\Yoga

Karana

Enum: JayeshMepani\PanchangCore\Core\Enums\Karana

Vara

Enum: JayeshMepani\PanchangCore\Core\Enums\Vara

Core Enums

Basic enumeration types used throughout the package.

PanchangService

Service: JayeshMepani\PanchangCore\Panchanga\PanchangService

AstronomyService

Service: JayeshMepani\PanchangCore\Astronomy\AstronomyService

SunService

Service: JayeshMepani\PanchangCore\Astronomy\SunService

PanchangaEngine

Service: JayeshMepani\PanchangCore\Panchanga\PanchangaEngine

$tithi = $engine->calculateTithi(350.5, 125.3);
echo $tithi['name']; // "Dwadashi"
                

MuhurtaService

Service: JayeshMepani\PanchangCore\Panchanga\MuhurtaService

EclipseService

Service: JayeshMepani\PanchangCore\Astronomy\EclipseService

BhadraEngine

Service: JayeshMepani\PanchangCore\Festivals\Utils\BhadraEngine

AstroCore

Utility: JayeshMepani\PanchangCore\Core\AstroCore

Configuration

Complete reference for config/panchang.php.

Constants & Enums

Available options for calculation parameters.

FestivalService

Service: JayeshMepani\PanchangCore\Festivals\FestivalService

$today = $panchang->getFestivalSnapshot(
    CarbonImmutable::parse('2026-03-24'),
    23.247,
    69.668,
    'Asia/Kolkata'
);
$tomorrow = $panchang->getFestivalSnapshot(
    CarbonImmutable::parse('2026-03-25'),
    23.247,
    69.668,
    'Asia/Kolkata'
);

$festivals = $festivalService->resolveFestivalsForDate(
    CarbonImmutable::parse('2026-03-24'),
    $today,
    $tomorrow
);

foreach ($festivals as $festival) {
    echo $festival['name'] . "\n";
}

Laravel Integration

Complete guide for using Panchang Core in Laravel applications.

composer require jayeshmepani/panchang-core

Configuration

Publish the configuration file:

php artisan vendor:publish --provider="JayeshMepani\PanchangCore\PanchangServiceProvider" --tag="panchang-config"

This creates config/panchang.php:

return [
    'ephe_path' => env('PANCHANG_EPHE_PATH', ''),
    'ayanamsa' => env('PANCHANG_AYANAMSA', 'LAHIRI'),
    'defaults' => [
        'tradition' => 'Smarta',
        'region' => 'North',
    ],
];

Using the Facade

use JayeshMepani\PanchangCore\Facades\Panchang;
use Carbon\CarbonImmutable;

// Get complete panchanga
$details = Panchang::getDayDetails(
    date: CarbonImmutable::parse('2026-03-24'),
    lat: 23.2472,
    lon: 69.6683,
    tz: 'Asia/Kolkata'
);

echo $details['Tithi']['name'];    // "Dwadashi"
echo $details['Nakshatra']['name']; // "Magha"

Service Container

Or inject via constructor:

use JayeshMepani\PanchangCore\Panchanga\PanchangService;

class PanchangController extends Controller
{
    public function __construct(
        private PanchangService $panchang
    ) {}

    public function show()
    {
        $details = $this->panchang->getDayDetails(
            date: CarbonImmutable::now(),
            lat: 28.6139,
            lon: 77.2090,
            tz: 'Asia/Kolkata'
        );

        return view('panchang', compact('details'));
    }
}

Return Value Structures

Complete data structures returned by main methods.

getDayDetails() Return Structure

[
  'Tithi'=>[ 'index'=>12, 'name'=>'Dwadashi', 'paksha'=>'Shukla', 'fraction_left'=>0.7666, ],
  'Nakshatra'=>[ 'index'=>10, 'name'=>'Magha', 'pada'=>2, 'lord'=>'Sun', ],
  'Yoga'=>['index'=>9, 'name'=>'Shula'],
  'Karana'=>['index'=>23, 'name'=>'Bava'],
  'Vara'=>['index'=>2, 'name'=>'Tuesday', 'lord'=>'Mars'],
  'Muhurta_Full_Day'=>[ 
    ['name'=>'Rudra', 'start'=>'06:14', 'end'=>'07:02'], // ... 30 periods
  ],
  'Chogadiya_Full_Day'=>[
    ['name'=>'Amrit', 'mode'=>'Day', 'start'=>'06:14', 'end'=>'07:46'], // ... 16 divisions
  ],
  'Hora_Full_Day'=>[
    ['planet'=>'Sun', 'start'=>'06:14', 'end'=>'07:14'], // ... 24 horas
  ],
  'Prahara_Full_Day'=>[
    ['name'=>'Pratah Prahara', 'start'=>'06:14', 'end'=>'09:18'], // ... 8 objects
  ],
  'Lagna_Full_Day'=>[
    ['sign_name'=>'Mesha', 'start'=>'06:14', 'end'=>'08:22'], // ... 12/13 signs
  ],
  'Dur_Muhurta_Full_Day'=>[
    ['name'=>'Rudra', 'start'=>'06:14', 'end'=>'07:02'], // Inauspicious Muhurtas only
  ],
  'Festivals'=>[['name'=>'Pradosh Vrat', 'type'=>'vrat']],
  'Sunrise'=>'06:14:00',
  'Sunset'=>'18:32:00',
  'Moonrise'=>'15:45:00',
  'Moonset'=>'04:20:00',
]

getFestivalSnapshot() Return Structure

[
  'Festivals' => [
    ['name' => 'Holika Dahan', 'type' => 'festival', 'priority' => 1],
  ],
  'Tithi' => [...],
  'Nakshatra' => [...],
]

Real-World Examples

Complete working examples for common use cases.

1. Daily Panchang Display

// Show today's panchang
$today = Panchang::getDayDetails(
    date: CarbonImmutable::now(),
    lat: $userLat,
    lon: $userLon,
    tz: $userTz
);

echo "Tithi: " . $today['Tithi']['name'];
echo "Nakshatra: " . $today['Nakshatra']['name'];

2. Festival Calendar

// Get festivals for entire month
$monthFestivals = [];
for ($day = 1; $day <= 31; $day++) {
    $date = CarbonImmutable::create(2026, 10, $day);
    $fest = Panchang::getFestivalSnapshot($date, $lat, $lon, $tz);
    
    if (!empty($fest['Festivals'])) {
        $monthFestivals[$day] = $fest['Festivals'];
    }
}

3. Tradition-Specific Resolution

// Smarta-style date resolution (date-scoped festivals)
$smarta = Panchang::getDayDetails(
    CarbonImmutable::parse('2026-09-06'),
    28.61, 77.20, 'Asia/Kolkata'
)['Festivals'];

// Next-day festival context (for comparison)
$vaishnava = Panchang::getDayDetails(
    CarbonImmutable::parse('2026-09-07'),
    28.61, 77.20, 'Asia/Kolkata'
)['Festivals'];

4. Birth Chart Basics

// Get planetary positions for a birth date
$birthData = [
    'year' => 1990, 'month' => 5, 'day' => 15,
    'hour' => 14, 'minute' => 30, 'second' => 0,
    'tz' => 'Asia/Kolkata', 'lat' => 28.61, 'lon' => 77.20
];

$planets = $astronomy->getPlanets($birthData);
$ascendant = $astronomy->getAscendant($birthData);

echo "Sun: " . $planets['Sun'] . "°\n";
echo "Ascendant: " . $ascendant . "°";

5. Comprehensive Full-Day Data

// Get all advanced time divisions for a date
$details = Panchang::getDayDetails($date, $lat, $lon, $tz);

$lagnas   = $details['Lagna_Full_Day'];     // Exact Sign entry times
$horas    = $details['Hora_Full_Day'];       // 24 planetary rulers
$praharas = $details['Prahara_Full_Day'];    // 8 canonical periods
$muhurtas = $details['Muhurta_Full_Day'];    // 30 named Muhurtas
$durs     = $details['Dur_Muhurta_Full_Day']; // Inauspicious Muhurtas

Accuracy & Date Range

Technical specifications of the Swiss Ephemeris astronomical engine.

Error Handling

Understanding and handling errors.

Common Exceptions

Best Practices

try {
    $details = Panchang::getDayDetails(
        date: $date,
        lat: $lat, // Validate: -90 to 90
        lon: $lon, // Validate: -180 to 180
        tz: $tz    // Validate: timezone_exists($tz)
    );
} catch (RuntimeException $e) {
    Log::error('Panchang calculation failed', [
        'error' => $e->getMessage(),
        'location' => compact('lat', 'lon', 'tz')
    ]);

    return response()->json([
        'error' => 'Unable to calculate panchang for this location'
    ], 500);
}

FAQ & Troubleshooting

Common questions and solutions.

License

Quick Reference