گام 5: عیب‌یابی مشکلات

5.0 version
Maintained

عیب‌یابی مشکلات

راه‌اندازی پروژه، همچنین شامل داشتن ابزارهای مناسب برای اشکال‌زدایی مشکلات است.

نصب وابستگی‌های بیشتر

به خاطر داشته باشید که پروژه با وابستگی های کمی ایجاد شده است. یعنی بدون موتور قالبگیری، بدون ابزارهای اشکال‌زدایی و بدون سامانه‌ی لاگ‌گیری. ایده اینست که شما می‌تواند هر زمان که احتیاج داشتید، وابستگی‌های بیشتر را بیافزایید. اگر در حال توسعه‌ی یک HTTP API و یا یک ابزار رابط خط فرمان (CLI) هستید، چرا باید به یک موتور قالبگیری وابسته باشید؟

چگونه می‌توانیم وابستگی‌های بیشتری را اضافه کنیم؟ از طریق Composer. در کنار بسته‌های «معمولی» Composer، قصد داریم تا با دو نوع «ویژه» از این بسته‌ها کار کنیم:

  • کامپوننت‌های سیمفونی: بسته‌هایی که ویژگی‌های مرکزی و انتزاع‌های سطح پایین که اکثر اپلیکیشن‌ها به آن احتیاج دارند را پیاده‌سازی می‌کنند (راه‌یابی، کنسول، کلاینت HTTP، نهان‌سازی، mailer و ...)؛
  • باندل‌های سیمفونی: بسته‌هایی که ویژگی‌های سطح بالا را اضافه می‌کنند و ادغام با کتابخانه‌های شخص ثالث را فراهم می‌آورند (باندل‌ها اکثراً توسط جامعه‌ی سیمفونی ارائه می‌شوند).

برای شروع، بیایید نمایه‌ساز سیمفونی (Symfony Profiler) را اضافه کنیم، یک ابزار که در هنگام نیاز به یافتن ریشه‌ی یک مشکل، به جلوگیری از تلف‌شدن زمان‌مان بسیار کمک می‌کند.

1
$ symfony composer req profiler --dev

profiler یک اسم مستعار برای بسته‌ی symfony/profiler-pack است.

اسامی مستعار (Aliases) از ویژگی‌های Composer نیستند، بلکه یک مفهوم هستند که توسط سیمفونی و برای راحتی شما مهیا شده‌اند. اسامی مستعار، میانبرهایی برای بسته‌های محبوب Composer هستند. یک ORM برای اپلیکیشن خود می‌خواهید؟ orm را نصب (require) کنید. می‌خواهید API توسعه دهید؟ `` api`` را نصب کنید. این اسامی مستعار به صورت خودکار به یک یا چند بسته‌ی معمولی Composer تبدیل می‌شوند. این اسامی براساس نظرات شخصی تیم مرکزی سیمفونی ساخته شده‌اند.

یک ویژگی شسته‌رفته‌ی دیگر این است که همواره می‌توانید از vendor symfony صرف نظر کنید.``cache`` را به جای symfony/cache نصب کنید.

نکته

آیا به خاطر دارید که قبلاً به یک افزونه‌ی Composer با عنوان symfony/flex اشاره کردیم؟ اسامی مستعار یکی از ویژگی‌های آن هستند.

درک و فهم محیط‌های سیمفونی

آیا متوجه پرچم --dev در فرمان composer req شدید؟ از آنجایی که نمایه‌ساز سیمفونی تنها در روند توسعه‌ی اپلیکیشن مفید است، می‌خواهیم از نصب آن در محیط عمل‌آوری جلوگیری کنیم.

سیمفونی از ایده‌ی محیط‌ها (environments) پشتیبانی می‌کند. سیمفونی به صورت پیشفرض و توکار (built-in) از ۳ محیط پشتیبانی می‌کند، اما شما می‌توانید به هر تعداد که می‌خواهید محیط اضافه کنید. این محیط‌های توکار عبارتند از: dev، prod و test. تمام محیط‌ها از کدهای یکسانی بهره می‌برند، اما دارای پیکربندی (configurations) متفاوت هستند.

برای نمونه، تمام ابزارهای اشکال‌زدایی در محیط dev فعال هستند. در محیط prod، اپلیکیشن برای کارایی و سرعت هرچه بیشتر بهینه می‌شود.

