Change signatures of point creation methods to put the CRS first so t…

…hat optional elements are last (PHP 8.1 compat)
dvdoug · Oct 10, 2021 · fb549da · fb549da
1 parent 55f10a7
commit fb549da
Show file tree

Hide file tree

Showing 32 changed files with 628 additions and 649 deletions.
diff --git a/docs/coordinate_conversions_easy.rst b/docs/coordinate_conversions_easy.rst
@@ -23,10 +23,10 @@ Examples:
 
     // Converting from NAD83 to Florida State Plane
     $from = GeographicPoint::create(
+        Geographic2D::fromSRID(Geographic2D::EPSG_NAD83),
         new Degree(28.46),
         new Degree(-80.53),
-        null,
-        Geographic2D::fromSRID(Geographic2D::EPSG_NAD83)
+        null
     );
     $toCRS = Projected::fromSRID(Projected::EPSG_NAD83_FLORIDA_EAST);
     $to = $from->convert($toCRS); // $to instanceof ProjectedPoint
@@ -41,9 +41,9 @@ Examples:
 
     // Converting from Florida State Plane to NAD83
     $from = ProjectedPoint::createFromEastingNorthing(
-        new Metre(246029.85),
-        new Metre(457274.616),
         Projected::fromSRID(Projected::EPSG_NAD83_FLORIDA_EAST)
+        new Metre(246029.85),
+        new Metre(457274.616)
     );
     $toCRS = Geographic2D::fromSRID(Geographic2D::EPSG_NAD83);
     $to = $from->convert($toCRS); // $to instanceof GeographicPoint
@@ -63,9 +63,9 @@ between almost any two CRSs is possible as long as they have a common link.
 .. code-block:: php
 
     $from = ProjectedPoint::createFromEastingNorthing(
+        Projected::fromSRID(Projected::EPSG_OSGB36_BRITISH_NATIONAL_GRID),
         new Metre(577275),
-        new Metre(69741),
-        Projected::fromSRID(Projected::EPSG_OSGB36_BRITISH_NATIONAL_GRID)
+        new Metre(69741)
     );
     $toCRS = Projected::fromSRID(Projected::EPSG_WGS_84_UTM_ZONE_31N);
     $to = $from->convert($toCRS);
@@ -116,10 +116,10 @@ For conversions from a ``GeographicPoint`` to a ``UTMPoint``, call the ``->asUTM
 .. code-block:: php
 
     $from = GeographicPoint::create(
+        Geographic2D::fromSRID(Geographic2D::EPSG_WGS_84),
         new Degree(43.642567),
         new Degree(-79.387139),
-        null,
-        Geographic2D::fromSRID(Geographic2D::EPSG_WGS_84)
+        null
     );
     $to = $from->asUTMPoint();
 

diff --git a/docs/creating_points_compound.rst b/docs/creating_points_compound.rst
@@ -8,9 +8,9 @@ A ``CompoundPoint`` can be constructed by calling ``CompoundPoint::create``, whi
 .. code-block:: php
 
     public static function create(
+        Compound $crs,
         GeographicPoint|ProjectedPoint $horizontalPoint,
         VerticalPoint $verticalPoint,
-        Compound $crs,
         ?DateTimeInterface $epoch = null
     ): CompoundPoint
 
@@ -30,24 +30,24 @@ Example:
     // Horizontal location of Ben Nevis peak using British National Grid
     $horizontalCRS = Projected::fromSRID(Projected::EPSG_OSGB36_BRITISH_NATIONAL_GRID);
     $horizontalPoint = ProjectedPoint::createFromEastingNorthing(
+        $horizontalCRS,
         new Metre(216692),
-        new Metre(771274),
-        $horizontalCRS
+        new Metre(771274)
     );
 
     // Height above Newlyn Sea Level of Ben Nevis peak
     $verticalCRS = Vertical::fromSRID(Vertical::EPSG_ODN_HEIGHT);
     $verticalPoint = VerticalPoint::create(
-        new Metre(1345),
-        $verticalCRS
+        $verticalCRS,
+        new Metre(1345)
     );
 
     // Full coordinate of Ben Nevis Peak
     $compoundCRS = Compound::fromSRID(Compound::EPSG_OSGB36_BRITISH_NATIONAL_GRID_PLUS_ODN_HEIGHT);
     $point = CompoundPoint::create(
+        $compoundCRS,
         $horizontalPoint,
-        $verticalPoint,
-        $compoundCRS
+        $verticalPoint
     );
 
     $horizontal = $point->getHorizontalPoint(); // GeographicPoint|ProjectedPoint

diff --git a/docs/creating_points_geocentric.rst b/docs/creating_points_geocentric.rst
@@ -8,10 +8,10 @@ A ``GeocentricPoint`` can be constructed by calling ``GeocentricPoint::create``
 .. code-block:: php
 
     public static function create(
+        Geocentric $crs,
         Length $x,
         Length $y,
         Length $z,
-        Geocentric $crs,
         ?DateTimeInterface $epoch = null
     ): GeocentricPoint
 
