Dami Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require czogori/dami
   

   Add the service provider to config/app.php under providers:

   Czogori\Dami\DamiServiceProvider::class,
   

2. Publish Config (Optional)

   php artisan vendor:publish --provider="Czogori\Dami\DamiServiceProvider"
   

   Check config/dami.php for default settings (e.g., API keys, default models).

3. First Use Case: Basic Data Masking

   use Czogori\Dami\Facades\Dami;
   
   // Mask a sensitive field (e.g., email)
   $maskedEmail = Dami::mask('user@example.com', 'email');
   // Output: `*****@example.com`
   
   // Mask a phone number
   $maskedPhone = Dami::mask('+1234567890', 'phone');
   // Output: `+1*****890`
   

4. Key Facade Methods

   • Dami::mask($value, $type): Mask data by type (e.g., email, phone, credit_card).
   • Dami::config(): Access or modify runtime config.
   • Dami::extend(): Add custom masking rules (see Implementation Patterns).

Implementation Patterns

Core Workflows

1. Model Integration (Eager Loading) Use the HasMaskable trait to auto-mask attributes when retrieved:

   use Czogori\Dami\Traits\HasMaskable;
   
   class User extends Model
   {
       use HasMaskable;
   
       protected $maskable = ['email', 'phone']; // Fields to mask by default
   }
   
   // Usage:
   $user = User::find(1);
   // $user->email is automatically masked in responses (e.g., API, Blade).
   

2. API Response Filtering Override AppServiceProvider to mask responses globally:

   public function boot()
   {
       Dami::extend('api', function ($value, $type) {
           return Dami::mask($value, $type);
       });
   
       Response::macro('masked', function () {
           return $this->setContent(Dami::mask($this->content, 'api'));
       });
   }
   

3. Dynamic Masking in Controllers

   public function show(User $user)
   {
       return response()->json([
           'email' => Dami::mask($user->email, 'email'),
           'phone' => Dami::mask($user->phone, 'phone'),
       ]);
   }
   

4. Blade Directives Add a Blade directive for templates:

   // In AppServiceProvider@boot()
   Blade::directive('mask', function ($expression) {
       return "<?php echo Czogori\Dami\Facades\Dami::mask({$expression}, '{$expression}'); ?>";
   });
   
   // Usage in Blade:
   @mask($user->email)
   

Integration Tips

• Laravel Scout: Mask sensitive search results by extending the toSearchableArray() method:

  public function toSearchableArray()
  {
      return array_map(function ($value, $key) {
          return in_array($key, $this->maskable) ? Dami::mask($value, $key) : $value;
      }, $this->attributes, array_keys($this->attributes));
  }
  

• Laravel Nova: Use the maskable trait in Nova resources to hide sensitive fields in the UI:

  public static $maskable = ['ssn', 'credit_card'];
  
  public function fields(Request $request)
  {
      $fields = parent::fields($request);
      foreach ($this->$maskable as $field) {
          $fields->push( new Text($field, function () {
              return Dami::mask($this->{$field}, $field);
          }));
      }
      return $fields;
  }
  

• Logging: Mask sensitive data in logs:

  use Czogori\Dami\Facades\Dami;
  
  Log::info('User action', [
      'user_email' => Dami::mask(auth()->user()->email, 'email'),
      'ip' => request()->ip(),
  ]);
  

Gotchas and Tips

Pitfalls

1. Performance Overhead

   • Masking on every request (e.g., in AppServiceProvider) can slow down responses.
   • Fix: Use lazy masking (e.g., only in API responses or Blade templates).

2. Config Overrides

   • Default masking rules are set in config/dami.php. Overriding them globally may affect unexpected areas.
   • Fix: Use Dami::config(['type' => 'custom_rule']) sparingly or per-request.

3. Custom Types Not Triggering

   • If you define a new type (e.g., license_plate) but it doesn’t work, ensure:
     • The type is registered in config/dami.php under types.
     • You’re using the correct case (e.g., Dami::mask($value, 'license_plate')).

4. Database Storage

   • Warning: Masking is for display only. Sensitive data remains unmasked in the database.
   • Tip: Use Laravel’s Encryption for storage.

5. Blade Caching

   • If using @mask directives, clear Blade cache after adding new directives:

     php artisan view:clear
     

Debugging

1. Check Masked Output Dump the masked value to verify:

   dd(Dami::mask('test@email.com', 'email')); // Should show `*****@email.com`
   

2. Inspect Config

   dd(Dami::config());
   

3. Enable Debug Mode Set debug to true in config/dami.php to log masking operations:

   'debug' => env('DAMI_DEBUG', false),
   

Extension Points

1. Custom Masking Rules Extend the package by adding new types:

   Dami::extend('license_plate', function ($value) {
       return '****' . substr($value, -3);
   });
   

2. Conditional Masking Use closures for dynamic rules:

   Dami::extend('dynamic', function ($value, $type) {
       return auth()->check() ? $value : Dami::mask($value, $type);
   });
   

3. Override Default Rules Replace existing types (e.g., for stricter email masking):

   Dami::extend('email', function ($value) {
       return '*****' . substr($value, strpos($value, '@'));
   });
   

4. Event-Based Masking Listen for dami.masking events to log or modify masking:

   event(new Czogori\Dami\Events\MaskingEvent($value, $type, $maskedValue));
   

Pro Tips

• Environment-Specific Rules Use config/dami.php to define different rules per environment:

  'types' => [
      'email' => [
          'dev' => '*****@{domain}',
          'production' => '****@{domain}',
      ],
  ],
  

• Partial Masking For partial masking (e.g., show first 3 digits of a phone):

  Dami::extend('phone_partial', function ($value) {
      return '+' . substr($value, 0, 3) . '****' . substr($value, -2);
  });
  

• Testing Mock the facade in tests:

  $this->mock(Dami::class)->shouldReceive('mask')
      ->with('test@example.com', 'email')
      ->andReturn('*****@example.com');