تعویض از یک محیط به محیط دیگر، می‌تواند با تغییرِ متغیر محیط APP_ENV انجام شود.

هنگامی که بر روی SymfonyCloud استقرار را انجام دادید، محیط (ذخیره‌شده در APP_ENV) به صورت خودکار به prod تعویض گردید.

مدیریت پیکربندی‌های محیط

APP_ENV می‌تواند با استفاده از متغیر‌های محیط «واقعی» و از طریق ترمینال تنظیم گردد:

1
$ export APP_ENV=dev

استفاده از متغیر‌های محیط واقعی، روش ترجیحی برای تنظیم مقادیری همچون APP_ENV در محیط عمل‌آوری است. اما در محیط توسعه، تعریف تعداد زیادی متغیر محیط بر روی رایانه‌ی محلی، زحمت زیادی دارد. به جای اینکار، مقادیر مورد نظر را از طریق فایل .env تعریف کنید.

هنگامی پروژه ایجاد گردید، یک فایل .env معقول، به صورت خودکار تولید شد.

.env
1
2
3
4
5
6
###> symfony/framework-bundle ###
APP_ENV=dev
APP_SECRET=c2927f273163f7225a358e3a1bbbed8a
#TRUSTED_PROXIES=127.0.0.1,127.0.0.2
#TRUSTED_HOSTS='^localhost|example\.com$'
###< symfony/framework-bundle ###

نکته

به لطف recipe‌های سیمفونی Flex، هر بسته‌ای می‌تواند متغیر‌های محیط بیشتری را به این فایل اضافه کند.

فایل .env، در مخزن Git مربوطه، commit شده است و مقادیر پیشفرض در محیط عمل‌آوری را تعیین می‌کند. شما می‌توانید این مقادیر را با ایجاد فایل .env.local باطل کرده و مقادیر جدیدتان را جایگزین کنید. این فایل نباید commit شود و به همین علت به کمک فایل .gitignore نادیده گرفته شده است.

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

لاگ‌کردن تمام چیزها

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

1
$ symfony composer req logger

بیایید ابزارهای اشکال‌زدایی را تنها در محیط توسعه نصب کنیم:

1
$ symfony composer req debug --dev

کشف ابزارهای اشکال‌زدایی سیمفونی

اگر صفحه‌ی اصلی را در مرورگر تازه‌سازی (refresh) کنید، می‌بایست یک نوارابزار (toolbar) در پایین صفحه مشاهده کنید:

اولین چیزی که احتمالاً متوجه آن خواهید شد، یک 404 قرمز رنگ است. به خاطر داشته باشید که چون هنوز صفحه‌ی اصلی را طراحی نکرده‌ایم، این صفحه تنها یک جانشین موقت و پیش‌فرض برای آن می‌باشد. این صفحه که به شما خو‌ش‌آمد می‌گوید، با وجود اینکه زیبا است، اما هنوز هم یک صفحه‌ی خطا است. بنابراین کد وضعیت HTTP درست برای آن، ۲۰۰ نیست بلکه ۴۰۰ است. به لطف ابزار اشکال‌زدایی، شما بلافاصله اطلاعات را در اختیار دارید.

اگر بر روی علامت تعجب کوچک کلیک کنید، پیغامِ استثناءِ (Exception) «واقعی» را به عنوان بخشی از لاگ‌های درون نمایه‌ساز سیمفونی دریافت می‌کنید. اگر می‌خواهید ردپای پشته (stack trace) را ببینید، بر روی لینک «Exception» در منوی سمت چپ کلیک کنید.

هر زمان که مشکلی در کد وجود داشته باشد، شما صفحه استثنایی همچون صفحه‌ی زیر مشاهده خواهید کرد که تمام چیزهای مورد نیاز برای فهمیدن مشکل و اینکه از کجا ناشی می‌شود را در اختیارتان می‌گذارد:

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

لاگ‌ها در جلسات اشکال‌زدایی بسیار کمک‌کننده هستند. سیمفونی یک فرمان مناسب برای دنبال کردن تمام لاگ‌ها دارد (از وب سرور، PHP و اپلیکیشن شما):

1
$ symfony server:log

بیایید یک آزمایش کوچک انجام دهیم. فایل public/index.php را باز کنید و کد PHP درون آن را خراب کنید (مثلاً کلمه foobar را جایی در میان کدها اضافه کنید). در درون مرورگر، صفحه را تازه‌سازی و جریان لاگ‌ها را مشاهده کنید:

