Road to 2.x

[Sibyx]

Motivation

Greetings, all! It's been quite a few years since the 1.x release of the phpGPX library, which was built upon an API from way back in 2018. That version harks back to the PHP5 era, and since then, we've seen the introduction of PHP 7.x and 8.x. It seems like the right time to begin contemplating a significant update for phpGPX, an exciting opportunity to incorporate lessons learned from past mistakes, and integrate some of the innovative features now available in PHP such as typing - a function that would be particularly fitting for this project.

This discussion post serves as a platform for me to collate my thoughts and ideas, and for you to provide your invaluable feedback and suggestions. I welcome any ideas for new features, or alternative viewpoints on the plans I've proposed. This is an open discussion, so if you disagree with any aspect of the plan, feel free to voice your thoughts, and we'll take it from there.

Proposed Changes and Improvements

• The new phpGPX will be built upon PHP 8.1, and we won't be offering support for older versions.
• We will introduce strict typing.
• We'll transition to using objects in place of arrays (for Stats and so forth).
• The existing documentation will be revamped completely (the current state leaves much to be desired).
• We will reevaluate the implementation of GPX extensions, aiming to enhance interoperability as much as possible and introduce a certain degree of customization.
• We will get rid of the Summarizable interface and it's toArray method. Models will use \JsonSerializable interface and return GeoJSON

Interesting Aspects

• We will conduct a performance comparison between versions 1.x and 2.x.

Project Roadmap

• Upgrade to PHPUnit 10.
• Documentation
• Introduce strict typing.
• Convert to an object-oriented approach.
• Introduce middlewares.
• Extension processing (create an universal approach) - Implementing way point and creation time extensions #41
• Statistics - get Bounds of the GPX Routes #28
• startedAt and finishedAt values are not present if the first (or last) point is without timestamp #51
• Further steps to be determined based on discussions and feedback.

All ideas and suggestions are welcome! I'm excited to see where this journey takes us. The future 2.x version lives in develop branch.

[Sibyx]

Strict typing

Dilema

I found an interesting point that I would like. to address - the trade-off between strictness and flexibility in the new version of the library. Here's the dilemma:

On one hand, if we introduce strict typing and enforce mandatory properties as per the GPX schema, we could potentially achieve more reliable and bug-free code. This would ensure that all necessary properties are present and correctly typed, leading to a more robust library.

However, on the other hand, this could limit the usability of the library for GPX files that are missing minor attributes. For example, if a GPX file does not include the 'name' attribute within the copyright section, under strict rules, it would be deemed "invalid", preventing the library from processing it, despite the rest of the file being perfectly valid and usable.

Let's take a look at an example GPX file:

<gpx>
    <metadata>
        <name>Example GPX</name>
        <copyright>
            <!-- Missing 'name' attribute here -->
            <year>2023</year>
            <license>http://example.com/license</license>
        </copyright>
    </metadata>
    <!-- More GPX data -->
</gpx>

With strict typing and enforced mandatory attributes, this GPX file would be considered invalid due to the absence of the 'name' attribute in the copyright element. This could restrict the library from processing it.

Hence, the challenge we face is to determine the right balance between maintaining the strictness that comes with adherence to the GPX schema, and ensuring the flexibility to handle GPX files which may not completely follow the schema.

Solution

Properties will be defined as nullable for the sake of input flexibility. The values will be converted to correct type if possible.

[ChristianAdamski]

I think that's not the best idea. Why? I have no professional interest in GPX, I was just ask by other Drupal users to implment this. I therefor simply asked two friends to provide personal fitness GPX files. One provided by a Garmin watch, the other by a Bosch Thingie.

Neither contains a name attribute there.

So I would try to represent real life here as best as possible. Which seems to be that large corporation tend to ignore specs?

[Sibyx]

That's exactly what I was afraid of. However, the idea of defining every property as nullable freaks me out. I agree that we should try to be as close to reality as possible, even though it's somewhat disheartening. I've been wondering whether there will be any significant performance impact. To sum up, I will try to keep the code as flexible for the input as possible.

[Sibyx]

You were absolutely right. This is exactly what we ended up doing — all model properties that correspond to optional GPX elements are nullable typed properties. For example in Point:

public ?float $elevation = null;
public ?\DateTime $time = null;
public ?string $name = null;

Real-world GPX files from Garmin, Bosch, Strava, etc. parse just fine — we don't reject anything that's valid XML. The strict typing applies to the PHP side (you get ?float instead of mixed), not to what the parser accepts. So you get type safety without sacrificing compatibility with messy real-world files.

