PII Detection, Partial Masking, Stats API, and PHP 8.5 Support (#62)

Adds powerful new capabilities for PII detection, introduces partial masking, and provides a statistics API for monitoring scrubbing activity. 

## New Features

### 5 New PII Detection Patterns
| Pattern | Example | Masked Output |
|---------|---------|---------------|
| SSN | `123-45-6789` | `***-**-****` |
| Phone | `+1 (555) 123-4567` | `(***) ***-****` |
| IPv4 | `192.168.1.1` | `***.***.***.***` |
| IPv6 | `2001:0db8:...` | `****:****:...` |
| IBAN | `GB82WEST1234...` | `********************` |

### Partial Masking Support
New patterns use contextual replacement values via `getReplacementValue()` method:
```php
// Before: everything becomes "**redacted**"
// After: SSN → "***-**-****", Phone → "(***) ***-****"
```

### Detection Statistics API
```php
// Get stats for current request
$stats = Scrubber::getStats();
// ['total_scrubs' => 5, 'patterns_matched' => ['JsonWebToken' => 2, 'EmailAddress' => 3]]

// Test what patterns match
$result = Scrubber::test('Contact: john@example.com, SSN: 123-45-6789');
// ['matched' => true, 'patterns' => ['EmailAddress' => 1, 'SocialSecurityNumber' => 1], 'scrubbed' => '...']

// Reset stats
Scrubber::resetStats();
```

### PHP 8.5 Support
- Added PHP 8.5 to composer.json constraints
- Added PHP 8.5 to CI test matrix

## Performance Fixes (#61)
- Optimized regex repository access pattern
- Changed from `Collection::each()` to native `foreach` loop
- Cached config values instead of calling per-pattern

Author: yordadev

.github/workflows/phpunit.yml

@@ -11,7 +11,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        php: [8.2, 8.3, 8.4]
+        php: [8.2, 8.3, 8.4, 8.5]
         laravel: ['10.*', '11.*', '12.*']
         include:
           - php: 8.2
@@ -46,11 +46,21 @@ jobs:
             laravel: 12.*
             testbench: 10.*
 
+          - php: 8.5
+            laravel: 11.*
+            testbench: 9.*
+
+          - php: 8.5
+            laravel: 12.*
+            testbench: 10.*
+
         exclude:
           - laravel: 12.*
             php: 8.1
           - laravel: 10.*
             php: 8.4
+          - laravel: 10.*
+            php: 8.5
 
     name: PHP${{ matrix.php }} - Laravel ${{ matrix.laravel }}${{ matrix.skip && ' (skipped)' || '' }}
 

README.md

@@ -19,6 +19,11 @@
 A Laravel package to scrub sensitive information that breaks operational security policies from being leaked on
 accident ~~_or not_~~ by developers.
 
+## Requirements
+
+- PHP 8.1, 8.2, 8.3, 8.4, or 8.5
+- Laravel 10.x, 11.x, or 12.x
+
 ## Installation
 
 install the package via composer:
@@ -171,6 +176,27 @@ Scrubber::processMessage('<insert jwt token here>');
 // **redacted**
 ```
 
+### Detection Statistics API
+
+Track what patterns are matching and how often:
+
+```php
+// Get scrubbing statistics for the current request
+$stats = Scrubber::getStats();
+// ['total_scrubs' => 5, 'patterns_matched' => ['JsonWebToken' => 2, 'EmailAddress' => 3]]
+
+// Test a string without modifying stats - useful for debugging
+$result = Scrubber::test('Contact: john@example.com, SSN: 123-45-6789');
+// [
+//     'matched' => true,
+//     'patterns' => ['EmailAddress' => 1, 'SocialSecurityNumber' => 1],
+//     'scrubbed' => 'Contact: **redacted**, SSN: ***-**-****'
+// ]
+
+// Reset statistics between requests
+Scrubber::resetStats();
+```
+
 ## Log Channel Opt-in
 
 This package provides you the ability to define through the configuration file what channels you want to scrub
@@ -215,6 +241,28 @@ class.
     ],
 ```
 
+> **Note**: The package includes 31 built-in patterns. See all available patterns in [RegexCollection.php](https://github.com/YorCreative/Laravel-Scrubber/blob/main/src/Repositories/RegexCollection.php).
+
+### PII Detection with Partial Masking
+
+The following patterns use contextual replacement values for improved readability instead of the generic `**redacted**`:
+
+| Pattern | Detects | Masked Output |
+|---------|---------|---------------|
+| `RegexCollection::$SOCIAL_SECURITY_NUMBER` | US Social Security Numbers | `***-**-****` |
+| `RegexCollection::$PHONE_NUMBER` | Phone numbers (US/International) | `(***) ***-****` |
+| `RegexCollection::$IP_ADDRESS_V4` | IPv4 addresses | `***.***.***.***` |
+| `RegexCollection::$IP_ADDRESS_V6` | IPv6 addresses | `****:****:****:...` |
+| `RegexCollection::$IBAN` | International Bank Account Numbers | `********************` |
+
+```php
+Scrubber::processMessage('SSN: 123-45-6789, Phone: (555) 123-4567');
+// "SSN: ***-**-****, Phone: (***) ***-****"
+
+Scrubber::processMessage('Server IP: 192.168.1.1');
+// "Server IP: ***.***.***.***"
+```
+
 ### Opting Into Custom Extended Classes
 
 > To create custom scrubbers, see the [Extending the Scrubber](#extending-the-scrubber) section.

composer.json

@@ -16,7 +16,7 @@
     ],
     "minimum-stability": "dev",
     "require": {
-        "php": "^8.1|^8.2|^8.3",
+        "php": "^8.1|^8.2|^8.3|^8.4|^8.5",
         "illuminate/contracts": "^9.0|^10.0|^11.0|^12.0",
         "monolog/monolog": "^2.0|^3",
         "guzzlehttp/guzzle": "^7.5",

phpunit.xml

@@ -7,6 +7,9 @@
     <testsuite name="Feature">
       <directory suffix="Test.php">./tests/Feature</directory>
     </testsuite>
+    <testsuite name="Performance">
+      <directory suffix="Test.php">./tests/Performance</directory>
+    </testsuite>
   </testsuites>
   <php>
     <env name="APP_ENV" value="testing"/>

src/RegexCollection/Iban.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace YorCreative\Scrubber\RegexCollection;
+
+use YorCreative\Scrubber\Interfaces\RegexCollectionInterface;
+
+class Iban implements RegexCollectionInterface
+{
+    public function getPattern(): string
+    {
+        // Matches IBAN: 2 letter country code + 2 check digits + up to 30 alphanumeric characters
+        return '\b[A-Z]{2}\d{2}[A-Z0-9]{4,30}\b';
+    }
+
+    public function getTestableString(): string
+    {
+        // Test IBAN (GB format with zeros)
+        return 'GB00TEST00000000000000';
+    }
+
+    public function isSecret(): bool
+    {
+        return false;
+    }
+
+    public function getReplacementValue(): string
+    {
+        return '********************';
+    }
+}

src/RegexCollection/IpAddressV4.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace YorCreative\Scrubber\RegexCollection;
+
+use YorCreative\Scrubber\Interfaces\RegexCollectionInterface;
+
+class IpAddressV4 implements RegexCollectionInterface
+{
+    public function getPattern(): string
+    {
+        // Matches IPv4 addresses: 192.168.1.1, 10.0.0.1, etc.
+        return '\b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\b';
+    }
+
+    public function getTestableString(): string
+    {
+        return '192.168.0.1';
+    }
+
+    public function isSecret(): bool
+    {
+        return false;
+    }
+
+    public function getReplacementValue(): string
+    {
+        return '***.***.***.***';
+    }
+}

src/RegexCollection/IpAddressV6.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace YorCreative\Scrubber\RegexCollection;
+
+use YorCreative\Scrubber\Interfaces\RegexCollectionInterface;
+
+class IpAddressV6 implements RegexCollectionInterface
+{
+    public function getPattern(): string
+    {
+        // Matches IPv6 addresses including compressed forms
+        return '\b(?:[0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}\b|\b(?:[0-9a-fA-F]{1,4}:){1,7}:\b|\b(?:[0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}\b|\b(?:[0-9a-fA-F]{1,4}:){1,5}(?::[0-9a-fA-F]{1,4}){1,2}\b|\b(?:[0-9a-fA-F]{1,4}:){1,4}(?::[0-9a-fA-F]{1,4}){1,3}\b|\b::(?:[0-9a-fA-F]{1,4}:){0,5}[0-9a-fA-F]{1,4}\b|\b[0-9a-fA-F]{1,4}::(?:[0-9a-fA-F]{1,4}:){0,5}[0-9a-fA-F]{1,4}\b';
+    }
+
+    public function getTestableString(): string
+    {
+        return '2001:0db8:85a3:0000:0000:8a2e:0370:7334';
+    }
+
+    public function isSecret(): bool
+    {
+        return false;
+    }
+
+    public function getReplacementValue(): string
+    {
+        return '****:****:****:****:****:****:****:****';
+    }
+}

src/RegexCollection/PhoneNumber.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace YorCreative\Scrubber\RegexCollection;
+
+use YorCreative\Scrubber\Interfaces\RegexCollectionInterface;
+
+class PhoneNumber implements RegexCollectionInterface
+{
+    public function getPattern(): string
+    {
+        // Matches various phone formats:
+        // +1 (555) 123-4567, 555-123-4567, (555) 123-4567, 5551234567, +1-555-123-4567
+        return '(?:\+?1[-.\s]?)?(?:\(?\d{3}\)?[-.\s]?)?\d{3}[-.\s]?\d{4}\b';
+    }
+
+    public function getTestableString(): string
+    {
+        return '+1 (555) 000-0000';
+    }
+
+    public function isSecret(): bool
+    {
+        return false;
+    }
+
+    public function getReplacementValue(): string
+    {
+        return '(***) ***-****';
+    }
+}

src/RegexCollection/SocialSecurityNumber.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace YorCreative\Scrubber\RegexCollection;
+
+use YorCreative\Scrubber\Interfaces\RegexCollectionInterface;
+
+class SocialSecurityNumber implements RegexCollectionInterface
+{
+    public function getPattern(): string
+    {
+        // Matches SSN formats: 123-45-6789, 123 45 6789, 123456789
+        return '\b(?!000|666|9\d{2})\d{3}[-\s]?(?!00)\d{2}[-\s]?(?!0000)\d{4}\b';
+    }
+
+    public function getTestableString(): string
+    {
+        // Using obviously fake SSN for tests - 123-45-6789 is a well-known test value
+        // This matches the regex pattern but is universally recognized as fake
+        return '123-45-6789';
+    }
+
+    public function isSecret(): bool
+    {
+        return false;
+    }
+
+    public function getReplacementValue(): string
+    {
+        return '***-**-****';
+    }
+}

src/Repositories/RegexCollection.php

@@ -55,4 +55,14 @@ class RegexCollection
     public static string $TWILIO_APP_SID = 'TwilioAppSid';
 
     public static string $EMAIL_ADDRESS = 'EmailAddress';
+
+    public static string $SOCIAL_SECURITY_NUMBER = 'SocialSecurityNumber';
+
+    public static string $PHONE_NUMBER = 'PhoneNumber';
+
+    public static string $IP_ADDRESS_V4 = 'IpAddressV4';
+
+    public static string $IP_ADDRESS_V6 = 'IpAddressV6';
+
+    public static string $IBAN = 'Iban';
 }