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]

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]

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.