پرش به مطلب اصلی

Log (لاگ تغییرات)

برای جزئیات استفاده مستقیم از Facade و واکشی برنامه‌نویسی لاگ‌ها، Logging را ببینید.

یک ابزار برای نمایش و فیلتر کردن لاگ‌های تغییرات مدل‌ها در پنل است. با تعریف یک کلاس Log می‌توانید منابع (مدل‌ها) موردنظر، فیلدهای قابل‌نمایش، فیلترها و ظاهر صفحه لاگ را سفارشی کنید.

ایجاد کلاس Log​

php artisan dornica:make-log UserLog

برای ماژول:

php artisan dornica:make-log UserLog --module=MODULE_NAME

ساختار پایه کلاس Log​

<?php

namespace App\Generators\Logs;

use App\Models\User;
use App\Models\Role;
use Dornica\Foundation\Doravel\Facade\Doravel;
use Dornica\Foundation\Logging\BaseLog;
use Dornica\Foundation\Logging\Builders\LogField;

class UserLog extends BaseLog
{
    public function __construct()
    {
        $this
            ->setTitle('لاگ کاربران و نقش‌ها')
            ->setResource([
                User::class => 'کاربران',
                Role::class => 'نقش‌ها',
            ])
            ->setPerPage(20)
            ->setUserIdentifierField('username', 'نام کاربری')
            ->setUserRoute(fn ($user) => route(
                generateUserManagementRouteName('management.show'),
                ['user' => encryptValue($user->id)]
            ));
    }

    public function fields(): array
    {
        return [
            LogField::make('first_name')->label('نام'),
            LogField::make('last_name')->label('نام خانوادگی'),
            LogField::make('email')->label('ایمیل'),
        ];
    }
}

تنظیم منابع (Resource)​

با متد setResource() مشخص می‌کنید لاگ‌های کدام مدل‌ها در این صفحه نمایش داده شوند.

use App\Models\User;
use App\Models\Role;

// آرایه ساده — برچسب از نام کلاس گرفته می‌شود
$this->setResource([User::class, Role::class]);

// آرایه انجمنی — برچسب سفارشی برای هر مدل
$this->setResource([
    User::class => 'کاربران',
    Role::class => 'نقش‌ها',
]);

رفتار پیش‌فرض در کوئری​

  • اگر setResource() تنظیم شده باشد، فقط لاگ‌های مربوط به همان مدل‌ها (entity_type) واکشی می‌شوند.
  • اگر چند مدل تعریف کرده باشید، به‌صورت پیش‌فرض لاگ همه آن مدل‌ها در نتیجه نمایش داده می‌شود (whereIn).

فیلتر «بخش مربوطه»​

وقتی بیش از یک مدل در setResource() تعریف شود، فیلتر «بخش مربوطه» در فرم بالای صفحه نمایش داده می‌شود. آیتم‌های این select از همان منابع ساخته می‌شوند.

  • اگر کاربر مقداری انتخاب نکند: لاگ همه منابع نمایش داده می‌شود.
  • اگر یک بخش انتخاب شود: فقط لاگ همان مدل فیلتر می‌شود (پارامتر section).

تعریف فیلدها​

در متد fields() با LogField مشخص می‌کنید کدام ستون‌های old_values / new_values در UI نمایش داده شوند.

use Dornica\Foundation\Logging\Builders\LogField;

public function fields(): array
{
    return [
        LogField::make('status')->label('وضعیت')
    ];
}

تنظیمات دیگر​

$this
    ->setTitle('لاگ تغییرات')           // عنوان کارت
    ->setPerPage(15)                    // تعداد در هر صفحه
    ->setUserIdentifierField('code', 'کد ملی');    // فیلد شناسه کاربر در فیلتر (اختیاری)

لینک به کاربر (created_by)​

با setUserRoute() می‌توانید برای نام کاربر ثبت‌کننده لاگ یک URL تعریف کنید. وقتی callback مقدار غیرخالی برگرداند، نام کاربر در UI قابل کلیک می‌شود.

$this->setUserRoute(fn ($user) => route(
    generateUserManagementRouteName('management.show'),
    ['user' => encryptValue($user->id)]
));
  • آرگومان اول callback همان مدل userable لاگ است.
  • آرگومان دوم (اختیاری) خود رکورد لاگ است: fn ($user, $log) => ...
  • اگر route تنظیم نشود یا callback مقدار خالی/null برگرداند، نام کاربر به‌صورت متن معمولی نمایش داده می‌شود.

استفاده از Blade Layout Log​

در صورتی که از Blade Layout استفاده می‌کنید، می‌توانید صفحه لاگ را در یک نما رندر کنید.

ثبت Log در کنترلر
use Dornica\PanelKit\BladeLayout\Facade\BladeLayout;
use App\Logs\UserLog;

public function index()
{
    BladeLayout::log(UserLog::class);

    return view('users.log');
}
رندر Log در فایل Blade
<x-default-layout>

    {!! bladeLayout()->log()->render() !!}

</x-default-layout>

فیلترهای موجود در UI​

فرم فیلتر صفحه لاگ شامل موارد زیر است:

فیلترپارامترتوضیح
شناسه کاربرمقدار setUserIdentifierField() ( که به طور پیش فرض کدملی میباشد.)جستجو در userable
نوع عملیاتtypeایجاد، ویرایش، حذف
بخش مربوطهsectionفقط وقتی بیش از یک Resource تعریف شده باشد
آی‌پیipجستجوی جزئی
بازه تاریخcreated_from / created_toتاریخ شمسی

نکات مهم​

  • برای ثبت خودکار لاگ تغییرات مدل‌ها، از مکانیزم Logger دُراول (رویداد ModelChanged) استفاده می‌شود.
  • برای یک منبع تکی، فیلتر «بخش مربوطه» نمایش داده نمی‌شود؛ فقط محدودیت همان مدل در کوئری اعمال می‌شود.
  • برای واکشی برنامه‌ای لاگ‌ها، ثبت دستی، و استفاده از Facade Logger به‌همراه BaseLog، مستند Logging (پیشرفته) را ببینید.