תיעוד

Yii מספקת אפשרות לתיעוד גמישה ונרחבת. הודעות אשר מתועדות ניתנות לסיווג על פי רמות וקטגוריות. שימוש בפילטרים של רמות וקטגוריות, ניתן לנתב את ההודעות הנבחרות ליעדים שונים, כמו קבצים, אימיילים, תצוגה בחלונות בדפדפן וכדומה.

1. תיעוד הודעות ¶

ניתן לתעד הודעות על ידי קריאה ל Yii::log או Yii::trace. ההבדל בין שני המתודות הללו היא שהמתודה השנייה מתעדת הודעה רק בזמן שהאפליקציה נמצאת במצב של ניפוי שגיאות.

Yii::log($message, $level, $category);
Yii::trace($message, $category);

בעת תיעוד הודעה, אנו צריכים להגדיר את הקטגוריה והרמה שלו. קטגוריה הינה סטרינג בפורמט של xxx.yyy.zzz בדומה שמות מקוצרים. לדוגמא, אם ההודעה מתועדת תחת CController, אנו יכולים להשתמש בקטגוריה system.web.CController. רמת ההודעה צריכה להיות אחד מהערכים הבאים:

• trace: זוהי הרמה הנמצאת בשימוש על ידי Yii::trace. היא נועדה לעקוב אחר תהליך יצירת האפליקציה בזמן הפיתוח.

• info: רמה זו נועדה לתיעוד של הודעות כלליות.

• profile: רמה זו נועדה לתיעוד של הודעות פרופיל, אשר נרחיב עליהם בהמשך.

• warning: רמה זו נועדה לתיעוד של הודעות אזהרה.

• error: רמה זו נועדה לתיעוד של הודעות שגיאה.

2. ניתוב הודעות ¶

הודעות המתועדות על ידי Yii::log או Yii::trace נשמרות בזיכרון. אנו בדרך כלל צריכים להציג אותם בדפדפן, או לשמור אותם במקום אחסון קבוע כמו קבצים, אימיילים. זה נקרא ניתוב הודעות, כלומר, שליחת ההודעות ליעד שונה.

באפליקציות Yii, ניתוב הודעות מנוהל על ידי הרכיב CLogRouter. הוא מנהל סט של מה שנקרא ניתוב תיעודים. כל נתב מייצג יעד עבור ההודעות. ניתן לבצע פילטר על גבי הודעות המועברות בנתב על פי הרמות והקטגוריות שלהן.

בכדי להשתמש בניתוב הודעות, אנו צריכים להתקין ולטעון מראש את רכיב האפליקציה CLogRouter. כמו כן אנו צריכים להגדיר את המאפיין routes עם הנתבים בהם אנו רוצים להשתמש. הקוד הבא מציג דוגמא לקובץ הגדרות אשר מוגדר להשתמש עם ניתוב הודעות:

array(
    ......
    'preload'=»array('log'),
    'components'=»array(
        ......
        'log'=»array(
            'class'=»'CLogRouter',
            'routes'=»array(
                array(
                    'class'=»'CFileLogRoute',
                    'levels'=»'trace, info',
                    'categories'=»'system.*',
                ),
                array(
                    'class'=»'CEmailLogRoute',
                    'levels'=»'error, warning',
                    'emails'=»'admin@example.com',
                ),
            ),
        ),
    ),
)

בדוגמא למעלה, יש ברשותנו שני נתבים. הנתב הראשון הינו CFileLogRoute השומר את ההודעות בקובץ תחת התיקיה הזמנית באפליקציה. רק ההודעות שרמה שלהן היא trace או info ושהקטגוריה שלהם מתחילה ב system נשמרות. הנתב השני הינו CEmailLogRoute אשר שולח את ההודעות לכתובות האימיילים המוגדרות. רק ההודעות שהרמה שלהן היא error או warning נשלחות.

ניתן להשתמש בסוגי הנתבים הבאים באפליקציות Yii:

