Coding

2006-10-07T10:35:26Z

Delius: /* General rules */ Added link to Developer:Output_functions

Any collaborative project needs consistency and stability to stay strong.

These '''coding guidelines''' are to provide a goal for all Moodle code to strive to. It's true that some of the older existing code falls short in a few areas, but it will all be fixed eventually. All new code definitely must adhere to these standards as closely as possible.

==General rules==

# All code files should use the .php extension.
# All template files should use the .html extension.
# All text files should use Unix-style text format (most text editors have this as an option).
# All php tags must be 'full' tags like <?php ?> ... not 'short' tags like <? ?>.
# All existing copyright notices must be retained. You can add your own if necessary.
# Each file should include the main config.php file.
# Each file should check that the user is authenticated correctly, using require_login() and isadmin(), isteacher(), iscreator() or isstudent().
# All access to databases should use the functions in ''lib/dmllib.php'' whenever possible - this allows compatibility across a wide range of databases. You should find that almost anything is possible using these functions. If you must write SQL code then make sure it is: cross-platform; restricted to specific functions within your code (usually a lib.php file); and clearly marked.
# Don't create or use global variables except for the standard $CFG, $SESSION, $THEME, $SITE, $COURSE and $USER.
# All variables should be initialised or at least tested for existence using isset() or empty() before they are used.
# All strings should be translatable - create new texts in the "lang/en_utf8" files with concise English lowercase names and retrieve them from your code using get_string() or print_string().
# All help files should be translatable - create new texts in the "lang/en_utf8/help" directory and call them using helpbutton(). If you need to update a help file:
#* with a minor change, where an old translation of the file would still make sense, then it's OK to make the change but you should notify translation AT moodle DOT org.
#* for a major change you should create a new file by adding an incrementing number (eg filename2.html) so that translators can easily see it's a new version of the file. Obviously the new code and the help index files should also be modified to point to the newest versions.
# Incoming data from the browser (sent via GET or POST) automatically has magic_quotes applied (regardless of the PHP settings) so that you can safely insert it straight into the database. All other raw data (from files, or from databases) must be escaped with addslashes() before inserting it into the database. Because this is so often done incorrectly, there is more explanation on this issue of adding and stripping slashes on a [[Developer:Slashes|separate page]].
# VERY IMPORTANT: All texts within Moodle, especially those that have come from users, should be printed using the format_text() function. This ensures that text is filtered and cleaned correctly. More information can be found on the page about [[Developer:Output_functions|output functions]].
# User actions should be logged using the [[Logs|add_to_log()]] function. These logs are used for [[Settings#Show_activity_reports|activity reports]] and [[Logs]].

==Coding style==

I know it can be a little annoying to change your style if you're used to something else, but balance that annoyance against the annoyance of all the people trying later on to make sense of Moodle code with mixed styles. There are obviously many good points for and against any style that people use, but the current style just is, so please stick to it.

1. Indenting should be consistently 4 spaces. Don't use tabs AT ALL.

2. Variable names should always be easy-to-read, meaningful lowercase English words. If you really need more than one word then run them together, but keep them short as possible. Use plural names for arrays of objects.

GOOD: $quiz
GOOD: $errorstring
GOOD: $assignments (for an array of objects)
GOOD: $i (but only in little loops)

BAD: $Quiz
BAD: $aReallyLongVariableNameWithoutAGoodReason
BAD: $error_string

3. Constants should always be in upper case, and always start with the name of the module. They should have words separated by underscores.

define("FORUM_MODE_FLATOLDEST", 1);
4. Function names should be simple English lowercase words, and start with the name of the module to avoid conflicts between modules. Words should be separated by underscores. Parameters should always have sensible defaults if possible. Note there is no space between the function name and the following (brackets).

function forum_set_display_mode($mode=0) {
global $USER, $CFG;

if ($mode) {
$USER->mode = $mode;
} else if (empty($USER->mode)) {
$USER->mode = $CFG->forum_displaymode;
}
}

5. Blocks must always be enclosed in curly braces (even if there is only one line). Moodle uses this style:

if ($quiz->attempts) {
if ($numattempts > $quiz->attempts) {
error($strtoomanyattempts, "view.php?id=$cm->id");
}
}

6. Strings should be defined using single quotes where possible, for increased speed.

$var = 'some text without any variables';
$var = "with special characters like a new line \n";
$var = 'a very, very long string with a '.$single.' variable in it';
$var = "some $text with $many variables $within it";

7. Comments should be added as much as is practical, to explain the code flow and the purpose of functions and variables.

