Merge pull request #324 from EasyPost/type_hints

type hints
EasyPost · Nov 30, 2023 · a9b7ee5 · a9b7ee5
2 parents d573f88 + 1fed980
commit a9b7ee5
Show file tree

Hide file tree

Showing 40 changed files with 300 additions and 296 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,7 @@
 - Drops support for PHP 7.4
 - Adds support for PHP 8.3
 - Persists the HTTP client inside of the `EasyPostClient` via the `httpClient` property to reduce memory consumption on consecutive requests
+- Adds type hints for parameters and return values throughout the library, corrects docstring hints where necessary
 - Removed `withCarbonOffset` parameter from `create`, `buy`, and `regenerateRates` functions of the Shipment service as EasyPost now offers Carbon Neutral shipments by default for free
 - Fixes a bug where the original filtering criteria of `all` calls wasn't passed along to `getNextPage` calls. Now, these are persisted via a `_params` key on response objects locally
 - Removes the undocumented `createAndBuy` function from the `Batch` service. The proper usage is to create a batch first and buy it separately

diff --git a/lib/EasyPost/EasyPostClient.php b/lib/EasyPost/EasyPostClient.php
@@ -4,7 +4,6 @@
 
 use EasyPost\Constant\Constants;
 use EasyPost\Exception\General\EasyPostException;
-use EasyPost\Exception\General\MissingParameterException;
 use EasyPost\Hook\RequestHook;
 use EasyPost\Hook\ResponseHook;
 use EasyPost\Service\AddressService;
