Added missing type definitions; added comments

benjaminhansen · Jul 22, 2024 · 81133d6 · 81133d6
1 parent f0c8c4d
commit 81133d6
Show file tree

Hide file tree

Showing 7 changed files with 75 additions and 18 deletions.
diff --git 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,32 +248,47 @@ 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);
         $url = "{$this->baseUrl()}/stations/{$observation_station}";
         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);
         $url = "{$this->baseUrl()}/offices/{$forecast_office}";
         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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -4,7 +4,7 @@
 
 trait IsCallable
 {
-    public function raw()
+    public function raw(): object
     {
         return $this->data;
     }