Moodle二次開發(fā)指南-代碼編寫指南

1、通用規(guī)則所有代碼文件應當使用“.php”作為擴展名。所有模板文件應當使用“.html”作為擴展名。所有文本文件應當使用Unix風格的文本格式(多數(shù)的文本編輯器都有這個選項)。所有php標記都必須是“完整”標記，如?php?而非如?的短標記。所有已經(jīng)存在的版權聲明應當被保留。如果有必要，您可以加入自己的。每個文件都應當包含主config.php文件。每個文件都應當檢查用戶的身份是否正確，可以使用函數(shù)require_login()和isadmin()、isteacher()、iscreator()或者isstudent()。所有訪問數(shù)據(jù)庫的操作都應當使用lib/datalib.php中的函數(shù)這樣可

2、以兼容更多的數(shù)據(jù)庫服務器。所有的事情都應當是可以用這些函數(shù)來完成的，如果遇到必須要寫SQL代碼的情況，請記住這些代碼應當是跨平臺的，且僅僅對您代碼中的特定函數(shù)(通常在一個lib.php文件中)有效，且代碼中用注釋進行明確說明。不要建立和使用標準全局變量$CFG、$SESSION、$THEME、$SITE、$COURSE和$USER之外的全局變量。所有變量都應當被初始化或者至少在使用前用isset()或empty()等函數(shù)進行檢測。所有字符串都應當可翻譯在“l(fā)ang/en_utf8目錄中創(chuàng)建新的文本文件，字符串應當使用簡潔的英文小寫名稱，并通過函數(shù)get_string()或print_strin

3、g()來取得。為了保證語言包的向后兼容，絕對不要刪除字符串。所有幫助文件應當可翻譯一一在“l(fā)ang/en_utf8/help”目錄中創(chuàng)建文本文件并且通過helpbutton()函數(shù)來調用它們。如果要更新幫助文件：對于小的修改，舊的翻譯文件仍然可以繼續(xù)使用時，可以直接進行修改，但您應當通知translationATmoodleDOTorg。對于大的修改，應當創(chuàng)建新的文件，新文件的文件名是在原文件名的末尾添加一個數(shù)字，并在以后逐漸增加(如filename2.html)，這樣翻譯人員就可以方便地知道文件有了一個新的版本。很顯然，新的代碼和幫助索引文件都必須修改以指向新版本的文件。從瀏覽器發(fā)來的信息(

4、以GET或POST形式發(fā)送)都應用了magic_quotes(無論PHP的設置如何)，因此直接將它們插入到數(shù)據(jù)庫中是安全的。所有其它的原始數(shù)據(jù)(來自文件或數(shù)據(jù)庫的)都必須在插入數(shù)據(jù)庫前使用addslashes()進行預處理。由于在這個問題上人們經(jīng)常出錯，我們編寫了一個獨立的頁面來介紹如何添加和刪除“”符號。非常重要：Moodle中所有的文本，特別是用戶提供的文本，都必須使用format_text()函數(shù)來輸出。這樣就可以確保文本已經(jīng)正確地過濾。在輸出函數(shù)頁面上有關于這個問題的更多信息。.用戶的動作應當用add_to_log()函數(shù)記錄下來，這些信息會被用于活動報告和日志編碼風格我知道，如果您已

5、經(jīng)習慣了一種編碼風格而我卻讓您改變它是有一點討厭的，但比較而言，這比日后所有人都需要去搞清混合風格的Moodle代碼要好一些。對于人們使用的任何編碼風格都有很多支持和反對的意見，但現(xiàn)在正在使用的風格已經(jīng)存在了，因此請堅持下去?？s進應當是4個連續(xù)的空格。絕對不要使用制表符。變量名應當是容易理解、有含義的小寫英文單詞。如果確實需要兩個或以上的單詞，請把它們連在一起，但要保持名稱盡可能短。對于數(shù)組對象，請使用復數(shù)名稱。好的：$quiz好的：$errorstring好的：$assignments(foranarrayofobjects)好的：$i(butonlyinlittleloops)壞的：$Qu

