[andy/gpx.git] / src / libgpx / gpxreader.php

<?php
/**
 * gpxreader.php
 *
 * Copyright 2018 Andy Street <andy@street.me.uk>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
 * MA 02110-1301, USA.
 *
 *
 */

namespace libgpx;

use \DateTime;
use \DateTimeZone;
use \DomainException;
use \Exception;
use \InvalidArgumentException;
use \RuntimeException;

/**
 * Read GPX files.
 *
 * @author Andy Street <andy@street.me.uk>
 */
class GPXReader
{

  /**
   * The namespace of the XML currently being parsed.
   *
   * @var string
   */
  protected $ns;

  /**
   * The GPX version of the XML currently being parsed.
   *
   * @var string
   */
  protected $version;

  /**
   * The reader currently reading the XML.
   *
   * @var XMLReader
   */
  protected $xml;

  /**
   * Read GPX from a string.
   *
   * @param string $xml The GPX XML data.
   * @return GPX The GPX data.
   * @throws RuntimeException If the XML could not be read.
   * @throws MalformedGPXException If the GPX file is invalid.
   */
  public function readString(string $xml)
  {
    try {
      $this->xml = new XMLReader();
      if (!$this->xml->XML($xml, null, LIBXML_NOERROR | LIBXML_NOWARNING)) {
        throw new RuntimeException('Unable to read XML from string.');
      }
      return $this->read();
    } finally {
      $this->xml = null;
    }
  }

  /**
   * Read GPX from a file.
   *
   * This function is an alias of `GPXReader::readURI()`.
   *
   * @param string $filename The name of the file containing GPX XML data.
   * @return GPX The GPX data.
   * @throws RuntimeException If the XML could not be read.
   * @throws MalformedGPXException If the GPX file is invalid.
   */
  public function readFile(string $filename)
  {
    return $this->readURI($filename);
  }

  /**
   * Read GPX from a URI.
   *
   * @param string $uri The location of the file containing GPX XML data.
   * @return GPX The GPX data.
   * @throws RuntimeException If the XML could not be read.
   * @throws MalformedGPXException If the GPX file is invalid.
   */
  public function readURI(string $uri)
  {
    try {
      $this->xml = new XMLReader();
      if (!$this->xml->open($uri, null, LIBXML_NOERROR | LIBXML_NOWARNING)) {
        throw new RuntimeException(sprintf('Unable to read XML from: %s', $uri));
      }
      return $this->read();
    } finally {
      $this->xml = null;
    }
  }

  /**
   * Read GPX data from XML.
   *
   * @param XMLReader $xml Where to read the GPX data from.
   * @return GPX The data that was read.
   * @throws MalformedGPXException If the GPX file was invalid or not supported.
   */
  protected function read()
  {
    $xml = $this->xml;
    try {
      // Fast forward to the root element.
      while ($xml->nodeType !== XMLReader::ELEMENT) {
        $xml->read();
      }

      // Detect file version
      switch ($xml->namespaceURI) {
        case libgpx::NAMESPACE_GPX_1_0:
          $this->version = '1.0';
          $this->ns = libgpx::NAMESPACE_GPX_1_0;
          break;
        case libgpx::NAMESPACE_GPX_1_1:
          $this->version = '1.1';
          $this->ns = libgpx::NAMESPACE_GPX_1_1;
          break;
        default:
          throw new MalformedGPXException('Unknown or unsupported file format.');
      }

      // Read GPX element.
      if ($xml->localName == 'gpx')
        return $this->readGPX();
      else
        throw new MalformedGPXException('Root element must be "gpx".');

    } finally {
      $this->version = null;
      $this->ns = null;
    }
  }

