From 81133d605862fef1979bdac59c057c3b7ea6f460 Mon Sep 17 00:00:00 2001 From: BJ Hansen Date: Mon, 22 Jul 2024 17:59:29 -0500 Subject: [PATCH] Added missing type definitions; added comments --- src/Api.php | 66 ++++++++++++++++++++++++++--- src/Features/BaseFeature.php | 4 +- src/Features/LatestObservations.php | 1 - src/Features/ObservationStation.php | 4 +- src/Features/Point.php | 12 +++--- src/Support/Carbon.php | 4 ++ src/Traits/IsCallable.php | 2 +- 7 files changed, 75 insertions(+), 18 deletions(-) diff --git a/src/Api.php b/src/Api.php index edd5e6c..3194bd5 100644 --- a/src/Api.php +++ b/src/Api.php @@ -13,7 +13,6 @@ use BenjaminHansen\NWS\Exceptions\CacheException; use BenjaminHansen\NWS\Support\Carbon; use DateInterval; -use DateTime; use DateTimeZone; class Api @@ -28,10 +27,15 @@ class Api private DateTimeZone $timezone; private string $cache_driver = 'Files'; - public function __construct(string $domain, string $email) + public function __construct(string $domain, string $email, string|DateTimeZone $timezone = null) { - // default the api requests to a reasonable timezone - $this->timezone('UTC'); + if($timezone) { + // set the timezone that was passed into the constructor + $this->timezone($timezone); + } else { + // default the api requests to a reasonable timezone + $this->timezone('UTC'); + } // set our user agent for the API requests $this->userAgent($domain, $email); @@ -45,6 +49,9 @@ public function __construct(string $domain, string $email) ]); } + /* + ** get/set the user_agent for the API http client + */ private function userAgent(string $domain = null, string $email = null): string|self { if($domain && $email) { @@ -55,6 +62,9 @@ private function userAgent(string $domain = null, string $email = null): string| } } + /* + ** get/set the cache_lifetime used for the API's caching layer, if you opted for it. + */ public function cacheLifetime(int|DateInterval $lifetime = null): string|self|DateInterval { if($lifetime) { @@ -65,6 +75,9 @@ public function cacheLifetime(int|DateInterval $lifetime = null): string|self|Da } } + /* + ** get/set the cache_driver used for the caching layer, if you opted for it. + */ public function cacheDriver(string $driver = null): string|self { if($driver) { @@ -75,6 +88,9 @@ public function cacheDriver(string $driver = null): string|self } } + /* + ** Opt-in for using the caching layer. This is STRONGLY recommended! + */ public function useCache(int $lifetime = null, string $driver = null): self { if($lifetime) { @@ -91,6 +107,9 @@ public function useCache(int $lifetime = null, string $driver = null): self return $this; } + /* + ** get/set the base_url for all API requests made the NWS + */ public function baseUrl(string $base_url = null): string|self { if($base_url) { @@ -101,6 +120,9 @@ public function baseUrl(string $base_url = null): string|self } } + /* + ** Clear the local cache + */ public function clearCache(): self { if(($this->cache && $this->cache->clear()) || !$this->cache) { @@ -110,6 +132,9 @@ public function clearCache(): self throw new CacheException("Failed to clear the cache!"); } + /* + ** get/set the timezone used to cast all datetime values returned from the API + */ public function timezone(string|DateTimeZone $timezone = null): DateTimeZone|self { if($timezone) { @@ -125,7 +150,12 @@ public function timezone(string|DateTimeZone $timezone = null): DateTimeZone|sel } } - public function get($url): object|bool + /* + ** The main meat and potatoes of this project. Each request URL must pass through this method and the results + ** are either returned from the local cache or are retrieved from the NWS API endpoint to be returned directly + ** or stashed in the cache first and then returned to the user. + */ + public function get(string $url): object|bool { // the user did not opt to use the cache, so make a direct request to the URL endpoint // and bypass all the following cache-related code, returning early @@ -179,22 +209,31 @@ public function get($url): object|bool // if the URL is not in our cache exclusion array, we should cache it if(!stripos_array($url, $this->cache_exclusions)) { - $this->cache->set($key, $data, $this->cache_lifetime); + $this->cache->set($key, $data, $this->cacheLifetime()); } return $data; } + /* + ** Return the status of the NWS API endpoint + */ public function status(): string { return trim($this->get($this->base_url)->status); } + /* + ** Check if the API status is OK and return a boolean + */ public function ok(): bool { return strtolower($this->status()) === "ok"; } + /* + ** Make sure that the API status is OK, otherwise bail out + */ public function assertOk(string $message = null): self { if(!$this->ok()) { @@ -209,12 +248,18 @@ public function assertOk(string $message = null): self return $this; } + /* + ** Get a specific lat/lon point and its corresponding weather data + */ public function point(float $lat, float $lon): Point { $url = "{$this->baseUrl()}/points/{$lat},{$lon}"; return new Point($this->get($url), $this); } + /* + ** Get a specific observation station and its corresponding weather data + */ public function observationStation(string $observation_station): ObservationStation { $observation_station = strtoupper($observation_station); @@ -222,12 +267,18 @@ public function observationStation(string $observation_station): ObservationStat return new ObservationStation($this->get($url), $this); } + /* + ** Get ALL observation stations and their corresponding weather data + */ public function observationStations(): ObservationStations { $url = "{$this->baseUrl()}/stations"; return new ObservationStations($this->get($url), $this); } + /* + ** Get a specific Weather Forecast Office and its pertinent information + */ public function forecastOffice(string $forecast_office): ForecastOffice { $forecast_office = strtoupper($forecast_office); @@ -235,6 +286,9 @@ public function forecastOffice(string $forecast_office): ForecastOffice return new ForecastOffice($this->get($url), $this); } + /* + ** Get the NWS API's glossary for term lookups, etc. + */ public function glossary(): Glossary { $url = "{$this->baseUrl()}/glossary"; diff --git a/src/Features/BaseFeature.php b/src/Features/BaseFeature.php index 60c6412..765f6be 100644 --- a/src/Features/BaseFeature.php +++ b/src/Features/BaseFeature.php @@ -9,8 +9,8 @@ class BaseFeature { use IsCallable; - public $data; - public $api; + public object $data; + public Api $api; public function __construct(object $data, Api $api) { diff --git a/src/Features/LatestObservations.php b/src/Features/LatestObservations.php index f4f4330..22c6d84 100644 --- a/src/Features/LatestObservations.php +++ b/src/Features/LatestObservations.php @@ -5,7 +5,6 @@ use BenjaminHansen\NWS\Api; use BenjaminHansen\NWS\Support\Helpers; use BenjaminHansen\NWS\Support\Carbon; -use DateInterval; class LatestObservations extends BaseFeature { diff --git a/src/Features/ObservationStation.php b/src/Features/ObservationStation.php index 85aea2e..994ebec 100644 --- a/src/Features/ObservationStation.php +++ b/src/Features/ObservationStation.php @@ -12,12 +12,12 @@ public function __construct(object $data, Api $api) parent::__construct($data, $api); } - public function latitude() + public function latitude(): string|int|float { return $this->geometry_coordinates()[1]; } - public function longitude() + public function longitude(): string|int|float { return $this->geometry_coordinates()[0]; } diff --git a/src/Features/Point.php b/src/Features/Point.php index da2478a..b8dfbb0 100644 --- a/src/Features/Point.php +++ b/src/Features/Point.php @@ -13,27 +13,27 @@ public function __construct(object $data, Api $api) parent::__construct($data, $api); } - public function city() + public function city(): string { return $this->properties_relativeLocation_properties_city(); } - public function state() + public function state(): UsState { return new UsState($this->properties_relativeLocation_properties_state()); } - public function cwa() + public function cwa(): string { - $this->properties_cwa(); + return $this->properties_cwa(); } - public function latitude() + public function latitude(): string|int|float { return $this->geometry_coordinates()[1]; } - public function longitude() + public function longitude(): string|int|float { return $this->geometry_coordinates()[0]; } diff --git a/src/Support/Carbon.php b/src/Support/Carbon.php index 2eeb7ae..6c79052 100644 --- a/src/Support/Carbon.php +++ b/src/Support/Carbon.php @@ -11,6 +11,10 @@ public function __construct($time = null, $timezone = null) parent::__construct($time, $timezone); } + /* + ** If the current timezone is not equal to the one passed to this method, + ** then set the timezone to the provided value + */ public function setTimezoneIfNot($timezone): self { if($this->getTimezone()->getName() !== $timezone->getName()) { diff --git a/src/Traits/IsCallable.php b/src/Traits/IsCallable.php index 98b59cc..d84f00f 100644 --- a/src/Traits/IsCallable.php +++ b/src/Traits/IsCallable.php @@ -4,7 +4,7 @@ trait IsCallable { - public function raw() + public function raw(): object { return $this->data; }