README

PHP SDK for the Flightradar24 API, built on PSR-18. Bring your own PSR-18 HTTP client and PSR-17 request factory; all API responses are mapped into immutable readonly DTOs.

Requirements

• PHP 8.5+
• A Flightradar24 API token
• Any PSR-18 HTTP client and PSR-17 request factory (e.g. guzzlehttp/guzzle, or symfony/http-client + nyholm/psr7)

Installation

composer require lookyman/flightradar24
# plus an HTTP client + factory, for example:
composer require guzzlehttp/guzzle guzzlehttp/psr7

Authentication

A token is required — there is no environment-variable fallback. Pass it to the Transport constructor. A blank token throws Lookyman\Flightradar24\Exception\MissingApiTokenException.

Usage

use GuzzleHttp\Client as GuzzleClient;
use GuzzleHttp\Psr7\HttpFactory;
use Lookyman\Flightradar24\Client;
use Lookyman\Flightradar24\Query\Boundary;
use Lookyman\Flightradar24\Query\FlightPositionsQuery;
use Lookyman\Flightradar24\Transport\Transport;

$client = new Client(new Transport($token, new GuzzleClient(), new HttpFactory()));

// Single object:
$airport = $client->airports->getFull('WAW');
echo $airport->name; // "Warsaw Chopin"

// List:
$positions = $client->livePositions->getLight(new FlightPositionsQuery(
    new Boundary(52.5, 52.0, 20.8, 21.3),
));
printf("Found %d aircraft.\n", count($positions));

Every call is synchronous and returns the DTO (or list<Dto>) directly. See examples/basic_usage.php.

Endpoint coverage

Query value objects

• FlightPositionsQuery — all live-position filters (bounds, callsigns, categories, altitudeRanges, gspeed, limit, …); serialises to the API's CSV query format.
• Boundary — north, south, west, east; validates latitude/longitude ranges and north > south.
• AltitudeRange — minAltitude, maxAltitude.
• HistoricFlightPositionsQuery — like FlightPositionsQuery plus a required timestamp (int unix seconds or \DateTimeInterface).
• FlightSummaryQuery — flight filters plus flightDatetimeFrom/flightDatetimeTo (string|\DateTimeInterface), sort, limit.
• FlightEventsQuery — required flightIds and eventTypes (FlightEventType|string).
• Enums: UsagePeriod (24h, 7d, 30d, 1y), FlightCategory (service-type codes), FlightEventType (takeoff, landed, …).

Error handling

Fr24Exception (extends \RuntimeException)
├── MissingApiTokenException   blank API token passed to the Transport constructor
├── TransportException         PSR-18 client failure (network/timeout) or JSON decode error
└── ApiException               non-2xx response
    ├── BadRequestException        400
    ├── AuthenticationException    401
    ├── PaymentRequiredException   402
    ├── NotFoundException          404
    └── RateLimitException         429

Any unmapped 4xx/5xx status surfaces as the base ApiException, which exposes the PSR-7 response:

use Lookyman\Flightradar24\Exception\ApiException;

try {
    $airport = $client->airports->getFull('ZZZ');
} catch (ApiException $e) {
    $status = $e->response->getStatusCode();
    $body = json_decode((string) $e->response->getBody(), true);
}

License

MIT. See LICENSE.