شروع کار با لاراول – پیکربندی

با ادامه ترجمه مستندات فارسی Laravel 10  بخش (شروع کار با لاراول – پیکربندی)، در خدمت شما کاربران گرامی وب‌سایت آموزشی لاراول کارا هستیم. امیدواریم که این مطلب برای شما مفید واقع شده باشد. در صورت داشتن هرگونه سوال یا ابهام، لطفاً در قسمت نظرات با ما در ارتباط باشید.

# معرفی (Introduction)

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

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

بررسی کلی برنامه

بررسی و مشاهده سریع پیکربندی، درایورها و محیط برنامه شما، می‌توانید از دستور artisan about استفاده کنید:

php artisan about

اگر فقط به بخش خاصی از خروجی بررسی کلی برنامه علاقه‌مند هستید، می‌توانید با استفاده از گزینه –only آن بخش را فیلتر کنید:

php artisan about --only=environment

# پیکربندی محیط (Environment Configuration)

استفاده از مقادیر پیکربندی متفاوت بر اساس محیطی که برنامه در آن اجرا می‌شود، کاربردی است. به عنوان مثال، ممکن است بخواهید در سرور تولید از یک درایور نهانگر متفاوت (cache driver) با درایور نهانگری که در کامپیوتر شخصی خودتان استفاده می‌کنید، استفاده کنید.

لاراول برای انجام این کار از کتابخانه DotEnv PHP استفاده می‌کند. در یک نصب جدید لاراول، پوشه اصلی برنامه شما شامل یک فایل .env.example است که شامل تعریف بسیاری از متغیرهای محیطی متداول است. در فرایند نصب لاراول، این فایل به صورت خودکار به فایل .env کپی می‌شود.

فایل .env پیش فرض لاراول شامل برخی از مقادیر پیکربندی متداول است که بسته به اینکه برنامه شما در سرور تولید یا در کامپیوتر شخصی شما اجرا می‌شود، ممکن است متفاوت باشد. سپس این مقادیر از فایل‌های مختلف پیکربندی لاراول در پوشه config با استفاده از تابع env لاراول بازیابی می‌شوند.

اگر با یک تیم توسعه‌دهنده کار می‌کنید، ممکن است بخواهید فایل .env.example را به همراه برنامه‌ی خود ارائه دهید. با قرار دادن مقادیر نمونه در فایل پیکربندی مثال، سایر توسعه دهندگان می‌توانند به وضوح مشاهده کنند کدام متغیرهای محیطی برای اجرای برنامه شما لازم است.

امنیت فایل محیط
فایل .env شما نباید در کنترل منبع (source control) برنامه شما قرار گیرد، زیرا هر توسعه دهنده / سروری که از برنامه شما استفاده می‌کند، به پیکربندی محیط متفاوت نیاز دارد. علاوه بر این، این مسئله در صورت دسترسی ناشناس به مخزن کنترل منبع شما، خطر امنیتی ایجاد می‌کند زیرا هرگونه اعتبار حساسی که در فایل .env وجود دارد، به طور آشکار برای همه قابل مشاهده است.

اما، با استفاده از رمزنگاری محیطی Laravel، می‌توانید فایل .env خود را رمزگذاری کنید. فایل رمزنگاری شده محیطی می‌تواند به صورت ایمن در کنترل منبع قرار داده شود.

فایل‌های محیطی اضافی
قبل از بارگذاری متغیرهای محیطی برنامه شما، لاراول تعیین می‌کند که آیا متغیر محیطی APP_ENV به صورت خارجی تعیین شده است یا آیا آرگومان CLI –env مشخص شده است یا نه. در صورت وجود، لاراول سعی می‌کند فایل .env.[APP_ENV] را بارگذاری کند اگر وجود داشته باشد. اگر وجود نداشته باشد، فایل پیش فرض .env بارگذاری می‌شود.

# انواع متغیرهای محیطی (Environment Variable Types)