@@ -27,19 +27,19 @@ Examples:
     // Ascension Island GPS tracking station in ITRF2008 (unknown date), traditional arguments
     $crs = Geocentric::fromSRID(Geocentric::EPSG_ITRF2008);
     $point = GeocentricPoint::create(
+        $crs,
         new Metre(6121152),
         new Metre(-1563979),
-        new Metre(-872615),
-        $crs
+        new Metre(-872615)
     );
 
     // Ascension Island GPS tracking station in ITRF2008 (2020-02-01), traditional arguments
     $crs = Geocentric::fromSRID(Geocentric::EPSG_ITRF2008);
     $point = GeocentricPoint::create(
+        $crs,
         new Metre(6121152),
         new Metre(-1563979),
         new Metre(-872615),
-        $crs,
         new DateTime('2020-02-01')
     );
 

diff --git a/docs/creating_points_geographic.rst b/docs/creating_points_geographic.rst
@@ -9,10 +9,10 @@ A ``GeographicPoint`` can be constructed by calling ``GeographicPoint::create``,
 .. code-block:: php
 
     public static function create(
+        Geographic $crs,
         Angle $latitude,
         Angle $longitude,
         ?Length $height = null,
-        Geographic $crs,
         ?DateTimeInterface $epoch = null
     ): GeographicPoint
 
@@ -32,19 +32,19 @@ Examples:
     // the Statue of Liberty in WGS84 (unknown date), traditional arguments, decimal degrees
     $crs = Geographic2D::fromSRID(Geographic2D::EPSG_WGS_84);
     $point = GeographicPoint::create(
+        $crs,
         new Degree(40.689167),
         new Degree(-74.044444),
-        null,
-        $crs
+        null
     );
 
     // the Statue of Liberty in WGS84 (2020-02-01), traditional arguments, string representation of degrees
     $crs = Geographic2D::fromSRID(Geographic2D::EPSG_WGS_84);
     $point = GeographicPoint::create(
+        $crs,
         Degree::fromDegreeMinuteSecondHemisphere('40° 41′ 21″ N'),
         Degree::fromDegreeMinuteSecondHemisphere('74° 2′ 40″ W'),
         null,
-        $crs,
         new DateTime('2020-02-01')
     );
 

diff --git a/docs/creating_points_projected.rst b/docs/creating_points_projected.rst
@@ -19,23 +19,23 @@ following signatures:
 .. code-block:: php
 
     public static function createFromEastingNorthing(
+        Projected $crs,
         Length $easting,
         Length $northing,
-        Projected $crs,
         ?DateTimeInterface $epoch = null
     ): ProjectedPoint
 
     public static function createFromWestingNorthing(
+        Projected $crs,
         Length $westing,
         Length $northing,
-        Projected $crs,
         ?DateTimeInterface $epoch = null
     ): ProjectedPoint
 
     public static function createFromWestingSouthing(
+        Projected $crs,
         Length $westing,
         Length $southing,
-        Projected $crs,
         ?DateTimeInterface $epoch = null
     ): ProjectedPoint
 
@@ -51,17 +51,17 @@ Examples:
     // Nelson's Column in British National Grid (unknown date), traditional arguments
     $crs = Projected::fromSRID(Projected::EPSG_OSGB36_BRITISH_NATIONAL_GRID);
     $point = ProjectedPoint::createFromEastingNorthing(
+        $crs,
         new Metre(530017),
-        new Metre(180419),
-        $crs
+        new Metre(180419)
     );
 
     // Nelson's Column in British National Grid (2020-02-01), traditional arguments
     $crs = Projected::fromSRID(Projected::EPSG_OSGB36_BRITISH_NATIONAL_GRID);
     $point = ProjectedPoint::createFromEastingNorthing(
+        $crs,
         new Metre(530017),
         new Metre(180419),
-        $crs,
         new DateTime('2020-02-01')
     );
 
@@ -122,7 +122,7 @@ rather than a standard ``ProjectedPoint``. Alternatively, you can construct one
         ?DateTimeInterface $epoch = null
     ): BritishNationalGridPoint
 