@@ -83,10 +82,10 @@ class EasyPostClient extends BaseService
      * @param object $mockingUtility
      */
     public function __construct(
-        $apiKey,
-        $timeout = Constants::TIMEOUT,
-        $apiBase = Constants::API_BASE,
-        $mockingUtility = null
+        string $apiKey,
+        float $timeout = Constants::TIMEOUT,
+        string $apiBase = Constants::API_BASE,
+        ?object $mockingUtility = null
     ) {
         // Client properties
         $this->apiKey = $apiKey;
@@ -96,22 +95,16 @@ public function __construct(
         $this->requestEvent = new RequestHook();
         $this->responseEvent = new ResponseHook();
         $this->httpClient = new Client();
-
-        if (!$this->apiKey) {
-            throw new MissingParameterException(
-                'No API key provided. See https://www.easypost.com/docs for details, or contact ' . Constants::SUPPORT_EMAIL . ' for assistance.' // phpcs:ignore
-            );
-        }
     }
 
     /**
      * Get a Service when calling a property of an EasyPostClient.
      *
      * @param string $serviceName
-     * @return BaseService
+     * @return mixed
      * @throws EasyPostException
      */
-    public function __get($serviceName)
+    public function __get(string $serviceName)
     {
         $serviceClassMap = [
             'address' => AddressService::class,
@@ -159,7 +152,7 @@ public function __get($serviceName)
      *
      * @return string
      */
-    public function getApiKey()
+    public function getApiKey(): string
     {
         return $this->apiKey;
     }
@@ -169,7 +162,7 @@ public function getApiKey()
      *
      * @return float
      */
-    public function getTimeout()
+    public function getTimeout(): float
     {
         return $this->timeout;
     }
@@ -179,7 +172,7 @@ public function getTimeout()
      *
      * @return string
      */
-    public function getApiBase()
+    public function getApiBase(): string
     {
         return $this->apiBase;
     }
@@ -189,7 +182,7 @@ public function getApiBase()
      *
      * @return bool
      */
-    public function mock()
+    public function mock(): bool
     {
         return $this->mockingUtility !== null;
     }
@@ -199,7 +192,7 @@ public function mock()
      *
      * @return object
      */
-    public function getMockingUtility()
+    public function getMockingUtility(): object
     {
         return $this->mockingUtility;
     }
@@ -210,7 +203,7 @@ public function getMockingUtility()
      * @param callable $function
      * @return void
      */
-    public function subscribeToRequestHook($function)
+    public function subscribeToRequestHook(callable $function): void
     {
         $this->requestEvent->addHandler($function);
     }
@@ -221,7 +214,7 @@ public function subscribeToRequestHook($function)
      * @param callable $function
      * @return void
      */
-    public function unsubscribeFromRequestHook($function)
+    public function unsubscribeFromRequestHook(callable $function): void
     {
         $this->requestEvent->removeHandler($function);
     }
@@ -232,7 +225,7 @@ public function unsubscribeFromRequestHook($function)
      * @param callable $function
      * @return void
      */
-    public function subscribeToResponseHook($function)
+    public function subscribeToResponseHook(callable $function): void
     {
         $this->responseEvent->addHandler($function);
     }
@@ -243,7 +236,7 @@ public function subscribeToResponseHook($function)
      * @param callable $function
      * @return void
      */
-    public function unsubscribeFromResponseHook($function)
+    public function unsubscribeFromResponseHook(callable $function): void
     {
         $this->responseEvent->removeHandler($function);
     }

diff --git a/lib/EasyPost/EasyPostObject.php b/lib/EasyPost/EasyPostObject.php
@@ -8,33 +8,18 @@
 
 class EasyPostObject implements \ArrayAccess, \Iterator
 {
-    /**
-     * @var array
-     */
-    protected $_values;
-
-    /**
-     * @var array
-     */
-    protected $_immutableValues;
-
-    /**
-     * @var string
-     */
-    private $_parent;
-
-    /**
-     * @var string
-     */
-    private $_name;
+    protected array $_values;
+    protected array $_immutableValues;
+    private mixed $_parent;
+    private mixed $_name;
 
     /**
      * Constructor for EasyPost objects.
      *
-     * @param string $parent
-     * @param string $name
+     * @param mixed $parent
+     * @param mixed $name
      */
-    public function __construct($parent = null, $name = null)
+    public function __construct(mixed $parent = null, mixed $name = null)
     {
         $this->_values = [];
         $this->_immutableValues = ['id'];
@@ -48,7 +33,7 @@ public function __construct($parent = null, $name = null)
      * @param string $k
      * @param mixed $v
      */
-    public function __set($k, $v)
+    public function __set(string $k, mixed $v): void
     {
         $this->_values[$k] = $v;
 
@@ -71,7 +56,7 @@ public function __set($k, $v)
      * @param string $k
      * @return bool
      */
-    public function __isset($k)
+    public function __isset(string $k): bool
     {
         return isset($this->_values[$k]);
     }
@@ -81,7 +66,7 @@ public function __isset($k)
      *
      * @param string $k
      */
-    public function __unset($k)
+    public function __unset(string $k): void
     {
         if (!in_array($k, $this->_immutableValues)) {
             unset($this->_values[$k]);
@@ -106,7 +91,7 @@ public function __unset($k)
      * @param string $k
      * @return mixed
      */
-    public function __get($k)
+    public function __get(string $k): mixed
     {
         if (array_key_exists($k, $this->_values)) {
             return $this->_values[$k];
@@ -121,12 +106,12 @@ public function __get($k)
     /**
      * Construct EasyPost objects from a response.
      *
-     * @param EasyPostClient $client
+     * @param EasyPostClient|null $client
      * @param array $values
      * @param string $class
      * @return mixed
      */
-    public static function constructFrom($client, $values, $class)
+    public static function constructFrom(?EasyPostClient $client, array $values, string $class): mixed
     {
         $object = new $class($client);
         $object->convertEach($client, $values);
@@ -137,10 +122,10 @@ public static function constructFrom($client, $values, $class)
     /**
      * Convert each piece of an EasyPost object.
      *
-     * @param EasyPostClient $client
+     * @param EasyPostClient|null $client
      * @param array $values
      */
-    public function convertEach($client, $values)
+    public function convertEach(?EasyPostClient $client, array $values): void
     {
         foreach ($values as $k => $v) {
             // We don't want `_params` to become the default `EasyPostObject` since it needs to remain a normal array
@@ -155,46 +140,42 @@ public function convertEach($client, $values)
     /**
      * ArrayAccess methods.
      *
-     * @param string $k
+     * @param mixed $k
      * @param mixed $v
      */
-    #[\ReturnTypeWillChange]
-    public function offsetSet($k, $v)
+    public function offsetSet(mixed $k, mixed $v): void
     {
         $this->$k = $v;
     }
 
     /**
      * ArrayAccess methods.
      *
-     * @param string $k
+     * @param mixed $k
      * @return bool
      */
-    #[\ReturnTypeWillChange]
-    public function offsetExists($k)
+    public function offsetExists(mixed $k): bool
     {
         return array_key_exists($k, $this->_values);
     }
 
     /**
      * ArrayAccess methods.
      *
-     * @param string $k
+     * @param mixed $k
      */
-    #[\ReturnTypeWillChange]
-    public function offsetUnset($k)
+    public function offsetUnset(mixed $k): void
     {
         unset($this->$k);
     }
 
     /**
      * ArrayAccess methods.
      *
-     * @param string $k
+     * @param mixed $k
      * @return mixed
      */
-    #[\ReturnTypeWillChange]
-    public function offsetGet($k)
+    public function offsetGet(mixed $k): mixed
     {
         return array_key_exists($k, $this->_values) ? $this->_values[$k] : null;
     }
@@ -204,8 +185,7 @@ public function offsetGet($k)
      *
      * @return void
      */
-    #[\ReturnTypeWillChange]
-    public function rewind()
+    public function rewind(): void
     {
         reset($this->_values);
     }
@@ -215,8 +195,7 @@ public function rewind()
      *
      * @return mixed
      */
-    #[\ReturnTypeWillChange]
-    public function current()
+    public function current(): mixed
     {
         return current($this->_values);
     }
@@ -226,30 +205,27 @@ public function current()
      *
      * @return mixed
      */
-    #[\ReturnTypeWillChange]
-    public function key()
+    public function key(): mixed
     {
         return key($this->_values);
     }
 
     /**
      * Iterator methods.
      *
-     * @return mixed
+     * @return void
      */
-    #[\ReturnTypeWillChange]
-    public function next()
+    public function next(): void
     {
-        return next($this->_values);
+        next($this->_values);
     }
 
     /**
      * Iterator methods.
      *
      * @return bool
      */
-    #[\ReturnTypeWillChange]
-    public function valid()
+    public function valid(): bool
     {
         $key = key($this->_values);
         return ($key !== null && $key !== false);
@@ -258,9 +234,9 @@ public function valid()
     /**
      * Convert object to JSON.
      *
-     * @return string
+     * @return string|bool
      */
-    public function __toJSON()
+    public function __toJSON(): string|bool
     {
         if (defined('JSON_PRETTY_PRINT')) {
             return json_encode($this->__toArray(true), JSON_PRETTY_PRINT);
@@ -274,18 +250,18 @@ public function __toJSON()
      *
      * @return string
      */
-    public function __toString()
+    public function __toString(): string
     {
         return $this->__toJSON();
     }
 
     /**
      * Convert object to an array.
      *
-     * @param bool $recursive
+     * @param bool|null $recursive
      * @return array
      */
-    public function __toArray($recursive = false)
+    public function __toArray(?bool $recursive = false): array
     {
         if ($recursive) {
             return Util::convertEasyPostObjectToArray($this->_values);