• CDbLogRoute: שומר את ההודעות בטבלה במסד הנתונים.
• CEmailLogRoute: שולח את ההודעות אל אימיילים שהוגדרו מראש.
• CFileLogRoute: שומר את ההודעות בקובץ תחת התיקיה הזמנית של האפליקציה.
• CWebLogRoute: מציג את ההודעות בסוף כל עמוד בדפדפן.
• CProfileLogRoute: מציג את הודעות הפרופיל בסוף כל עמוד בדפדפן.

» Info|מידע: ניתוב הודעות מתבצע בסוף הבקשה הנוכחית כשהאירוע onEndRequest מתרחש. בכדי לעצור את טעינת הסקריפט וביצוע הבקשה במקום כלשהו, יש לקרוא למתודה [()CApplication::end] במקום ()die או ()exit, בגלל ש-[()CApplication::end] יטען את האירוע onEndRequest כדי שיהיה ניתן לתעד ולנתב את ההודעות כראוי.

סינון הודעות

כפי שכבר ציינו, ניתן לסנן הודעות על פי הרמות והקטגוריות בהם הן נמצאות לפני שהן נשלחות לניתוב כלשהו. זה נעשה על ידי הגדרת המאפיינים levels ו categories של הנתב המדובר. מספר רב של רמות או קטגוריות צריכות להיות משורשרות (מחוברות אחת לשנייה) בעזרת פסיק ( , ).

מאחר וקטגוריות הודעות הם בפורמט של xxx.yyy.zzz, אנו יכולים להתייחס אליהם כהיררכית קטגוריות. במיוחד, אנו אומרים ש xxx הוא האב של xxx.yyy שהוא האב של xxx.yyy.zzz. לכן אנו יכולים להשתמש ב-*.xxx בכדי לייצג את הקטגוריה xxx וכל תתי הקטגוריות הנמצאות תחתיו.

תיעוד מידע בהקשר מסויים

החל מגרסא 1.0.6, אנו יכולים להגדיר לתעד מידע נוסף בהקשר מסויים, כמו לדוגמא משתנים מוגדרים מראש של PHP (כמו GET_$ ו SERVER_$), מספר מזהה ב Session, שם משתמש וכדומה. זה נעשה על ידי הגדרת המאפיין CLogRoute::filter בנתב מסויים לפילטר המתאים.

המערכת מגיעה עם מחלקה נוחה בשם CLogFilter שניתן להשתמש בה כפילטר הדרוש ברוב המקרים. כברירת מחדל, CLogFilter יתעד הודעות עם משתנים כמו GET_$ ו SERVER_$ אשר מכילים בדרך כלל מידע חשוב בהקשר למערכת. כמו כן, ניתן להגדיר את CLogFilter כדי שיספק קידומת עבור הודעות עם מספר מזהה יחודי כלשהו, שם משתמש וכדומה, אשר יכול לפשט בצורה משמעותית את החיפוש הגלובלי כשאנו בודקים את ההודעות המתועדות הרבות.

ההגדרות הבאות מציגות כיצד להפעיל תיעוד מידע בהקשר מסויים. דע שכל נתב הודעות יכול להכיל את פילטר ההודעות שלו. וכברירת מחדל, נתב הודעות לא מכיל פילטר הודעות.

array(
    ......
    'preload'=»array('log'),
    'components'=»array(
        ......
        'log'=»array(
            'class'=»'CLogRouter',
            'routes'=»array(
                array(
                    'class'=»'CFileLogRoute',
                    'levels'=»'error',
                    'filter'=»'CLogFilter',
                ),
                ...נתבי הודעות נוספים...
            ),
        ),
    ),
)

