Swiss Ephemeris Ffi Laravel Package

Technical Evaluation

Architecture fit. The package is intentionally thin: a service provider, a facade, and a SwissEphFFI class that binds the Swiss Ephemeris C library through ext-ffi and exposes all 106 public C functions with 1:1 signatures and constants. For a Laravel application this is a correct shape but a dangerous default — the facade delegates raw FFI\CData buffers (double[6], char[256]) directly to the caller. That is infrastructure, not domain code. The architectural decision a TPM must enforce is that the FFI layer never leaves a dedicated service boundary: an internal EphemerisService/AstrologyCalculator interface returning typed value objects (longitude, latitude, distance, speed, retrograde flag, error enum). Every consumer — controllers, jobs, Blade, API resources — talks to that interface. This keeps the package swappable and makes a fork a weekend rather than a quarter.

Integration feasibility. Prerequisites are concrete and verifiable: PHP 8.3+, ext-ffi, ffi.enable=true (or correct preload configuration), and ephemeris .se1 data files on disk. The package bundles multi-platform native libraries and publishes them to storage/app/swisseph/ (v1.1.1 moved this off public/), which is the right deployment posture: outside the web root, no swetest CLI dependency baked into the container. Feasibility is therefore gated by environment, not by code — shared hosting and hardened container policies commonly disallow FFI. Validate host and CI capability before roadmap commitment.

Technical risk.

Key questions.

• Does legal accept AGPL-3.0, or will we purchase the Swiss Ephemeris Professional License? Answer before staffing.
• Can we guarantee ffi.enable=true across local, CI, staging, and every production target (including any managed PHP hosting)?
• Is our differentiator precision on arbitrary dates/bodies, or volume? Volume favors precomputed tables; arbitrary-query favors this package.
• Which subset of the 106 functions do we actually need? A narrow surface dramatically reduces test and support burden.
• Do we need concurrency? If yes, decide now: queue worker pool vs. dedicated ephemeris microservice.
• Who owns the upstream sync cadence (VERSION.md / UPSTREAM_SYNC.md, DE441 .se1 rebuilds)?
• Is a named internal owner accountable for the fork-if-abandoned contingency?

Integration Approach

Stack fit. Strong for Laravel on PHP 8.3+ with the facade and conventional publishing. The FFI boundary is the only exotic element; everything around it (Composer, service provider, config publish, storage paths) is idiomatic. Fit is poor for any environment where FFI is policy-disallowed, and poor for teams without a PHP engineer comfortable with C memory semantics.

Migration path. Three realistic origins:

1. From swetest shell-out — the cleanest win. Replaces a subprocess-per-request pattern with in-process calls, removes CLI dependency from images, eliminates shell-escaping and output-parsing fragility. Ship behind the adapter interface so behaviour is provably identical before cutover.
2. From a pure-PHP approximation library — expect output to change. Precision-critical features (houses, eclipses, ayanamsa, rise/set) will shift. Requires a golden-file comparison harness and a product decision about retroactive user-visible differences.
3. From the php-sweph C extension — viable only if FFI is easier to operate than a compiled extension. The published benchmark shows bit-parity and competitive performance, so the decision is operational (rebuild-on-PHP-upgrade vs. ffi.enable configuration), not accuracy.

Starting from nothing, the path is: install → publish native libs and .se1 files to storage/app/swisseph/ → thin adapter → typed DTOs → feature work.

Compatibility. Constraints to validate explicitly: PHP version floor (8.3), OS/architecture coverage of the bundled binaries (Linux/macOS/Windows documented; confirm your container base image and any ARM targets), extension availability on the chosen PHP build, and ffi.enable/preload semantics per environment. Note the documented singleton behaviour: once the FFI instance is initialized, a later custom library path is not re-applied — configuration must be resolved at boot, not lazily mid-request. Also reconcile the internal SE_VERSION string (2.10.03) against the tracked upstream tag (v2.10.3final) so version reporting in our own telemetry is unambiguous.

