Merge pull request #4 from dynamik-dev/task/refactor-2

add helper, readme update

Author: christopherarter

.DS_Store

@@ -1,16 +1,14 @@
 # Cloak
 
+![Cloak PHP Example](cloak-php.png)
+
 A simple, extensible PHP package for redacting sensitive data from strings and revealing them later.
 
 ```php
-use DynamikDev\Cloak\Cloak;
-
-$cloak = Cloak::make();
-
-$cloaked = $cloak->cloak('Email me at john@example.com');
+$cloaked = cloak('Email me at john@example.com');
 // "Email me at {{EMAIL_x7k2m9_1}}"
 
-$original = $cloak->uncloak($cloaked);
+$original = uncloak($cloaked);
 // "Email me at john@example.com"
 ```
 
@@ -27,18 +25,14 @@ composer require dynamik-dev/cloak-php
 
 ## Quick Start
 
-### Basic Usage
+### Using Helper Functions
 
 ```php
-use DynamikDev\Cloak\Cloak;
-
-$cloak = Cloak::make();
-
 $text = 'Contact: john@example.com, Phone: 555-123-4567';
-$cloaked = $cloak->cloak($text);
+$cloaked = cloak($text);
 // "Contact: {{EMAIL_x7k2m9_1}}, Phone: {{PHONE_x7k2m9_1}}"
 
-$original = $cloak->uncloak($cloaked);
+$original = uncloak($cloaked);
 // "Contact: john@example.com, Phone: 555-123-4567"
 ```
 
@@ -48,16 +42,29 @@ $original = $cloak->uncloak($cloaked);
 use DynamikDev\Cloak\Detector;
 
 // Only detect emails
-$cloaked = $cloak->cloak($text, [Detector::email()]);
+$cloaked = cloak($text, [Detector::email()]);
 
 // Multiple detectors
-$cloaked = $cloak->cloak($text, [
+$cloaked = cloak($text, [
     Detector::email(),
     Detector::phone('US'),
     Detector::ssn(),
 ]);
 ```
 
+### Using the Cloak Class
+
+For more control, use the `Cloak` class directly:
+
+```php
+use DynamikDev\Cloak\Cloak;
+
+$cloak = Cloak::make();
+
+$cloaked = $cloak->cloak($text);
+$original = $cloak->uncloak($cloaked);
+```
+
 ### Configuring with Builder Methods
 
 ```php
@@ -67,7 +74,6 @@ use DynamikDev\Cloak\Encryptors\OpenSslEncryptor;
 
 $cloak = Cloak::make()
     ->withDetectors([Detector::email()])
-    ->withTtl(7200)
     ->encrypt(OpenSslEncryptor::generateKey());
 
 $cloaked = $cloak->cloak('Sensitive: john@example.com');

README.md

@@ -6,7 +6,10 @@
     "autoload": {
         "psr-4": {
             "DynamikDev\\Cloak\\": "src/"
-        }
+        },
+        "files": [
+            "src/helpers.php"
+        ]
     },
     "autoload-dev": {
         "psr-4": {

cloak-php.png

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+use DynamikDev\Cloak\Cloak;
+use DynamikDev\Cloak\Contracts\StoreInterface;
+
+if (! function_exists('cloak')) {
+    /**
+     * Cloak sensitive data in text using the provided detectors.
+     *
+     * @param string $text The text to cloak
+     * @param array<int, \DynamikDev\Cloak\Contracts\DetectorInterface>|null $detectors Optional detectors to use
+     * @param StoreInterface|null $store Optional store instance
+     * @return string The cloaked text with placeholders
+     */
+    function cloak(string $text, ?array $detectors = null, ?StoreInterface $store = null): string
+    {
+        return Cloak::make($store)->cloak($text, $detectors);
+    }
+}
+
+if (! function_exists('uncloak')) {
+    /**
+     * Uncloak text by replacing placeholders with original values.
+     *
+     * @param string $text The text containing placeholders
+     * @param StoreInterface|null $store Optional store instance
+     * @return string The uncloaked text with original values
+     */
+    function uncloak(string $text, ?StoreInterface $store = null): string
+    {
+        return Cloak::make($store)->uncloak($text);
+    }
+}

composer.json

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+use DynamikDev\Cloak\Detector;
+
+it('cloak helper function works', function () {
+    $text = 'Email: test@example.com';
+    $result = cloak($text);
+
+    expect($result)->toMatch('/Email: \{\{EMAIL_[a-zA-Z0-9]{6}_1\}\}/');
+});
+
+it('uncloak helper function works', function () {
+    $text = 'Email: test@example.com';
+    $cloaked = cloak($text);
+    $uncloaked = uncloak($cloaked);
+
+    expect($uncloaked)->toBe($text);
+});
+
+it('cloak helper accepts custom detectors', function () {
+    $text = 'Email: test@example.com SSN: 123-45-6789';
+    $result = cloak($text, [Detector::email()]);
+
+    expect($result)->toMatch('/\{\{EMAIL_[a-zA-Z0-9]{6}_1\}\}/');
+    expect($result)->toContain('123-45-6789');
+});
+
+it('helpers use default ArrayStore', function () {
+    $text = 'test@example.com';
+    $cloaked = cloak($text);
+
+    expect($cloaked)->toMatch('/\{\{EMAIL_[a-zA-Z0-9]{6}_1\}\}/');
+    expect(uncloak($cloaked))->toBe($text);
+});