AstroPHP is a deterministic, provider-based astronomical and astrological engine for PHP.

It is designed to be:

• framework-agnostic
• network-optional
• precision-adaptive
• API-stable
• production-ready

The core engine is pure PHP and decoupled from HTTP, CMS systems, and automatic geocoding.

AstroPHP separates:

• astronomical computation
• astrological logic
• transport layer (HTTP/UI)
• geocoding
• precision strategy

The engine is deterministic by default and does not perform implicit network calls.

AstroPHP supports three interchangeable ephemeris strategies.

• pre-computed binary ephemeris tables
• offline
• very high precision for covered years
• deterministic
• default table generation range: 1700–2100 (configurable at generation time)

• pure PHP astronomical computation
• much wider date coverage (used as fallback outside table range)
• lower precision than table
• offline
• deterministic

• NASA JPL Horizons
• highest available precision
• requires network
• explicitly enabled via configuration

• If planet_provider=table, AstroPHP uses table.
• If a date is outside table range and table.fallback_to_core_on_out_of_range=true, AstroPHP falls back to core.
• If planet_provider=jpl, JPL is used explicitly.

Runtime provider selection lives in astrolib_runtime_config.php.

Main facade: src/AstroPHP.php

Available methods:

• AstroPHP\AstroPHP::natal(array $input): array
• AstroPHP\AstroPHP::ascendant(array $input): array
• AstroPHP\AstroPHP::solarReturn(array $input): array
• AstroPHP\AstroPHP::synastry(array $input): array (NOT_IMPLEMENTED)
• AstroPHP\AstroPHP::transits(array $input): array (NOT_IMPLEMENTED)
• AstroPHP\AstroPHP::progressions(array $input): array (NOT_IMPLEMENTED)

All public methods return:

[
  'ok' => bool,
  'meta' => [
    'engine' => 'astrophp',
    'version' => 'x.y.z',
    'schema_version' => '1',
    'calculation' => 'natal|ascendant|solar_return|synastry|transits|progressions',
    'timestamp_utc' => 'YYYY-MM-DDTHH:MM:SSZ',
  ],
  'data' => [ ... ],   // when ok=true
  'error' => [         // when ok=false
    'code' => 'INVALID_INPUT|OUT_OF_RANGE|CALCULATION_ERROR|INTERNAL_ERROR|NOT_IMPLEMENTED',
    'message' => 'clean user-facing message',
    'details' => [ ... ] // only when debug=true
  ]
]

Stable keys in data:

• data.planets: [{ key, lon, lat, speed, sign_key, sign_index, sign_label?, house }]
• data.houses: 12 cusps; default format is array, index 0 = house 1
• data.angles: { asc, mc, dsc, ic }
• data.aspects: [{ a, b, type, orb, applying }]
• with options.include_aspect_math=true: [{ ..., angle, delta }]
• data.context: included only with debug=true or options.include_context=true

All output floats are rounded to 8 decimals.

Units:

• angles in degrees
• speed in degrees/day

With local providers (table and core):

• no network calls
• no automatic geocoding
• same input -> same output

If jpl is enabled, network usage is explicit and intentional.

PLANET_KEYS:

• sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto, mean_node, true_node, lilith_mean, chiron

ASPECT_KEYS:

• conjunction, opposition, trine, square, sextile, quincunx, semisextile, semisquare, sesquiquadrate, quintile, biquintile

SIGN_KEYS:

• aries, taurus, gemini, cancer, leo, virgo, libra, scorpio, sagittarius, capricorn, aquarius, pisces

<?php
use AstroPHP\AstroPHP;

$result = AstroPHP::natal([
  'date' => '1990-01-15',
  'time' => '08:45',
  'timezone' => 'Europe/Rome',
  'lat' => 41.2917,
  'lon' => 13.2439,
  'house_system' => 'K',
  'options' => [
    'aspects' => true
  ],
]);

webapp/ is optional HTTP/UI integration:

• geocoding happens only there
• core engine remains strict and deterministic
• provider/geocoder strategy remains configurable

composer install
composer test

or

vendor/bin/phpunit

• src/AstroPHP.php public facade
• src/Schema.php validation and normalization
• src/Exceptions/* typed errors
• src/Services/ChartService.php business logic
• src/Services/*EphemerisProvider.php provider strategies
• src/Ephemeris/BinaryEphemerisReader.php APHE reader and interpolation
• webapp/* optional HTTP/UI layer
• tests/* PHPUnit tests

• Public API is versioned.
• Output schema is stable.
• Breaking changes follow semantic versioning.