1
2
Dec 21 10:04:59 |DEBUG| PHP    PHP Parse error:  syntax error, unexpected 'use' (T_USE) in public/index.php on line 5 path="/usr/bin/php7.42" php="7.42.0"
Dec 21 10:04:59 |ERROR| SERVER GET  (500) / ip="127.0.0.1"

خروجی به صورت زیبایی رنگ‌آمیزی شده است تا توجه شما را به خطا‌ها جلب کند.

یکی دیگر از یاوران فوق‌العاده در اشکال‌زدایی، تابع dump() در سیمفونی است. این تابع همواره در دسترس است و به شما این امکان را می‌دهد تا متغیر‌های پیچیده را به شکلی زیبا و پویا، دامپ (Dump) نمایید.

فایل public/index.php را موقتاً تغییر دهید تا شیءِ «Request» را دامپ کند:

patch_file
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
--- a/public/index.php
+++ b/public/index.php
@@ -23,5 +23,8 @@ if ($trustedHosts = $_SERVER['TRUSTED_HOSTS'] ?? $_ENV['TRUSTED_HOSTS'] ?? false
 $kernel = new Kernel($_SERVER['APP_ENV'], (bool) $_SERVER['APP_DEBUG']);
 $request = Request::createFromGlobals();
 $response = $kernel->handle($request);
+
+dump($request);
+
 $response->send();
 $kernel->terminate($request, $response);

زمانی که صفحه را تازه‌سازی کردید، به آیکون جدید «target» در نوارابزار توجه کنید. این گزینه به شما اجازه می‌دهد تا دامپ را بررسی کنید. بر روی آن کلیک کنید تا به حالت تمام صفحه بروید و پیمایش راحت‌تر گردد:

قبل از commit‌کردن سایر تغییرات انجام‌شده در این گام، تغییرات (اخیر) را revert کنید:

1
$ git checkout public/index.php

پیکربندی IDE شما

در محیط توسعه، هنگامی که یک استثناء (exception) پرتاب (throw) می‌شود، سیمفونی یک صفحه حاوی پیغام استثناء و ردپای پشته را نمایش می‌دهد. هنگامی که یک مسیر فایل نمایش داده می‌شود، سیمفونی یک لینک اضافه می‌کند که کلیک بر روی آن، فایل مورد نظر را در IDE مورد علاقه‌تان و در خط صحیح، باز می‌کند. برای سودبردن از این ویژگی، باید IDE تان را پیکربندی کنید. سیمفونی به صورت آماده از IDEهای زیادی پشتیبانی می‌کند؛ من برای این پروژه از ویژوال استودیو کد استفاده می‌کنم:

patch_file
1
2
3
4
5
6
7
8
--- a/config/packages/framework.yaml
+++ b/config/packages/framework.yaml
@@ -14,3 +14,5 @@ framework:
     #fragments: true
     php_errors:
         log: true
+
+    ide: vscode

فایل‌ها لینک‌شده تنها به استثناءها محدود نیستند. برای نمونه پس از پیکربندی IDE، کنترلر در نوارابزار اشکال‌زدایی وب، کلیک‌پذیر می‌شود.

اشکال‌زدایی محصول

همیشه اشکال‌زدایی سرورهای عمل‌آوری، سخت‌تر است. مثلاً شما به نمایه‌ساز سیمفونی دسترسی ندارید. لاگ‌ها کمتر شامل درازگویی هستند، اما دنبال‌کردن لاگ‌ها امکان پذیر است:

1
$ symfony logs

حتی می‌توانید از طریق SSH، به کانتینر وب متصل شوید:

1
$ symfony ssh

نگران نباشید، نمی‌توانید چیزی را به آسانی خراب کنید. اکثر فایل‌سیستم، در حالت تنها-خواندنی (read-only) قرار دارند. شما نمی‌توانید در محیط عمل‌آوری یک هات‌فیکس انجام دهید. اما بعداً در کتاب، راهی بسیار بهتر خواهید آموخت.


  • « Previous گام 4: اتخاذ یک متدولوژی
  • Next » گام 6: ساخت یک کنترلر

This work, including the code samples, is licensed under a Creative Commons BY-NC-SA 4.0 license.