متن نوشته

• معرفی
  • چگونه کار می کند
• گرفتن متن
  • پشته ها
• بازیابی متن
  • تعیین وجود آیتم
• حذف متن
• زمینه پنهان
• مناسبت ها
  • کم آبی
  • آبرسان

معرفی

قابلیت های "متن" لاراول شما را قادر می سازد تا اطلاعات را در طول درخواست ها، کارها و دستورات اجرا شده در برنامه خود ضبط، بازیابی و به اشتراک بگذارید. این اطلاعات جمع‌آوری‌شده همچنین در گزارش‌های نوشته‌شده توسط برنامه شما گنجانده می‌شود، و به شما بینش عمیق‌تری از تاریخچه اجرای کد اطراف را می‌دهد که قبل از نوشتن یک ورودی گزارش رخ داده است و به شما امکان می‌دهد جریان‌های اجرا را در یک سیستم توزیع‌شده ردیابی کنید.

چگونه کار می کند

بهترین راه برای درک قابلیت‌های زمینه لاراول این است که آن را در عمل با استفاده از ویژگی‌های ورود به سیستم مشاهده کنید. برای شروع، می توانید با استفاده از نما اطلاعاتی را به بافت اضافه کنید Context . در این مثال، ما از یک میان افزار برای اضافه کردن URL درخواست و یک شناسه ردیابی منحصر به فرد به متن در هر درخواست ورودی استفاده خواهیم کرد:

<?php
 
namespace App\Http\Middleware;
 
use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Context;
use Illuminate\Support\Str;
use Symfony\Component\HttpFoundation\Response;
 
class AddContext
{
    /**
     * Handle an incoming request.
     */
    public function handle(Request $request, Closure $next): Response
    {
        Context::add('url', $request->url());
        Context::add('trace_id', Str::uuid()->toString());
 
        return $next($request);
    }
}

اطلاعات اضافه شده به متن به طور خودکار به عنوان ابرداده به هر ورودی گزارشی که در سراسر درخواست نوشته شده است اضافه می شود. افزودن زمینه به عنوان ابرداده اجازه می دهد تا اطلاعات ارسال شده به ورودی های گزارش فردی از اطلاعات به اشتراک گذاشته شده از طریق متمایز شود Context . به عنوان مثال، تصور کنید که ورودی log زیر را بنویسیم:

Log::info('User authenticated.', ['auth_id' => Auth::id()]);

گزارش نوشته شده حاوی اطلاعات auth_id ارسال شده به ورودی گزارش است، اما همچنین حاوی متن url و trace_id به عنوان ابرداده است:

User authenticated. {"auth_id":27} {"url":"https://example.com/login","trace_id":"e04e1a11-e75c-4db3-b5b5-cfef4ef56697"}

اطلاعات اضافه شده به زمینه نیز برای مشاغل ارسال شده به صف در دسترس قرار می گیرد. به عنوان مثال، تصور کنید ما یک ProcessPodcast کار را پس از افزودن برخی اطلاعات به متن، به صف ارسال می کنیم:

// In our middleware...
Context::add('url', $request->url());
Context::add('trace_id', Str::uuid()->toString());
 
// In our controller...
ProcessPodcast::dispatch($podcast);

هنگامی که کار ارسال می شود، هر اطلاعاتی که در حال حاضر در زمینه ذخیره شده است، گرفته شده و با آن کار به اشتراک گذاشته می شود. سپس اطلاعات گرفته شده در حالی که کار در حال اجرا است به شرایط فعلی بازگردانده می شود. بنابراین، اگر روش دسته کار ما نوشتن در گزارش بود:

class ProcessPodcast implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
 
    // ...
 
    /**
     * Execute the job.
     */
    public function handle(): void
    {
        Log::info('Processing podcast.', [
            'podcast_id' => $this->podcast->id,
        ]);
 
        // ...
    }
}

ورودی گزارش به دست آمده حاوی اطلاعاتی است که در طول درخواستی که در ابتدا کار را ارسال کرده است به متن اضافه شده است:

