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

Logging

استفاده از Facade Logging​

Logging مسئول ثبت و واکشی لاگ تغییرات مدل‌ها در دُراول است. برای نمایش UI از Log Generator و کلاس‌های BaseLog استفاده می‌شود؛ این سند نحوه کار مستقیم با Facade را توضیح می‌دهد.

اطلاع

پیکربندی UI و فیلدهای قابل‌نمایش در Log Generator آمده است. این صفحه برای استفاده برنامه‌نویسی از Facade و ترکیب آن با BaseLog است.

امکانات​

متدشرح
storeذخیره یک رکورد لاگ با LogPayload. معمولاً از طریق رویداد ModelChanged فراخوانی می‌شود.
configانتخاب کلاس BaseLog (یا نمونه آن) و شروع زنجیره واکشی.
filterاعمال یک فیلتر تکی روی نتیجه (مثلاً type، ip، فیلد شناسه کاربر).
filtersاعمال چند فیلتر به‌صورت آرایه.
fromRequestخواندن فیلترها از query string درخواست HTTP (اختیاری؛ در صورت عدم ارسال، از request() فعلی استفاده می‌شود).
pageتعیین شماره صفحه برای pagination.
getدریافت نتیجه نهایی (paginator یا آرایه بسته به driver).

ثبت لاگ (store)​

ثبت خودکار با فعال بودن dornica-app.logging.enable و رویداد ModelChanged انجام می‌شود. برای ثبت دستی:

use Dornica\Foundation\Logging\Facade\Logging;
use Dornica\Foundation\Logging\LogType;
use Dornica\Foundation\Logging\Support\LogPayload;

Logging::store(new LogPayload(
    entity: $user,
    action: LogType::UPDATE,
    oldValues: ['email' => 'old@example.com'],
    newValues: ['email' => 'new@example.com'],
    context: [
        'user' => auth()->user(),
        'ip' => request()->ip(),
        'page_route' => request()->route()?->getName(),
    ],
    batchId: app(\Dornica\Foundation\Logging\LogBatchManager::class)->current(),
));

واکشی لاگ بدون Request​

برای API، Job، Command یا هر جایی که Request HTTP در دسترس نیست، فیلترها را مستقیم پاس دهید:

use Dornica\Foundation\Logging\Facade\Logging;
use App\Generators\Logs\UserLog;

$logs = Logging::config(UserLog::class)
    ->filter('ip', '192.168')
    ->filter('type', [1, 2])
    ->page(1)
    ->get();

یا به‌صورت دسته‌ای:

$logs = Logging::config(UserLog::class)
    ->filters([
        'code' => '0012345678',
        'created_from' => '1403/01/01 00:00',
        'created_to' => '1403/01/31 23:59',
    ])
    ->get();

بدون هیچ فیلتری (فقط محدودیت‌های setResource() در کلاس Log):

$logs = Logging::config(UserLog::class)->get();

واکشی لاگ از Request​

در کنترلر یا جایی که query string فیلتر UI را دارد:

use Dornica\Foundation\Logging\Facade\Logging;
use App\Generators\Logs\UserLog;

$logs = Logging::config(UserLog::class)
    ->fromRequest($request)
    ->get();

// یا با request فعلی:
$logs = Logging::config(UserLog::class)->fromRequest()->get();

کار همزمان با BaseLog و Facade Logging​

BaseLog برای پیکربندی (منابع، فیلدها، برچسب‌ها، pagination UI) است. Facade Logging برای اجرای کوئری روی driver (database / elastic).

از طریق BaseLog​

متد getLogs() در BaseLog در واقع همان Facade را صدا می‌زند؛ پارامتر اختیاری است:

$log = new UserLog();

// بدون فیلتر
$logs = $log->getLogs();

// از Request
$logs = $log->getLogs($request);

// از آرایه فیلتر
$logs = $log->getLogs(['ip' => '127.0.0.1']);

از طریق Facade (پیشنهادی برای منطق سفارشی)​

$query = Logging::config(UserLog::class);

if ($request->filled('ip')) {
    $query->filter('ip', $request->input('ip'));
}

$logs = $query->get();

نمایش UI (Log Generator)​

در Blade Layout، BaseLog برای رندر فرم فیلتر و فرمت خروجی استفاده می‌شود؛ Livewire component داخلی از Logging::config() برای واکشی استفاده می‌کند:

use Dornica\PanelKit\BladeLayout\Facade\BladeLayout;
use App\Generators\Logs\UserLog;

BladeLayout::log(UserLog::class);

return view('users.log');
{!! bladeLayout()->log()->render() !!}
نکته

برای صفحه پنل از BaseLog + Blade Layout کافی است. برای API، export، یا گزارش‌گیری برنامه‌ای از Logging::config() استفاده کنید.

پارامترهای فیلتر​

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

Driver​

Driver از config('dornica-app.logging.driver') خوانده می‌شود. مقدار پیش‌فرض database است.

  • database: خروجی LengthAwarePaginator با Eloquent
  • elastic: خروجی آرایه‌ای با کلیدهای data و pagination (در حال حاضر غیرفعال در تنظیمات پیش‌فرض)

توضیحات تکمیلی​

  • config: کلاس BaseLog پروژه (مثلاً UserLog::class) را مشخص می‌کند؛ محدودیت resource و perPage از همان کلاس اعمال می‌شود.
  • filter / filters: فیلترها جدا از get اعمال می‌شوند تا وابستگی به Request اجباری نباشد.
  • fromRequest: فقط query string را به فیلترها map می‌کند؛ برای سناریوهای HTTP مناسب است.
  • ثبت خودکار: با ModelChanged و listener StoreModelChangeLog؛ مدل‌های ignore شده در dornica-app.logging.ignore_models ثبت نمی‌شوند.
Logging::config($log)->fromRequest($request)->get();