Initial commit

.gitignore

@@ -0,0 +1,2 @@
+vendor
+composer.lock

LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2021 National Flood Experts
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,26 @@
+# NCAT-PHP
+
+This is a simple implementation for [NOAA's NCAT API Service.](https://geodesy.noaa.gov/web_services/ncat/index.shtml) You can learn more about the National Geodetic Survey from NOAA [here.](https://www.ngs.noaa.gov/)
+
+Here is a simple example on how to use the package.
+
+```php
+$ncat = new NationalFloodExperts\NCAT\NCAT();
+
+// Make a request to the Latitude-longitude-height service
+$data = $ncat->llhRequest([
+  'lat' => 40.0,
+  'lon' => -80.0,
+  'eht' => 100.0,
+  'inDatum' => 'NAD83(1986)',
+  'outDatum' => 'NAD83(2011)'
+]);
+
+// Make a request to the U.S. National Grid service
+$data = $ncat->usngRequest([
+  'usng' => '15SWB4788338641',
+  'inDatum' => 'NAD83(2011)',
+  'outDatum' => 'NAD83(NSRS2007)',
+  'eht' => 100.0
+]);
+```

composer.json

@@ -0,0 +1,40 @@
+{
+    "name": "nationalfloodexperts/ncat",
+    "description": "A simple implementation of NOAA's NCAT API.",
+    "keywords": [
+      "NOAA",
+      "NCAT",
+      "NGS",
+      "VERTCON",
+      "Geodetic"
+    ],
+    "license": "MIT",
+    "authors": [
+      {
+        "name": "Robert Stefanic",
+        "email": "[email protected]",
+        "role": "Developer"
+      }
+    ],
+    "autoload": {
+        "psr-4": {
+            "NationalFloodExperts\\NCAT\\": "src"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "NationalFloodExperts\\NCAT\\Test\\": "tests"
+        }
+    },
+    "minimum-stability": "dev",
+    "prefer-stable": true,
+    "require": {
+        "guzzlehttp/guzzle": "^7.3"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "9"
+    },
+    "scripts": {
+        "test": "vendor/bin/phpunit"
+    }
+}

src/Exceptions/CannotConnectToNCATException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace NationalFloodExperts\NCAT\Exceptions;
+
+use Exception;
+
+class CannotConnectToNCATException extends Exception
+{
+    public function __construct(string $reason)
+    {
+        parent::__construct("Cannot connnect to NCAT: $reason");
+    }
+}

src/Exceptions/NCATTimeoutException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace NationalFloodExperts\NCAT\Exceptions;
+
+use Exception;
+
+class NCATTimeoutException extends Exception
+{
+    public function __construct()
+    {
+        parent::__construct("The connection to the NCAT server has timed out");
+    }
+}

src/Exceptions/RequiredParameterMissingException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace NationalFloodExperts\NCAT\Exceptions;
+
+use Exception;
+
+class RequiredParameterMissingException extends Exception
+{
+    public function __construct(string $parameterName)
+    {
+        parent::__construct("Missing Parameter '$parameterName'");
+    }
+}

src/NCAT.php

@@ -0,0 +1,108 @@
+<?php
+
+namespace NationalFloodExperts\NCAT;
+
+use NationalFloodExperts\NCAT\Exceptions\CannotConnectToNCATException;
+use NationalFloodExperts\NCAT\Exceptions\NCATTimeoutException;
+use NationalFloodExperts\NCAT\Exceptions\RequiredParameterMissingException;
+
+use GuzzleHttp\Client;
+use GuzzleHttp\ClientInterface;
+use GuzzleHttp\Exception\ConnectException;
+use GuzzleHttp\Exception\RequestException;
+
+class NCAT
+{
+    const BASE_URI = 'https://geodesy.noaa.gov/api/ncat/';
+    const CONNECT_TIMEOUT = 6;
+    const TIMEOUT = 10;
+
+    /** @var \GuzzleHttp\Client */
+    protected $client;
+
+    public function __construct(ClientInterface $client = null)
+    {
+        $this->client = $client ?? new Client([
+            'base_uri' => self::BASE_URI,
+            'connect_timeout' => self::CONNECT_TIMEOUT,
+            'timeout' => self::TIMEOUT
+        ]);
+    }
+
+    public function llhRequest(array $parameters = [])
+    {
+        $requiredLLHParameters = ['lat', 'lon', 'inDatum', 'outDatum'];
+        return $this->makeRequest('llh', $requiredLLHParameters, $parameters);
+    }
+
+    public function spcRequest(array $parameters = [])
+    {
+        $requiredSPCParameters = ['northing', 'easting', 'inDatum', 'outDatum', 'spcZone'];
+        return $this->makeRequest('spc', $requiredSPCParameters, $parameters);
+    }
+
+    public function utmRequest(array $parameters = [])
+    {
+        /*
+         * According to the NCAT documentation, the "spcZone" parameter is
+         * required for a UTM request. However, requests can be made without
+         * it. Since the documentation says that it is requried, we will check
+         * for it before making a request.
+         *
+         * More information below:
+         * https://geodesy.noaa.gov/web_services/ncat/utm-service.shtml
+         */
+        $requiredUTMParameters = ['northing', 'easting', 'inDatum', 'outDatum', 'spcZone', 'utmZone'];
+        return $this->makeRequest('utm', $requiredUTMParameters, $parameters);
+    }
+
+    public function xyzRequest(array $parameters = [])
+    {
+        $requiredXYZParameters = ['x', 'y', 'z', 'inDatum', 'outDatum'];
+        return $this->makeRequest('xyz', $requiredXYZParameters, $parameters);
+    }
+
+    public function usngRequest(array $parameters = [])
+    {
+        $requiredUSNGParameters = ['usng', 'inDatum', 'outDatum'];
+        return $this->makeRequest('usng', $requiredUSNGParameters, $parameters);
+    }
+
+    public function makeRequest($endpoint, $requiredParameters, $givenParameters)
+    {
+        $this->checkForRequiredParameters($requiredParameters, $givenParameters);
+
+        try {
+            $queryString = $this->buildQueryString($givenParameters);
+            $response = $this->client->get("$endpoint?$queryString");
+            return json_decode($response->getBody());
+        } catch (ConnectException $exception) {
+            throw new CannotConnectToNCATException('The connection with the NCAT server could not be established');
+        } catch (RequestException $exception) {
+            if (in_array($exception->getResponse()->getStatusCode(), ['408'])) {
+                throw new NCATTimeoutException();
+            }
+            throw $exception;
+        }
+    }
+
+    public function checkForRequiredParameters($requiredParameters, $parameters)
+    {
+        foreach ($requiredParameters as $required) {
+            if (!array_key_exists($required, $parameters)) {
+                throw new RequiredParameterMissingException($required);
+            }
+        }
+    }
+
+    public function buildQueryString(array $parameters): string
+    {
+        $queryString = '';
+
+        foreach ($parameters as $key => $value) {
+            $queryString .= $key . '=' . $value . '&';
+        }
+
+        return substr($queryString, 0, -1);
+    }
+}

tests/LLHRequestTest.php

@@ -0,0 +1,136 @@
+<?php
+
+namespace NationalFloodExperts\NCAT\Test;
+
+use NationalFloodExperts\NCAT\Exceptions\NCATTimeoutException;
+use NationalFloodExperts\NCAT\Exceptions\RequiredParameterMissingException;
+use NationalFloodExperts\NCAT\NCAT;
+
+use Exception;
+use PHPUnit\Framework\TestCase;
+
+class LLHRequestTest extends TestCase
+{
+    /** @test */
+    public function it_should_throw_an_error_if_required_parameters_are_missing_from_a_LLH_request()
+    {
+        $validLLHParameters = [
+            'lat' => 40.0,
+            'lon' => -80.0,
+            'inDatum' => 'nad83(1986)',
+            'outDatum' => 'nad83(2011)',
+        ];
+
+        $ncat = new NCAT();
+
+        foreach (['lat', 'lon', 'inDatum', 'outDatum'] as $requiredParameter) {
+            $llhParametersWithMissingRequiredField = array_filter($validLLHParameters, function ($key) use ($requiredParameter) {
+                return $key !== $requiredParameter;
+            }, ARRAY_FILTER_USE_KEY);
+
+            try {
+                $ncat->llhRequest($llhParametersWithMissingRequiredField);
+                $this->fail('Failed to assert that the RequiredParameterMissingException was thrown');
+            } catch (RequiredParameterMissingException $exception) {
+                $this->assertInstanceOf(RequiredParameterMissingException::class, $exception);
+            } catch (Exception $exception) {
+                $this->fail('Wrong exception thrown ' . $exception->getMessage());
+            }
+        }
+    }
+
+    /** @test */
+    public function it_should_throw_an_error_if_the_request_times_out()
+    {
+        $mockClient = TestingUtils::mockTimeoutRequest();
+        $ncat = new NCAT($mockClient);
+
+        $this->expectException(NCATTimeoutException::class);
+        $ncat->llhRequest([
+            'lat' => 40.0,
+            'lon' => -80.0,
+            'orthoHt' => 99.0,
+            'inDatum' => 'nad83(1986)',
+            'outDatum' => 'nad83(2011)',
+            'inVertDatum' => 'NGVD29',
+            'outVertDatum' => 'NAVD88'
+        ]);
+    }
+
+    /** @test */
+    public function it_should_make_a_LLH_request_if_all_of_the_required_parameters_are_included()
+    {
+        $mockClient = TestingUtils::mockOKRequest(json_encode($this->mockLLHResponseData()));
+        $ncat = new NCAT($mockClient);
+
+        $response = $ncat->llhRequest([
+            'lat' => 40.0,
+            'lon' => -80.0,
+            'orthoHt' => 99.0,
+            'inDatum' => 'nad83(1986)',
+            'outDatum' => 'nad83(2011)',
+            'inVertDatum' => 'NGVD29',
+            'outVertDatum' => 'NAVD88'
+        ]);
+
+        $this->assertEquals($response->srcLat, 40.0);
+        $this->assertEquals($response->srcLon, -80.0);
+    }
+
+    private function mockLLHResponseData()
+    {
+        /*
+         * Example request and response taken from the following URL:
+         * https://geodesy.noaa.gov/web_services/ncat/lat-long-height-service.shtml
+         */
+        return [
+              "ID" => "1627751399354",
+              "nadconVersion" => "5.0",
+              "vertconVersion" => "3.0",
+              "srcDatum" => "NAD83(1986)",
+              "destDatum" => "NAD83(2011)",
+              "srcVertDatum" => "N/A",
+              "destVertDatum" => "N/A",
+              "srcLat" => "40.0000000000",
+              "srcLatDms" => "N400000.00000",
+              "destLat" => "39.9999983008",
+              "destLatDms" => "N395959.99388",
+              "deltaLat" => "-0.189",
+              "sigLat" => "0.000263",
+              "sigLat_m" => "0.0081",
+              "srcLon" => "-80.0000000000",
+              "srcLonDms" => "W0800000.00000",
+              "destLon" => "-79.9999976143",
+              "destLonDms" => "W0795959.99141",
+              "deltaLon" => "0.204",
+              "sigLon" => "0.000221",
+              "sigLon_m" => "0.0052",
+              "srcEht" => "100.000",
+              "destEht" => "N/A",
+              "sigEht" => "N/A",
+              "srcOrthoht" => "N/A",
+              "destOrthoht" => "N/A",
+              "sigOrthoht" => "N/A",
+              "spcZone" => "PA S-3702",
+              "spcNorthing_m" => "76,470.391",
+              "spcEasting_m" => "407,886.681",
+              "spcNorthing_usft" => "250,886.607",
+              "spcEasting_usft" => "1,338,208.220",
+              "spcNorthing_ift" => "250,887.109",
+              "spcEasting_ift" => "1,338,210.896",
+              "spcConvergence" => "-01 27 35.22",
+              "spcScaleFactor" => "0.99999024",
+              "spcCombinedFactor" => "N/A",
+              "utmZone" => "UTM Zone 17",
+              "utmNorthing" => "4,428,235.878",
+              "utmEasting" => "585,360.668",
+              "utmConvergence" => "00 38 34.18",
+              "utmScaleFactor" => "0.99968970",
+              "utmCombinedFactor" => "N/A",
+              "x" => "N/A",
+              "y" => "N/A",
+              "z" => "N/A",
+              "usng" => "17SNE8536028235"
+        ];
+    }
+}