  /**
   * Read a gpx type.
   *
   * @return GPX The GPX data.
   * @throws MalformedGPXException If the GPX file was invalid or not supported.
   */
  protected function readGPX()
  {
    // Sanity check - ensure version attribute and schema declaration match.
    if ($this->xml->getAttribute('version') != $this->version)
      throw new MalformedGPXException(
        'GPX version attribute does not match namespace declaration.'
      );

    $result = new GPX();
    $result->setCreator($this->xml->getAttribute('creator'));

    $struct = [
      'elements' => [
        'wpt' => function ($gpx) {
          $gpx->getWaypoints()[] = $this->readWpt();
        },
        'rte' => function ($gpx) {
          $gpx->getRoutes()[] = $this->readRte();
        },
        'trk' => function ($gpx) {
          $gpx->getTracks()[] = $this->readTrk();
        }
      ]
    ];
    if ($this->version == '1.1') {
      $struct['elements']['metadata'] = function ($gpx) {
        $this->readMetadata($gpx);
      };
    } else {
      $struct['elements']['name'] = function ($gpx) {
        $gpx->setName($this->readXSDString());
      };
      $struct['elements']['desc'] = function ($gpx) {
        $gpx->setDesc($this->readXSDString());
      };
      $struct['elements']['author'] = function ($gpx) {
        $author = $gpx->getAuthor();
        if ($author === null) {
          $author = new Person();
          $gpx->setAuthor($author);
        }
        $author->setName($this->readXSDString());
      };
      $struct['elements']['email'] = function ($gpx) {
        $author = $gpx->getAuthor();
        if ($author === null) {
          $author = new Person();
          $gpx->setAuthor($author);
        }
        $author->setEmail($this->readXSDString());
      };
      $struct['elements']['url'] = function ($gpx, &$state) {
        $href = $this->readXSDString();
        $links = $gpx->getLinks();
        if ($links->isEmpty()) {
          $link = new Link($href);
          if (isset($state['urlname'])) {
            $link->setText($state['urlname']);
            unset($state['urlname']);
          }
          $links[] = $link;
        } else {
          $links->bottom()->setHref($href);
        }
      };
      $struct['elements']['urlname'] = function ($gpx, &$state) {
        $text = $this->readXSDString();
        $links = $gpx->getLinks();
        if ($links->isEmpty()) {
          $state['urlname'] = $text;
        } else {
          $links->bottom()->setText($text);
        }
      };
      $struct['elements']['time'] = function ($gpx) {
        $gpx->setTime($this->string2DateTime($this->readXSDString()));
      };
      $struct['elements']['keywords'] = function ($gpx) {
        $keywords = $gpx->getKeywords();
        $words = explode(',', $this->readXSDString());
        foreach ($words as $word)
          $keywords[] = trim($word);
      };
      $struct['elements']['bounds'] = false;
    }

    $this->readStruct($struct, $result);
    return $result;
  }

  /**
   * Read a metadata type.
   *
   * Note: This is GPX 1.1 only as GPX 1.0 does not have a metadata type.
   *
   * @param GPX $gpx The gpx object to populate.
   * @return void
   * @throws MalformedGPXException If the GPX file was invalid or not supported.
   */
  protected function readMetadata(GPX $gpx)
  {
    $struct = [
      'elements' => [
        'name' => function ($gpx) {
          $gpx->setName($this->readXSDString());
        },
        'desc' => function ($gpx) {
          $gpx->setDesc($this->readXSDString());
        },
        'author' => function ($gpx) {
          $gpx->setAuthor($this->readPerson());
        },
        'copyright' => function ($gpx) {
          $gpx->setCopyright($this->readCopyright());
        },
        'link' => function ($gpx) {
          $links = $gpx->getLinks();
          $links[] = $this->readLink();
        },
        'time' => function ($gpx) {
          $gpx->setTime($this->string2DateTime($this->readXSDString()));
        },
        'keywords' => function ($gpx) {
          $keywords = $gpx->getKeywords();
          $words = explode(',', $this->readXSDString());
          foreach ($words as $word)
            $keywords[] = trim($word);
        },
        'bounds' => false, // Not required as it is calculated internally.
        'extensions' => function ($gpx) {
          $this->readExtension($gpx->getMetadataExtensions());
        }
      ]
    ];
    $this->readStruct($struct, $gpx);
  }

  /**
   * Read a person type.
   *
   * @return Person The person data.
   * @throws MalformedGPXException If the GPX file was invalid or not supported.
   */
  protected function readPerson()
  {
    $struct = [
      'elements' => [
        'name' => function ($person) {
          $person->setName($this->readXSDString());
        },
        'email' => function ($person) {
          $id = $this->xml->getAttribute('id');
          if ($id === null)
            throw new MalformedGPXException(
              'Missing required attribute "id" in "email"'
            );
          $domain = $this->xml->getAttribute('domain');
          if ($domain === null)
            throw new MalformedGPXException(
              'Missing required attribute "domain" in "email"'
            );
          $person->setEmail($id . '@' . $domain);
          $this->xml->read();
        },
        'link' => function ($person) {
          $person->setLink($this->readLink());
        }
      ]
    ];
    $person = new Person();
    $this->readStruct($struct, $person);
    return $person;
  }

