Hidden String Laravel Package

Getting Started

Minimal Setup

1. Installation Add to your composer.json:

   composer require paragonie/hidden-string
   

   No configuration required—just autoload.

2. First Use Case Wrap sensitive strings (passwords, tokens, API keys) to prevent exposure in stack traces:

   use ParagonIE\HiddenString\HiddenString;
   
   $password = new HiddenString('s3cr3tP@ss');
   

3. Where to Look First

   • Class Docs (README)
   • Usage Examples (GitHub README)
   • API Reference (Methods like getString(), append(), etc.)

Implementation Patterns

Core Workflows

1. Wrapping Sensitive Data Replace raw strings with HiddenString in:

   • Authentication logic (e.g., Auth::attempt()).
   • API key handling (e.g., Http::withToken()).
   • Database queries (e.g., DB::select() with bound params).

   // Before
   $token = 'sk_live_123abc';
   
   // After
   $token = new HiddenString('sk_live_123abc');
   

2. Integration with Laravel

   • Request Validation: Cast sensitive fields to HiddenString in Form Requests:

     public function rules() {
         return ['password' => 'required|string'];
     }
     
     public function prepareForValidation() {
         $this->merge([
             'password' => new HiddenString($this->password)
         ]);
     }
     

   • Service Containers: Bind HiddenString to interfaces for type safety:

     $this->app->bind(SensitiveString::class, function () {
         return new HiddenString('default');
     });
     

3. String Operations Use HiddenString methods for safe manipulation:

   $hidden = new HiddenString('prefix_');
   $hidden->append('suffix'); // Returns new HiddenString('prefix_suffix')
   $hidden->toString();       // Returns 'prefix_suffix' (unwrapped)
   

4. Database Interactions Avoid exposing secrets in logs/queries:

   DB::table('users')->where('api_token', $hiddenToken)->update(['last_used' => now()]);
   

Gotchas and Tips

Pitfalls

1. Double Wrapping Wrapping an already-wrapped HiddenString throws RuntimeException. Validate first:

   if (!$string instanceof HiddenString) {
       $string = new HiddenString($string);
   }
   

2. Serialization Caveats HiddenString implements __toString() but not Serializable. Use getString() for serialization:

   $serialized = serialize($hidden->getString());
   

3. JSON Encoding json_encode() on HiddenString returns null. Use getString() explicitly:

   json_encode(['token' => $hidden->getString()]);
   

4. Laravel Debugging

   • Tinker/Dump: dd() or dump() will show [HiddenString] instead of raw values.
   • Logs: Ensure APP_DEBUG=false in production to avoid accidental leaks.

Debugging Tips

• Check Stack Traces: Use HiddenString in error contexts to verify masking:

  throw new \RuntimeException('Failed with token: ' . $hiddenToken);
  // Stack trace will show: "Failed with token: [HiddenString]"
  

• Unit Testing: Mock HiddenString for assertions:

  $this->assertInstanceOf(HiddenString::class, $sensitiveData);
  

Extension Points

1. Custom Masking Override __toString() for custom output (e.g., [REDACTED]):

   class CustomHiddenString extends HiddenString {
       public function __toString() {
           return '[REDACTED]';
       }
   }
   

2. Laravel Service Provider Add a macro to auto-wrap strings in logs:

   \Log::macro('sensitive', function ($message, $context = []) {
       array_walk($context, function (&$value) {
           $value = $value instanceof HiddenString ? '[HIDDEN]' : $value;
       });
       return \Log::info($message, $context);
   });
   

3. Environment Variables Use with vlucas/phpdotenv to hide .env secrets:

   $dotenv = Dotenv::createImmutable(__DIR__);
   $dotenv->load();
   $dbPassword = new HiddenString($_ENV['DB_PASSWORD']);