6、iz壞的:$aReallyLongVariableNameWithoutAGoodReason壞的：$error_string常量應當總是大寫的，并總是以模塊的名稱作為前綴。單詞之間應當用下劃線分隔。TOC o 1-5 h zI1IIIIIIdefine(FORUM_MODE_FLATOLDEST，1);IIIIIIIJ4.函數(shù)名稱應當是簡單的英文小寫單詞，且總是以模塊名作為前綴以防止模塊之間的沖突。單詞之間以下劃線分隔。變量如果可能應當總有合理的缺省值。注意在函數(shù)名和其后的括號之間沒有空格。functionforum_set_display_mode($mode=0)global$USER,

7、$CFG;if($mode)$USER-mode=$mode;elseif(empty($USER-mode)$USER-mode=$CFG-forum_displaymode;5語句塊必須總是使用大括號(即便是只有一行)。Moodle使用如下風格:if($quiz-attempts)if($numattempts$quiz-attempts)error($strtoomanyattempts,view.php?id=$cmid)6.字符串應當盡可能用單引號定義以提高速度。$var=sometextwithoutanyvariables;$var=withspecialcharactersli

8、keanewlinen;$var=avery,verylongstringwitha.$single.variableinit;$var=some$textwith$manyvariables$withinit;TOC o 1-5 h zIIIIII實用的注釋應當盡可能填寫，用以解釋代碼流程和函數(shù)與變量的功能。每個函數(shù)和類都應該使用流行的phpDoc格式編寫，以便自動生成代碼文檔。內嵌注釋應使用/風格，并且整齊布局，使其能融入代碼中并和代碼對齊。I1IIIIII/*Thedescriptionshouldbefirst,withasteriskslaidoutexactlylikethisex

9、ample.Ifyouwanttorefertoaanotherfunction,doitlikethis:linkclean_param().Then,adddescriptionsforeachparameterasfollows.*TOC o 1-5 h zIIIIIIparamint$postidThePHPtypeisfollowedbythevariablenameparamarray$scaleThePHPtypeisfollowedbythevariablenameparamarray$ratingsThePHPtypeisfollowedbythevariablenamere

10、turnmixed*/IIIIfunctionforum_get_ratings_mean($postid,$scale,$ratings二NULL)if(!$ratings)$ratings=array();/Initializetheemptyarrayif($rates=get_records(forum_ratings,post,$postid)TOC o 1-5 h zII/Processeachratinginturnforeach($ratesas$rate).etcIIIIIIIIII換行可以被大方地使用一一把東西分散開看起來會比較清楚。一般情況下，在花括號和普通命令之間應當有

11、一個換行符，但在花括號和變量或函數(shù)之間可以沒有換行符：I1IIIIIIIIforeach($objectsas$key=$thing)process($thing);if($x=$y)$a=$b;elseif($x=$z)$a=$c;else$a=$d;當復制一個對象時，要使用php5的clone（）函數(shù)（否則得到的就僅僅是指向第一個對象的引用）。Moodle會保證這種方法在php4上也能正常工作。1壞的：$b=$a;好的：$b=clone($a);如果你要復制的并非對象，但包含了對象（如對象數(shù)組），那么要使用fullclone（）函數(shù)。數(shù)據(jù)庫結構每個表格都必須有一個自增的id字段（INT10

12、）作為主鍵。（參考IdColumnReasons包含著模塊中數(shù)據(jù)實例的主表格必須和模塊同名（譬如widget），并且至少包含如下字段：id-如上一條所述course-每個實例所屬的課程idname-每個實例的完整名稱與模塊相關的其它表格的命名規(guī)則是：如果它包含的信息是關于“things”的，貝怕的名字應當是widget_things（注意采用復數(shù)形式）。表名和字段名都應當避免使用各種數(shù)據(jù)庫的保留字。因此在創(chuàng)建前要仔細檢查。字段名稱應當簡短并使用小寫，與變量名的規(guī)則相同。在可能的情況下，包含著對其它表格（如widget）引用的字段應當命名為widgetid。（注意這是個新約定，有一些老的表格并未

13、遵守。）布爾字段應當使用小整數(shù)類型（如INT4）并存儲為0或1,這樣就可以在需要時擴展它。多數(shù)的表格應當有一個timemodified字段（INT10）,并用PHP的time（）函數(shù)取得的當前時間戳來更新它。給每個字段定義一個缺省值（并保證它是有意義的）。每個表名都必須有前綴（$CFG-prefix）。在大多數(shù)情況下，您必須自己注意此問題。并且在Postgres中，所有的索引名也必須有前綴。Inordertoguaranteecross-dbcompatibilityfollowthesesimplerulesabouttheuseoftheASkeyword（onlyifyouneedtab

14、le/columaliases,ofcourse）:不要將關鍵字AS用于表格別名要將關鍵字AS用于字段別名不要創(chuàng)建UNIQUEKEY(限制)，用UNIQUEINDEX來代替它。Inthefuture,ifwedecidetoaddreferentialintegritytoMoodleandweneedUNIQUEKEYstheywillbeused,butnotnow.PleasenotethattheXMLDBeditorallowsyoutospecifybothXMLDB-onlyUNIQUEandFOREIGNconstraints(andthatsgood,inordertohav

15、etheXMLwelldefined)butonlyunderlyingINDEXeswillbegenerated.ThoseXMLDB-onlyUNIQUEKEYs(readpreviouspoint)onlymustbedefinedifsuchfield/fieldsaregoingtobethetargetforsome(XMLDB-onlytoo)FOREIGNKEY.Else,createthemassimpleUNIQUEINDEXes.與某個版塊相關的表格命名時需要遵守以下規(guī)則：$CFG-prefix+block_+name_of_the_block+anything_els

16、e。例如，$CFG-prefix是mdl_，則與rss_client版塊相關的表格，其名稱前綴應當是mdl_block_rss_client(在末尾添加多一些的詞不會帶來任何問題，如mdl_block_rss_client_anothertable)。在Moodle2.0中，這個規(guī)則會100%地強制執(zhí)行，開發(fā)者需在此之前做好準備。要了解詳情，請參考Task6786。不要在穩(wěn)定的部分對數(shù)據(jù)庫進行修改。如果修改的話，用戶從一個穩(wěn)定版本升級到另一個會帶來重復的修改。這將會帶來嚴重的錯誤。在SQL查詢中查詢整數(shù)變量時，不要給變量加引號。例如，get_records_select(question,ca

17、tegory=$catid)是對的。get_records_select(question,category=$catid)是錯的。這會隱藏變量$catid沒有定義的地方的錯誤。安全問題(處理表單和URL數(shù)據(jù))不要依靠register_globals。每個變量必須在每個源文件里正確初始化。變量的來源必須顯而易見。初始化所有的數(shù)組和對象，即使它是空的。$a=array()或$obj=newstdClass();。不要使用optional_variable()函數(shù)，使用optional_param()函數(shù)來替代它。根據(jù)數(shù)據(jù)類型選擇正確的PARAM_XXXX值。不要使用require_variabl

18、e()函數(shù)(現(xiàn)在不推薦使用該函數(shù))，使用require_param()函數(shù)來替代它。根據(jù)數(shù)據(jù)類型選擇正確的PARAM_XXXX值。早使用data_submitted()時要小心，在使用數(shù)據(jù)前仍要對其進行清理。使用$_GET、$_POST或$_REQUEST。根據(jù)您的需要使用更合適的required_param()或optional_param()。檢查一個動作時，不要使用像if(isset($_GETsomething)這樣的代碼?？梢允褂弥T如：$something=optional_param(something,-1,PARAM_ALPHA)，并且根據(jù)它取值的范圍來判斷，如if($something=0).在所有可能的情況下，把您所有的required_param()、optional_param()和其它的變量初始化一起放在每個文件的開頭，這樣它們會