החל מגרסא 1.0.7, Yii מאפשרת לשמור את המיקום (קובץ ושורה) שההודעה תועדה עבור הודעות אשר מתועדות על ידי Yii::trace. אפשרות זו כבויה כברירת מחלד מאחר והיא משפיעה לרעה על ביצועי המערכת. בכדי להפעיל אפשרות זו, יש להגדיר פשוט משתנה גלובלי YII_TRACE_LEVEL בתחילת הסקריפט (בקובץ index.php לפני הטעינה של הקובץ yii.php) עם ערך הגדול מ-0. Yii תוסיף עבור כל הודעה מתועדת את הקובץ והשורה שבה ההודעה תועדה. המספר המוגדר בערך הגלובלי YII_TRACE_LEVEL הוא כדי שהמערכת תדע להציג את עומק הקריאה, זאת אומרת שאם ההודעה תועדה בקובץ שנטען שלישי מתחילת הסקריפט (מהרצת קובץ index.php) ואנו הגדרנו את המשתנה YII_TRACE_LEVEL למספר 2 רק שני הקבצים האחרונים בדרך להודעה יתועדו. מידע זה שימושי בעיקר בזמן פיתוח מאחר וזה יכול לעזור בזיהוי המקומות בהם ההודעה תועדה.

שימוש במשתנה הגלובלי YII_TRACE_LEVEL נעשה בצורה הבאה:

define('YII_TRACE_LEVEL', 2);

3. תיעוד ביצועים (פרופיל) ¶

תיעוד ביצועים הינה אפשרות מיוחדת בתיעוד ההודעות. שימוש בתיעוד ביצועים נעשה בעיקר כדי למדוד את הזמן הדרוש עבור הרצת קוד מסויים בכדי לדעת איפה נמצא צוואר הבקבוק.

בכדי להשתמש בתיעוד ביצועים, אנו צריכים לזהות אילו חלקי קוד צריכים להיות מתועדים. אנו מסמנים את ההתחלה והסוף עבור כל חתיכת קוד על ידי הוספת המתודות הבאות:

Yii::beginProfile('blockID');
...חתיכת הקוד שאנו רוצים לבצע עליו את תיעוד הביצועים....
Yii::endProfile('blockID');

blockID הינו שם יחודי המזהה את הקוד הספציפי הזה.

יש לזכור, קטעי קוד צריכים להיות משורשרים בהיררכיה נכונה. זאת אומרת, קטע קוד לא יכול להצטלב עם קטע קוד אחר. הוא חייב להיות מקביל או תחום לגמרי על ידי קטע קוד אחר.

בכדי להציג את תוצאות תיעוד הביצועים, אנו צריכים להתקין רכיב אפליקציה בשם CLogRouter אשר משתמש בניתוב מסוג CProfileLogRoute. זה דומה למה שאנו עושים עם ניתובי הודעות רגילים. הנתב CProfileLogRoute יציג את תוצאות הביצועים בסוף העמוד בדפדפן.

תיעוד ביצועי שאילתות SQL

תיעוד ביצועים הוא שימושי במיוחד בעת השימוש במסד נתונים מאחר ושאילתות SQL הם הגורם העיקרי לצווארי בקבוק באפליקציה. אנו יכולים לציין באופן ידני ביטויים של beginProfile ו endProfile במקומות מסויימים בכדי למדוד את הזמן הנדרש עבור כל שאילתת SQL, החל מגרסא 1.0.6, Yii מספקת גישה יותר שיטתית כדי לפתור בעיה זו.

על ידי הגדרת המאפיין CDbConnection::enableProfiling לערך השווה ל true בהגדרות האפליקציה, כל שאילתית SQL שתתבצע תתועד. ניתן להציג תוצאות אלו על ידי שימוש בנתב CProfileLogRoute שהצגנו קודם לכן, המציג לנו כמה זמן נמדד עבור כל שאילתת SQL. כמו כן אנו יכולים לקרוא למתודה [()CDbConnection::getStats] כדי לשלוף את מספר שאילתות SQL שבוצעו ואת הזמן הכולל שלקח לבצע אותם.