behzad/file-logger

A lightweight Laravel package for logging model changes in files with restore capabilities.

v1.0.6 2025-10-18 11:29 UTC

Requires

• php: ^8.2|^8.3|^8.4
• illuminate/database: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0|^10.0
• phpunit/phpunit: ^10.0|^11.0

MIT

• Behzad

• logging
• Audit
• laravel
• eloquent
• file-logger
• model-changes

README

یک پکیج سبک و کاربردی برای لاگ کردن تغییرات مدل‌ها در فایل‌های JSON

نصب

✨ ویژگی‌ها

• 🔍 لاگ خودکار تغییرات - تمام عملیات Create, Update, Delete
• 💾 ذخیره در فایل JSON - بدون نیاز به دیتابیس اضافی
• 🔄 بازیابی رکوردهای حذف شده - Restore از روی لاگ‌ها
• 👤 ثبت اطلاعات کاربر - User ID, IP, User Agent
• ⚙️ کانفیگ انعطاف‌پذیر - تنظیمات کامل و قابل شخصی‌سازی
• 🎯 Exclude فیلدها - عدم لاگ فیلدهای حساس مثل password
• 📊 File Rotation - مدیریت خودکار سایز فایل‌ها
• 🚀 Performance بالا - بدون تاثیر منفی روی عملکرد
• 🛠️ Artisan Commands - دستورات مفید برای مدیریت لاگ‌ها
• 🎨 Facade Support - استفاده آسان با Facade

📦 نصب

نصب از طریق Composer

composer require behzad/file-logger

انتشار فایل کانفیگ

php artisan vendor:publish --tag=file-logger-config

🚀 راه‌اندازی سریع

گام 1: اضافه کردن Trait به مدل

<?php

<<<<<<< Updated upstream
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
=======
php artisan vendor:publish --tag=file-logger-config

>>>>>>> Stashed changes
use Behzad\FileLogger\Traits\FileLoggerTrait;

class Post extends Model
{
    use FileLoggerTrait;

    protected $fillable = ['title', 'content', 'status'];
}
<<<<<<< Updated upstream

گام 2: استفاده خودکار

// Create - لاگ می‌شود
$post = Post::create([
    'title' => 'عنوان پست',
    'content' => 'محتوای پست',
    'status' => 'published'
]);

// Update - لاگ می‌شود
$post->update(['title' => 'عنوان جدید']);

// Delete - لاگ می‌شود
$post->delete();

📖 مستندات کامل

🔧 تنظیمات (Configuration)

فایل config/file-logger.php:

<?php

return [
    // مسیر ذخیره لاگ‌ها
    'storage_path' => storage_path('logs/file_logger'),

    // فرمت ذخیره (json یا line)
    'format' => 'json',

    // لاگ کردن IP کاربر
    'log_ip' => true,

    // لاگ کردن User Agent
    'log_user_agent' => true,

    // فیلدهایی که نباید لاگ شوند
    'excluded_fields' => [
        'password',
        'remember_token',
        'api_token',
    ],

    // حداکثر سایز فایل لاگ (MB)
    'max_file_size' => 10,

    // فرمت تاریخ
    'date_format' => 'Y-m-d H:i:s',
];

📝 ساختار لاگ

{
    "event_type": "updated",
    "model": "App\\Models\\Post",
    "model_id": 123,
    "old_values": {
        "title": "عنوان قدیمی",
        "status": "draft"
    },
    "new_values": {
        "title": "عنوان جدید",
        "status": "published"
    },
    "user_id": 1,
    "ip": "192.168.1.1",
    "user_agent": "Mozilla/5.0...",
    "timestamp": "2025-10-18 14:30:45"
}

🎯 استفاده پیشرفته

1️⃣ بازیابی رکوردهای حذف شده

روش اول: استفاده از مدل

// بازیابی تمام رکوردهای حذف شده
$result = Post::restoreFromFile();

// نتیجه:
// [
//     'success' => true,
//     'restored_count' => 5,
//     'records' => [...]
// ]

روش دوم: استفاده از Facade

use Behzad\FileLogger\Facades\FileLogger;

$result = FileLogger::restoreFromFile(Post::class);

روش سوم: دستور Artisan

php artisan file-logger:restore "App\Models\Post"

2️⃣ مشاهده لاگ‌ها

$logs = Post::getLogs();

3️⃣ پاک کردن لاگ‌ها

Post::clearLogs();

🛠️ دستورات Artisan

# پاک کردن تمام لاگ‌ها (با تایید)
php artisan file-logger:clear

# پاک کردن لاگ یک مدل خاص
php artisan file-logger:clear Post

# پاک کردن لاگ با نام کامل کلاس
php artisan file-logger:clear "App\Models\User"

بازیابی از لاگ

# بازیابی رکوردهای حذف شده
php artisan file-logger:restore "App\Models\Post"

🤝 مشارکت

مشارکت‌ها همیشه خوش‌آمد هستند! لطفاً: Repository را Fork کنید یک Branch جدید بسازید (git checkout -b feature/amazing-feature) تغییرات را Commit کنید (git commit -m 'Add amazing feature') به Branch خود Push کنید (git push origin feature/amazing-feature) یک Pull Request باز کنید

📄 لایسنس

این پکیج تحت لایسنس MIT منتشر شده است.

👨‍💻 توسعه‌دهنده

📧 Email: [e-mail] 🐙 GitHub: @Amirbehzad11

=======

2.بازیابی رکورد های حذف شده

Stashed changes