src/libgpx/gpx.php

   1 <?php
   2 /**
   3  * gpx.php
   4  *
   5  * Copyright 2018 Andy Street <andy@street.me.uk>
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  20  * MA 02110-1301, USA.
  21  *
  22  *
  23  */
  24
  25 namespace libgpx;
  26
  27 use \DateTimeInterface;
  28
  29 /**
  30  * A GPX file.
  31  *
  32  * @see https://www.topografix.com/gpx.asp
  33  *
  34  * @author Andy Street <andy@street.me.uk>
  35  */
  36 class GPX implements Geographic
  37 {
  38
  39   /**
  40    * The program that created the GPX file.
  41    *
  42    * @var string
  43    */
  44   protected $creator;
  45
  46   /**
  47    * The name of the GPX file.
  48    *
  49    * @var string
  50    */
  51   protected $name;
  52
  53   /**
  54    * A description of the contents of the GPX file.
  55    *
  56    * @var string
  57    */
  58   protected $desc;
  59
  60   /**
  61    * The person or organization who created the GPX file.
  62    *
  63    * @var Person
  64    */
  65   protected $author;
  66
  67   /**
  68    * Copyright and license information governing use of the file.
  69    *
  70    * @var Copyright
  71    */
  72   protected $copyright;
  73
  74   /**
  75    * Links to other resources that describe this GPX file.
  76    *
  77    * @var TypedDoublyLinkedList (Link)
  78    */
  79   protected $links;
  80
  81   /**
  82    * The creation time of the file.
  83    *
  84    * @var DateTimeInterface
  85    */
  86   protected $time;
  87
  88   /**
  89    * A list of keywords classifying this GPX file.
  90    *
  91    * @var TypedDoublyLinkedList (string)
  92    */
  93   protected $keywords;
  94
  95   /**
  96    * A list of XML snippets describing unsupported metadata.
  97    *
  98    * @var TypedDoublyLinkedList (string)
  99    */
 100   protected $metadataExtensions;
 101
 102   /**
 103    * A list of waypoints.
 104    *
 105    * @var TypedDoublyLinkedList (Point)
 106    */
 107   protected $waypoints;
 108
 109   /**
 110    * A list of routes.
 111    *
 112    * @var TypedDoublyLinkedList (Route)
 113    */
 114   protected $routes;
 115
 116   /**
 117    * Fetch the name of the program that created the GPX file.
 118    *
 119    * @return string|null The creator or null if not set.
 120    */
 121   public function getCreator()
 122   {
 123     return $this->creator;
 124   }
 125
 126   /**
 127    * Set the name of the program that created the GPX file.
 128    *
 129    * @param string|null $creator The program name or null to delete.
 130    * @return void
 131    */
 132   public function setCreator(string $creator = null)
 133   {
 134     $this->creator = $creator;
 135   }
 136
 137   /**
 138    * Fetch the file name.
 139    *
 140    * @return string|null The name or null if not set.
 141    */
 142   public function getName()
 143   {
 144     return $this->name;
 145   }
 146
 147   /**
 148    * Set the name of the file.
 149    *
 150    * @param string|null $name The file name or null to delete.
 151    * @return void
 152    */
 153   public function setName(string $name = null)
 154   {
 155     $this->name = $name;
 156   }
 157
 158   /**
 159    * Fetch the description of the file.
 160    *
 161    * @return string|null The description or null if not set.
 162    */
 163   public function getDesc()
 164   {
 165     return $this->desc;
 166   }
 167
 168   /**
 169    * Set the description of the file.
 170    *
 171    * @param string|null $desc The description or null to delete.
 172    * @return void
 173    */
 174   public function setDesc(string $desc = null)
 175   {
 176     $this->desc = $desc;
 177   }
 178
 179   /**
 180    * Fetch the author of the file.
 181    *
 182    * @return Person|null The author or null if not set.
 183    */
 184   public function getAuthor()
 185   {
 186     return $this->author;
 187   }
 188
 189   /**
 190    * Set the author of the file.
 191    *
 192    * @param Person|null $author The author or null to delete.
 193    * @return void
 194    */
 195   public function setAuthor(Person $author = null)
 196   {
 197     $this->author = $author;
 198   }
 199
 200   /**
 201    * Fetch the copyright details for the file.
 202    *
 203    * @return Copyright|null The copyright or null if not set.
 204    */
 205   public function getCopyright()
 206   {
 207     return $this->copyright;
 208   }
 209
 210   /**
 211    * Set the copyright details for the file.
 212    *
 213    * @param Copyright|null $copyright The copyright detail or null to delete.
 214    * @return void
 215    */
 216   public function setCopyright(Copyright $copyright = null)
 217   {
 218     $this->copyright = $copyright;
 219   }
 220
 221   /**
 222    * Fetch links to other resources.
 223    *
 224    * @param boolean $create Create the list if it does not already exist.
 225    * @return TypedDoublyLinkedList
 226    */
 227   public function getLinks(bool $create = true)
 228   {
 229     if ($create && $this->links === null)
 230       $this->links = new TypedDoublyLinkedList('libgpx\Link');
 231     return $this->links;
 232   }
 233
 234   /**
 235    * Fetch the time the GPX file was created.
 236    *
 237    * @return DateTimeInterface|null A timestamp or null if not set.
 238    */
 239   public function getTime()
 240   {
 241     return $this->time;
 242   }
 243
 244   /**
 245    * Set the time at which the file was created.
 246    *
 247    * @param DateTimeInterface $time The creation time or null to delete.
 248    */
 249   public function setTime(DateTimeInterface $time = null)
 250   {
 251     $this->time = $time;
 252   }
 253
 254   /**
 255    * Fetch a list of keywords for this GPX file.
 256    *
 257    * @param boolean $create Create the list if it does not already exist.
 258    * @return TypedDoublyLinkedList The keywords
 259    */
 260   public function getKeywords(bool $create = true)
 261   {
 262     if ($create && $this->keywords === null)
 263       $this->keywords = new TypedDoublyLinkedList('string');
 264     return $this->keywords;
 265   }
 266
 267   /**
 268    * Fetch a list of XML snippets describing unsupported metadata.
 269    *
 270    * @param boolean $create Create the list if it does not already exist.
 271    * @return TypedDoublyLinkedList The keywords
 272    */
 273   public function getMetadataExtensions(bool $create = true)
 274   {
 275     if ($create && $this->metadataExtensions === null)
 276         $this->metadataExtensions = new TypedDoublyLinkedList('string');
 277     return $this->metadataExtensions;
 278   }
 279
 280   /**
 281    * Fetch a list of waypoints.
 282    *
 283    * @param boolean $create Create the list if it does not already exist.
 284    * @return TypedDoublyLinkedList A list of waypoints.
 285    */
 286   public function getWaypoints(bool $create = true)
 287   {
 288     if ($create && $this->waypoints === null)
 289       $this->waypoints = new TypedDoublyLinkedList('libgpx\Point');
 290     return $this->waypoints;
 291   }
 292
 293   /**
 294    * Fetch a list of routes.
 295    *
 296    * @param boolean $create Create the list if it does not already exist.
 297    * @return TypedDoublyLinkedList A list of routes.
 298    */
 299   public function getRoutes(bool $create = true)
 300   {
 301     if ($create && $this->routes === null)
 302       $this->routes = new TypedDoublyLinkedList('libgpx\Route');
 303     return $this->routes;
 304   }
 305
 306   /**
 307    * Fetch a bounding box that covers the feature.
 308    *
 309    * @return Bounds|null A bounding box covering the extent of the feature or
 310    *         null if not applicable.
 311    */
 312   public function getBounds()
 313   {
 314     $result = null;
 315     $lists = [
 316       $this->waypoints,
 317       $this->routes
 318     ];
 319     foreach ($lists as $list) {
 320       if ($list === null) continue;
 321       foreach ($list as $geo) {
 322         $bounds = $geo->getBounds();
 323         if ($bounds === null) continue;
 324         $result = ($result === null ? $bounds : $result->extend($bounds));
 325       }
 326     }
 327     return $result;
 328   }
 329
 330 }