Jpl Moshier Ephemeris Php Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require jayeshmepani/jpl-moshier-ephemeris-php
   

   Ensure your PHP version is 8.3+ (FFI requirement).

2. First Use Case: Basic Ephemeris Query

   use JPL\Ephemeris\Ephemeris;
   
   // Initialize the ephemeris engine (auto-detects native lib)
   $ephemeris = new Ephemeris();
   
   // Load a built-in ephemeris file (e.g., DE440)
   $ephemeris->loadEphemeris(__DIR__.'/vendor/jayeshmepani/jpl-moshier-ephemeris-php/resources/de440.bsp');
   
   // Query the position of Earth (3) at J2000 epoch
   $time = 0.0; // JD - 2451545.0
   $result = $ephemeris->jme_ephem($time, 3, 0);
   
   if ($result['status'] === JME\JME_OK) {
       echo "Position: ["
           . $result['state'][0] . ", "
           . $result['state'][1] . ", "
           . $result['state'][2] . "]";
   }
   

3. Where to Look First

   • src/Ephemeris.php: Core class with auto-detection for native libraries.
   • resources/: Pre-bundled ephemeris files (e.g., de440.bsp).
   • libs/: OS-specific native libraries (auto-resolved).
   • tests/: Example use cases and edge-case handling.

Implementation Patterns

Core Workflows

1. Automatic Native Library Resolution

   // No manual path needed - auto-detects:
   // - Ubuntu 22/24 (glibc detection)
   // - macOS arm64 (Darwin kernel 14/15)
   // - Windows MSVC 2022
   $ephemeris = new Ephemeris(); // Uses default constructor
   

   • Custom Path Override (if needed):

     $ephemeris = new Ephemeris('/custom/path/to/libjme.so');
     

2. Ephemeris Loading

   $ephemeris = new Ephemeris();
   $ephemeris->loadEphemeris('/path/to/custom.bsp'); // Supports custom files
   

3. Time Handling

   • JD (Julian Date): All functions use JD - 2451545.0 (J2000 epoch).
   • Conversion Helper:

     $jd = JME\jme_jd2cal(2451545.0 + $time); // Convert back to Gregorian
     

4. Query Patterns

   • State Vectors (jme_ephem):

     $result = $ephemeris->jme_ephem($time, $bodyId, 0); // 0 = position + velocity
     

   • Light-Time Correction (jme_ltex):

     $correctedTime = $ephemeris->jme_ltex($time, $bodyId, $observerId);
     

5. Laravel Integration

   • Service Provider (auto-detects native lib):

     // app/Providers/EphemerisServiceProvider.php
     public function register()
     {
         $this->app->singleton(Ephemeris::class, function () {
             return new Ephemeris(); // Auto-resolves native lib
         });
     }
     

6. Caching Results

   $cacheKey = "ephemeris:{$bodyId}:{$time}";
   if (!Cache::has($cacheKey)) {
       $result = $ephemeris->jme_ephem($time, $bodyId, 0);
       Cache::put($cacheKey, $result, now()->addHours(1));
   }
   

Gotchas and Tips

Pitfalls

1. Native Library Auto-Detection

   • Fallback Behavior: If auto-detection fails, falls back to bundled libs/default.
   • Debug Detection:

     $ephemeris = new Ephemeris();
     error_log("Using library: " . $ephemeris->getNativeLibraryPath());
     

2. FFI Requirements

   • PHP FFI must be enabled in php.ini:

     extension=ffi
     

   • Verify Detection:

     if (!extension_loaded('ffi')) {
         throw new \RuntimeException('FFI extension required');
     }
     

3. Error Handling

   • Always check $result['status']:

     if ($result['status'] !== JME\JME_OK) {
         throw new \RuntimeException("JME Error: {$result['status']} - " . $result['errbuf']);
     }
     

4. Precision Warnings

   • Avoid rounding in input times/coordinates. Use raw double precision:

     $time = 123456789.123456789; // High precision
     

5. Thread Safety

   • Native libjme is NOT thread-safe. Use a single Ephemeris instance per request in Laravel.

Debugging Tips

1. Log Library Path

   error_log("Native library path: " . $ephemeris->getNativeLibraryPath());
   

2. Validate Auto-Detection

   $ephemeris = new Ephemeris();
   $libPath = $ephemeris->getNativeLibraryPath();
   if (strpos($libPath, 'default') !== false) {
       error_log("Warning: Using fallback library");
   }
   

3. FFI Debugging

   • Enable FFI logging:

     FFI::debug(true);
     

Extension Points

1. Custom Library Paths

   // Override auto-detection for specific environments
   if (app()->environment('staging')) {
       $ephemeris = new Ephemeris('/staging/libs/libjme.so');
   }
   

2. Wrap Additional Functions

   public function getBodyPosition($time, $bodyId) {
       $result = $this->jme_ephem($time, $bodyId, 0);
       return $result['state'] ?? null;
   }
   

3. Laravel Observers

   // app/Observers/AstronomicalEventObserver.php
   public function calculatingPosition($event) {
       $position = app(Ephemeris::class)->getBodyPosition($event->time, $event->bodyId);
       $event->position = $position;
   }
   

4. Performance Optimization

   • Preload Ephemeris: Load in a service container singleton.
   • Parallel Queries: Use Laravel queues with parallel: for batch processing.

Config Quirks

• No .env Config: Native library resolution is automatic.
• OS-Specific Notes:
  • Ubuntu: Detects glibc version for ubuntu22/ubuntu24 variants.
  • macOS: Detects Darwin kernel version for arm64 compatibility.
  • Windows: Uses MSVC 2022 by default.
• Fallback: If detection fails, uses libs/default/ (may require manual setup).