  /**
   * Read a link type.
   *
   * @return Link The link data.
   * @throws MalformedGPXException If the GPX file was invalid or not supported.
   */
  protected function readLink()
  {
    $href = $this->xml->getAttribute('href');
    if ($href === null)
      throw new MalformedGPXException(
        'Missing required attribute "href" in "link"'
      );
    $struct = [
      'elements' => [
        'text' => function ($link) {
          $link->setText($this->readXSDString());
        },
        'type' => function ($link) {
          $link->setType($this->readXSDString());
        }
      ]
    ];
    $link = new Link($href);
    $this->readStruct($struct, $link);
    return $link;
  }

  /**
   * Read a copyright type.
   *
   * @return Copyright The copyright data.
   * @throws MalformedGPXException If the GPX file was invalid or not supported.
   */
  protected function readCopyright()
  {
    $author = $this->xml->getAttribute('author');
    if ($author === null)
      throw new MalformedGPXException(
        'Missing required attribute "author" in "copyright"'
      );
    $struct = [
      'elements' => [
        'year' => function ($copyright) {
          try {
            $year = $this->readXSDString();
            $copyright->setYear($year);
          } catch (InvalidArgumentException $e) {
            throw new MalformedGPXException(
              sprintf('"%s" is not a valid year', $year)
            );
          }
        },
        'license' => function ($copyright) {
          $copyright->setLicense($this->readXSDString());
        }
      ]
    ];
    $copyright = new Copyright($author);
    $this->readStruct($struct, $copyright);
    return $copyright;
  }

  /**
   * Read an extensions type.
   *
   * This is suitable for GPX 1.1 only as private elements are mixed into other
   * elements in GPX 1.0.
   *
   * @param TypedDoublyLinkedList $list The list to fill with extension XML.
   * @return void
   * @throws MalformedGPXException If the GPX file was invalid.
   */
  protected function readExtension(TypedDoublyLinkedList $list)
  {
    $struct = [
      'extensions' => function ($list) {
        $list[] = $this->xml->readOuterXml();
        $this->xml->next();
      }
    ];
    $this->readStruct($struct, $list);
  }

  /**
   * Read a wpt type.
   *
   * @see https://www.topografix.com/GPX/1/1/#type_wptType
   *
   * @return Point
   * @throws MalformedGPXException If the GPX file was invalid or not supported.
   */
  protected function readWpt()
  {
    try {
      $result = new Point(
        $this->string2float($this->xml->getAttribute('lat')),
        $this->string2float($this->xml->getAttribute('lon'))
      );
      $struct = $this->getDataTypeStruct();
      $struct['elements']['ele'] = function ($point) {
        $point->setEle($this->string2float($this->readXSDString()));
      };
      $struct['elements']['time'] = function ($point) {
        $point->setTime($this->string2DateTime($this->readXSDString()));
      };
      $struct['elements']['magvar'] = function ($point) {
        $point->setMagvar($this->string2float($this->readXSDString()));
      };
      $struct['elements']['geoidheight'] = function ($point) {
        $point->setGeoidHeight($this->string2float($this->readXSDString()));
      };
      $struct['elements']['sym'] = function ($point) {
        $point->setSymbol($this->readXSDString());
      };
      // "type" only appears in "wpt" in GPX 1.0
      if ($this->version == '1.0')
        $struct['elements']['type'] = function ($point) {
          $point->setType($this->readXSDString());
        };
      $struct['elements']['fix'] = function ($point) {
        $point->setFix($this->readXSDString());
      };
      $struct['elements']['sat'] = function ($point) {
        $point->setSatellites($this->string2int($this->readXSDString()));
      };
      $struct['elements']['hdop'] = function ($point) {
        $point->setHdop($this->string2float($this->readXSDString()));
      };
      $struct['elements']['vdop'] = function ($point) {
        $point->setVdop($this->string2float($this->readXSDString()));
      };
      $struct['elements']['pdop'] = function ($point) {
        $point->setPdop($this->string2float($this->readXSDString()));
      };
      $struct['elements']['ageofdgpsdata'] = function ($point) {
        $point->setAgeOfDGPSData($this->string2float($this->readXSDString()));
      };
      $struct['elements']['dgpsid'] = function ($point) {
        $point->setDGPSId($this->string2int($this->readXSDString()));
      };
      $this->readStruct($struct, $result);
    } catch (DomainException $e) {
      throw new MalformedGPXException(
        $e->getMessage(), $e->getCode(), $e
      );
    }
    return $result;
  }