تمامی متغیرهای موجود در فایل .env شما به عنوان رشته‌های معمولاً تفسیر می‌شوند. به همین دلیل، برخی متغیرهای رزرو شده ایجاد شده‌اند که به شما اجازه می‌دهند از تعداد گسترده‌ای از انواع متغیرها در تابع env() استفاده کنید.

.env Value	env() Value
true	(bool) true
(true)	(bool) true
false	(bool) false
(false)	(bool) false
empty	(string) ”
(empty)	(string) ”
null	(null) null
(null)	(null) null

اگر نیاز دارید تا یک متغیر محیطی با مقداری شامل فضا تعریف کنید، می‌توانید آن مقدار را در دو نقل قول دوتایی (” “) قرار دهید:

APP_NAME="My Application"

# بازیابی پیکربندی محیط (Retrieving Environment Configuration)

دریافت پیکربندی محیطی
تمامی متغیرهای موجود در فایل .env شما هنگام دریافت یک درخواست، به صورت خودکار در متغیر فراگیر PHP یعنی $_ENV بارگذاری خواهند شد. با این حال، شما می‌توانید از تابع env برای بازیابی مقدار این متغیرها در فایل‌های پیکربندی استفاده کنید. در واقع، اگر فایل‌های پیکربندی Laravel را بررسی کنید، خواهید دید که بسیاری از گزینه‌ها قبلاً از این تابع استفاده شده است:

'debug' => env('APP_DEBUG', false),

مقدار دومی که به تابع env ارسال می‌شود، “مقدار پیش‌فرض” نامیده میشود. این مقدار به‌جای مقدار متغیر محیطی برگردانده می‌شود اگر برای کلید داده شده، هیچ متغیر محیطی وجود نداشته باشد.

# تعیین محیط فعلی (Determining The Current Environment)

محیط اجرایی کنونی برنامه از طریق متغیر APP_ENV در فایل .env شما تعیین می‌شود. شما می‌توانید به این مقدار با استفاده از متد environment روی facade App دسترسی داشته باشید:

use Illuminate\Support\Facades\App;
 
$environment = App::environment();

همچنین می‌توانید پارامترهایی را به متد environment ارسال کنید تا محیط با مقدار داده شده مطابقت داشته باشد. این متد در صورت مطابقت مقدارهای داده شده، true برمی‌گرداند:

if (App::environment('local')) {
    // The environment is local
}
 
if (App::environment(['local', 'staging'])) {
    // The environment is either local OR staging...
}

# رمزگذاری فایل‌های محیطی (Encrypting Environment Files)

فایل‌های محیطی بدون رمزگذاری، هرگز نباید در کنترل منبع قرار گیرند. با این حال، Laravel به شما اجازه می‌دهد تا فایل‌های محیطی خود را رمزگذاری کنید تا بتوانید آن‌ها را به صورت ایمن در کنترل منبع همراه با برنامه‌ی خود قرار دهید.

رمزگذاری
برای رمزگذاری یک فایل محیطی، می‌توانید از دستور env:encrypt استفاده کنید:

php artisan env:encrypt

اجرای دستور env:encrypt، فایل .env شما را رمزگذاری کرده و محتوای رمزنگاری شده را در فایل .env.encrypted قرار می‌دهد. کلید رمزگشایی در خروجی دستور نمایش داده می‌شود و باید در یک مدیریت رمز عبور امن ذخیره شود. اگر می‌خواهید که کلید رمزگشایی خود را ارائه دهید، می‌توانید از گزینه –key هنگام فراخوانی دستور استفاده کنید:

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

به طور پیش فرض، Laravel از رمزگذار AES-256-CBC استفاده می‌کند که نیاز به یک کلید 32 کاراکتر دارد. با استفاده از گزینه –cipher هنگام فراخوانی دستور، می‌توانید از هر رمزگذاری پشتیبانی شده توسط رمزگذار Laravel استفاده کنید.