[Sibyx]

Middlewares

The additional computational processes for statistical analysis can be managed through middleware that implement the library interface. These middleware will execute in a specified sequence, post GPX parsing, following the basic statistical computations (or the library may include some middleware for elementary stats by default). To better understand my concept, consider the code below. It is merely a rough draft, hence open to modifications.

$phpgpx = new \phpGPX();

$phpgpx->middlewares->add(new \phpGPX\Middlewares\GpxReductionSmoothingMiddleware(2, 5));
$phpgpx->middlewares->add(new \phpGPX\Middlewares\TrackPointExtensionStatsMiddleware());
$phpgpx->middlewares->add(new CustomMiddleware());

$file = $phpgpx->load('example.gpx');

Implementing such a layer should substantially simplify the extension or modification of the library's behavior. I aim to develop a preliminary model for this layer. This should enhance the library's configurability (I'm not particularly fond of the current use of constants for this purpose).

[ChristianAdamski]

Just out of curiosity, why not turn this around? Have phpGPX represent (only) the GPX data. And then hand that over?

$data = new \phpGPX();
$magic = new \phpGPX\MagicExtensionWhatever();
$magic->load($data);
$magic->doSomething();

[Sibyx]

I would like to keep it inside the core models and later create an XSD schema as an extension for that purpose. I do not want to pass the data as a reference. I hope that it makes sense.

[Sibyx]

I ended up agreeing with your instinct here more than my original proposal. The middleware idea was over-engineered — chaining arbitrary transforms on the parsed data added complexity without clear benefit.

What we have instead is a single-pass Engine with pluggable analyzers. The key difference from middleware:

• Models stay clean — they're pure data containers, no processing logic
• Engine is opt-in — if you just want to parse/serialize GPX, don't pass an engine and no stats are computed
• Analyzers are composable — pick only what you need, configure each independently

// Just parse, no stats
$gpx = new phpGPX();
$file = $gpx->load('track.gpx');

// Parse + compute stats
$gpx = new phpGPX(engine: Engine::default());
$file = $gpx->load('track.gpx');
echo $file->tracks[0]->stats->distance;

This is essentially the separation you suggested — phpGPX represents GPX data, and the Engine is a separate concern that processes it. No data passed by reference, no mutation chains.

For more information check:

• phpGPX: Statistics
• phpGPX: Statistics Architecture

[Sibyx]

Removal of Summarizable and toArray

As part of the new major release, I propose the removal of the Summarizable interface along with its toArray method. This decision stems from my belief that all models should instead implement the JsonSerializable interface, thereby returning a GeoJSON compatible result where feasible.

The usage of arrays in this context seems antiquated and unnecessarily complex, hence it doesn't align with the direction of our project. I anticipate that the removal of these features won't be a significant loss for the users. However, I welcome any thoughts and potential concerns about this proposed change.

[ChristianAdamski]

Love it. Love every part of it.

[Sibyx]

Done! Summarizable and toArray() are gone. All models implement JsonSerializable and return GeoJSON (RFC 7946). The output is a proper FeatureCollection with tracks/routes as LineString geometries and waypoints as Point geometries.

[Sibyx]

phpGPX 2.0.0-beta.1 is out

Hey everyone! It's been a while since the last update, so here's a wrap-up of everything that has landed on the develop branch since the 2.x discussion started. The branch is now at 2.0.0-beta.1

New features

Removed legacy interfaces

The 1.x codebase carried several interfaces that added complexity without real value:

• Summarizable / toArray() removed — replaced by JsonSerializable returning GeoJSON (RFC 7946). Models now implement jsonSerialize() directly.
• GpxSerializable removed — this was a dead interface. Parsers handle all XML serialization via the Data Mapper pattern, so models don't need to know about XML.
• StatsCalculator interface removed — stats computation is now handled by the Engine (see below).

Single-pass stats Engine

The middleware idea I originally proposed didn't work out — it was over-engineered for what we need. Instead, I built a single-pass Engine with pluggable analyzers:

$gpx = new phpGPX(engine: Engine::default());
$file = $gpx->load('track.gpx');
// Stats are computed automatically
echo $file->tracks[0]->stats->distance;

The engine walks each segment's points once, calling all registered analyzers. Built-in analyzers:

Analyzer	What it computes
DistanceAnalyzer	Cumulative distance (with optional smoothing)
ElevationAnalyzer	Elevation gain/loss (with optional smoothing + spike filtering)
AltitudeAnalyzer	Min/max altitude with coordinates
TimestampAnalyzer	Start/end timestamps with coordinates, duration
BoundsAnalyzer	Coordinate bounds (min/max lat/lon)
MovementAnalyzer	Moving duration, moving average speed
TrackPointExtensionAnalyzer	Heart rate, cadence, temperature aggregates

For fine-grained control you can build the engine manually and pick only the analyzers you need:

$engine = (new Engine())
    ->addAnalyzer(new DistanceAnalyzer(applySmoothing: true, smoothingThreshold: 3))
    ->addAnalyzer(new ElevationAnalyzer(applySmoothing: true, spikesThreshold: 100))
    ->addAnalyzer(new AltitudeAnalyzer());

Extension Registry

Extensions are no longer hardcoded. A new ExtensionRegistry maps XML namespace URIs to parser classes:

• ExtensionInterface on models — defines getTagName(), getNamespace(), jsonSerialize()
• ExtensionParserInterface on parsers — defines parse(), toXML(), getTagName(), getNamespace()
• Extensions model is now a keyed collection: $point->extensions->get(TrackPointExtension::class)
• Default registry auto-registers Garmin TrackPointExtension v1 + v2
• Custom extensions:

$gpx = new phpGPX();
$gpx->registerExtension('http://example.com/ext/v1', MyExtensionParser::class, 'myext');

Instance-based configuration

All static config properties on the phpGPX class are gone. Configuration is now split:

• Config value object — output-only settings (prettyPrint)
• Analyzer constructors — processing config (smoothing thresholds, spike filtering, etc.)
• Engine::default() factory — convenient defaults with named parameters

$gpx = new phpGPX(
    config: new Config(prettyPrint: true),
    engine: Engine::default(
        sortByTimestamp: true,
        applyElevationSmoothing: true,
        elevationSmoothingThreshold: 2,
    ),
);

No more global mutable state. Multiple phpGPX instances can coexist with different configurations.

Model cleanup

• Point constants (WAYPOINT, TRACKPOINT, ROUTEPOINT) replaced with PointType enum
• AbstractExtension base class removed — replaced by ExtensionInterface
• Constructors simplified across all models
• Strict typing on all model properties (nullable where optional per GPX spec)
• All parsers now extend AbstractParser reducing duplicated boilerplate

Breaking changes from 1.x

1.x	2.x
phpGPX::load() (static)	(new phpGPX())->load() (instance)
phpGPX::$CALCULATE_STATS = true	new phpGPX(engine: Engine::default())
phpGPX::$APPLY_ELEVATION_SMOOTHING	Engine::default(applyElevationSmoothing: true)
All static phpGPX::$CONFIG_* properties	Config object + analyzer constructors
$model->toArray()	$model->jsonSerialize() (GeoJSON)
Point::TRACKPOINT (constant)	PointType::Trackpoint (enum)
$ext->trackPointExtension	$ext->get(TrackPointExtension::class)
Summarizable interface	Removed — use JsonSerializable
GpxSerializable interface	Removed — parsers handle XML
StatsCalculator interface	Removed — use Engine

Issues addressed in 2.x

Here's the status of issues from the phpGPX 2.0 milestone and related reports:

Issue	Title	Status	How
#5	GeoJSON support	Done	Models implement JsonSerializable returning RFC 7946 GeoJSON
#15	Create statistics from GPX extensions	Done	TrackPointExtensionAnalyzer computes HR, cadence, temperature stats
#28	Statistics - get Bounds of the GPX Routes	Done	BoundsAnalyzer computes coordinate bounds for segments, tracks, and routes
#42	Custom trackpoint extension (Bad-Elf)	Done	ExtensionRegistry allows registering any extension by namespace URI
#51	startedAt/finishedAt missing without timestamp	Done	TimestampAnalyzer scans all points, not just first/last
#59	Elevation gain/loss incorrect with GPS gaps	Done	ElevationAnalyzer with configurable smoothing + spike threshold filtering
#68	Middlewares	Replaced	Single-pass Engine with pluggable analyzers (see above)
#69	Removal of Summarizable and toArray	Done	Replaced by JsonSerializable returning GeoJSON
#70	Min altitude is not necessarily the first point	Done	AltitudeAnalyzer tracks actual min/max with coordinates
#72	Add GPX version attribute	Done	GpxFile::$version parsed and preserved on round-trip

Still open:

Issue	Title	Status
#41	Waypoint and creation time extensions	Open — needs extension registry work
#75	GPX Style Extension	Draft PR — registry is ready for it
#76	Documentation	In progress — mkdocs-material site is set up

---

A note on backporting to 1.x

Several of the fixes above (especially #51, #59, #70) address bugs that also exist in 1.x. We should find a way how to backport properly.

Your feedback

If you want to try it out:

composer require sibyx/phpgpx:2.0.0-beta.1

Feedback welcome — especially on the Engine API and extension registry. If you hit any issues, please open an issue or comment here.

[nono303]

Hi @Sibyx & many Thx for this great Job!
I just tried v2 and here's my feedback

->toXML()

✅ metadata bounds
✅ TrackPointExtension whell filled with all originals gpxtpx
⚠️ <time> would be preferable to end with Z instead of +00:00 (I think Z is the standard and it lighten the gpx)

--- \phpGPX\v2\vendor\sibyx\phpGPX\src\phpGPX\Helpers\DateTimeHelper.php	Tue Mar 10 15:22:08 2026 UTC
+++ \phpGPX\v2\vendor\sibyx\phpGPX\src\phpGPX\Helpers\DateTimeHelper.php	Tue Mar 10 15:18:08 2026 UTC
@@ -20,7 +20,7 @@
 	 * @return null|string
 	 * @throws \Exception
 	 */
-	public static function formatDateTime($datetime, string $format = 'c', ?string $timezone = 'UTC'): ?string
+	public static function formatDateTime($datetime, string $format = 'Y-m-d\TH:i:sp', ?string $timezone = 'UTC'): ?string
 	{
 		$formatted = null;
 

[tracks|routes]->stats

✅ distance, realDistance, averageSpeed, averagePace changed ~1% against 1.3.3 confirm 5a6b94a

✅bounds array with named key is also nice

⚠️ startedAt & finishedAt: Timezone must be UTC and not the generally bad local php.ini value (see below for an improvement on this)

--- \phpGPX\v2\vendor\sibyx\phpGPX\src\phpGPX\Helpers\DateTimeHelper.php	Tue Mar 10 15:10:59 2026 UTC
+++ \phpGPX\v2\vendor\sibyx\phpGPX\src\phpGPX\Helpers\DateTimeHelper.php	Tue Mar 10 15:10:47 2026 UTC
@@ -38,11 +38,10 @@
 	 * @return \DateTime
 	 * @throws \Exception
 	 */
-	public static function parseDateTime($value, string $timezone = 'Europe/London'): \DateTime
+	public static function parseDateTime($value, string $timezone = 'UTC'): \DateTime
 	{
 		$timezone = new \DateTimeZone($timezone);
 		$datetime = new \DateTime($value, $timezone);
-		$datetime->setTimezone(new \DateTimeZone(date_default_timezone_get()));
 
 		return $datetime;
 	}

->metadata

✅ all sounds good

---

According to this new structure with Engine & extension registry, here is some ideas to be implemented (I’ve already done them hardcoded in my 1.x fork)

1. GpxFile->stats :

return merged stats of all tracks|routes (or a pointer to [tracks|routes]->stats if there is only one)
⏩ The goal is to provide a single stat array for gpx records that create new (and not ) on pause.

This correspond to $stats[0] on my dirty implementation
out of phpGPX.

2. DateTimeHelper timezone

For startedAt & finishedAt DateTime , we can use lat & lon to determine the good Timezone.

• I’ve implemented getTzAtLatLon() with a self-hosted java web-service (easy to set-up, fast & reliable) but there is also online WS that do it like https://developers.google.com/maps/documentation/timezone/overview
• Also tested native php with module geos but they seems abandoned and didn't works with 2026a / php 8.4+.. (https://github.com/minube/geo-timezone https://github.com/tochka-developers/geo-timezone https://github.com/pthreat/geo-timezone)
• This one https://stackoverflow.com/a/15535345 works with but with very hazardous result...

3. Elevation setter.

The idea might be to add in the engine an ElevationSetter($path_to_hgt, $mode)

• $mode could be "OVERRIDE" (like for noisy records…) or "FIX_NULL" (with there is not or 0 value)
• This setter would have to be called before analyzer

Here is how I implemented it in 1.x

---

Other ideas but I would like to have your feedback on how I can works on this with maybe a quick-starter for the extension registry (like class & methods skeleton) to participate "dans les règles de l'art" 😉

Perhaps you could open an issue for each point you'd like me to dig, specifying where and how I can integrate it into a PR on develop.