  /**
   * Read a rte type.
   *
   * @see https://www.topografix.com/GPX/1/1/#type_rteType
   *
   * @return Route
   * @throws MalformedGPXException If the GPX file was invalid or not supported.
   */
  protected function readRte()
  {
    try {
      $result = new Route();
      $struct = $this->getDataTypeStruct();
      $struct['elements']['number'] = function ($route) {
        $route->setNumber($this->string2int($this->readXSDString()));
      };
      $struct['elements']['rtept'] = function ($route) {
        $route->getPoints()[] = $this->readWpt();
      };
      $this->readStruct($struct, $result);
    } catch (DomainException $e) {
      throw new MalformedGPXException(
        $e->getMessage(), $e->getCode(), $e
      );
    }
    return $result;
  }

  /**
   * Read a trk type.
   *
   * @see https://www.topografix.com/GPX/1/1/#type_trkType
   *
   * @return Track
   * @throws MalformedGPXException If the GPX file was invalid or not supported.
   */
  protected function readTrk()
  {
    try {
      $result = new Track();
      $struct = $this->getDataTypeStruct();
      $struct['elements']['number'] = function ($track) {
        $track->setNumber($this->string2int($this->readXSDString()));
      };
      $struct['elements']['trkseg'] = function ($track) {
        $track->getSegments()[] = $this->readTrkseg();
      };
      $this->readStruct($struct, $result);
    } catch (DomainException $e) {
      throw new MalformedGPXException(
        $e->getMessage(), $e->getCode(), $e
      );
    }
    return $result;
  }

  /**
   * Read a trkseg type.
   *
   * @see https://www.topografix.com/GPX/1/1/#type_trksegType
   *
   * @return TrackSegment
   * @throws MalformedGPXException If the GPX file was invalid or not supported.
   */
  protected function readTrkseg()
  {
    $result = new TrackSegment();
    $struct = [
      'elements' => [
        'trkpt' => function ($segment) {
          $segment->getPoints()[] = $this->readWpt();
        }
      ]
    ];
    if ($this->version == '1.1')
      $struct['elements']['extensions'] = function ($segment) {
        $this->readExtension($segment->getExtensions());
      };
    $this->readStruct($struct, $result);
    return $result;
  }

  /**
   * Read a data structure from XML.
   *
   * This is a generalized function for parsing XML data structures and
   * populating values based on data retrieved. The main control element is the
   * `$struct` array which holds a list of callable functions which are used to
   * modify the supplied object. The structure of the array is:
   *
   *     [
   *       'extensions' => function($object, &$state) {...},
   *       'elements' => [
   *         'nodename' => function($object, &$state) {...}
   *       ]
   *     ]
   *
   * The following keys are defined:
   *
   *   * `extensions` - Call the supplied anonymous function if any XML element
   *                    is encountered in a namespace other than the document
   *                    namespace.
   *   * `elements`   - Call the supplied anonymous function if an XML element
   *                    is encountered in the document namespace with a matching
   *                    node name.
   *
   * The anonymous function parameters are as follows:
   *
   *   * `$object` - The object to be populated (as passed to this function)
   *   * `$state`  - An array that can be used to store data temporarily while
   *                 the structure is being written. This is useful if a value
   *                 that is being read is split across several XML elements.
   *
   * @param array $struct a data structure as defined above.
   * @param object $object The object to populate with data.
   * @return void
   * @throws MalformedGPXException If the GPX file was invalid or not supported.
   */
  protected function readStruct($struct, $object)
  {
    $xml = $this->xml;
    if ($xml->isEmptyElement) {
      $xml->read();
      return;
    }
    $element = $xml->localName;
    $xml->read();
    $state = [];
    while (true) {
      if (
        $xml->nodeType == XMLReader::END_ELEMENT
        && $xml->namespaceURI == $this->ns
        && $xml->localName == $element
      ) return;
      if ($xml->nodeType != XMLReader::ELEMENT) {
        $xml->read();
        continue;
      }
      if (
        $xml->namespaceURI == $this->ns
        && isset($struct['elements'][$xml->localName])
      ) {
        if (is_callable($struct['elements'][$xml->localName])) {
          $struct['elements'][$xml->localName]($object, $state);
        } else {
          $xml->read();
        }
        continue;
      }
      if (
        $xml->namespaceURI != $this->ns
        && isset($struct['extensions'])
        && is_callable($struct['extensions'])
      ) {
        $struct['extensions']($object, $state);
        continue;
      }
      throw new MalformedGPXException(
        sprintf(
          'Unknown element "%s" in element "%s"',
          $xml->localName,
          $element
        )
      );
    }
  }

