Docblock/exception consistency

paragonie · Nov 1, 2017 · 2ab0b7a · 2ab0b7a
1 parent cf653cb
commit 2ab0b7a
Show file tree

Hide file tree

Showing 6 changed files with 73 additions and 35 deletions.
diff --git a/src/Bundle.php b/src/Bundle.php
@@ -1,6 +1,7 @@
 <?php
 namespace ParagonIE\Certainty;
 
+use ParagonIE\Certainty\Exception\FilesystemException;
 use ParagonIE\ConstantTime\Hex;
 
 /**
@@ -12,19 +13,29 @@
  */
 class Bundle
 {
-    /** @var string $chronicleHash */
+    /**
+     * @var string $chronicleHash
+     */
     protected $chronicleHash = '';
 
-    /** @var Validator $customValidator */
+    /**
+     * @var Validator $customValidator
+     */
     protected $customValidator;
 
-    /** @var string $filePath */
+    /**
+     * @var string $filePath
+     */
     protected $filePath = '';
 
-    /** @var string $sha256sum */
+    /**
+     * @var string $sha256sum
+     */
     protected $sha256sum = '';
 
-    /** @var string $signature */
+    /**
+     * @var string $signature
+     */
     protected $signature = '';
 
     /**
@@ -48,7 +59,6 @@ public function __construct(
         $this->sha256sum = $sha256sum;
         $this->signature = $signature;
         $this->chronicleHash = $chronicleHash;
-        $newClass = new Validator();
         if (!empty($customValidator)) {
             if (\class_exists($customValidator)) {
                 $newClass = new $customValidator();
@@ -57,6 +67,9 @@ public function __construct(
                 }
             }
         }
+        if (!isset($newClass)) {
+            $newClass = new Validator();
+        }
         $this->customValidator = $newClass;
     }
 
@@ -66,15 +79,15 @@ public function __construct(
      * @param string $destination
      * @param bool $unlinkIfExists
      * @return bool
-     * @throws \Exception
+     * @throws FilesystemException
      */
     public function createSymlink($destination = '', $unlinkIfExists = false)
     {
         if (\file_exists($destination)) {
             if ($unlinkIfExists) {
                 \unlink($destination);
             } else {
-                throw new \Exception('Destination already exists.');
+                throw new FilesystemException('Destination already exists.');
             }
         }
         return \symlink($this->filePath, $destination);
@@ -92,7 +105,7 @@ public function getFilePath()
      * Get the SHA256 hash of this bundle's contents. Defaults
      * to returning a hex-encoded string.
      *
-     * @param bool $raw
+     * @param bool $raw Return a raw binary string rather than hex-encoded?
      * @return string
      */
     public function getSha256Sum($raw = false)
@@ -107,7 +120,7 @@ public function getSha256Sum($raw = false)
      * Get the Ed25519 signature for this bundle. Defaults
      * to returning a hex-encoded string.
      *
-     * @param bool $raw
+     * @param bool $raw Return a raw binary string rather than hex-encoded?
      * @return string
      */
     public function getSignature($raw = false)

diff --git a/src/Exception/BundleException.php b/src/Exception/BundleException.php
@@ -0,0 +1,11 @@
+<?php
+namespace ParagonIE\Certainty\Exception;
+
+/**
+ * Class BundleException
+ * @package ParagonIE\Certainty\Exception
+ */
+class BundleException extends \Exception
+{
+
+}
diff --git a/src/Fetch.php b/src/Fetch.php
@@ -1,6 +1,10 @@
 <?php
 namespace ParagonIE\Certainty;
 
+use ParagonIE\Certainty\Exception\BundleException;
+use ParagonIE\Certainty\Exception\EncodingException;
+use ParagonIE\Certainty\Exception\FilesystemException;
+
 /**
  * Class Fetch
  * @package ParagonIE\Certainty
@@ -10,15 +14,17 @@ class Fetch
     const CHECK_SIGNATURE_BY_DEFAULT = false;
     const CHECK_CHRONICLE_BY_DEFAULT = false;
 
-    /** @var string $dataDirectory */
+    /**
+     * @var string $dataDirectory
+     */
     protected $dataDirectory = '';
 
     /**
      * Fetch constructor.
      *
      * You almost certainly want to use RemoteFetch instead.
      *
-     * @param string $dataDir
+     * @param string $dataDir Where the certificates and configuration lives
      */
     public function __construct($dataDir = '')
     {
@@ -33,10 +39,11 @@ public function __construct($dataDir = '')
      * Get the latest bundle. Checks the SHA256 hash of the file versus what
      * is expected. Optionally checks the Ed25519 signature.
      *
-     * @param bool|null $checkEd25519Signature
-     * @param bool|null $checkChronicle
+     * @param bool|null $checkEd25519Signature Enforce Ed25519 signatures?
+     * @param bool|null $checkChronicle        Require cert bundles be stored
+     *                                         inside a Chronicle instance?
      * @return Bundle
-     * @throws \Exception
+     * @throws BundleException
      */
     public function getLatestBundle($checkEd25519Signature = null, $checkChronicle = null)
     {
@@ -70,15 +77,15 @@ public function getLatestBundle($checkEd25519Signature = null, $checkChronicle =
                 }
             }
         }
-        throw new \Exception('No valid bundles were found in the data directory.');
+        throw new BundleException('No valid bundles were found in the data directory.');
     }
 
     /**
      * Get an array of all of the Bundles, ordered most-recent to oldest.
      *
      * No validation is performed automatically.
      *
-     * @param string $customValidator
+     * @param string $customValidator Fully-qualified class name for Validator
      * @return array<int, Bundle>
      */
     public function getAllBundles($customValidator = '')
@@ -89,30 +96,30 @@ public function getAllBundles($customValidator = '')
     /**
      * List bundles
      *
-     * @param string $customValidator
+     * @param string $customValidator Fully-qualified class name for Validator
      * @return array<int, Bundle>
      * @throws \Exception
      */
     protected function listBundles($customValidator = '')
     {
         if (!\file_exists($this->dataDirectory . '/ca-certs.json')) {
-            throw new \Exception('ca-certs.json not found in data directory.');
+            throw new FilesystemException('ca-certs.json not found in data directory.');
         }
         if (!\is_readable($this->dataDirectory . '/ca-certs.json')) {
-            throw new \Exception('ca-certs.json is not readable.');
+            throw new FilesystemException('ca-certs.json is not readable.');
         }
         $contents = \file_get_contents($this->dataDirectory . '/ca-certs.json');
         if (!\is_string($contents)) {
-            throw new \Exception('ca-certs.json could not be read.');
+            throw new FilesystemException('ca-certs.json could not be read.');
         }
         $data = \json_decode($contents, true);
         if (!\is_array($data)) {
-            throw new \Exception('ca-certs.json is not a valid JSON file.');
+            throw new EncodingException('ca-certs.json is not a valid JSON file.');
         }
         $bundles = [];
         foreach ($data as $row) {
             if (!isset($row['date'], $row['file'], $row['sha256'], $row['signature'])) {
-                // No
+                // The necessary keys are not defined.
                 continue;
             }
             $key = (int) (\preg_replace('/[^0-9]/', '', $row['date']) . '0000');

diff --git a/src/LocalCACertBuilder.php b/src/LocalCACertBuilder.php
@@ -15,42 +15,42 @@
 class LocalCACertBuilder extends Bundle
 {
     /**
-     * @var string
+     * @var string $chroniclePublicKey
      */
     protected $chroniclePublicKey = '';
 
     /**
-     * @var string
+     * @var string $chronicleRepoName
      */
     protected $chronicleRepoName = 'paragonie/certainty';
 
     /**
-     * @var string
+     * @var string $chronicleUrl
      */
     protected $chronicleUrl = '';
 
     /**
-     * @var string
+     * @var string $contents
      */
     protected $contents = '';
 
     /**
-     * @var string
+     * @var string $original
      */
     protected $original = '';
 
     /**
-     * @var string
+     * @var string $outputPem
      */
     protected $outputPem = '';
 
     /**
-     * @var string
+     * @var string $outputJson
      */
     protected $outputJson = '';
 
     /**
-     * @var string
+     * @var string $secretKey
      */
     protected $secretKey = '';
 

diff --git a/src/RemoteFetch.php b/src/RemoteFetch.php
@@ -18,13 +18,19 @@ class RemoteFetch extends Fetch
     const CHECK_CHRONICLE_BY_DEFAULT = true;
     const DEFAULT_URL = 'https://raw.githubusercontent.com/paragonie/certainty/master/data/';
 
-    /** @var \DateInterval */
+    /**
+     * @var \DateInterval $cacheTimeout
+     */
     protected $cacheTimeout;
 
-    /** @var Client */
+    /**
+     * @var Client $http
+     */
     protected $http;
 
-    /** @var string */
+    /**
+     * @var string $url
+     */
     protected $url = '';
 
     /**
@@ -65,6 +71,7 @@ public function __construct(
         } else {
             throw new \TypeError('Invalid timeout. Expected a DateInterval or string.');
         }
+        /** @var \DateInterval $timeoutObj */
         $this->cacheTimeout = $timeoutObj;
     }
 

diff --git a/src/Validator.php b/src/Validator.php
@@ -145,7 +145,7 @@ public static function checkChronicleHash(Bundle $bundle)
      * Actually validates the contents of a Chronicle entry.
      *
      * @param Bundle $bundle
-     * @param array $result
+     * @param array $result  Chronicle API response (post signature validation)
      * @return bool
      * @throws CryptoException
      * @throws InvalidResponseException