Add encrypt_file_with_password(), and `decrypt_file_with_password()…

…` functions

CHANGELOG.md

@@ -4,7 +4,8 @@
 
 ### Features
 
-* Add `encrypt_with_password()` and `decrypt_with_password()` functions to
+* Add `encrypt_with_password()`, `decrypt_with_password()`,
+  `encrypt_file_with_password()`, and `decrypt_file_with_password()` functions to
   encrypt and decrypt data
 
 ### Fixes

bin/generate-tests.php

@@ -89,6 +89,8 @@
     // Customized tests
     'crypto:decrypt',
     'crypto:encrypt',
+    'crypto:decrypt-file',
+    'crypto:encrypt-file',
     'fingerprint:task-with-a-fingerprint-and-force',
     'fingerprint:task-with-a-fingerprint-global',
     'fingerprint:task-with-a-fingerprint',

doc/going-further/helpers/crypto.md

@@ -40,3 +40,41 @@ function decrypt(string $content): void
     io()->writeln(decrypt_with_password($content, 'my super secret password'));
 }
 ```
+
+## The `encrypt_file_with_password()` function
+
+Castor provides a `encrypt_file_with_password()` function to allow to encrypt a
+file with a password:
+
+```php
+use Castor\Attribute\AsArgument;
+use Castor\Attribute\AsTask;
+
+use function Castor\encrypt_file_with_password;
+use function Castor\io;
+
+#[AsTask(description: 'Encrypt file with a password')]
+function encrypt_file(string $file): void
+{
+    encrypt_file_with_password($file, 'my super secret password');
+}
+```
+
+## The `decrypt_file_with_password()` function
+
+Castor provides a `decrypt_file_with_password()` function to allow to decrypt a
+file with a password:
+
+```php
+use Castor\Attribute\AsArgument;
+use Castor\Attribute\AsTask;
+
+use function Castor\decrypt_file_with_password;
+use function Castor\io;
+
+#[AsTask(description: 'Decrypt file with a password')]
+function decrypt_file(string $file): void
+{
+    decrypt_file_with_password($file, 'my super secret password');
+}
+```

doc/reference.md

@@ -11,7 +11,9 @@ Castor provides the following built-in functions:
 - [`capture`](getting-started/run.md#the-capture-function)
 - [`check`](going-further/helpers/assertion.md#the-check-function)
 - [`context`](getting-started/context.md#the-context-function)
+- [`decrypt_file_with_password`](going-further/helpers/cryto.md#the-decrpty_file_with_password-function)
 - [`decrypt_with_password`](going-further/helpers/cryto.md#the-decrpty_with_password-function)
+- [`encrypt_file_with_password`](going-further/helpers/cryto.md#the-encrypt_file_with_password-function)
 - [`encrypt_with_password`](going-further/helpers/cryto.md#the-encrypt_with_password-function)
 - [`exit_code`](getting-started/run.md#the-exit_code-function)
 - [`finder`](going-further/helpers/filesystem.md#the-finder-function)

examples/cryto.php

@@ -5,7 +5,9 @@
 use Castor\Attribute\AsArgument;
 use Castor\Attribute\AsTask;
 
+use function Castor\decrypt_file_with_password;
 use function Castor\decrypt_with_password;
+use function Castor\encrypt_file_with_password;
 use function Castor\encrypt_with_password;
 use function Castor\io;
 
@@ -20,3 +22,15 @@ function decrypt(string $content): void
 {
     io()->writeln(decrypt_with_password($content, 'my super secret password'));
 }
+
+#[AsTask(description: 'Encrypt file with a password')]
+function encrypt_file(string $file): void
+{
+    encrypt_file_with_password($file, 'my super secret password');
+}
+
+#[AsTask(description: 'Decrypt file with a password')]
+function decrypt_file(string $file): void
+{
+    decrypt_file_with_password($file, 'my super secret password');
+}

src/functions.php

@@ -836,6 +836,38 @@ function decrypt_with_password(string $content, string $password): string
     return Container::get()->symmetricCrypto->decrypt($content, $password);
 }
 
+function encrypt_file_with_password(string $sourcePath, string $password, ?string $destinationPath = null): void
+{
+    if (!file_exists($sourcePath)) {
+        throw new \InvalidArgumentException(\sprintf('The file "%s" does not exist.', $sourcePath));
+    }
+
+    $content = file_get_contents($sourcePath);
+    if (false === $content) {
+        throw new \RuntimeException(\sprintf('Failed to read the file "%s".', $sourcePath));
+    }
+
+    $encrypted = encrypt_with_password($content, $password);
+
+    Container::get()->fs->dumpFile($destinationPath ?? $sourcePath, $encrypted);
+}
+
+function decrypt_file_with_password(string $sourcePath, string $password, ?string $destinationPath = null): void
+{
+    if (!file_exists($sourcePath)) {
+        throw new \InvalidArgumentException(\sprintf('The file "%s" does not exist.', $sourcePath));
+    }
+
+    $content = file_get_contents($sourcePath);
+    if (false === $content) {
+        throw new \RuntimeException(\sprintf('Failed to read the file "%s".', $sourcePath));
+    }
+
+    $decrypted = decrypt_with_password($content, $password);
+
+    Container::get()->fs->dumpFile($destinationPath ?? $sourcePath, $decrypted);
+}
+
 function guard_min_version(string $minVersion): void
 {
     $currentVersion = Container::get()->application->getVersion();

tests/Generated/ListTest.php.output.txt

@@ -35,7 +35,9 @@ context:context                                                   Displays infor
 context:context-info-forced                                       Displays information about the context
 context:context-with                                              Displays information about the context, using a specific context
 crypto:decrypt                                                    Decrypt content with a password
+crypto:decrypt-file                                               Decrypt file with a password
 crypto:encrypt                                                    Encrypt content with a password
+crypto:encrypt-file                                               Encrypt file with a password
 env:env                                                           Display environment variables
 event-listener:my-task                                            An dummy task with event listeners attached
 failure:allow-failure                                             A failing task authorized to fail