Merge pull request #11 from IlicMiljan/add-and-improve-php-docs

Improve PHP Docs
IlicMiljan · Mar 10, 2024 · f8309f9 · f8309f9
2 parents de2a40a + 6c111cb
commit f8309f9
Show file tree

Hide file tree

Showing 8 changed files with 79 additions and 48 deletions.
diff --git a/src/Cache/CacheItemPoolAdapter.php b/src/Cache/CacheItemPoolAdapter.php
@@ -15,6 +15,9 @@ public function __construct(CacheItemPoolInterface $cachePool)
         $this->cachePool = $cachePool;
     }
 
+    /**
+     * @inheritDoc
+     */
     public function get(string $key, callable $callable, ?int $ttl = null): mixed
     {
         try {

diff --git a/src/Cipher/AdvancedEncryptionStandardCipher.php b/src/Cipher/AdvancedEncryptionStandardCipher.php
@@ -23,12 +23,7 @@ public function __construct(
     }
 
     /**
-     * @param string $string
-     * @return string
-     *
-     * @throws FailedCalculatingInitializationVectorLength
-     * @throws FailedGeneratingInitializationVector
-     * @throws FailedEncryptingValue
+     * @inheritDoc
      */
     public function encrypt(#[SensitiveParameter] string $string): string
     {
@@ -44,11 +39,7 @@ public function encrypt(#[SensitiveParameter] string $string): string
     }
 
     /**
-     * @param string $string
-     * @return string
-     *
-     * @throws FailedCalculatingInitializationVectorLength
-     * @throws FailedDecryptingValue
+     * @inheritDoc
      */
     public function decrypt(#[SensitiveParameter] string $string): string
     {
@@ -90,6 +81,12 @@ public function generateInitializationVector(string $cipher): string
         return $iv;
     }
 
+    /**
+     * @param string $cipher
+     * @return int
+     *
+     * @throws FailedCalculatingInitializationVectorLength
+     */
     public function calculateInitializationVectorLength(string $cipher): int
     {
         $ivLength = openssl_cipher_iv_length($cipher);
@@ -101,6 +98,12 @@ public function calculateInitializationVectorLength(string $cipher): int
         return $ivLength;
     }
 
+    /**
+     * @param string $key
+     * @return void
+     *
+     * @throws InvalidKeyLength
+     */
     public function validateKey(string $key): void
     {
         if (strlen($key) !== self::KEY_LENGTH) {

diff --git a/src/Cipher/AsymmetricEncryptionCipher.php b/src/Cipher/AsymmetricEncryptionCipher.php
@@ -15,10 +15,7 @@ public function __construct(
     }
 
     /**
-     * @param string $string
-     * @return string
-     *
-     * @throws FailedEncryptingValue
+     * @inheritDoc
      */
     public function encrypt(#[SensitiveParameter] string $string): string
     {
@@ -30,10 +27,7 @@ public function encrypt(#[SensitiveParameter] string $string): string
     }
 
     /**
-     * @param string $string
-     * @return string
-     *
-     * @throws FailedDecryptingValue
+     * @inheritDoc
      */
     public function decrypt(#[SensitiveParameter] string $string): string
     {

diff --git a/src/EncryptionService.php b/src/EncryptionService.php
@@ -2,10 +2,62 @@
 
 namespace IlicMiljan\SecureProps;
 
+use IlicMiljan\SecureProps\Cipher\Exception\CipherException;
+use IlicMiljan\SecureProps\Exception\EncryptionServiceException;
+use IlicMiljan\SecureProps\Reader\Exception\ReaderException;
 use SensitiveParameter;
 
+/**
+ * Defines the contract for encryption services.
+ *
+ * This interface outlines the methods required for implementing encryption and
+ * decryption functionality.
+ *
+ * Implementations of this interface can be used to securely encrypt and decrypt
+ * values, ensuring that sensitive information is protected during storage or
+ * transmission.
+ */
 interface EncryptionService
 {
+    /**
+     * Encrypts the given value.
+     *
+     * Encrypts a provided value using the implementation's specific encryption
+     * algorithm. The value can be of any type, but implementations might
+     * restrict the types they accept.
+     *
+     * @param mixed $value The value to encrypt. While mixed, specific
+     *                     implementations may require certain types.
+     *
+     * @return mixed The encrypted value. The type of the return value might
+     *               vary based on the implementation.
+     *
+     * @throws EncryptionServiceException If the value cannot be encrypted due
+     *                                    to any reason.
+     * @throws CipherException If there is an error with the encryption process.
+     * @throws ReaderException If there is an error reading the properties for
+     *                         encryption.
+     */
     public function encrypt(#[SensitiveParameter] mixed $value): mixed;
+
+    /**
+     * Decrypts the given value.
+     *
+     * Decrypts a provided value using the implementation's specific decryption
+     * algorithm. This is intended to reverse the encryption process and
+     * retrieve the original value.
+     *
+     * @param mixed $value The value to decrypt. While mixed, specific
+     *                     implementations may require certain types.
+     *
+     * @return mixed The decrypted value. The type of the return value might
+     *               vary based on the implementation.
+     *
+     * @throws EncryptionServiceException If the value cannot be decrypted due
+     *                                    to any reason.
+     * @throws CipherException If there is an error with the decryption process.
+     * @throws ReaderException If there is an error reading the properties for
+     *                         decryption.
+     */
     public function decrypt(#[SensitiveParameter] mixed $value): mixed;
 }
diff --git a/src/ObjectEncryptionService.php b/src/ObjectEncryptionService.php
@@ -4,11 +4,8 @@
 
 use IlicMiljan\SecureProps\Attribute\Encrypted;
 use IlicMiljan\SecureProps\Cipher\Cipher;
-use IlicMiljan\SecureProps\Cipher\Exception\CipherException;
-use IlicMiljan\SecureProps\Exception\EncryptionServiceException;
 use IlicMiljan\SecureProps\Exception\ValueMustBeObject;
 use IlicMiljan\SecureProps\Exception\ValueMustBeString;
-use IlicMiljan\SecureProps\Reader\Exception\ReaderException;
 use IlicMiljan\SecureProps\Reader\ObjectPropertiesReader;
 use ReflectionProperty;
 use SensitiveParameter;
@@ -22,12 +19,9 @@ public function __construct(
     }
 
     /**
-     * @param mixed $value
-     * @return object
+     * @inheritDoc
      *
-     * @throws EncryptionServiceException
-     * @throws CipherException
-     * @throws ReaderException
+     * @return object
      */
     public function encrypt(#[SensitiveParameter] mixed $value): object
     {
@@ -49,13 +43,9 @@ public function encrypt(#[SensitiveParameter] mixed $value): object
     }
 
     /**
-     * @param mixed $value
+     * @inheritDoc
      *
      * @return object
-     *
-     * @throws EncryptionServiceException
-     * @throws CipherException
-     * @throws ReaderException
      */
     public function decrypt(#[SensitiveParameter] mixed $value): object
     {

diff --git a/src/Reader/CachingObjectPropertiesReader.php b/src/Reader/CachingObjectPropertiesReader.php
@@ -3,7 +3,6 @@
 namespace IlicMiljan\SecureProps\Reader;
 
 use IlicMiljan\SecureProps\Cache\Cache;
-use IlicMiljan\SecureProps\Cache\Exception\InvalidCacheKey;
 use IlicMiljan\SecureProps\Reader\Exception\ObjectPropertyNotFound;
 use Psr\Cache\CacheItemInterface;
 use ReflectionException;
@@ -21,8 +20,7 @@ public function __construct(
     }
 
     /**
-     * @throws InvalidCacheKey
-     * @throws ObjectPropertyNotFound
+     * @inheritDoc
      */
     public function getPropertiesWithAttribute(object $object, string $attributeClass): array
     {

diff --git a/src/Reader/RuntimeObjectPropertiesReader.php b/src/Reader/RuntimeObjectPropertiesReader.php
@@ -8,9 +8,7 @@
 class RuntimeObjectPropertiesReader implements ObjectPropertiesReader
 {
     /**
-     * @param object $object
-     * @param string $attributeClass
-     * @return ReflectionProperty[]
+     * @inheritDoc
      */
     public function getPropertiesWithAttribute(object $object, string $attributeClass): array
     {

diff --git a/src/StringEncryptionService.php b/src/StringEncryptionService.php
@@ -3,8 +3,6 @@
 namespace IlicMiljan\SecureProps;
 
 use IlicMiljan\SecureProps\Cipher\Cipher;
-use IlicMiljan\SecureProps\Cipher\Exception\CipherException;
-use IlicMiljan\SecureProps\Exception\EncryptionServiceException;
 use IlicMiljan\SecureProps\Exception\ValueMustBeString;
 use SensitiveParameter;
 
@@ -16,12 +14,9 @@ public function __construct(
     }
 
     /**
-     * @param mixed $value
+     * @inheritDoc
      *
      * @return string
-     *
-     * @throws EncryptionServiceException
-     * @throws CipherException
      */
     public function encrypt(#[SensitiveParameter] mixed $value): string
     {
@@ -33,11 +28,9 @@ public function encrypt(#[SensitiveParameter] mixed $value): string
     }
 
     /**
-     * @param mixed $value
-     * @return string
+     * @inheritDoc
      *
-     * @throws EncryptionServiceException
-     * @throws CipherException
+     * @return string
      */
     public function decrypt(#[SensitiveParameter] mixed $value): string
     {