اگر برنامه شما دارای چندین فایل محیطی مانند .env و .env.staging باشد، با استفاده از گزینه –env، می‌توانید نام فایل محیطی مورد نظر برای رمزگذاری را مشخص کنید:

php artisan env:encrypt --env=staging

استفاده از این گزینه، فایل .env.staging شما را رمزگذاری کرده و محتوای رمزنگاری شده را در فایل .env.staging.encrypted ذخیره می‌کند.

رمزگشایی
برای رمزگشایی یک فایل محیطی، می‌توانید از دستور env:decrypt استفاده کنید. این دستور نیاز به یک کلید رمزگشایی دارد که Laravel آن را از متغیر محیطی LARAVEL_ENV_ENCRYPTION_KEY بازیابی می‌کند:

php artisan env:decrypt

همچنین، می‌توانید کلید را به‌صورت مستقیم به دستور با استفاده از گزینه –key ارائه دهید:

php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

وقتی دستور env:decrypt فراخوانی می‌شود، Laravel محتوای فایل .env.encrypted را رمزگشایی کرده و محتوای رمزگشایی شده را در فایل .env قرار می‌دهد.

گزینه –cipher می‌تواند در دستور env:decrypt برای استفاده از یک رمزگذاری سفارشی مورد استفاده قرار گیرد:

php artisan env:decrypt --key=qUWuNRdfuImXcKxZ --cipher=AES-128-CBC

اگر برنامه شما دارای چندین فایل محیطی مانند .env و .env.staging باشد، می‌توانید نام فایل محیطی مورد نظر برای رمزگشایی را با استفاده از گزینه –env مشخص کنید:

php artisan env:decrypt --env=staging

برای جایگزینی یک فایل محیطی موجود با محتوای رمزگشایی شده، می‌توانید گزینه –force را در دستور env:decrypt ارائه دهید:

php artisan env:decrypt --force

# دسترسی به مقادیر پیکربندی (Accessing Configuration Values)

شما می‌توانید به راحتی از تابع config سراسری در هر جای برنامه‌ی خود استفاده کنید تا به مقادیر پیکربندی خود دسترسی پیدا کنید. مقادیر پیکربندی با استفاده از نحو “dot” در دسترس هستند. این نحو شامل نام فایل و گزینه‌ای است که شما می‌خواهید به آن دسترسی پیدا کنید. در صورتی که گزینه‌ی پیکربندی وجود نداشته باشد، می‌توانید یک مقدار پیش‌فرض را مشخص کنید که در این صورت برگردانده می‌شود.

$value = config('app.timezone');
 
// Retrieve a default value if the configuration value does not exist...
$value = config('app.timezone', 'Asia/Seoul');

برای تنظیم مقادیر پیکربندی در زمان اجرا، یک آرایه را به تابع config منتقل کنید.

config(['app.timezone' => 'America/Chicago']);

# حالت حافظه‌پنهانی پیکربندی (Configuration Caching)

برای افزایش سرعت برنامه‌ی شما، بهتر است تمام فایل‌های پیکربندی را با استفاده از دستور config:cache به یک فایل واحد کش تبدیل کنید. این کار باعث می‌شود تمام گزینه‌های پیکربندی برنامه‌ی‌تان در یک فایل واحد ترکیب شوند و به سرعت توسط چارچوب بارگذاری شوند.

بهتر است دستور php artisan config:cache را به‌عنوان یکی از مراحل اجرایی برای محیط تولید خود اجرا کنید. این دستور در زمان توسعه نباید اجرا شود، زیرا گزینه‌های پیکربندی در طول توسعه ممکن است تغییر کنند.

بعد از اجرای دستور config:cache، فایل .env برنامه‌ی‌تان در درخواست‌ها یا دستورات Artisan توسط چارچوب بارگذاری نخواهد شد. به همین دلیل، تابع env فقط مقادیر متغیرهای محیطی سیستم را برمی‌گرداند.