Processing podcast. {"podcast_id":95} {"url":"https://example.com/login","trace_id":"e04e1a11-e75c-4db3-b5b5-cfef4ef56697"}

اگرچه ما بر روی ویژگی‌های مربوط به ورود به سیستم داخلی در زمینه لاراول تمرکز کرده‌ایم، مستندات زیر نشان می‌دهد که چگونه زمینه به شما اجازه می‌دهد اطلاعات را در سراسر درخواست HTTP / مرز کار در صف به اشتراک بگذارید و حتی چگونه داده‌های زمینه پنهان را که با گزارش نوشته نشده‌اند اضافه کنید. ورودی های.

گرفتن متن

شما می توانید اطلاعات را در زمینه فعلی با استفاده از روش Context نما ذخیره کنید add :

use Illuminate\Support\Facades\Context;
 
Context::add('key', 'value');

برای افزودن چندین آیتم به طور همزمان، می توانید یک آرایه انجمنی را به add متد ارسال کنید:

Context::add([
    'first_key' => 'value',
    'second_key' => 'value',
]);

این add روش هر مقدار موجودی که کلید یکسانی دارد را لغو می کند. اگر فقط می خواهید اطلاعاتی را به زمینه اضافه کنید در صورتی که کلید از قبل وجود نداشته باشد، می توانید از addIf روش زیر استفاده کنید:

Context::add('key', 'first');
 
Context::get('key');
// "first"
 
Context::addIf('key', 'second');
 
Context::get('key');
// "first"

پشته ها

Context توانایی ایجاد "پشته" را ارائه می دهد، که لیستی از داده های ذخیره شده به ترتیبی است که آنها اضافه می شوند. با فراخوانی روش می توانید اطلاعات را به پشته اضافه کنید push :

use Illuminate\Support\Facades\Context;
 
Context::push('breadcrumbs', 'first_value');
 
Context::push('breadcrumbs', 'second_value', 'third_value');
 
Context::get('breadcrumbs');
// [
//     'first_value',
//     'second_value',
//     'third_value',
// ]

پشته ها می توانند برای گرفتن اطلاعات تاریخی در مورد یک درخواست مفید باشند، مانند رویدادهایی که در سراسر برنامه شما اتفاق می افتد. به عنوان مثال، می‌توانید یک شنونده رویداد ایجاد کنید تا هر بار که یک پرس و جو اجرا می‌شود، به پشته فشار داده شود و پرس و جوی SQL و مدت زمان را به صورت چند تایی ثبت کند:

use Illuminate\Support\Facades\Context;
use Illuminate\Support\Facades\DB;
 
DB::listen(function ($event) {
    Context::push('queries', [$event->time, $event->sql]);
});

بازیابی متن

Context می توانید با استفاده از روش نما اطلاعات را از زمینه بازیابی کنید get :

use Illuminate\Support\Facades\Context;
 
$value = Context::get('key');

این only روش ممکن است برای بازیابی زیرمجموعه ای از اطلاعات در زمینه استفاده شود:

$data = Context::only(['first_key', 'second_key']);

اگر می خواهید تمام اطلاعات ذخیره شده در زمینه را بازیابی کنید، می توانید all روش زیر را فراخوانی کنید:

$data = Context::all();

تعیین وجود آیتم

شما می توانید از این has روش برای تعیین اینکه آیا متن مقداری برای کلید داده شده ذخیره شده است یا خیر استفاده کنید:

use Illuminate\Support\Facades\Context;
 
if (Context::has('key')) {
    // ...
}

این has روش true بدون توجه به مقدار ذخیره شده باز خواهد گشت. بنابراین، برای مثال، یک کلید با یک null مقدار موجود در نظر گرفته می شود:

Context::add('key', null);
 
Context::has('key');
// true

حذف متن

این forget روش ممکن است برای حذف یک کلید و مقدار آن از زمینه فعلی استفاده شود:

use Illuminate\Support\Facades\Context;
 
Context::add(['first_key' => 1, 'second_key' => 2]);
 
Context::forget('first_key');
 
Context::all();
 
// ['second_key' => 2]

با ارائه یک آرایه به روش ممکن است چندین کلید را همزمان فراموش کنید forget :

