Privacy Filter Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require directorytree/privacy-filter
   

   Run the publisher (if needed) to publish the config:

   php artisan vendor:publish --provider="DirectoryTree\PrivacyFilter\PrivacyFilterServiceProvider"
   

2. First Use Case: Detect private entities (e.g., PII) in a string:

   use DirectoryTree\PrivacyFilter\Facades\PrivacyFilter;
   
   $text = "John Doe's SSN is 123-45-6789 and email is john@example.com";
   $results = PrivacyFilter::filter($text);
   
   // Outputs detected entities (e.g., SSN, email)
   dd($results);
   

3. Where to Look First:

   • Facade: DirectoryTree\PrivacyFilter\Facades\PrivacyFilter (primary entry point).
   • Config: config/privacy-filter.php (model path, binary path, etc.).
   • Service Provider: DirectoryTree\PrivacyFilter\PrivacyFilterServiceProvider (boot logic).

Implementation Patterns

Core Workflows

1. Filtering Text for PII:

   // Basic usage
   $results = PrivacyFilter::filter($text);
   
   // With custom model (if configured)
   $results = PrivacyFilter::filter($text, 'custom-model.gguf');
   

2. Batch Processing:

   $texts = ["Text 1 with PII", "Text 2 with PII"];
   $results = PrivacyFilter::batchFilter($texts);
   

3. Integration with Laravel Requests:

   // Filter user input (e.g., form submissions)
   $request->validate(['text' => 'required']);
   $filtered = PrivacyFilter::filter($request->input('text'));
   

4. Middleware for Automatic Filtering:

   // app/Http/Middleware/FilterPII.php
   public function handle(Request $request, Closure $next) {
       if ($request->has('sensitive_data')) {
           $request->merge(['filtered_data', PrivacyFilter::filter($request->sensitive_data)]);
       }
       return $next($request);
   }
   

5. Model Management:

   • Download/update models via Artisan:

     php artisan privacy-filter:download-model
     

   • Specify custom model paths in config/privacy-filter.php:

     'model_path' => storage_path('app/privacy-models'),
     

Integration Tips

• Queue Jobs for Async Processing:

  // Dispatch a job to filter text in the background
  FilterTextJob::dispatch($text)->onQueue('privacy');
  

• Laravel Events: Trigger events after filtering (e.g., log detected PII):

  PrivacyFilter::filter($text)->then(function ($results) {
      event(new PIIDetected($results));
  });
  

• API Responses: Sanitize API responses by filtering sensitive fields:

  $response = PrivacyFilter::filter($user->bio);
  return response()->json(['bio' => $response]);
  

Gotchas and Tips

Pitfalls

1. Binary Compatibility:

   • The package installs pre-compiled binaries for Linux/macOS/Windows. Ensure your server’s OS matches the binary (check config/privacy-filter.php for binary_path).
   • Fix: Manually compile the binary or use Docker if OS mismatches occur.

2. Model Downloads:

   • Models are not included by default and must be downloaded via Artisan:

     php artisan privacy-filter:download-model
     

   • Gotcha: Large models may fail on low-memory servers. Monitor disk space in storage_path('app/privacy-models').

3. Performance:

   • Filtering long texts (>10KB) may time out. Use batch processing or queue jobs for large payloads.
   • Tip: Cache results for repeated texts (e.g., in Redis):

     $cacheKey = 'privacy_filter_' . md5($text);
     $results = cache()->remember($cacheKey, now()->addHours(1), fn() => PrivacyFilter::filter($text));
     

4. False Positives/Negatives:

   • The underlying privacy-filter.cpp may misclassify edge cases (e.g., non-PII data like "123 Main St" flagged as an address).
   • Tip: Extend the package by subclassing DirectoryTree\PrivacyFilter\PrivacyFilter and overriding filter() logic.

5. Configuration Overrides:

   • Avoid hardcoding paths. Use the config file or environment variables:

     PRIVACY_FILTER_MODEL_PATH=/custom/path/to/models
     

Debugging

1. Binary Path Issues:

   • Verify the binary exists at config('privacy-filter.binary_path'). Reinstall with:

     composer require directorytree/privacy-filter --update-with-dependencies
     

2. Model Loading Errors:

   • Check storage/logs/laravel.log for missing model files. Manually download from PrivacyFilterBinaries.

3. Permission Denied:

   • Ensure the Laravel storage directory is writable:

     chmod -R 775 storage/
     

Extension Points

1. Custom Models:

   • Add new models to config('privacy-filter.models'):

     'models' => [
         'default' => 'default-model.gguf',
         'custom'  => 'path/to/custom-model.gguf',
     ],
     

   • Use them in code:

     PrivacyFilter::filter($text, 'custom');
     

2. Post-Processing:

   • Extend the PrivacyFilter facade to add callbacks:

     PrivacyFilter::extend(function ($filter) {
         $filter->after(function ($results) {
             // Log or transform results
         });
     });
     

3. Testing:

   • Mock the binary in tests using Laravel’s expectsJobs() or fake():

     use DirectoryTree\PrivacyFilter\Jobs\FilterTextJob;
     
     $this->fake(FilterTextJob::class);
     PrivacyFilter::filter($text); // Won't execute the binary
     

4. Custom Entities:

   • The package uses privacy-filter.cpp's default rules. To add custom rules (e.g., company-specific PII), rebuild the binary with your custom rules and replace the default binary.