  /**
   * Generate a data structure for reading DataType elements.
   *
   * @return array
   */
  protected function getDataTypeStruct()
  {
    $result = [
      'elements' => [
        'name' => function ($type) {
          $type->setName($this->readXSDString());
        },
        'cmt' => function ($type) {
          $type->setComment($this->readXSDString());
        },
        'desc' => function ($type) {
          $type->setDescription($this->readXSDString());
        },
        'src' => function ($type) {
          $type->setSource($this->readXSDString());
        }
      ]
    ];
    if ($this->version == '1.1') {
      $result['elements']['link'] = function ($type) {
        $type->getLinks()[] = $this->readLink();
      };
      $result['elements']['type'] = function ($type) {
        $type->setType($this->readXSDString());
      };
      $result['elements']['extensions'] = function ($type) {
        $this->readExtension($type->getExtensions());
      };
    } else {
      $result['elements']['url'] = function ($type, &$state) {
        $href = $this->readXSDString();
        $links = $type->getLinks();
        if ($links->isEmpty()) {
          $link = new Link($href);
          if (isset($state['urlname'])) {
            $link->setText($state['urlname']);
            unset($state['urlname']);
          }
          $links[] = $link;
        } else {
          $links->bottom()->setHref($href);
        }
      };
      $result['elements']['urlname'] = function ($type, &$state) {
        $text = $this->readXSDString();
        $links = $type->getLinks();
        if ($links->isEmpty()) {
          $state['urlname'] = $text;
        } else {
          $links->bottom()->setText($text);
        }
      };
      $result['extensions'] = function ($type) {
        $type->getExtensions()[] = $this->xml->readOuterXML();
        $this->xml->next();
      };
    }
    return $result;
  }

  /**
   * Read an `xsd:string` type from XML.
   *
   * @return string The text string.
   * @throws MalformedGPXException If the element has non-text children.
   */
  protected function readXSDString()
  {
    $xml = $this->xml;
    $result = '';
    if ($xml->nodeType != XMLReader::ELEMENT || $xml->isEmptyElement)
      return $result;
    $element = $xml->name;
    while ($xml->read()) {
      switch ($xml->nodeType) {
        case XMLReader::TEXT:
        case XMLReader::CDATA:
          $result .= $xml->value;
          break;
        case XMLReader::END_ELEMENT:
          $xml->read();
          break 2;
        default:
          throw new MalformedGPXException(
            sprintf('Element "%s" contains non-text data.', $element)
          );
      }

    }
    return $result;
  }

  /**
   * Convert a string to DateTime.
   *
   * @param string $timestamp The timestamp to convert.
   * @return DateTime The parsed DateTime.
   * @throws MalformedGPXException If the timestamp could not be parsed.
   */
  protected function string2DateTime(string $timestamp)
  {
    try {
      $result = new DateTime($timestamp, new DateTimeZone('Z'));
    } catch (Exception $e) {
      throw new MalformedGPXException(
        sprintf('Unknown datetime format "%s"', $timestamp)
      );
    }
    return $result;
  }

  /**
   * Convert a string to a float.
   *
   * @param string $value The string value to convert.
   * @return float
   * @throws MalformedGPXException If the value is not numeric.
   */
  protected function string2float(string $value)
  {
    if (!is_numeric($value))
      throw new MalformedGPXException(
        sprintf('Expected decimal value but got "%s"', $value)
      );
    return floatval($value);
  }

  /**
   * Convert a string to a int.
   *
   * @param string $value The string value to convert.
   * @return int
   * @throws MalformedGPXException If the value is not numeric.
   */
  protected function string2int(string $value)
  {
    if (!is_numeric($value))
      throw new MalformedGPXException(
        sprintf('Expected decimal value but got "%s"', $value)
      );
    return intval($value);
  }

}