- What Laravel versions does this package support, and are there any PHP version requirements?
- This package requires PHP 8.3+ due to its FFI dependency and has no explicit Laravel version lock, but it’s tested with Laravel 10+ and 11. The FFI extension must be enabled (`ffi.enable=true` in php.ini), which may not be available on shared hosting or legacy environments. Always verify compatibility with your Laravel kernel and PHP runtime.
- How do I install this package in a Laravel project, and where are the prebuilt binaries stored?
- Install via Composer: `composer require jayeshmepani/swiss-ephemeris-ffi`. The package automatically publishes prebuilt Swiss Ephemeris binaries to `storage/app/swisseph/` during installation. Ensure the `storage` directory is writable and not publicly accessible. No additional configuration is needed for basic usage.
- Can I use this package in Laravel queues (e.g., Horizon) or async jobs without threading issues?
- No, this package is not thread-safe due to FFI’s singleton nature and Swiss Ephemeris’s internal state. Use it only in synchronous routes, CLI commands, or single-threaded contexts. For queues, offload work to a separate process or use a facade wrapper to enforce synchronous execution. Async jobs may fail silently if multiple workers access the library simultaneously.
- Does this package support custom Swiss Ephemeris builds (e.g., modified libswisseph for research)?
- No, the package bundles prebuilt binaries (Linux/macOS/Windows) for libswisseph 2.10.3 and does not support custom builds. If you need modified versions, manually install the library to a custom path and configure the package’s `SWISSEPH_LIBRARY_PATH` environment variable. This requires rebuilding binaries and may introduce compatibility risks.
- How does error handling work, and can I integrate it with Laravel’s exception system?
- The package exposes raw C error buffers via `serr` strings. To integrate with Laravel, extend the facade or create middleware to translate `serr` into custom exceptions (e.g., `AstroCalculationException`). Example: `throw new AstroCalculationException($ffi->serr, $code)`. The README includes a basic error-handling snippet for reference.
- What’s the storage overhead for the prebuilt DE441 ephemeris files, and can I exclude asteroids?
- The full dataset (760K+ asteroids) occupies ~100MB+ in `storage/app/swisseph/`. To reduce size, exclude unnecessary `.se1` files during installation or manually delete them post-install. The package does not support partial downloads; you must manage files manually. For minimal setups, retain only essential planetary data (e.g., `planets.se1`).
- Is this package suitable for production Laravel SaaS apps, or should I consider alternatives like php-astro?
- This package is ideal for production if you need **bit-level precision** (e.g., real-time horoscopes, scientific tools) and can meet its requirements (PHP 8.3+, FFI enabled, AGPL compliance). Alternatives like `php-astro` offer higher-level abstractions but may introduce rounding errors. Choose this package only if sub-millisecond accuracy and 1:1 API parity are non-negotiable.
- How do I update to Swiss Ephemeris v3.0 when it’s released, and will it break my Laravel app?
- The package does not auto-update bundled binaries. When v3.0 is released, manually download the new binaries, replace files in `storage/app/swisseph/`, and clear Laravel’s cache (`php artisan cache:clear`). Test thoroughly, as API changes (e.g., new constants) may require facade updates. Monitor upstream announcements for breaking changes.
- Can I use this in a Laravel microservice, or is it better suited for monolithic apps?
- This package is **best for dedicated microservices** (e.g., a `CelestialService`) due to its singleton design and storage dependencies. Avoid monolithic apps where global state risks could propagate across routes. For microservices, ensure the service initializes the FFI library once and reuses it, minimizing overhead.
- What are the AGPL-3.0 license implications for my Laravel SaaS, and how can I comply?
- AGPL-3.0 requires open-sourcing your entire stack (including client-side code) if you modify or redistribute the package. Alternatives: Purchase a commercial Swiss Ephemeris license (~$500/year), restrict usage to non-commercial features, or replace the package with a permissively licensed alternative (e.g., MIT-licensed wrappers). Review the [Swiss Ephemeris licensing FAQ](https://www.astro.com/swisseph/license_en.htm) for details.