Context::forget(['first_key', 'second_key']);

زمینه پنهان

Context توانایی ذخیره داده های "پنهان" را ارائه می دهد. این اطلاعات پنهان به گزارش‌ها اضافه نمی‌شود و از طریق روش‌های بازیابی داده‌های مستند شده در بالا قابل دسترسی نیست. Context مجموعه متفاوتی از روش ها را برای تعامل با اطلاعات زمینه پنهان ارائه می دهد:

use Illuminate\Support\Facades\Context;
 
Context::addHidden('key', 'value');
 
Context::getHidden('key');
// 'value'
 
Context::get('key');
// null

روش‌های "پنهان" عملکرد روش‌های غیر پنهان مستند شده در بالا را منعکس می‌کنند:

Context::addHidden(/* ... */);
Context::addHiddenIf(/* ... */);
Context::pushHidden(/* ... */);
Context::getHidden(/* ... */);
Context::onlyHidden(/* ... */);
Context::allHidden(/* ... */);
Context::hasHidden(/* ... */);
Context::forgetHidden(/* ... */);

مناسبت ها

Context دو رویداد را ارسال می‌کند که به شما امکان می‌دهد به فرآیند آب‌گیری و آب‌رسانی بافت بچسبید.

برای نشان دادن نحوه استفاده از این رویدادها، تصور کنید که در میان افزار برنامه خود، app.locale مقدار پیکربندی را بر اساس هدر درخواست HTTP دریافتی تنظیم کنید Accept-Language . رویدادهای Context به شما این امکان را می‌دهند که این مقدار را در طول درخواست دریافت کنید و آن را در صف بازیابی کنید و اطمینان حاصل کنید که اعلان‌های ارسال شده در صف دارای app.locale ارزش صحیح هستند. ما می‌توانیم از رویدادهای زمینه و داده‌های پنهان برای رسیدن به این هدف استفاده کنیم، که مستندات زیر نشان می‌دهند.

کم آبی

هر زمان که یک کار به صف فرستاده می شود، داده های موجود در زمینه "کم آب" می شوند و در کنار بار کار ثبت می شوند. این Context::dehydrating روش به شما امکان می دهد یک بسته را ثبت کنید که در طول فرآیند کم آبی فراخوانی می شود. در این بسته شدن، می‌توانید تغییراتی در داده‌هایی ایجاد کنید که با کار در صف به اشتراک گذاشته می‌شوند.

به طور معمول، شما باید dehydrating تماس های برگشتی را در boot متد کلاس برنامه خود ثبت کنید AppServiceProvider :

use Illuminate\Log\Context\Repository;
use Illuminate\Support\Facades\Config;
use Illuminate\Support\Facades\Context;
 
/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Context::dehydrating(function (Repository $context) {
        $context->addHidden('locale', Config::get('app.locale'));
    });
}

شما نباید از Context نما در dehydrating کال بک استفاده کنید، زیرا این باعث تغییر زمینه فرآیند فعلی می شود. مطمئن شوید که فقط در مخزن ارسال شده به callback تغییرات ایجاد می کنید.

آبرسان

هر زمان که یک کار در صف شروع به اجرا در صف می کند، هر زمینه ای که با آن کار به اشتراک گذاشته شده است به شرایط فعلی "هیدراته" می شود. این Context::hydrating روش به شما امکان می دهد یک بسته را ثبت کنید که در طول فرآیند هیدراتاسیون فراخوانی می شود.

به طور معمول، شما باید hydrating تماس های برگشتی را در boot متد کلاس برنامه خود ثبت کنید AppServiceProvider :

use Illuminate\Log\Context\Repository;
use Illuminate\Support\Facades\Config;
use Illuminate\Support\Facades\Context;
 
/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Context::hydrating(function (Repository $context) {
        if ($context->hasHidden('locale')) {
            Config::set('app.locale', $context->getHidden('locale'));
        }
    });
}

شما نباید از Context نما در hydrating کال بک استفاده کنید و در عوض مطمئن شوید که فقط در مخزن ارسال شده به callback تغییراتی ایجاد می کنید.