Laravel Eloquent Attribute Maskeleme: Hassas Verileri Otomatik Gizleme

Kullanıcı listesi sayfasında e-posta adresleri açık açık görünüyor: [email protected]. Admin panelde sorun yok ama ya bu veri API'den dışarı çıkıyorsa? Ya da destek ekibi gerçek e-postaları görmemeli ama kayıtları inceleyebilmeliyse?

laravel-attribute-mask paketi tam bunu yapıyor: Eloquent model'den veri çekildiği anda hassas alanları otomatik maskeliyor. [email protected] → p***[email protected]. Veritabanındaki veri değişmiyor, sadece okunurken maskeleniyor.

Kurulum

composer require irabbi360/laravel-attribute-mask
php artisan vendor:publish --tag="attribute-mask-config"

Kullanım

Model'inize HasMaskedAttributes trait'ini ekleyin ve maskelenecek alanları tanımlayın:

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Irabbi360\LaravelAttributeMask\Traits\HasMaskedAttributes;

class User extends Model
{
    use HasMaskedAttributes;

    protected function maskables(): array
    {
        return [
            'email' => 'email',
            'phone' => 'phone',
            'name' => 'text',
        ];
    }
}

Veya property olarak:

protected array $maskable = ['email', 'phone', 'name'];

Artık model'i çektiğinizde:

$user = User::find(1);

$user->email;  // p***[email protected]
$user->phone;  // 053****4567
$user->name;   // Pr***an

Veritabanında veri aynen duruyor. Sadece $user->email dediğinizde maskelenmiş hali geliyor. API response'larında, Blade view'larda, JSON export'larda — her yerde maskelenmiş.

Config Ayarları

config/attribute-mask.php dosyasında detaylı kontrol var:

return [
    'enabled' => true,       // Global aç/kapa
    'mask_char' => '*',      // Maskeleme karakteri

    'email' => [
        'show_domain' => true,     // @example.com görünsün mü?
        'start_visible' => 1,      // Baştan kaç karakter görünsün
        'end_visible' => 1,        // Sondan kaç karakter görünsün
    ],

    'phone' => [
        'start_visible' => 3,      // Baştan 3 rakam: 053
        'end_visible' => 4,        // Sondan 4 rakam: 4567
    ],

    'text' => [
        'start_visible' => 2,
        'end_visible' => 2,
    ],
];

Bu ayarlarla:

• [email protected] → t**[email protected] (domain görünüyor)
• 05341234567 → 053****4567
• Ahmet Yılmaz → Ah*********az

Gerçek Veriyi Almak

Bazen maskelenmemiş veriyi almanız gerekir (admin panelde, export'ta vs.):

// getOriginal ile
$user->getOriginal('email');  // [email protected]

// Veya geçici olarak maskelemeyi kapat
config(['attribute-mask.enabled' => false]);
$user->email;  // [email protected]
config(['attribute-mask.enabled' => true]);

Nerelerde Kullanılır?

KVKK / GDPR uyumluluğu: Kişisel verilerin gereksiz yere gösterilmemesi yasal zorunluluk. Destek ekibine, moderatörlere veya düşük yetkili kullanıcılara maskelenmiş veri gösterin.

API güvenliği: Dış dünyaya açık API endpoint'lerinde hassas alanları maskeleyerek veri sızıntısı riskini azaltın.

Log ve debug: Loglara yazılan kullanıcı verileri maskelenmiş olsun. Log::info($user->toArray()) dediğinizde gerçek e-posta loglara düşmesin.

Çoklu rol sistemi: Admin gerçek veriyi görsün, editör maskelenmiş görsün. Middleware veya policy ile enabled config'ini role göre değiştirin:

// Middleware'de
if (! auth()->user()->isAdmin()) {
    config(['attribute-mask.enabled' => true]);
}

Dikkat Edilmesi Gerekenler

• Maskeleme sadece okuma tarafında çalışır. $user->email = '[email protected]' dediğinizde gerçek değer yazılır.
• where sorguları maskelenmemiş veriyle çalışır: User::where('email', '[email protected]') doğru sonuç döner.
• JSON serialization'da (toArray, toJson) maskelenmiş değerler gelir. API response'larınız otomatik güvenli.
• getOriginal() her zaman gerçek değeri döner — bu bir kaçış kapısı, dikkatli kullanın.

Sonuç

Küçük bir paket ama büyük etki. Özellikle KVKK kapsamında kişisel verileri korumak zorundaysanız, bu trait'i model'lere eklemek 5 dakikalık bir iş ve ciddi bir güvenlik katmanı sağlıyor. Elle maskeleme fonksiyonları yazmaktan çok daha temiz ve tutarlı bir yaklaşım.