-    // from  a grid reference
+    // from a grid reference
     public static function fromGridReference(
         string $reference,
         ?DateTimeInterface $epoch = null
@@ -141,9 +141,9 @@ Examples:
     // Nelson's Column
     $crs = Projected::fromSRID(Projected::EPSG_OSGB36_BRITISH_NATIONAL_GRID);
     $point = ProjectedPoint::createFromEastingNorthing(
+        $crs,
         new Metre(530017),
-        new Metre(180419),
-        $crs
+        new Metre(180419)
     );
 
     // also Nelson's Column
@@ -195,9 +195,9 @@ Examples:
     // Spire of Dublin
     $crs = Projected::fromSRID(Projected::EPSG_TM75_IRISH_GRID);
     $point = ProjectedPoint::createFromEastingNorthing(
+        $crs,
         new Metre(315904),
-        new Metre(234671),
-        $crs
+        new Metre(234671)
     );
 
     // also Spire of Dublin
@@ -245,9 +245,9 @@ Examples:
     // Spire of Dublin
     $crs = Projected::fromSRID(Projected::EPSG_IRENET95_IRISH_TRANSVERSE_MERCATOR);
     $point = ProjectedPoint::createFromEastingNorthing(
+        $crs,
         new Metre(715830),
         new Metre(734697),
-        $crs
     );
 
     // also Spire of Dublin
@@ -274,7 +274,7 @@ Treat each zone/hemisphere as a fully independent projection
 | Pros: no confusion about what the coordinates represent
 | Cons: when converting to UTM, you need to know in advance which zone/hemisphere the points reside in
 
-For many ``Geographic`` CRSs, there are corresponding dedicated ``Projected`` CRS for each individual UTM zone and
+For many ``Geographic2D`` CRSs, there are corresponding dedicated ``Projected`` CRS for each individual UTM zone and
 hemisphere. In total there are over 1000 individual such CRSs defined.
 
 Examples:
@@ -289,22 +289,22 @@ Examples:
     // Piazza San Marco, Venice
     $crs = Projected::fromSRID(Projected::EPSG_WGS_84_UTM_ZONE_33N);
     $point = ProjectedPoint::createFromEastingNorthing(
+        $crs,
         new Metre(291789),
         new Metre(5034599),
-        $crs
     );
 
     // Piazza San Marco, Venice
     $crs = Projected::fromSRID(Projected::EPSG_ETRS89_UTM_ZONE_33N);
     $point = ProjectedPoint::createFromEastingNorthing(
+        $crs,
         new Metre(291789),
         new Metre(5034599),
-        $crs
     );
 
 Prefix easting with the zone
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-| Pros: you only have to know the hemisphere when converting to UTM (latitude ± 0)
+| Pros: you only have to know the hemisphere when converting to UTM (i.e. is latitude ± 0)
 | Cons: coordinates are not distances, WGS84 only
 
 Because the previously described system has some practical difficulties in use when working with points that are not
@@ -331,9 +331,9 @@ Example:
     // Piazza San Marco, Venice
     $crs = Projected::fromSRID(Projected::EPSG_WGS_84_UTM_GRID_SYSTEM_NORTHERN_HEMISPHERE);
     $point = ProjectedPoint::createFromEastingNorthing(
+        $crs,
         new Metre(33291789), // UTM is defined as metres, but this coordinate is actually not...
-        new Metre(5034599),
-        $crs
+        new Metre(5034599)
     );
 
 Treat UTM as special
@@ -348,11 +348,11 @@ This is done via ``UTMPoint`` which is a specialised extension of ``ProjectedPoi
 .. code-block:: php
 
     public function __construct(
+        Geographic $crs,
         Length $easting,
         Length $northing,
         int $zone,
         string $hemisphere, //one of UTMPoint::HEMISPHERE_NORTH or UTMPoint::HEMISPHERE_SOUTH
-        Geographic $crs,
         ?DateTimeInterface $epoch = null
     ): UTMPoint
 
@@ -368,11 +368,11 @@ Example:
     // Piazza San Marco, Venice
     $crs = Geographic2D::fromSRID(Geographic2D::EPSG_WGS_84);
     $point = new UTMPoint(
+        $crs,
         new Metre(291789),
         new Metre(5034599),
         33,
         UTMPoint::HEMISPHERE_NORTH,
-        $crs
     );
 
     $easting = $point->getEasting(); // Metre

diff --git a/docs/creating_points_vertical.rst b/docs/creating_points_vertical.rst
@@ -9,8 +9,8 @@ A ``VerticalPoint`` can be constructed by calling ``VerticalPoint::create``, whi
 .. code-block:: php
 
     public static function create(
-        Length $height,
         Vertical $crs,
+        Length $height,
         ?DateTimeInterface $epoch = null
     ): VerticalPoint
 
@@ -27,15 +27,15 @@ Examples:
     // an arbitrary height in New Zealand Vertical Datum (unknown date), traditional arguments
     $crs = Vertical::fromSRID(Vertical::EPSG_NZVD2016_HEIGHT);
     $point = VerticalPoint::create(
+        $crs,
         new Metre(12.34),
-        $crs
     );
 
     // an arbitrary height in New Zealand Vertical Datum (2020-02-01), traditional arguments
     $crs = Vertical::fromSRID(Vertical::EPSG_NZVD2016_HEIGHT);
     $point = VerticalPoint::create(
-        new Metre(12.34),
         $crs,
+        new Metre(12.34),
         new DateTime('2020-02-01')
     );
 

diff --git a/src/BritishNationalGridPoint.php b/src/BritishNationalGridPoint.php
@@ -28,7 +28,7 @@ class BritishNationalGridPoint extends ProjectedPoint
 
     public function __construct(Length $easting, Length $northing, ?DateTimeInterface $epoch = null)
     {
-        parent::__construct($easting, $northing, null, null, Projected::fromSRID(Projected::EPSG_OSGB36_BRITISH_NATIONAL_GRID), $epoch);
+        parent::__construct(Projected::fromSRID(Projected::EPSG_OSGB36_BRITISH_NATIONAL_GRID), $easting, $northing, null, null, $epoch);
     }
 
     /**