Jpl Moshier Ephemeris Php Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require jayeshmepani/jpl-moshier-ephemeris-php:^2.0
   

   Ensure your PHP version is 8.3+ (FFI requirement). Version 2.0.0 ships JME 2.0.0 native runtimes (Linux/macOS/Windows with matching CALCEPH).

2. First Use Case: Basic Ephemeris Query

   use JPL\Ephemeris\Ephemeris;
   
   // Initialize the ephemeris engine (auto-detects native lib)
   $ephemeris = new Ephemeris();
   
   // Register the ephemeris directory (relative kernel names resolve here in 2.0)
   $ephemeris->setEphemerisDir(__DIR__.'/vendor/jayeshmepani/jpl-moshier-ephemeris-php/resources');
   
   // High-level JPL calculations open the configured kernel automatically
   $time = 0.0; // JD - 2451545.0
   $result = $ephemeris->jme_ephem($time, 3, 0); // 3 = Earth (core body)
   
   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) — also the default kernel directory root.
   • libs/: OS-specific native libraries (auto-resolved; rebuilt from JME 2.0.0 C17 source).
   • tests/: Example use cases and contract tests that document the 2.0 behaviors.

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. Kernel Loading (v2 behavior)

   • High-level JPL calculations open the configured kernel automatically — you no longer need a separate explicit loadEphemeris() before calling jme_ephem() etc.
   • Relative kernel names are resolved through the configured ephemeris directory:

     $ephemeris = new Ephemeris();
     $ephemeris->setEphemerisDir('/var/ephemeris');
     // 'de440.bsp' is now looked up under /var/ephemeris/
     $ephemeris->jme_ephem($time, 3, 0);
     

   • Absolute paths from a prior explicit loadEphemeris('/path/to/custom.bsp') still work if you prefer to be explicit.

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
     

   • Extended Bodies — use named constants (v2):

     use const JME\JME_BODY_*; // see libjme constants
     
     // Extended-body IDs moved to JME's reserved NEGATIVE range in 2.0.
     // Do NOT store raw numeric extended-body IDs; persist the symbolic name instead.
     $result = $ephemeris->jme_ephem($time, $extendedBodyConstant, 0);
     

   • Light-Time Correction (jme_ltex):

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

5. Laravel Integration

   • Service Provider (auto-detects native lib, wires the kernel directory):

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

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. BREAKING: Extended-Body Identifiers (2.0.0)

   • Extended-body IDs now live in JME's reserved negative range, separate from core-body IDs.
   • Any code that persisted raw numeric extended-body values must be migrated — switch to the corresponding named constants. Prefer persisting the symbolic name and resolving to constants at query time.
   • Method names and signatures are unchanged; the surface remains all 225 native functions / 478 public constants.

2. Unsupported Rise/Set Options Now Error

   • In 2.0, unsupported rise/set options return explicit errors instead of being silently ignored. If you relied on the old "silent no-op" behavior, validate inputs and handle the new error status.

3. Kernel Resolution Behavior Changed

   • High-level JPL calls now open the configured kernel automatically — an explicit loadEphemeris() is optional.
   • Relative kernel names resolve against the configured ephemeris directory, not the CWD. Set the directory explicitly if your kernels are not under resources/.
   • Debug detection:

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

4. FFI Requirements

   • PHP FFI must be enabled in php.ini:

     extension=ffi
     

   • Verify Detection:

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

5. Error Handling

   • Always check $result['status']:

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

6. Precision Warnings

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

     $time = 123456789.123456789; // High precision
     

7. 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. Confirm the 2.0 Runtime

   • The Linux x64 library reports version 2.0.0; verify after upgrades to be sure you are not still loading a 1.x build.

3. Validate Auto-Detection

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

4. 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 (kernel opens automatically on first high-level call in 2.0).
   • Parallel Queries: Use Laravel queues with parallel: for batch processing.

Config Quirks

• Ephemeris Directory: With 2.0's automatic kernel opening, configure the kernel directory once (e.g., ephemeris.dir in config/) so relative kernel names resolve consistently.
• Numeric House-System IDs: The house-name lookup now accepts numeric house-system identifiers (previously string-only).
• Extended-Body Display Names: Extended bodies now have consistent display names and name lookup — useful for UI/persistence over raw IDs.
• 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).