Download the PHP package guszandy/php-aprs without Composer

php-aprs

APRS (Automatic Packet Reporting System) for PHP — a packet parser, an APRS-IS client and a packet encoder, with no runtime dependencies beyond PHP itself.

PHP has had no actively maintained APRS library, so anyone building ham radio tooling on it has been hand-rolling packet parsing. This fills that gap.

What it does: decodes every position format APRS uses (uncompressed, compressed base91, Mic-E) plus messages, status, weather, objects, items and telemetry; connects to APRS-IS with server-side filtering and automatic reconnection; and builds valid packets for transmission.

What it does not do (yet): AX.25 KISS/TNC framing over serial or a sound modem, digipeater or igate server roles, and base91 telemetry in comments.

Contents

Installation · Receiving from APRS-IS · Building packets · Compressed and Mic-E · Other packet types · Error handling · Extending the parser · Contributing

Packet type support

APRS defines 22 data type identifiers. This library decodes 13 of them, covering everything in routine use on a live feed:

Undecoded types are not errors: you still get the envelope and the payload verbatim, so nothing is lost. The remaining nine are queries (only relevant if you answer them), 1990s weather hardware, and ,, which the specification defines as invalid by design.

Requirements

• PHP 8.1+
• No PHP extensions. The APRS-IS client uses core stream sockets, so ext-sockets is not required.

Installation

Quickstart

Messages, acknowledgements and bulletins come back as MessagePacket:

Receiving from APRS-IS

A read-only login needs no passcode and can never transmit — use it for anything that only listens. To inject packets you need a real passcode, which is derived from your callsign:

The passcode is not a secret — it is a deterministic hash of the base callsign that anyone can compute, so it proves identity only in the weakest sense. Only log in with a callsign you are licensed to use.

run() takes two more optional callbacks: one for malformed lines (which never interrupt the loop) and one fired whenever a read times out, which is where you would put keepalive or shutdown checks.

Server comment lines (# banners and keepalives) are not packets and are routed separately:

run() propagates a ConnectionException when the link drops, leaving retry policy to you. If you would rather the client handled it, use runForever().

Filters

Server-side filters are how you avoid pulling the whole world feed. Clauses combine as a logical OR, so each one you add widens the stream:

Building packets

PositionEncoder builds uncompressed position reports. Every method returns a new instance, so a configured encoder makes a convenient beacon template:

You never pick the Data Type Identifier yourself — it follows from whether a timestamp is set and whether the station is messaging-capable:

Course/speed, PHG and range are mutually exclusive — a position report carries at most one data extension — so setting one replaces any previous one.

MessageEncoder handles messages, acks, rejections and bulletins:

Passing a message number is what requests an acknowledgement; omit it for fire-and-forget messages. Encoding validates as it goes and throws EncodeException rather than emitting a malformed packet — a bad packet on air wastes channel time and may be re-digipeated widely before anyone notices.

Sending one is then just:

By default packets go out as SOURCE>APZPHP,WIDE1-1,WIDE2-1:.... APZ is the reserved tocall prefix for experimental and unregistered software; the default path is one local plus one wide hop, which is the polite maximum on the congested 2 m channel.

Compressed and Mic-E positions

Both formats parse into the same PositionPacket you already handle, so code written against the uncompressed format keeps working:

Compressed reports pack the position into 13 base91 bytes instead of 19 ASCII ones, and are far more precise — about 0.3 m against 18 m. Prefer them unless you need position ambiguity, which the format cannot express.

Course and speed share two bytes with the radio range, so only one can be sent, and both come back quantised: course to 4 degrees, speed to about 8%.

Mic-E hides the latitude and several flag bits inside the destination callsign, which is why a Mic-E packet appears to be addressed to gibberish like SUSUR1. The encoder therefore generates the destination for you:

Mic-E adds a message type, including an emergency state worth checking explicitly:

Two quirks are inherent to Mic-E rather than to this library: it has no timestamp field at all, and some positions encode to bytes below 0x20, which look like control characters in a TNC monitor but are perfectly valid on air.

Other packet types

Relayed traffic

An igate passing an RF packet to APRS-IS wraps it in a } envelope. The envelope names the gateway, not the station that sent it:

