מוסכמות
===========

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

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

קישורים
---

כברירת מחדל, Yii מזהה קישורים בפורמט הבא:

~~~
http://hostname/index.php?r=ControllerID/ActionID
~~~

הפרמטר `r` מכוון אל [נתב](/doc/guide/basics.controller#route) אשר ניתן לעבד אותו לקונטרולר ופעולה. במידה והמזהה היחודי של הפעולה `ActionID` חסר, הקונטרולר יריץ את פעולת ברירת המחדל המוגדרת באמצעות [CController::defaultAction]; במידה והמזהה היחודי של הקונטרולר `controllerID` חסר (או הפרמטר `r` חסר) האפליקציה תריץ את הקונטרולר המוגדר כברירת מחדל בעזרת [CWebApplication::defaultController].

בעזרת [CUrlManager], ניתן ליצור קישורים יותר ידידותיים גם ל SEO, כמו לדוגמא `http://hostname/ControllerID/ActionID.html`. ניתן לקרוא בהרחבה אודות אפשרות זו [בניהול קישורים](/doc/guide/topics.url).


קוד
----

Yii ממליצה לקרוא למשתנים, פונקציות ומחלקות בפורמט של camelCase (פורמט אשר רושמים ראשונה במילה כאות גדולה ולחבר אותם ללא רווחים). שמות משתנים ופונקציות צריכות שהמילה הראשונה בשם שלהם תיהיה כולה באותיות קטנות (מילה ראשונה באותיות קטנות כל שאר המילים האות הראשונה במילה כאות גדולה ולחברם ביחד ללא רווחים), כדי להבדיל אותם משמות מחלקה (לדוגמא  `$basePath`, `runController()`, `LinkPager`). למשתנים פרטיים (המוגדרים כ `private`) במחלקה מומלץ להוסיף קו תחתון (_) לשמם לדוגמא (`$_actionList`).

מאחר והתמיכה במרחבי שמות לא נתמכת בגרסאות PHP מתחת ל 5.3.0, מומלץ לקרוא למחלקות בשמות יחודיים כדי למנוע סתירות בין שמות מחלקות. מסיבה זו, כל המחלקות הבסיסיות של Yii מתחילות באות 'C'.

חוק ברזל לשמות מחלקות הוא שהם צריכים להסתיים במילה `Controller`. המזהה היחודי של הקונטרולר מוגדר כשם המחלקה באותיות קטנות בלבד וללא המילה `Controller`. לדוגמא, מחלקת הקונטרולר `PageController` תקבל את המזהה היחודי `page`. חוק זה מוודא שהאפליקציה תיהיה מאובטחת יותר. בנוסף הוא מציג את הקישורים בצורה נקייה יותר (לדוגמא `/index.php?r=page/index` במקום `/index.php?r=PageController/index` ).

הגדרות
-------------

הגדרות הם מערך זוגות של מפתחות וערכים. כל מפתח מייצג את שמו של המאפיין של הרכיב שצריך להגדיר, וכל ערך מייצג את הערך הראשוני של אותו מאפיין. לדוגמא , `array('name'=»'My
application', 'basePath'=»'./protected') מאתחל את המאפיינים `name` ו `basePath` באפליקציה בהתאם לערכים המוגדרים במערך.

כל המאפיינים (הציבוריים - Public) באובייקט ניתנים להגדרה. אם לא הוגדרו, המאפיינים יקבלו את ערך ברירת המחדל שלהם. כשמגדירים מאפיין כלשהו, רצוי לקרוא בדוקומנטציה אודות המאפיין כדי להגדיר את הערך המתאים.

קובץ
----

מוסכמות להגדרת שמות ושימוש בקבצים תלויים בסוג שלהם.

שמות קבצי מחלקות צריכות להקרא על פי המחלקה הציבורית הנמצאת בהם. לדוגמא, שם הקובץ של המחלקה [CController] הוא `CController.php`. מחלקה ציבורית הינה מחלקה שניתן להשתמש בה בכל מחלקה אחרת. רצוי שכל קובץ מחלקה יכיל מחלקה ציבורית אחת לכל היותר. מחלקות פרטיות (מחלקות אשר ניתן להשתמש בהם במחלקה ציבורית אחת בלבד) יכול להיות בתוך אותו קובץ של המחלקה הציבורית שבה היא משומשת.

קבצי תצוגה צריכים להקרא על פי שמות התצוגה. לדוגמא, שם קובץ התצוגה `index` יהיה `index.php`. קובץ תצוגה הוא קובץ PHP המכיל בעיקר קוד PHP ו HTML למטרת תצוגה בעיקר.

קבצי הגדרות יכולים להקרא באופן שרירותי. קובץ הגדרות הוא קובץ PHP המכיל ומחזיר מערך של הגדרות.

תיקיה
---------

Yii מניח כברירת מחדל כמה תיקיות אשר הוא משתמש למטרות שונות. את כל אחד ניתן להגדיר בצורה שונה במידה וצריך.

- `WebRoot/protected`: זוהי [התיקיה הראשית](/doc/guide/basics.application#application-base-directory) של האפליקציה המכילה קבצים וסקריפטים של PHP רגישים. Yii מגדירה שם מקוצר ברירת מחדל בשם `application` אשר מנותבת לתיקיה זו. תיקיה זו וכל מה שבתוכה צריכה להיות מוגנת מפני גישה של משתמשי קצה. ניתן להגדירה בעזרת [CWebApplication::basePath].

- `WebRoot/protected/runtime`: תיקיה זו מכילה קבצים זמניים פרטיים הנוצרים בזמן הרצת האפליקציה. תיקיה זו חייבת לקבל הרשאות כתיבה על ידי השרת. ניתן להגדירה בעזרת [CApplication::runtimePath].

- `WebRoot/protected/extensions`: תיקיה זו מכילה את כל התוספים למערכת. ניתן להגדירה בעזרת [CApplication::extensionPath].

- `WebRoot/protected/modules`: תיקיה זו מכילה את כל [המודולים](/doc/guide/basics.module) של האפליקציה, כל אחת מייצגת כתת-תיקיה.

- `WebRoot/protected/controllers`: תיקיה זו מכילה את כל הקונטרולרים של האפליקציה. ניתן להגדירה בעזרת [CWebApplication::controllerPath].

- `WebRoot/protected/views`: תיקיה זו מכילה את כל קבצי התצוגה, הכוללים את קבצי התצוגה של הקונטרולרים, קבצי תצוגת התבניות, וקבצי תצוגה מערכתיים. ניתן להגדירה בעזרת [CWebApplication::viewPath].

- `WebRoot/protected/views/ControllerID`: תיקיה זו מכילה את קבצי התצוגה לקונטרולר יחיד. במקרה הזה `ControllerID` מייצג את המזהה היחודי של הקונטרולר. ניתן להגדיר זאת על ידי [CController::viewPath].

- `WebRoot/protected/views/layouts`: תיקיה זו מכילה את כל קבצי התבניות של האפליקציה. ניתן להגדירה בעזרת [CWebApplication::layoutPath].

- `WebRoot/protected/views/system`: תיקיה זו מכילה את כל קבצי התצוגה המערכתיים כמו התצוגה של שגיאות ולוגים של המערכת. ניתן להגדיר זאת על ידי [CWebApplication::systemViewPath].

- `WebRoot/assets` : תיקיה זו מכילה את קבצי הנכסים (JS, CSS) , קבצים אלו הם פרטיים אשר ניתן לפרסמם כדי שמשתמשי קצה יוכלו לגשת אליהם. תיקיה זו צריכה לקבל הרשאות כתיבה על ידי השרת כדי לתפקד כראוי. ניתן להגדירה בעזרת [CAssetManager::basePath].

- `WebRoot/themes` : תיקיה זו מכילה עיצובים שונים אשר ניתן להשתמש בהם באפליקציה. כל תת תיקיה מייצגת עיצוב בודד ששמו הוא שם התיקיה בה הוא נמצא. ניתן להגדיר את נתיב התיקיה בעזרת [CThemeManager::basePath].
 
מסד נתונים
--------

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

- שמות הטבלאות והעמודות צריכות להיות כתובות באותיות קטנות בלבד.

- המילים בשם צריכים להיות מופרדים בקו תחתון ( _ ) לדוגמא `product_order`.

- שמות טבלאות יכולות להיות בפורמט של יחיד או רבים, אך לא שניהם. לפשטות, אנו ממליצים שימוש בפורמט של יחיד.

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

«div class="revision"»$Id: basics.convention.txt 1768 2010-02-01 01:34:15Z qiang.xue $«/div»