Quick start

Three calls, each one enough on its own to show the shape of the engine: a planet, a set of houses, a fixed star. Every block below was run to produce the output under it.

A planet

use Astronomy\Body;
use Astronomy\Ephemeris;
use Astronomy\Time;

$instant = new DateTimeImmutable('1981-05-11 07:15:00', new DateTimeZone('UTC'));

[$jdTT, $jdUt] = Time::fromClock($instant);

$mars = Ephemeris::position(Body::Mars, $jdTT);

echo $mars->formatted(), "\n";
echo $mars->sign()->name(), "\n";
printf("%.6f degrees per day, %s\n", $mars->speed, $mars->speed < 0 ? 'retrograde' : 'direct');

11° 54' 18" Taurus
Taurus
0.737086 degrees per day, direct

Time::fromClock() is the first thing worth understanding, because almost nothing in the engine takes a DateTimeImmutable directly. It returns a pair, [$jdTT, $jdUt], and the pair is the point: a body's position is computed in Terrestrial Time, which is a uniform clock with nothing to do with how fast the Earth happens to be spinning, while anything that depends on the Earth's own rotation (the houses, the horizon, a rise or a set) needs Universal Time instead. The two are about seventy seconds apart today, and the gap moves with delta T, which is observed and not constant. Returning both together, in that order, is what stops the two from getting mixed up: there is no method that quietly takes one where it needed the other.

$mars->speed is degrees of longitude per day, and it carries its own sign. Mars going forward here is not a coincidence of the date: the sign of the speed is the only thing that says whether a body is retrograde, and it is why Position keeps the speed attached to the position instead of as a separate call.

A set of houses

use Astronomy\Houses;
use Astronomy\HouseSystem;
use Astronomy\Time;

$instant = new DateTimeImmutable('1981-05-11 07:15:00', new DateTimeZone('UTC'));

[$jdTT, $jdUt] = Time::fromClock($instant);

$houses = Houses::calculate(HouseSystem::Placidus, $jdUt, latitude: 40.4165, geographicLongitude: -3.7026);

printf("ascendant  %8.4f\n", $houses->ascendant);
printf("midheaven  %8.4f\n", $houses->midheaven);
foreach ([1, 4, 7, 10] as $n) {
    printf("cusp %-2d    %8.4f\n", $n, $houses->cusps[$n]);
}

ascendant   85.9941
midheaven  332.0406
cusp 1      85.9941
cusp 4     152.0406
cusp 7     265.9941
cusp 10    332.0406

Notice $jdUt here, not $jdTT: houses are a question about where the sky is relative to the horizon of a place, and that is a question about how far the Earth has turned, so it takes Universal Time even though the planet a few lines above took Terrestrial Time. Cusp 1 is the ascendant and cusp 10 is the midheaven, which is why the code above prints the same numbers twice: $houses->ascendant and $houses->cusps[1] are the same angle, kept as a convenience so that a caller who thinks in cusps and one who thinks in angles do not both have to remember the mapping.

Twenty-three house systems answer to the same Houses::calculate(), by changing the first argument. Houses has the full list, what each one divides and the handful that throw instead of returning a cusp past the polar circle, where the definition itself runs out.

A fixed star

use Astronomy\Stars;
use Astronomy\Time;

$instant = new DateTimeImmutable('1981-05-11 07:15:00', new DateTimeZone('UTC'));

[$jdTT] = Time::fromClock($instant);

$regulus = Stars::find('Regulus');
$position = Stars::position($regulus, $jdTT);

echo $position->formatted(), "\n";
echo $position->sign()->name(), "\n";
echo $position->formattedDeclination(), "\n";

29° 34' Leo
Leo
+12° 04'

Stars::find() takes a name, not a designation: the catalogue carries 1,099 objects from Hipparcos-2 and SIMBAD, most of them known by a Bayer letter and a constellation rather than by anything a person would type, and find() is the door for the ones that do have a common name. The position it returns takes Terrestrial Time, like the planet above, because a star's apparent place is a light-time and aberration problem exactly the way a planet's is, only the star does not move enough for the difference to matter over a lifetime, and does move enough over a century that ignoring it is wrong.

Where each of those goes next