بنابراین، برای اطمینان از اینکه تابع env را فقط در فایل‌های پیکربندی برنامه‌ی‌تان فراخوانی کرده‌اید، باید اطمینان حاصل کنید. می‌توانید با بررسی فایل‌های پیکربندی پیش‌فرض Laravel، بسیاری از این مثال‌ها را مشاهده کنید. برای دسترسی به مقادیر پیکربندی، می‌توانید از تابع config به جای تابع env استفاده کنید. تابع config، به شما اجازه می‌دهد تا به مقادیر پیکربندی در هر جای برنامه‌ی‌تان دسترسی داشته باشید.

اگر بخواهید کش پیکربندی را پاک کنید، می‌توانید از دستور config:clear استفاده کنید:

php artisan config:clear

# حالت اشکال‌زدایی (Debug Mode)

گزینه اشکال‌زدایی (Debug) در فایل پیکربندی config/app.php شما، مشخص می‌کند که در صورت بروز خطا، چه میزان اطلاعات به کاربر نمایش داده شود. به طور پیش‌فرض، این گزینه به مقدار متغیر محیطی APP_DEBUG وابسته است که در فایل .env شما ذخیره شده است.

برای توسعه در محیط محلی، باید متغیر محیطی APP_DEBUG را برابر true قرار دهید. اما در سرور اصلی، این مقدار همیشه باید برابر false باشد. اگر متغیر APP_DEBUG در سرور اصلی برابر true قرار گیرد، می‌تواند باعث افشای اطلاعات پیکربندی حساس به کاربران نهایی شود. بنابراین، باید به‌خصوص در سرور اصلی از تنظیمات صحیح این گزینه اطمینان حاصل کرد تا اطلاعات حساس ناشی از اشکال‌زدایی در اختیار هرگونه دسترسی‌ندارنده قرار نگیرد.

# حالت نگهداری (Maintenance Mode)

وقتی برنامه شما در حالت نگهداری قرار دارد، یک نمایش سفارشی برای تمام درخواست‌هایی که به برنامه شما فرستاده می‌شوند، نمایش داده خواهد شد. این امکان را به شما می‌دهد که برنامه‌ی خود را در هنگام به‌روزرسانی یا نگهداری موقتاً “غیرفعال” کنید. برای برنامه شما، چک کردن وضعیت حالت نگهداری، در لایه میان‌افزار (middleware) پیش‌فرض قرار دارد. در صورتی که برنامه در حالت نگهداری باشد، یک instance از Symfony\Component\HttpKernel\Exception\HttpException با کد وضعیت (status code) 503 برگردانده خواهد شد.

برای فعال کردن حالت نگهداری، دستور Artisan down را اجرا کنید:

php artisan down

اگر می‌خواهید که هدر Refresh به همراه تمامی پاسخ‌های حالت نگهداری ارسال شود، می‌توانید هنگام فراخوانی دستور down، گزینه refresh را مشخص کنید. هدر Refresh به مرورگر می‌گوید که پس از تعداد ثانیه‌ای مشخص، صفحه را به‌صورت خودکار تازه کند:

php artisan down --refresh=15

همچنین، می‌توانید گزینه retry را به دستور down اضافه کنید تا به عنوان مقدار هدر Retry-After تنظیم شود، اما معمولاً مرورگرها این هدر را نادیده می‌گیرند. بنابراین، برای تنظیم صحیح حالت نگهداری، بهتر است در اجرای دستور down، فقط گزینه refresh را مشخص کنید و گزینه retry را اضافه نکنید.

php artisan down --retry=60

صرف نظر از حالت نگهداری (Bypassing Maintenance Mode)
برای این که بتوانید از طریق یک توکن مخفی، حالت نگهداری را صرف نظر کنید، می‌توانید از گزینه secret برای مشخص کردن توکن صرف نظر از حالت نگهداری استفاده کنید:

php artisan down --secret="1630542a-246b-4b66-afa1-dd72a4c43515"

بعد از قرار دادن برنامه در حالت نگهداری، می‌توانید به آدرس URL برنامه که با این توکن مطابقت دارد رفته و Laravel یک کوکی صرف نظر از حالت نگهداری را به مرورگر شما صادر می‌کند:

https://example.com/1630542a-246b-4b66-afa1-dd72a4c43515

وقتی به این مسیر پنهان دسترسی پیدا کنید، به مسیر / برنامه هدایت خواهید شد. پس از صدور کوکی به مرورگر شما، قادر خواهید بود به صورت عادی در برنامه حرکت کنید و به‌طور معمول از برنامه استفاده کنید.

توکن حالت نگهداری شما باید عموماً شامل حروف و اعداد باشد و اختیاریاً شامل خط فاصله (-) باشد. باید از کاراکترهایی که در آدرس‌های اینترنتی معنای ویژه‌ای دارند، مانند علامت سوال (?)، استفاده نکنید.

پیش‌نمایش (Pre-Rendering) نمایش حالت نگهداری
اگر در هنگام استقرار از دستور php artisan down استفاده کنید، کاربران شما هنوز ممکن است با خطاهایی مواجه شوند اگر در حین به‌روزرسانی وابستگی‌های Composer شما یا سایر اجزای زیرساخت شما، به برنامه دسترسی داشته باشند. این اتفاق به دلیل آن است که بخش قابل‌توجهی از چارچوب Laravel باید بوت شود تا بتواند درک کند که برنامه شما در حالت نگهداری است و با استفاده از موتور قالب‌بندی، نمایش حالت نگهداری را برای کاربران به نمایش بگذارد.

به همین دلیل، Laravel به شما اجازه می‌دهد تا یک پیش‌نمایش از نمایش حالت نگهداری را پیشینه‌سازی (pre-render) کنید که در ابتدای دوره درخواست بازگردانده می‌شود. این نمایش پیش‌نمایش شده، قبل از بارگذاری هر یک از وابستگی‌های برنامه شما، رندر می‌شود. شما می‌توانید یک قالب با استفاده از گزینه render دستور down پیش‌نمایش کنید:

php artisan down --render="errors::503"

هدایت درخواست‌های حالت نگهداری
هنگامی که برنامه در حالت نگهداری است، Laravel برای تمامی آدرس‌های برنامه‌ی که کاربر سعی در دسترسی به آنها را می‌کند، نمایش حالت نگهداری را نشان خواهد داد. در صورت تمایل، شما می‌توانید به Laravel دستور دهید تا همه درخواست‌ها را به یک URL خاص هدایت کند. برای این کار، می‌توانید از گزینه redirect استفاده کنید. به عنوان مثال، شما ممکن است بخواهید تمامی درخواست‌ها را به / URI هدایت کنید:

php artisan down --redirect=/

غیرفعال سازی حالت نگهداری
برای غیرفعال‌سازی حالت نگهداری، از دستور up استفاده کنید:

php artisan up

شما می‌توانید قالب پیش‌فرض حالت نگهداری را با تعریف قالب خود در resources/views/errors/503.blade.php سفارشی کنید.

حالت نگهداری و صف‌ها
در حین حالت نگهداری برنامه شما، هیچ کاری از صف‌های ردیابی نشده (queued jobs) انجام نخواهد شد. بعد از خروج برنامه از حالت نگهداری، کارهای ردیابی نشده به طور معمول ادامه خواهند داشت.

جایگزین‌های حالت نگهداری
اگرچه حالت نگهداری نیازمند برخی ثانیه‌های خاموشی برنامه شما است، اما می‌توانید از جایگزین‌هایی مانند Laravel Vapor و Envoyer برای انجام استقرار بدون هیچ‌ خاموشی استفاده کنید.