Attributing a position to $packet->source would credit every relayed packet to the igate. innermost() unwraps nested envelopes, which occur when traffic crosses more than one gateway; nesting beyond three deep is rejected as a probable relay loop.

Watch the order of your instanceof checks

MicEPacket and ObjectPacket both extend PositionPacket, so that everything which works on a position works on them too. The catch is that a PositionPacket branch placed first will swallow both:

The failure is silent: you get a position with no object name and no message type, rather than an error. If you only care about coordinates, a single PositionPacket check is correct and covers all three.

Weather also rides along with positions that use the _ symbol, in which case it appears on the PositionPacket:

APRS transmits weather in US customary units, so WeatherData keeps the raw values (temperatureF, windSpeedMph, rainfall in hundredths of an inch) and offers metric equivalents as methods — nothing is lost to conversion before you decide what you want. Every field is nullable, because stations report only the sensors they have.

Objects and items can be killed, meaning receivers should remove them:

Staying connected

runForever() reconnects with exponential backoff when the link drops:

A successful reconnection resets the backoff, so a link that fails once an hour retries quickly each time instead of creeping towards the ceiling. Delays are jittered by default — without that, every client that lost the same server reconnects in lockstep and hammers its replacement.

Tests can skip the waiting entirely with setSleeper().

Error handling

Nothing is dropped silently. There are two distinct outcomes for a packet this library cannot fully decode:

• Malformed packet — a Aprs\Exception\ParseException is thrown. The exception carries the original line in $e->raw and a description in $e->reason, so you can log or re-queue it.
• Unsupported payload type — the TNC2 envelope is still returned, as an Aprs\Packet\UnknownPacket with the payload preserved verbatim.

In a receive loop, tryParse() returns null instead of throwing:

API reference

Value objects

All immutable; every mutator returns a new instance.

Packets

Packet is the immutable base type; every packet exposes source, destination, path, payload, raw and toTnc2().

Enums: DataType, MessageKind, MicEMessageType.

Parsers

Client

Encoders

Exceptions

All implement Aprs\Exception\AprsException, so one catch covers the library.

Codec

Aprs\Codec\Base91 — the base91 representation APRS uses for compressed positions, Mic-E altitude and telemetry.

Position ambiguity

APRS lets a station blank up to four low-order digits to deliberately reduce precision. Coordinate decodes the position as the centre of the ambiguous area while remembering how many digits were blanked, so the original text can be reproduced exactly:

Extending the parser

Payload decoding is pluggable. Implement Aprs\Parser\PayloadParser and register it — parsers registered later win over the built-in ones, so this is also how you override a built-in decoder:

If your parser needs to parse packets itself — as third-party traffic does — also implement Aprs\Parser\ParserAware, and the PacketParser will hand itself over. That keeps nested packets going through the same set of parsers rather than a fresh default one.

Roadmap

Beyond 1.0, in rough order of usefulness: base91 telemetry in comments, the !DAO! precision extension, query and station-capability packets, and AX.25 KISS/TNC framing for talking to real radios — which is large enough that it may belong in a separate package.

Development

CI runs a fast syntax lint first, then the suite on PHP 8.1, 8.2 and 8.3, plus PHPStan level 6 and the PSR-12 check.

The suite is 290 tests and about 2,500 assertions, with no network access required — the APRS-IS client is tested through a scripted Connection double.

Contributing

See CONTRIBUTING.md. Short version: composer check must pass, and new test vectors should come from real packets with independently published decodes rather than from this library's own output.

Bug reports for decoding problems are especially welcome — please include the raw packet exactly as received, since without it there is usually no way to reproduce the issue.

Accuracy and provenance

Decoders are validated against published decodes from independent implementations, not only against this library's own encoders. That approach caught two real bugs before release: a floating-point error in coordinate round-tripping, and a Mic-E longitude encoding fault affecting everything below 10 degrees.

Where the APRS specification and its addenda disagree — and they do, notably on the Mic-E destination table — this library follows real packets and says so in a comment.

License

MIT — see LICENSE.

Test vectors are derived from the APRS 1.0.1 protocol specification, from published decodes of other implementations, and from packets observed on air. No code is ported from GPL-licensed reference implementations such as libfap.

References

• APRS 1.0.1 protocol reference
• APRS 1.2 addendum
• APRS-IS server-side filters
• Releasing