Sequencing.

1. Gate (before engineering): licensing decision + environment FFI proof-of-capability on one production-like target.
2. Spike (1–2 weeks): install, publish data files, compute a known chart, diff against swetest for our target bodies/house systems; measure cold-start and per-call latency in the real container.
3. Adapter: EphemerisService interface + typed result objects + centralized buffer/error handling + startup self-check for .se1 presence.
4. Regression harness: golden-file tests covering our named use cases and edge dates; wire into CI.
5. First feature slice: one user-visible capability (e.g. natal chart positions) behind a feature flag.
6. Concurrency/isolation decision: queue worker or microservice before any high-volume endpoint ships.
7. Operationalize: pinned version, documented upgrade procedure, owner assigned.

Operational Impact

Maintenance. Low code churn, non-trivial stewardship. The wrapper changes slowly; the environment does not — PHP upgrades, base-image changes, and FFI policy shifts are the real maintenance events. Upstream tracking is a genuine recurring task: pinned tag, VERSION.md/UPSTREAM_SYNC.md to reconcile, and periodic .se1 data refreshes (~dated releases; note the DE441 rebuild and the compatibility claim back to 1.67). Budget explicitly for the abandon scenario: pin indefinitely, or fork and maintain. With six stars, zero dependents, and one maintainer, assume no vendor roadmap influence.

Support. No SLA, no managed support, no compliance paper trail. Internal ownership is mandatory. Escalation for correctness questions routes to the upstream C library documentation and the parity test suite, not to the package author. The published benchmark and swetest parity tests are unusually strong evidence for a package this size — use them in design reviews, but treat "bit-level parity in verified test scenarios" as scoped, and own tests for our actual scenarios.

Scaling. The work is CPU-bound native computation, not I/O. Two distinct scaling regimes:

• On-demand, arbitrary-date queries — where the FFI path earns its keep. Scale by queue workers/processes, not by threads. Cache aggressively by (JD, body, flags, ephemeris path) since results are deterministic.
• High-volume consumer endpoints (daily horoscopes, sun-sign content) — precomputed tables are cheaper and safer. Do not put an FFI call on a hot request path by default.

Cost drivers: CPU per call, ephemeris file I/O and page cache (keep .se1 files on fast local disk, not network storage), and process count needed for isolation.

Failure modes.

• FFI disabled or extension missing → fatal at class load. Must be a startup capability check with a clear operator-facing error, not a runtime surprise.
• Missing/misconfigured .se1 files or library path → silent fallback to lower-precision or Moshier mode, or negative return with an error string in char[256]. This is the most insidious failure: the app keeps working with degraded accuracy. Enforce a boot-time data-file assertion and assert on swe_calc_ut return codes rather than truthiness.
• Native crash (segfault) → takes down the PHP-FPM worker or CLI process; no PHP exception to catch. Mitigate with process isolation (queue workers) and strict adapter discipline on buffer sizes and pointer lifetimes.
• Singleton path misconfiguration → custom library path ignored after init; document that config resolves at boot.
• Concurrency in a shared process → undefined results. Enforce synchronous, isolated execution.
• Licensing exposure → distribution of the AGPL-covered engine in a public SaaS triggers obligations. This is an operational risk with financial consequences, not a footnote.

Ramp-up. Two distinct skill requirements: (a) a PHP engineer fluent in FFI/C interop — buffer allocation, pointer lifetime, error string handling, no exception safety across the boundary; (b) domain literacy in astronomical coordinates, Julian day conventions, house systems, sidereal modes, and return-flag semantics. Neither is common. Plan 2–4 weeks for a strong generalist to be productive behind the adapter, and insist the adapter exists before anyone else touches the package. The README quick-start is accurate but the surrounding documentation (deployment, ephemeris setup, Laravel integration, troubleshooting) is external to the repo — treat onboarding as a documentation task we own, not one we inherit.