* Every function (and class) should use the popular [http://www.phpdoc.org/ phpDoc format]. This allows code documentation to be generated automatically.
* Inline comments should use the // style, laid out neatly so that it fits among the code and lines up with it.

/**
* The description should be first, with asterisks laid out exactly
* like this example. If you want to refer to a another function,
* do it like this: {@link clean_param()}. Then, add descriptions
* for each parameter as follows.
*
* @param int $postid The PHP type is followed by the variable name
* @param array $scale The PHP type is followed by the variable name
* @param array $ratings The PHP type is followed by the variable name
* @return mixed
*/
function forum_get_ratings_mean($postid, $scale, $ratings=NULL) {
if (!$ratings) {
$ratings = array(); // Initialize the empty array
if ($rates = get_records("forum_ratings", "post", $postid)) {
// Process each rating in turn
foreach ($rates as $rate) {
....etc

8. Space should be used liberally - don't be afraid to spread things out a little to gain some clarity. Generally, there should be one space between brackets and normal statements, but no space between brackets and variables or functions:

foreach ($objects as $key => $thing) {
process($thing);
}

if ($x == $y) {
$a = $b;
} else if ($x == $z) {
$a = $c;
} else {
$a = $d;
}

9. When making a COPY of an object, always use the php5 clone() function (otherwise you may end up with just a reference to the first object). Moodle will make sure this works consistently on php4 too.

BAD: $b = $a;
GOOD: $b = clone($a);

If the thing you want to copy is not an object, but may contain objects (eg an array of objects) then use fullclone() instead.

==Database structures==

# Every table must have an auto-incrementing id field (INT10) as primary index. (see [[IdColumnReasons]])
# The main table containing instances of each module must have the same name as the module (eg widget) and contain the following minimum fields:
#* id - as described above
#* course - the id of the course that each instance belongs to
#* name - the full name of each instance of the module
# Other tables associated with a module that contain information about 'things' should be named widget_things (note the plural).
# Table and column names should avoid using [[Database reserved words|reserved words in any database]]. Please check them before creation.
# Column names should be always lowercase, simple and short, following the same rules as for variable names.
# Where possible, columns that contain a reference to the id field of another table (eg widget) should be called widgetid. (Note that this convention is newish and not followed in some older tables)
# Boolean fields should be implemented as small integer fields (eg INT4) containing 0 or 1, to allow for later expansion of values if necessary.
# Most tables should have a timemodified field (INT10) which is updated with a current timestamp obtained with the PHP time() function.
# Always define a default value for each field (and make it sensible)
# Each table name should start with the database prefix ($CFG->prefix). In a lot of cases, this is taken care of for you automatically. Also, under Postgres, the name of every index must start with the prefix too.
# In order to guarantee [[XMLDB problems#Table and column aliases - the AS keyword|cross-db compatibility]] follow these simple rules about the use of the '''AS''' keyword (only if you need table/colum aliases, of course):
#* '''Don't use''' the '''AS''' keyword for '''table aliases'''.
#* '''Do use''' the '''AS''' keyword for '''column aliases'''.
# '''Never''' create UNIQUE KEYs (constraints) at all. Instead use UNIQUE INDEXes. In the future, if we decide to add referential integrity to Moodle and we need UNIQUE KEYs they will be used, but not now. Please note that the XMLDB editor allows you to specify both XMLDB-only UNIQUE and FOREIGN constraints (and that's good, in order to have the XML well defined) but only underlying INDEXes will be generated.
# Those XMLDB-only UNIQUE KEYs (read previous point) only must be defined if such field/fields '''are going to be the target''' for some (XMLDB-only too) FOREIGN KEY. Else, create them as simple UNIQUE INDEXes.
# Tables associated '''with one block''' must follow this convention with their names: '''$CFG->prefix + "block_" + name_of_the_block + anything_else'''. For example, assuming that $CFG->prefix is 'mdl_', all the tables for the block "rss_client" must start by 'mdl_block_rss_client' (being possible to add more words at the end, i.e. 'mdl_block_rss_client_anothertable'...). This rule will be 100% enforced with Moodle 2.0, giving time to developers until then. See [http://tracker.moodle.org/browse/MDL-6786 Task 6786] for more info about this.

==Security issues (and handling form and URL data)==

# Do not rely on 'register_globals'. Every variable must be properly initialised in every code file. It must be obvious where the variable came from
# Initialise all arrays and objects, even if empty. $a = array() or $obj = new stdClass();.
# Do not use the optional_variable() function (this function is now deprecated). Use the optional_param() function instead. Pick the correct PARAM_XXXX value for the data type you expect.
# Do not use the require_variable() function (this function is now deprecated). Use the required_param() function instead. Pick the correct PARAM_XXXX value for the data type you expect.
# Use data_submitted(), with care. Data must still be cleaned before use.
# Do not use $_GET, $_POST or $_REQUEST. Use the appropriate required_param() or optional_param() appropriate to your need.
# Do not check for an action using something like if (isset($_GET['something'])). Use, e.g., $something = optional_param( 'something',-1,PARAM_INT ) and then perform proper test for it being in its expected range of values e.g., if ($something>=0) {....
# Wherever possible group all your required_param(), optional_param() and other variables initialisation at the beginning of each file to make them easy to find.
# Use 'sesskey' mechanism to protect form handling routines from attack. Basic example of use: when form is generated, include <input type="hidden" name="sesskey" value="<?php echo sesskey(); ?>" />. When you process the form check with if (!confirm_sesskey()) {error('Bad Session Key');}.
# All filenames must be 'cleaned' using the clean_filename() function, if this has not been done already by appropriate use of required_param() or optional_param()
# Any data read from the database must have addslashes() applied to it before it can be written back. A whole object of data can be hit at once with addslashes_object().
# Wherever possible, data to be stored in the database must come from POST data (from a form with method="POST") as opposed to GET data (ie, data from the URL line).
# Do not use data from $_SERVER if you can avoid it. This has portability issues.
# If it hasn't been done somewhere else, make sure all data written to the database has been through the clean_param() function using the appropriate PARAM_XXXX for the datatype.
# If you write custom SQL code, make very sure it is correct. In particular watch out for missing quotes around values. Possible SQL 'injection' exploit.
# Check all data (particularly that written to the database) in every file it is used. Do not expect or rely on it being done somewhere else.
# Blocks of code to be included should contain a definite PHP structure (e.g, a class declaration, function definition(s) etc.) - straight blocks of code promote uninitialised variable usage.

[[es:Manual de Estilo de Código]]

Filters 1.9 and before

2006-10-07T10:33:54Z

Delius: /* To create a filter */

'''Please note:''' This page contains information for developers. You may prefer to read the [[Filters (administrator)| information about filters for teachers and administrators]].

-----

'''Filters''' allow for the for the automatic transformation of entered text into different, often more complex forms. For example the titles of [[Resources]] can automatically become hyperlinks that take you to the relevant resource, URLs pointing to [[mp3]] files can become [[Flash]] controls embedded in the webpage that let you pause and rewind the audio. The possibilities are endless and there are a number of standard filters included with Moodle and many more specialized filters contributed by the community.

==To create a filter==

To create a filter that removes all occurrences of the letter "x" - we'll call it "removex":

# Create a new folder inside Moodle's /filter/ folder, called "removex"
# Create a new PHP script file inside the folder you've just created - name it "filter.php"
# Write a new PHP function in this file, called "removex_filter()" which takes two parameters - a course ID and a piece of text to be filtered - and returns the processed text.

For our example the filter.php file would look like:
<?php
function filter_removex($courseid, $text) {
return str_replace("x", "", $text);
}
?>

When trying this out, remember to make sure that you activate the filter in the [[Filters (administrator)|filters administration screen]].

Also remember that text filtering functions, when activated, will be used intensively by the server, so you should optimise the filters as far as possible (cut down on database calls etc). Moodle caches the results of filtering to help with processing speed, but it's still worth being careful about your filter design.

Filters are applied to all text that is printed with the [[Developer:Output functions|output functions]] format_text() or format_string(). One thing to keep in mind when designing the filter is that the function format_text() first applies other transformations (for example text_to_html() or replace_smilies()) before the strings are passed to your filter. The function format_string() on the other hand passes the string as it is.

==Adding a settings screen==

Moodle 1.6 added the options for filters to have their own settings screen. To do this perform the following steps:
* In the same folder as the filter create a file called '''filterconfig.html'''.
* For the parameters you want to be edited provide appropriate form fields (note you should not provide the actual form tag itself)
* The format of the field names should be '''filter_filtername_fieldname'''; where '''filtername''' is the name of the filter (ie, the name of the folder) and '''fieldname''' the name of the field ('''filter''' is the actual word ''filter''). The field will be created as a config variable, so you can display the current value with '''$CFG->filter_filtername_fieldname. Example:

<textarea type="text" name="filter_censor_badwords" cols="60" rows="10">
<?php echo "$CFG->filter_censor_badwords"; ?>
</textarea>

* you will need to pay attention to setting the default value for these parameters. As filters are pluggable it is best to do it in the filter, but bear in mind that you must check the default both in the settings screen and in the filter itself as you cannot know which will be called first. Some filters with extensive lists of parameters call an external script for this purpose (see, for example, the multimedia filter)

==See also==

* [[Filters schema]] - a page containing some ideas and thoughts about modifications to the filters system
* [[Filters (administrator)]]

[[Category:Filter]]

Output functions

2006-10-07T10:32:41Z

Delius: Output functions moved to Developer:Output functions

This page tries to explain a bit how dynamic data should be sent from Moodle to the browser in a organised and standard way. Obviously it's possible to have your own output methods but, thinking that you are going to share your code (yep, this is an OpenSource project!) and in the collaborative way we try to build and maintain the system every day, it would be really better to follow the basic guidelines explained below.

By using them you will be helping to have better, more secure and readable code. Spend some minutes trying to understand them, please!

Of course, this functions can be discused, modified and new functions can arrive if there are some good reasons for it. Just discuss it in the [http://moodle.org/mod/forum/view.php?id=55 General developer forum] at [http://moodle.org moodle.org].

For each of the functions below we'll try to explain when they should be used, commenting the most important parameters supported and their meaning. Let's review them!

=== p() and s() ===

function s($var, $strip=false) and function p($var, $strip=false)

This functions share the same code so they will be explained together. The only difference is that s() returns the string while p() prints it directly.

This functions should be used to:

* print all the '''values of form fields''' like <nowiki><input></nowiki> or <nowiki><textarea></nowiki> tags.
* to '''show plain (non html) text''' that have been introduced by the user (search string, quiz responses...).
* in general, all the '''dynamic data, not being html''', that doesn't need to be cleaned nor processed by filters

It is important not to use these functions for strings that contain html markup.

The functions replace certain characters that would have special meaning in html ( <, >, ", ', and &) by html entities so that they are displayed as intended. Note that even though the value of form fields printed with p() will have these characters converted to html entities, the submitted values will contain the original characters again.

The key parameter for this function is:

* '''strip''': it decides if we want to strip slashes from the string or no. By default it's 'false' so no strip will be performed. We should set such parameter to 'true' only when data to be processed isn't coming from database but from http requests (forms, links...).

=== format_text() ===

function format_text($text, $format=FORMAT_MOODLE, $options=NULL, $courseid=NULL )

This function should be used to:

* print '''any html/plain/markdown/moodle text''', needing any of the features below. Mainly used for long strings like posts, answers, glossary items...

Note that this function is really '''heavy''' because it supports '''cleaning''' of dangerous contents, delegates process to enabled '''filter'''s, supports different '''formats''' of text (HTML, PLAIN, MARKDOWN, MOODLE) and performs a lot of '''automatic conversions''' like adding smilies, build links, so it's a really heavy function. Also, it includes one strong '''cache mechanism''' (DB based) that will alleviate the server from a lot of work processing the same texts time and again.

Some interesting parameters for this function are:

* '''format''': To tell the function about how the data has been entered. It defaults to FORMAT_MOODLE that is a cool format to process plain text because it features automatic link conversion, smilies and good conversion to html output. Other formats are FORMAT_HTML, FORMAT_PLAIN, FORMAT_MARKDOW.

* '''options''': Here we can specify how we want the process to be performed. You only need to define them if they are different from the default value assumed. Main options are:
**'''options->noclean''': To decide if we want to skip the clean of text, '''un-protecting us''' from attacks and other security flaws (defaults to false, so protection is enabled. You '''shouldn't set it to true never''' unless you are 200% sure that only controlled users can edit it (mainly admins). '''Never use it for general text places''' (posts...) or you will be, sooner or later, attacked! Note that this option is ignored for FORMAT_PLAIN, the text is never cleaned.
**'''options->filter''': To decide if you want to allow filters to process the text (defaults to true). This is ignored by FORMAT_PLAIN for which filters are never applied.
**'''options->smiley''': To decide if we want automatic conversion of smilies to images (defaults to true). This is ignored by FORMAT_PLAIN for which smileys are never converted.
**'''options->para''': To decide if you want every paragraph automatically enclosed between html paragraph tags (<nowiki><p>...</p></nowiki>) (defaults to true). This option only applies to FORMAT_MOODLE.
**'''options->newlines''': To decide if linefeeds in text should be converted to html newlines (<nowiki><br /></nowiki>) (defaults to true). This option only applies to FORMAT_MOODLE.
* '''courseid''': This parameter should be passed always to help filters to know how they should work. This parameter will become less and less important Moodle was 100% of the current course using some session or global variable (it's one work in progress just now) but, for now, it's recommended to set it always in the function call.

=== format_string() ===

function format_string ($string, $striplinks = false, $courseid=NULL )

This function should be used to:

* print '''short strings (non html) that need filter processing''' (activity titles, post subjects, glossary concepts...).

Please note that this function is basically one stripped version of the full format_text() function detailed above and '''it doesn't offer any of it options nor protections'''. It simply filters the strings and return the result, so we must ensure that text being processed has been properly cleaned at input time, using the proper xxx_param() functions.

Some interesting parameters for this function are:

* '''striplinks''': To decide if, after the text has been processed by filters, we must delete any link from the result test. Used when we want to show the text inside menus, page titles... (defaults to false).
* '''courseid''': This parameter should be passed always to help filters to know how they should work. This parameter will become less and less important Moodle was 100% of the current course using some session or global variable (it's one work in progress just now) but, for now, it's recommended to set it always in the function call.

=== print_textarea() ===

function print_textarea($usehtmleditor, $rows, $cols, $width,
$height, $name, $value=<nowiki>''</nowiki>, $courseid=0, $return=false)

This function should be used to:

* display <nowiki><textarea></nowiki> fields when we want to allow users (based in their preferences and browser capabilities) '''to use the visual HTML editor''' instead of one standard 'plain' area.

Some interesting parameters for this function are:

* '''usehtmleditor''': to decide if the HTML editor must be showed. The value of this parameter must be calculated by the can_use_html_editor() function.
* '''rows, cols''': to be applied it the standard textarea is showed.
* '''width, height''': to be applied if the HTML editor is used.
* '''name''': the name of the field that will contain the text once the form was submitted.
* '''value''': the initial value of the textarea.
* '''courseid''': This parameter should be passed always to help the editor to know where it is work. This parameter will become less and less important Moodle was 100% of the current course using some session or global variable (it's one work in progress just now) but, for now, it's recommended to set it always in the function call.
* '''return''': to decide if the generated html code must be returned to the caller (true) or printed directly (false). Defaults to false.

Coding

2006-10-07T10:29:11Z

Delius: /* General rules */ Added link to pages about slashes

Any collaborative project needs consistency and stability to stay strong.

These '''coding guidelines''' are to provide a goal for all Moodle code to strive to. It's true that some of the older existing code falls short in a few areas, but it will all be fixed eventually. All new code definitely must adhere to these standards as closely as possible.

==General rules==

# All code files should use the .php extension.
# All template files should use the .html extension.
# All text files should use Unix-style text format (most text editors have this as an option).
# All php tags must be 'full' tags like <?php ?> ... not 'short' tags like <? ?>.
# All existing copyright notices must be retained. You can add your own if necessary.
# Each file should include the main config.php file.
# Each file should check that the user is authenticated correctly, using require_login() and isadmin(), isteacher(), iscreator() or isstudent().
# All access to databases should use the functions in ''lib/dmllib.php'' whenever possible - this allows compatibility across a wide range of databases. You should find that almost anything is possible using these functions. If you must write SQL code then make sure it is: cross-platform; restricted to specific functions within your code (usually a lib.php file); and clearly marked.
# Don't create or use global variables except for the standard $CFG, $SESSION, $THEME, $SITE, $COURSE and $USER.
# All variables should be initialised or at least tested for existence using isset() or empty() before they are used.
# All strings should be translatable - create new texts in the "lang/en_utf8" files with concise English lowercase names and retrieve them from your code using get_string() or print_string().
# All help files should be translatable - create new texts in the "lang/en_utf8/help" directory and call them using helpbutton(). If you need to update a help file:
#* with a minor change, where an old translation of the file would still make sense, then it's OK to make the change but you should notify translation AT moodle DOT org.
#* for a major change you should create a new file by adding an incrementing number (eg filename2.html) so that translators can easily see it's a new version of the file. Obviously the new code and the help index files should also be modified to point to the newest versions.
# Incoming data from the browser (sent via GET or POST) automatically has magic_quotes applied (regardless of the PHP settings) so that you can safely insert it straight into the database. All other raw data (from files, or from databases) must be escaped with addslashes() before inserting it into the database. Because this is so often done incorrectly, there is more explanation on this issue of adding and stripping slashes on a [[Developer:Slashes|separate page]].
# VERY IMPORTANT: All texts within Moodle, especially those that have come from users, should be printed using the format_text() function. This ensures that text is filtered and cleaned correctly.
# User actions should be logged using the [[Logs|add_to_log()]] function. These logs are used for [[Settings#Show_activity_reports|activity reports]] and [[Logs]].

==Coding style==

I know it can be a little annoying to change your style if you're used to something else, but balance that annoyance against the annoyance of all the people trying later on to make sense of Moodle code with mixed styles. There are obviously many good points for and against any style that people use, but the current style just is, so please stick to it.

1. Indenting should be consistently 4 spaces. Don't use tabs AT ALL.

2. Variable names should always be easy-to-read, meaningful lowercase English words. If you really need more than one word then run them together, but keep them short as possible. Use plural names for arrays of objects.

GOOD: $quiz
GOOD: $errorstring
GOOD: $assignments (for an array of objects)
GOOD: $i (but only in little loops)

BAD: $Quiz
BAD: $aReallyLongVariableNameWithoutAGoodReason
BAD: $error_string

3. Constants should always be in upper case, and always start with the name of the module. They should have words separated by underscores.

define("FORUM_MODE_FLATOLDEST", 1);
4. Function names should be simple English lowercase words, and start with the name of the module to avoid conflicts between modules. Words should be separated by underscores. Parameters should always have sensible defaults if possible. Note there is no space between the function name and the following (brackets).

function forum_set_display_mode($mode=0) {
global $USER, $CFG;

if ($mode) {
$USER->mode = $mode;
} else if (empty($USER->mode)) {
$USER->mode = $CFG->forum_displaymode;
}
}

5. Blocks must always be enclosed in curly braces (even if there is only one line). Moodle uses this style:

if ($quiz->attempts) {
if ($numattempts > $quiz->attempts) {
error($strtoomanyattempts, "view.php?id=$cm->id");
}
}

6. Strings should be defined using single quotes where possible, for increased speed.

$var = 'some text without any variables';
$var = "with special characters like a new line \n";
$var = 'a very, very long string with a '.$single.' variable in it';
$var = "some $text with $many variables $within it";

7. Comments should be added as much as is practical, to explain the code flow and the purpose of functions and variables.

* Every function (and class) should use the popular [http://www.phpdoc.org/ phpDoc format]. This allows code documentation to be generated automatically.
* Inline comments should use the // style, laid out neatly so that it fits among the code and lines up with it.

/**
* The description should be first, with asterisks laid out exactly
* like this example. If you want to refer to a another function,
* do it like this: {@link clean_param()}. Then, add descriptions
* for each parameter as follows.
*
* @param int $postid The PHP type is followed by the variable name
* @param array $scale The PHP type is followed by the variable name
* @param array $ratings The PHP type is followed by the variable name
* @return mixed
*/
function forum_get_ratings_mean($postid, $scale, $ratings=NULL) {
if (!$ratings) {
$ratings = array(); // Initialize the empty array
if ($rates = get_records("forum_ratings", "post", $postid)) {
// Process each rating in turn
foreach ($rates as $rate) {
....etc

8. Space should be used liberally - don't be afraid to spread things out a little to gain some clarity. Generally, there should be one space between brackets and normal statements, but no space between brackets and variables or functions:

foreach ($objects as $key => $thing) {
process($thing);
}

if ($x == $y) {
$a = $b;
} else if ($x == $z) {
$a = $c;
} else {
$a = $d;
}

9. When making a COPY of an object, always use the php5 clone() function (otherwise you may end up with just a reference to the first object). Moodle will make sure this works consistently on php4 too.

BAD: $b = $a;
GOOD: $b = clone($a);

If the thing you want to copy is not an object, but may contain objects (eg an array of objects) then use fullclone() instead.

==Database structures==

# Every table must have an auto-incrementing id field (INT10) as primary index. (see [[IdColumnReasons]])
# The main table containing instances of each module must have the same name as the module (eg widget) and contain the following minimum fields:
#* id - as described above
#* course - the id of the course that each instance belongs to
#* name - the full name of each instance of the module
# Other tables associated with a module that contain information about 'things' should be named widget_things (note the plural).
# Table and column names should avoid using [[Database reserved words|reserved words in any database]]. Please check them before creation.
# Column names should be always lowercase, simple and short, following the same rules as for variable names.
# Where possible, columns that contain a reference to the id field of another table (eg widget) should be called widgetid. (Note that this convention is newish and not followed in some older tables)
# Boolean fields should be implemented as small integer fields (eg INT4) containing 0 or 1, to allow for later expansion of values if necessary.
# Most tables should have a timemodified field (INT10) which is updated with a current timestamp obtained with the PHP time() function.
# Always define a default value for each field (and make it sensible)
# Each table name should start with the database prefix ($CFG->prefix). In a lot of cases, this is taken care of for you automatically. Also, under Postgres, the name of every index must start with the prefix too.
# In order to guarantee [[XMLDB problems#Table and column aliases - the AS keyword|cross-db compatibility]] follow these simple rules about the use of the '''AS''' keyword (only if you need table/colum aliases, of course):
#* '''Don't use''' the '''AS''' keyword for '''table aliases'''.
#* '''Do use''' the '''AS''' keyword for '''column aliases'''.
# '''Never''' create UNIQUE KEYs (constraints) at all. Instead use UNIQUE INDEXes. In the future, if we decide to add referential integrity to Moodle and we need UNIQUE KEYs they will be used, but not now. Please note that the XMLDB editor allows you to specify both XMLDB-only UNIQUE and FOREIGN constraints (and that's good, in order to have the XML well defined) but only underlying INDEXes will be generated.
# Those XMLDB-only UNIQUE KEYs (read previous point) only must be defined if such field/fields '''are going to be the target''' for some (XMLDB-only too) FOREIGN KEY. Else, create them as simple UNIQUE INDEXes.
# Tables associated '''with one block''' must follow this convention with their names: '''$CFG->prefix + "block_" + name_of_the_block + anything_else'''. For example, assuming that $CFG->prefix is 'mdl_', all the tables for the block "rss_client" must start by 'mdl_block_rss_client' (being possible to add more words at the end, i.e. 'mdl_block_rss_client_anothertable'...). This rule will be 100% enforced with Moodle 2.0, giving time to developers until then. See [http://tracker.moodle.org/browse/MDL-6786 Task 6786] for more info about this.

==Security issues (and handling form and URL data)==

# Do not rely on 'register_globals'. Every variable must be properly initialised in every code file. It must be obvious where the variable came from
# Initialise all arrays and objects, even if empty. $a = array() or $obj = new stdClass();.
# Do not use the optional_variable() function (this function is now deprecated). Use the optional_param() function instead. Pick the correct PARAM_XXXX value for the data type you expect.
# Do not use the require_variable() function (this function is now deprecated). Use the required_param() function instead. Pick the correct PARAM_XXXX value for the data type you expect.
# Use data_submitted(), with care. Data must still be cleaned before use.
# Do not use $_GET, $_POST or $_REQUEST. Use the appropriate required_param() or optional_param() appropriate to your need.
# Do not check for an action using something like if (isset($_GET['something'])). Use, e.g., $something = optional_param( 'something',-1,PARAM_INT ) and then perform proper test for it being in its expected range of values e.g., if ($something>=0) {....
# Wherever possible group all your required_param(), optional_param() and other variables initialisation at the beginning of each file to make them easy to find.
# Use 'sesskey' mechanism to protect form handling routines from attack. Basic example of use: when form is generated, include <input type="hidden" name="sesskey" value="<?php echo sesskey(); ?>" />. When you process the form check with if (!confirm_sesskey()) {error('Bad Session Key');}.
# All filenames must be 'cleaned' using the clean_filename() function, if this has not been done already by appropriate use of required_param() or optional_param()
# Any data read from the database must have addslashes() applied to it before it can be written back. A whole object of data can be hit at once with addslashes_object().
# Wherever possible, data to be stored in the database must come from POST data (from a form with method="POST") as opposed to GET data (ie, data from the URL line).
# Do not use data from $_SERVER if you can avoid it. This has portability issues.
# If it hasn't been done somewhere else, make sure all data written to the database has been through the clean_param() function using the appropriate PARAM_XXXX for the datatype.
# If you write custom SQL code, make very sure it is correct. In particular watch out for missing quotes around values. Possible SQL 'injection' exploit.
# Check all data (particularly that written to the database) in every file it is used. Do not expect or rely on it being done somewhere else.
# Blocks of code to be included should contain a definite PHP structure (e.g, a class declaration, function definition(s) etc.) - straight blocks of code promote uninitialised variable usage.

[[es:Manual de Estilo de Código]]

Developer documentation

2006-09-29T20:38:57Z

Delius: /* Resources and tools */

<p class="note">'''Note:''' New developer documentation pages should be added to the ''Development namespace'' by typing <code>Development:</code> before the new page name i.e. <code><nowiki>[[New page name]]</nowiki></code>.</p>

==Guidelines==
The following guidelines are crucial reading for anyone wanting to contribute to the Moodle code base:
*[[Coding|Coding guidelines]] have to be followed by all Moodle developers
*[[Moodle architecture]] spells out the basic design goals behind Moodle
*[[Interface guidelines]] aim to provide a common feel to the Moodle user interface
*[[CVS (developer)|Moodle CVS for developers]] explains how to work with the Moodle code in CVS
*[[Unit tests]] explains how to run the unit tests, and how to write new test cases.
*[[Tracker]] explains the Moodle Tracker for keeping track of bugs, issues, feature requests etc

== Resources and tools ==

*[[Developer FAQ]] - frequently asked questions, especially useful for newcomers to Moodle
*[http://tracker.moodle.org/ Moodle tracker] - bug reports, feature requests and other tracked issues
*[http://moodle.org/mod/forum/view.php?id=55 General developer forum]
*[http://moodle.cvs.sourceforge.net/moodle/moodle/ CVS code] - browse the Moodle code via the web
*[http://moodle.org/xref/nav.html?index.html Cross reference] - phpxref output for browsing Moodle source code
*[http://phpdocs.moodle.org/ Moodle PHP doc reference] - automatically generated documentation
*[http://moodle.org/course/view.php?id=5#4 Development news and discussion] section of Using Moodle course
*[http://developer.yahoo.com/yui YUI documentation] - YUI is the official AJAX library in moodle.
*[[Setting up Eclipse for Moodle development]] - Eclipse is a great editor to use for php development, if you can work out how to set it up.
*[[Unmerged files]] - changes on the stable branch in CVS that have not been merged to HEAD

==How you can contribute==

The M in Moodle stands for 'Modular'. There are many different types of components that you can contribute that can be plugged into Moodle to provide additional functionality. When you have developed a new component please publish it in the [http://moodle.org/mod/data/view.php?id=6009 database of Moodle modules and plugins]. The following types of plugins currently exist (in alphabetical order):
*[[Modules (developer)|Activity modules]]
*[[Assignment types]]
*[[Authentication|Authentication methods]]
*[[Blocks Howto|Blocks]]
*[[Course formats]]
*[[Database fields (developer)|Database fields]]
*[[Database presets]]
*[[Enrolment plugins (developer)|Enrolment plugins]]
*[[Filters (developer)|Filters]]
*[[Question_engine]]
*[[Question import/export formats]]
*[[Question bank|Question bank teacher docs]]
*[[Question_engine#Question_types|Question types developper docs]]
*[[Quiz reports]]
*[[Resource types]]
*[[SSO plugins]]

There are also ways you can contribute that don't involve PHP programming:
*[[Themes]]
*[[Translation]]
*[[Database Schemas|Database schemas]]

You can also help a lot by
*[[Tests|Testing]]
*[[Tracker|Participating in the bug tracker]]

==Plans for the future==
Ideas for and details of planned future features of Moodle are initially discussed on the forums in the [http://moodle.org/course/view.php?id=5 Using Moodle] course at moodle.org. That developer discussions are intermixed with user discussions in the same forums may seem strange at first but is one of the reasons for the success of Moodle. It is important that both end-users and developers discuss the future features together.

Once ideas begin to crystalize on the forums they can be summarized in this wiki, either as part of the [[Roadmap]] or in the form of [[Developer notes]]. These pages then form the basis for further discussion in the forums.
*[[Roadmap]]
*[[Developer notes]]
*[[Student projects]]
*[[Developer conference|Developer conferences]]

==Documentation for core components==
This section is for documentation of specific components of the existing core Moodle code. Discussion of components that are under discussion or in development can be found in the [[Developer notes]] or on the [[Roadmap]].

*[[Migration to Role-driven model|Migration to Role-driven model]] @ v[[1.7]]
*[[UTF-8 migration|Migration to UTF-8]] @ v[[:Category:Moodle 1.6|1.6]]
*[[Question engine]]
*[[Quiz developer docs|Quiz module]]
*[[SCORM schema|SCORM module 1.5 schema]]
*[[Authentication API]]
*[[Stats package]]
*[[Email processing]]
*[[Cookieless Sessions]]

==Documentation for contributed code==
Many Moodle users contribute code for the benefit of other Moodle users. This can take the form of new activity modules, blocks, themes, resource plug-ins, assignment plug-ins, question type plug-ins, question import/export formats, quiz report plug-ins, course formats, ... This code is initially posted on the forums in the [http://moodle.org/course/view.php?id=5 Using Moodle] course and then often go into the [http://cvs.sourceforge.net/viewcvs.py/moodle/contrib/ contrib area] of the Moodle [[CVS]] repository. When you have developed a new component please publish it in the [http://moodle.org/mod/data/view.php?id=6009 database of Moodle modules and plugins]. Developer documentation for these components should be listed here.

==See also==
*[http://security.moodle.org/ Moodle Security Centre]
*[http://moodle.com/partners/ Moodle Partners] - providers of custom Moodle development services

[[es:Documentación para Desarrolladores]]
[[fr:Documentation développeur]]
[[zh:开发者文档]]

Development:Developer FAQ

2006-09-29T20:38:09Z

Delius: Mention that datalib.php has moved to dmllib.php

{{FAQ}}

==Help for new coders==

===Where can "newbies" to Moodle get help?===

The [http://moodle.org/mod/forum/view.php?f=33 General developer forum]! Feel free to ask any question, no matter how basic or advanced. Many people ask different levels of question every day, and the community is generally welcoming and quick to respond.

==Moodle's database==

===Where can I see a schema for the structure of the Moodle database?===

When installing Moodle, the database tables are generated and updated by various db-handling scripts located in various places. There is no canonical schema representation, although the [[Coding#Database_structures | coding guidelines for database structure]] give an outline of the general approach.

The reason that the database information isn't stored in one place is because of Moodle's '''modular structure'''. Each activity module, for example, comes as a folder with script files inside. If the module needs to store information in the database, it must include scripts in a "db" subfolder which define and update the database structure.

==How to get/set information when writing new Moodle code==

===How do I find out the currently-logged-on user?===

The global object $USER, which contains the numeric $USER->id among other things.

===How do I find out the current course?===
The global object $COURSE, which contains the numeric $COURSE->id

===How do I insert/retrieve records in the database, without creating my own database connections?===

Always use the "datalib" functions, such as insert_record() or get_record(). Since Moodle 1.7 these are found in lib/dmllib.php. Using these functions helps with database abstraction (e.g. running on either MySQL or Postgres) as well as maintaining a single database connection. Moodle uses ADODB for database abstraction.

Look at [http://moodle.sourceforge.net/dhawes-phpdoc/moodlecore/_lib_datalib_php.html the documentation for datalib.php] for the list of functions and details of use.

===How do I get/set configuration settings?===

To get config values you would typically access the global $CFG object directly, which is automatically created by the core Moodle scripts. To set these "main" config values use set_config($name, $value). The values are stored in the Moodle "config" database table, but these functions take care of cacheing on your behalf, so you should always use these rather than fetching the records directly.

There is also a second table of config settings specifically for plugins ("config_plugin"). These are not automatically loaded into the $CFG object, so to fetch these you would use get_config($plugin, $name). To set them use set_config($name, $value, $plugin).

[[Category: Developer]]
[[Category: FAQ]]

[[es:FAQ Desarrollador]]

2006-04-12T21:06:33Z

Delius: /* format_text() */ explained scope of options

Filters 1.9 and before

2006-04-12T21:02:35Z

Delius: /* To create a filter */

Filters 1.9 and before

2006-04-12T20:53:26Z

Delius: /* To create a filter */

Output functions

2006-04-12T20:44:25Z

Delius: /* p() and s() */

This page tries to explain a bit how dynamic data should be sent from Moodle to the browser in a organised and standard way. Obviously it's possible to have your own output methods but, thinking that you are going to share your code (yep, this is an OpenSource project!) and in the collaborative way we try to build and maintain the system every day, it would be really better to follow the basic guidelines explained below.

By using them you will be helping to have better, more secure and readable code. Spend some minutes trying to understand them, please!

Of course, this functions can be discused, modified and new functions can arrive if there are some good reasons for it. Just discuss it in the [http://moodle.org/mod/forum/view.php?id=55 General developer forum] at [http://moodle.org moodle.org].

For each of the functions below we'll try to explain when they should be used, commenting the most important parameters supported and their meaning. Let's review them!

=== p() and s() ===

function s($var, $strip=false) and function p($var, $strip=false)

This functions share the same code so they will be explained together. The only difference is that s() returns the string while p() prints it directly.

This functions should be used to:

* print all the '''values of form fields''' like <nowiki><input></nowiki> or <nowiki><textarea></nowiki> tags.
* to '''show plain (non html) text''' that have been introduced by the user (search string, quiz responses...).
* in general, all the '''dynamic data, not being html''', that doesn't need to be cleaned nor processed by filters

It is important not to use these functions for strings that contain html markup.

The functions replace certain characters that would have special meaning in html ( <, >, ", ', and &) by html entities so that they are displayed as intended. Note that even though the value of form fields printed with p() will have these characters converted to html entities, the submitted values will contain the original characters again.

The key parameter for this function is:

* '''strip''': it decides if we want to strip slashes from the string or no. By default it's 'false' so no strip will be performed. We should set such parameter to 'true' only when data to be processed isn't coming from database but from http requests (forms, links...).

=== format_text() ===

function format_text($text, $format=FORMAT_MOODLE, $options=NULL, $courseid=NULL )

This function should be used to:

* print '''any html/plain/markdown/moodle text''', needing any of the features below. Mainly used for long strings like posts, answers, glossary items...

Note that this function is really '''heavy''' because it supports '''cleaning''' of dangerous contents, delegates process to enabled '''filter'''s, supports different '''formats''' of text (HTML, PLAIN, MARKDOWN, MOODLE) and performs a lot of '''automatic conversions''' like adding smilies, build links, so it's a really heavy function. Also, it includes one strong '''cache mechanism''' (DB based) that will alleviate the server from a lot of work processing the same texts time and again.

Some interesting parameters for this function are:

* '''format''': To tell the function about how the data has been entered. It defaults to FORMAT_MOODLE that is a cool format to process plain text because it features automatic link conversion, smilies and good conversion to html output. Other formats are FORMAT_HTML, FORMAT_PLAIN, FORMAT_MARKDOW.

* '''options''': Here we can specify how we want the process to be performed. You only need to define them if they are different from the default value assumed. Main options are:
**'''options->noclean''': To decide if we want to skip the clean of text, '''un-protecting us''' from attacks and other security flaws (defaults to false, so protection is enabled. You '''shouldn't set it to true never''' unless you are 200% sure that only controlled users can edit it (mainly admins). '''Never use it for general text places''' (posts...) or you will be, sooner or later, attacked!
**'''options->filter''': To decide if you want to allow filters to process the text (defaults to true).
**'''options->smiley''': To decide if we want automatic conversion of smilies to images (defaults to true).
**'''options->para''': To decide if you want every paragraph automatically enclosed between html paragraph tags (<nowiki><p>...</p></nowiki>) (defaults to true).
**'''options->newlines''': To decide if linefeeds in text should be converted to html newlines (<nowiki><br /></nowiki>) (defaults to true).
* '''courseid''': This parameter should be passed always to help filters to know how they should work. This parameter will become less and less important Moodle was 100% of the current course using some session or global variable (it's one work in progress just now) but, for now, it's recommended to set it always in the function call.

=== format_string() ===

function format_string ($string, $striplinks = false, $courseid=NULL )

This function should be used to:

* print '''short strings (non html) that need filter processing''' (activity titles, post subjects, glossary concepts...).

Please note that this function is basically one stripped version of the full format_text() function detailed above and '''it doesn't offer any of it options nor protections'''. It simply filters the strings and return the result, so we must ensure that text being processed has been properly cleaned at input time, using the proper xxx_param() functions.

Some interesting parameters for this function are:

* '''striplinks''': To decide if, after the text has been processed by filters, we must delete any link from the result test. Used when we want to show the text inside menus, page titles... (defaults to false).
* '''courseid''': This parameter should be passed always to help filters to know how they should work. This parameter will become less and less important Moodle was 100% of the current course using some session or global variable (it's one work in progress just now) but, for now, it's recommended to set it always in the function call.

=== print_textarea() ===

function print_textarea($usehtmleditor, $rows, $cols, $width,
$height, $name, $value=<nowiki>''</nowiki>, $courseid=0, $return=false)

This function should be used to:

* display <nowiki><textarea></nowiki> fields when we want to allow users (based in their preferences and browser capabilities) '''to use the visual HTML editor''' instead of one standard 'plain' area.

Some interesting parameters for this function are:

* '''usehtmleditor''': to decide if the HTML editor must be showed. The value of this parameter must be calculated by the can_use_html_editor() function.
* '''rows, cols''': to be applied it the standard textarea is showed.
* '''width, height''': to be applied if the HTML editor is used.
* '''name''': the name of the field that will contain the text once the form was submitted.
* '''value''': the initial value of the textarea.
* '''courseid''': This parameter should be passed always to help the editor to know where it is work. This parameter will become less and less important Moodle was 100% of the current course using some session or global variable (it's one work in progress just now) but, for now, it's recommended to set it always in the function call.
* '''return''': to decide if the generated html code must be returned to the caller (true) or printed directly (false). Defaults to false.

Output functions

2006-04-12T20:27:50Z

Delius: /* p() and s() */

This page tries to explain a bit how dynamic data should be sent from Moodle to the browser in a organised and standard way. Obviously it's possible to have your own output methods but, thinking that you are going to share your code (yep, this is an OpenSource project!) and in the collaborative way we try to build and maintain the system every day, it would be really better to follow the basic guidelines explained below.

By using them you will be helping to have better, more secure and readable code. Spend some minutes trying to understand them, please!

Of course, this functions can be discused, modified and new functions can arrive if there are some good reasons for it. Just discuss it in the [http://moodle.org/mod/forum/view.php?id=55 General developer forum] at [http://moodle.org moodle.org].

For each of the functions below we'll try to explain when they should be used, commenting the most important parameters supported and their meaning. Let's review them!

=== p() and s() ===

function s($var, $strip=false) and function p($var, $strip=false)

This functions share the same code so they will be explained together. The only difference is that s() returns the string while p() prints it directly.

This functions should be used to:

* print all the '''values of form fields''' like <nowiki><input></nowiki> or <nowiki><textarea></nowiki> tags.
* to '''show plain (non html) text''' that have been introduced by the user (search string, quiz responses...).
* in general, all the '''dynamic data, not being html''', that doesn't need to be cleaned nor processed by filters

It is important not to use these functions for strings that contain html markup.

The functions replaces certain characters that would have special meaning in html ( <, >, ", ', and &) by html entities so that they are displayed as intended.

The key parameter for this function is:

* '''strip''': it decides if we want to strip slashes from the string or no. By default it's 'false' so no strip will be performed. We should set such parameter to 'true' only when data to be processed isn't coming from database but from http requests (forms, links...).

=== format_text() ===

function format_text($text, $format=FORMAT_MOODLE, $options=NULL, $courseid=NULL )

This function should be used to:

* print '''any html/plain/markdown/moodle text''', needing any of the features below. Mainly used for long strings like posts, answers, glossary items...

Note that this function is really '''heavy''' because it supports '''cleaning''' of dangerous contents, delegates process to enabled '''filter'''s, supports different '''formats''' of text (HTML, PLAIN, MARKDOWN, MOODLE) and performs a lot of '''automatic conversions''' like adding smilies, build links, so it's a really heavy function. Also, it includes one strong '''cache mechanism''' (DB based) that will alleviate the server from a lot of work processing the same texts time and again.

Some interesting parameters for this function are:

* '''format''': To tell the function about how the data has been entered. It defaults to FORMAT_MOODLE that is a cool format to process plain text because it features automatic link conversion, smilies and good conversion to html output. Other formats are FORMAT_HTML, FORMAT_PLAIN, FORMAT_MARKDOW.

* '''options''': Here we can specify how we want the process to be performed. You only need to define them if they are different from the default value assumed. Main options are:
**'''options->noclean''': To decide if we want to skip the clean of text, '''un-protecting us''' from attacks and other security flaws (defaults to false, so protection is enabled. You '''shouldn't set it to true never''' unless you are 200% sure that only controlled users can edit it (mainly admins). '''Never use it for general text places''' (posts...) or you will be, sooner or later, attacked!
**'''options->filter''': To decide if you want to allow filters to process the text (defaults to true).
**'''options->smiley''': To decide if we want automatic conversion of smilies to images (defaults to true).
**'''options->para''': To decide if you want every paragraph automatically enclosed between html paragraph tags (<nowiki><p>...</p></nowiki>) (defaults to true).
**'''options->newlines''': To decide if linefeeds in text should be converted to html newlines (<nowiki><br /></nowiki>) (defaults to true).
* '''courseid''': This parameter should be passed always to help filters to know how they should work. This parameter will become less and less important Moodle was 100% of the current course using some session or global variable (it's one work in progress just now) but, for now, it's recommended to set it always in the function call.

=== format_string() ===

function format_string ($string, $striplinks = false, $courseid=NULL )

This function should be used to:

* print '''short strings (non html) that need filter processing''' (activity titles, post subjects, glossary concepts...).

Please note that this function is basically one stripped version of the full format_text() function detailed above and '''it doesn't offer any of it options nor protections'''. It simply filters the strings and return the result, so we must ensure that text being processed has been properly cleaned at input time, using the proper xxx_param() functions.

Some interesting parameters for this function are:

* '''striplinks''': To decide if, after the text has been processed by filters, we must delete any link from the result test. Used when we want to show the text inside menus, page titles... (defaults to false).
* '''courseid''': This parameter should be passed always to help filters to know how they should work. This parameter will become less and less important Moodle was 100% of the current course using some session or global variable (it's one work in progress just now) but, for now, it's recommended to set it always in the function call.

=== print_textarea() ===

function print_textarea($usehtmleditor, $rows, $cols, $width,
$height, $name, $value=<nowiki>''</nowiki>, $courseid=0, $return=false)

This function should be used to:

* display <nowiki><textarea></nowiki> fields when we want to allow users (based in their preferences and browser capabilities) '''to use the visual HTML editor''' instead of one standard 'plain' area.

Some interesting parameters for this function are:

* '''usehtmleditor''': to decide if the HTML editor must be showed. The value of this parameter must be calculated by the can_use_html_editor() function.
* '''rows, cols''': to be applied it the standard textarea is showed.
* '''width, height''': to be applied if the HTML editor is used.
* '''name''': the name of the field that will contain the text once the form was submitted.
* '''value''': the initial value of the textarea.
* '''courseid''': This parameter should be passed always to help the editor to know where it is work. This parameter will become less and less important Moodle was 100% of the current course using some session or global variable (it's one work in progress just now) but, for now, it's recommended to set it always in the function call.
* '''return''': to decide if the generated html code must be returned to the caller (true) or printed directly (false). Defaults to false.

Coding

2006-04-10T16:02:19Z

Delius: /* General rules */ added rule about logging

Any collaborative project needs consistency and stability to stay strong.

These '''coding guidelines''' are to provide a goal for all Moodle code to strive to. It's true that some of the older existing code falls short in a few areas, but it will all be fixed eventually. All new code definitely must adhere to these standards as closely as possible.

==General rules==

# All code files should use the .php extension.
# All template files should use the .html extension.
# All text files should use Unix-style text format (most text editors have this as an option).
# All php tags must be 'full' tags like <?php ?> ... not 'short' tags like <? ?>.
# All existing copyright notices must be retained. You can add your own if necessary.
# Each file should include the main config.php file.
# Each file should check that the user is authenticated correctly, using require_login() and isadmin(), isteacher(), iscreator() or isstudent().
# All access to databases should use the functions in ''lib/datalib.php'' whenever possible - this allows compatibility across a wide range of databases. You should find that almost anything is possible using these functions. If you must write SQL code then make sure it is: cross-platform; restricted to specific functions within your code (usually a lib.php file); and clearly marked.
# Don't create or use global variables except for the standard $CFG, $SESSION, $THEME and $USER.
# All variables should be initialised or at least tested for existence using isset() or empty() before they are used.
# All strings should be translatable - create new texts in the "lang/en" files with concise English lowercase names and retrieve them from your code using get_string() or print_string().
# All help files should be translatable - create new texts in the "en/help" directory and call them using helpbutton(). If you need to update a help file:
#* with a minor change, where an old translation of the file would still make sense, then it's OK to make the change but you should notify translation AT moodle DOT org.
#* for a major change you should create a new file by adding an incrementing number (eg filename2.html) so that translators can easily see it's a new version of the file. Obviously the new code and the help index files should also be modified to point to the newest versions.
# Incoming data from the browser (sent via GET or POST) automatically has magic_quotes applied (regardless of the PHP settings) so that you can safely insert it straight into the database. All other raw data (from files, or from databases) must be escaped with addslashes() before inserting it into the database.
# IMPORTANT: All texts within Moodle, especially those that have come from users, should be printed using the format_text() function. This ensures that text is filtered and cleaned correctly.
# User actions should be logged using the [[add_to_log|add_to_log()]] function. These logs are used for [[Settings#Show_activity_reports|activity reports]] and [[Logs]].

==Coding style==

I know it can be a little annoying to change your style if you're used to something else, but balance that annoyance against the annoyance of all the people trying later on to make sense of Moodle code with mixed styles. There are obviously many good points for and against any style that people use, but the current style just is, so please stick to it.

1. Indenting should be consistently 4 spaces. Don't use tabs AT ALL.

2. Variable names should always be easy-to-read, meaningful lowercase English words. If you really need more than one word then run them together, but keep them short as possible. Use plural names for arrays of objects.

GOOD: $quiz
GOOD: $errorstring
GOOD: $assignments (for an array of objects)
GOOD: $i (but only in little loops)

BAD: $Quiz
BAD: $aReallyLongVariableNameWithoutAGoodReason
BAD: $error_string

3. Constants should always be in upper case, and always start with the name of the module. They should have words separated by underscores.

define("FORUM_MODE_FLATOLDEST", 1);
4. Function names should be simple English lowercase words, and start with the name of the module to avoid conflicts between modules. Words should be separated by underscores. Parameters should always have sensible defaults if possible. Note there is no space between the function name and the following (brackets).

function forum_set_display_mode($mode=0) {
global $USER, $CFG;

if ($mode) {
$USER->mode = $mode;
} else if (empty($USER->mode)) {
$USER->mode = $CFG->forum_displaymode;
}
}

5. Blocks must always be enclosed in curly braces (even if there is only one line). Moodle uses this style:

if ($quiz->attempts) {
if ($numattempts > $quiz->attempts) {
error($strtoomanyattempts, "view.php?id=$cm->id");
}
}

6. Strings should be defined using single quotes where possible, for increased speed.

$var = 'some text without any variables';
$var = "with special characters like a new line \n";
$var = 'a very, very long string with a '.$single.' variable in it';
$var = "some $text with $many variables $within it";

7. Comments should be added as much as is practical, to explain the code flow and the purpose of functions and variables.

* Every function (and class) should use the popular [http://www.phpdoc.org/ phpDoc format]. This allows code documentation to be generated automatically.
* Inline comments should use the // style, laid out neatly so that it fits among the code and lines up with it.

/**
* The description should be first, with asterisks laid out exactly
* like this example. If you want to refer to a another function,
* do it like this: {@link clean_param()}. Then, add descriptions
* for each parameter as follows.
*
* @param int $postid The PHP type is followed by the variable name
* @param array $scale The PHP type is followed by the variable name
* @param array $ratings The PHP type is followed by the variable name
* @return mixed
*/
function forum_get_ratings_mean($postid, $scale, $ratings=NULL) {
if (!$ratings) {
$ratings = array(); // Initialize the empty array
if ($rates = get_records("forum_ratings", "post", $postid)) {
// Process each rating in turn
foreach ($rates as $rate) {
....etc

8. Space should be used liberally - don't be afraid to spread things out a little to gain some clarity. Generally, there should be one space between brackets and normal statements, but no space between brackets and variables or functions:

foreach ($objects as $key => $thing) {
process($thing);
}

if ($x == $y) {
$a = $b;
} else if ($x == $z) {
$a = $c;
} else {
$a = $d;
}

==Database structures==

# Every table must have an auto-incrementing id field (INT10) as primary index. (see [[IdColumnReasons]])
# The main table containing instances of each module must have the same name as the module (eg widget) and contain the following minimum fields:
#* id - as described above
#* course - the id of the course that each instance belongs to
#* name - the full name of each instance of the module
# Other tables associated with a module that contain information about 'things' should be named widget_things (note the plural).
# Column names should be simple and short, following the same rules as for variable names.
# Where possible, columns that contain a reference to the id field of another table (eg widget) should be called widgetid. (Note that this convention is newish and not followed in some older tables)
# Boolean fields should be implemented as small integer fields (eg INT4) containing 0 or 1, to allow for later expansion of values if necessary.
# Most tables should have a timemodified field (INT10) which is updated with a current timestamp obtained with the PHP time() function.

==Security issues (and handling form and URL data)==

# Do not rely on 'register_globals'. Every variable must be properly initialised in every code file. It must be obvious where the variable came from
# Initialise all arrays and objects, even if empty. $a = array() or $obj = new stdClass();.
# Do not use the optional_variable() function (this function is now deprecated). Use the optional_param() function instead. Pick the correct PARAM_XXXX value for the data type you expect.
# Do not use the require_variable() function (this function is now deprecated). Use the required_param() function instead. Pick the correct PARAM_XXXX value for the data type you expect.
# Use data_submitted(), with care. Data must still be cleaned before use.
# Do not use $_GET, $_POST or $_REQUEST. Use the appropriate required_param() or optional_param() appropriate to your need.
# Do not check for an action using something like if (isset($_GET['something'])). Use, e.g., $something = optional_param( 'something',-1,PARAM_INT ) and then perform proper test for it being in its expected range of values e.g., if ($something>=0) {....
# Wherever possible group all your required_param(), optional_param() and other variables initialisation at the beginning of each file to make them easy to find.
# Use 'sesskey' mechanism to protect form handling routines from attack. Basic example of use: when form is generated, include <input type="hidden" name="sesskey" value="<?php echo sesskey(); ?>" />. When you process the form check with if (!confirm_sesskey()) {error('Bad Session Key');}.
# All filenames must be 'cleaned' using the clean_filename() function, if this has not been done already by appropriate use of required_param() or optional_param()
# Any data read from the database must have addslashes() applied to it before it can be written back. A whole object of data can be hit at once with addslashes_object().
# Wherever possible, data to be stored in the database must come from POST data (from a form with method="POST") as opposed to GET data (ie, data from the URL line).
# Do not use data from $_SERVER if you can avoid it. This has portability issues.
# If it hasn't been done somewhere else, make sure all data written to the database has been through the clean_param() function using the appropriate PARAM_XXXX for the datatype.
# If you write custom SQL code, make very sure it is correct. In particular watch out for missing quotes around values. Possible SQL 'injection' exploit.
# Check all data (particularly that written to the database) in every file it is used. Do not expect or rely on it being done somewhere else.
# Blocks of code to be included should contain a definite PHP structure (e.g, a class declaration, function definition(s) etc.) - straight blocks of code promote uninitialised variable usage.

[[es:Manual de Estilo de Código]]

User talk:Gustav Delius

2006-04-04T07:46:21Z

Delius:

==Developer wiki quiz pages==

Hi Gustav, please let me know whether it would be helpful if the quiz pages from the Using Moodle developer wiki should be moved into [[Developer notes]]. --[[User:Helen|Helen]] 07:04, 28 January 2006 (WST)

:Hi Helen, I had indeed been looking for those pages. They are of course outdated but would be a good starting point for a more up-to-date version. If you let me know where I can find them then I can copy them over myself. --[[User:Gustav|Gustav]] 07:08, 28 January 2006 (WST)

Thanks very much for working on these, Gustav, it will help a lot of future quiz programmers. --[[User:Martin|Martin]] 28 January 2006 (WST)

:Yes, I am very sorry that I neglected the quiz module the way I did in the past months. Ideally I would like to be able to hand over of the module to the OU team, perhaps when I see Jason Cole in Savannah. --[[User:Gustav|Gustav]] 17:02, 28 January 2006 (WST)

::Gustav, you have absolutely nothing to be sorry about. Your huge contribution to Moodle is greatly appreciated. --[[User:Helen|Helen]] 22:02, 28 January 2006 (WST)

Here I am testing the signature string which yesterday afternoon always gave midnight as the time. --[[User:Gustav Delius|Gustav Delius]] 15:46, 4 April 2006 (WST)

:Apparently it works in the morning. My suspicion is that as soon as WST goes beyond midnight it gets stuck at midnight, so I will test this again this afternoon GMT. Clearly Moodle is much more sophisticated with timezones than WikiMedia. --[[User:Gustav Delius|Gustav Delius]] 15:46, 4 April 2006 (WST)

Developer documentation

2006-04-03T15:54:00Z

Delius: /* Documentation for contributed code */ link to database of modules and plugins

==Guidelines==
The following guidelines are crucial reading for anyone wanting to contribute to the Moodle code base:
*[[Coding|Coding guidelines]] have to be followed by all Moodle developers
*[[Moodle architecture]] spells out the basic design goals behind Moodle
*[[Interface guidelines]] aim to provide a common feel to the Moodle user interface
*[[CVS (developer)|Moodle CVS for developers]] explains how to work with the Moodle code in CVS

== Resources and tools ==

*[http://moodle.org/bugs/ Moodle bug tracker] - bug reports, feature requests and other tracked issues
*[http://moodle.org/mod/forum/view.php?id=55 General developer forum]
*[http://cvs.sourceforge.net/viewcvs.py/moodle/moodle/ CVS code] - browse the Moodle code via the web
*[http://moodle.org/xref/nav.html?index.html Cross reference] - phpxref output for browsing Moodle source code
*[http://moodle.sourceforge.net/dhawes-phpdoc/ Moodle PHP doc reference] - automatically generated documentation
*[http://moodle.org/course/view.php?id=5#4 Development news and discussion] section of Using Moodle course
*[[Unmerged files]] - changes on the stable branch in CVS that have not been merged to HEAD

==How you can contribute==

The M in Moodle stands for 'Modular'. There are many different types of components that you can contribute that can be plugged into Moodle to provide additional funtionality. When you have developed a new component please publish it in the [http://moodle.org/mod/data/view.php?id=6009 database of Moodle modules and plugins]. The following types of plugins currently exist (in alphabetical order):
*[[Modules (developer)|Activity modules]]
*[[Assignment types]]
*[[Authentication|Authentication methods]]
*[[Blocks Howto|Blocks]]
*[[Course formats]]
*[[Database fields]]
*[[Database presets]]
*[[Enrolment plugins]]
*[[Filters (developer)|Filters]]
*[[Question import/export formats]]
*[[Question types]]
*[[Quiz reports]]
*[[Resource types]]
*[[SSO plugins]]

There are also ways you can contribute that don't involve PHP programming:
*[[Themes]]
*[[Translation|Translations]]
*[[Database Schemas|Database schemas]]

You can also help a lot by
*[[Tests|Testing]]
*[[Bug tracker|Participating in the bug tracker]]

==Plans for the future==
Ideas for and details of planned future features of Moodle are initially discussed on the forums in the [http://moodle.org/course/view.php?id=5 Using Moodle] course at moodle.org. That developer discussions are intermixed with user discussions in the same forums may seem strange at first but is one of the reasons for the success of Moodle. It is important that both end-users and developers discuss the future features together.

Once ideas begin to crystalize on the forums they can be summarized in this wiki, either as part of the [[Roadmap]] or in the form of [[Developer notes]]. These pages then form the basis for further discussion in the forums.
*[[Roadmap]]
*[[Developer notes]]
*[[Developer conference|Developer conferences]]

==Documentation for core components==
This section is for documentation of specific components of the existing core Moodle code. Discussion of components that are under discussion or in development can be found in the [[Developer notes]] or on the [[Roadmap]].

*[[UTF-8 migration|Migration to UTF-8]]
*[[Question engine]]
*[[Quiz developer docs|Quiz module]]
*[[SCORM schema|SCORM module 1.5 schema]]
*[[Authentication API]]
*[[Stats package]]
*[[Email processing]]
*[[Cookieless Sessions]]

==Documentation for contributed code==
Many Moodle users contribute code for the benefit of other Moodle users. This can take the form of new activity modules, blocks, themes, resource plug-ins, assignment plug-ins, question type plug-ins, question import/export formats, quiz report plug-ins, course formats, ... This code is initially posted on the forums in the [http://moodle.org/course/view.php?id=5 Using Moodle] course and then often go into the [http://cvs.sourceforge.net/viewcvs.py/moodle/contrib/ contrib area] of the Moodle [[CVS]] repository. When you have developed a new component please publish it in the [http://moodle.org/mod/data/view.php?id=6009 database of Moodle modules and plugins]. Developer documentation for these components should be listed here.

==See also==
*[http://security.moodle.org/ Moodle Security Centre]
*[http://moodle.com/partners/ Moodle Partners] - providers of custom Moodle development services

[[es:Documentación para Desarrolladores]]

2006-02-21T21:42:10Z

Delius: /* Question->options */

True/False question type

2006-02-21T21:39:52Z

Delius: /* Response storage */

{{Questiontype developer docs}}

==Database tables==
Each true/false question creates two records in the quiz_answers table, one for the 'true' option, one for the 'false' option. The ids of these answers are stored in the 'trueanswer' and 'falseanswer' field of the quiz_truefalse table.
;id
:int(10) unsigned NOT NULL auto_increment,
;question
:int(10) unsigned NOT NULL default '0',
;trueanswer
:int(10) unsigned NOT NULL default '0',
:id of the answer 'True' (not necessarily the correct answer).
;falseanswer
:int(10) unsigned NOT NULL default '0',
:id of the answer 'False' (not necessarily the wrong answer).

It is important to distinguish between the answer 'True' and the correct answer. When setting up a true/false question the teacher decides whether the answer 'True' or the answer 'False' is the correct answer. So 'true' and 'false' here refer to the statement in the question text, not to the correctness of the answer.

The way Moodle stores which of the answers is the correct answer is via the 'fraction' field in the quiz_answers table. The correct answer has 'fraction' = 1, the wrong one has 'fraction' = 0.

==Response storage==

The response from the student in <nowiki>$state->responses['']</nowiki> is the id of the answer chosen by the student. This then also gets stored in the 'answer' field in the quiz_states table.

==Question->options==

$question->options object holds the data from the quiz_truefalse table and the ->answers property which is an array with indices 'true' and 'false' and the values are the corresponding answer objects.

==State->options==

[[Category:Quiz]]

True/False question type

2006-02-21T21:39:30Z

Delius: /* Database tables */

{{Questiontype developer docs}}

==Database tables==
Each true/false question creates two records in the quiz_answers table, one for the 'true' option, one for the 'false' option. The ids of these answers are stored in the 'trueanswer' and 'falseanswer' field of the quiz_truefalse table.
;id
:int(10) unsigned NOT NULL auto_increment,
;question
:int(10) unsigned NOT NULL default '0',
;trueanswer
:int(10) unsigned NOT NULL default '0',
:id of the answer 'True' (not necessarily the correct answer).
;falseanswer
:int(10) unsigned NOT NULL default '0',
:id of the answer 'False' (not necessarily the wrong answer).

It is important to distinguish between the answer 'True' and the correct answer. When setting up a true/false question the teacher decides whether the answer 'True' or the answer 'False' is the correct answer. So 'true' and 'false' here refer to the statement in the question text, not to the correctness of the answer.

The way Moodle stores which of the answers is the correct answer is via the 'fraction' field in the quiz_answers table. The correct answer has 'fraction' = 1, the wrong one has 'fraction' = 0.

==Response storage==

Each true/false question defines two answer records, one for the 'true' option, one for the 'false' option. The ids of these answers are stored in the 'trueanswer' and 'falseanswer' field of the quiz_truefalse table.

The response from the student in <nowiki>$state->responses['']</nowiki> is the id of the answer chosen by the student. This then also gets stored in the 'answer' field in the quiz_states table.

==Question->options==

$question->options object holds the data from the quiz_truefalse table and the ->answers property which is an array with indices 'true' and 'false' and the values are the corresponding answer objects.

==State->options==

[[Category:Quiz]]