MoodleDocs - User contributions [en]

CAS server (SSO) authentication

2010-09-22T18:44:03Z

Trick: /* Overview */ fixed link

Location: Settings link in ''Administration > Users > [[Authentication]]''

== Overview ==

CAS is "Single Sign-on for the Web" and is developed by [http://www.ja-sig.org/products/cas/ JA-SIG] in an open-source, collaborative manner. CAS is very beneficial in environments where a number of different web applications share a set of common users. If all the web applications were <em>"CASified"</em> a user would log in once and would then be able to move between the various web applications without ever having to present authentication credentials again. CAS is similar to the [[Shibboleth]] authentication mechanism, but it is vastly simpler to set up and lacks a number of broader features like federated trust and authorization infrastructure.

The details for how CAS works are [http://www.jasig.org/cas/cas2-architecture well documented], but CAS essentially works by configuring a web application (moodle.example.com) to not do authentication itself, but to instead forward unauthenticated users to a <em>"CAS Server"</em> (cas.example.com) which will then return an authentication token to the original web application (moodle.example.com). Moodle can extract the username from the token and then use its internal authorization mechanisms (roles, enrollments, capabilities) and user attributes (name, picture, etc.). The advantage is that the moodle.example.com service never has to handle passwords and that users, once they've authenticated the first time, can move seamlessly to another web application without having to present their credentials again.

== Configuration ==

Assuming that you already have a working CAS server, configuration is fairly straightforward through the web interface.

One caveat for those converting from LDAP or other authentication mechanisms:

* For any user that you wish to authenticate with CAS but which already has been using Moodle, and thus has an entry in the Moodle database, you will need to change the value of the "auth" field for the user in the mdl_user table. So, if they used LDAP before, but now you wish for them to use CAS and their username is "foobar" you'll need to edit the database with some SQL something like: <code>UPDATE mdl_user SET auth='cas' where auth='ldap' and username='foobar';</code> Without this change the user will constantly be presented with a failed login message, but otherwise no clue as to why login failed even though their credentials were accepted by the CAS server.

[[Category:Authentication]]

[[fr:Utiliser un serveur CAS (SSO)]]
[[de:Authentifizierung über einen CAS-Server (SSO)]]

Development:Modules

2009-06-03T18:25:44Z

Trick: /* Activity modules */ backwards slash

=== Activity modules ===

Activity modules reside in the '''/mod''' directory. Each module is in a separate subdirectory and consists of the following mandatory elements (plus extra scripts unique to each module):

* ''mod_form.php'' - a form to set up or update an instance of this module
* ''version.php'' - defines some meta-info
* ''icon.gif'' - a 16x16 icon for the module
* ''db/install.xml'' - defines the structure of db tables for all database types. Is used during module installation
* ''db/upgrade.php'' - defines changes in the structure of db tables. Is used during module upgrade
* ''db/access.php'' - defines module capabilities
* ''index.php'' - a page to list all instances in a course
* ''view.php'' - a page to view a particular instance
* ''lib.php'' - any/all functions defined by the module should be in here. If the module name is called '''widget''', then the required functions include:
:* widget_install() - will be called during the installation of the module
:* widget_add_instance() - code to add a new instance of widget
:* widget_update_instance() - code to update an existing instance
:* widget_delete_instance() - code to delete an instance
:* widget_user_outline() - given an instance, return a summary of a user's contribution
:* widget_user_complete() - given an instance, print details of a user's contribution
:* widget_get_view_actions() / widget_get_view_actions() - Used by the participation report (course/report/participation/index.php) to classify actions in the logs table.
:* Other functions available but not required are:
:** widget_delete_course() - code to clean up anything that would be leftover after all instances are deleted
:** widget_process_options() - code to pre-process the form data from module settings
:** [[Development:Implementing Reset course functionality in a module|widget_reset_course_form() and widget_delete_userdata()]] - used to implement [[Reset course]] feature.
:* To avoid possible conflict, any module functions should be named starting with widget_ and any constants you define should start with WIDGET_
* ''backuplib.php'' and ''restorelib.php'' (optional)
* ''settings.php'' or ''settingstree.php'' - (optional) a definition of an admin settings page for this module. mod/assignment/settings.php is a good simple example. mod/quiz/settingstree.php is a more complex example.
* ''defaults.php'' - lets you easily define default values for your configuration variables. It is included by upgrade_activity_modules in lib/adminlib.php. It should define an array $defaults. These values are then loaded into the config table. Alternatively, if you set $defaults['_use_config_plugins'] to true, the values are instead loaded into the config_plugins table, which is better practice. See mod/quiz/defaults.php for an example.
* ''lang/en_utf8/widget.php'' - (optional) Lastly, each module will have some language files that contain strings for that module.

=== IMPORTANT: ===
* When creating a new module, the new name of the module must not contain numbers or other special characters!

* You need a ''data base table'' with the same name as your module. This table must have at least three fields:
*# id
*# course
*# name

* You should also make sure that your activity module provides appropriate support for groups and meta-courses.

== See also ==

* [[Development:Blocks]]
* [[Development:Backup]]
* Tracker issue [http://tracker.moodle.org/browse/CONTRIB-52 CONTRIB-52 Improvements to make NEWMODULE really useful] - including download link for new module template supporting roles, formslib etc. (unfinished)
* http://download.moodle.org/plugins16/mod/NEWMODULE.zip - new module template for versions of Moodle prior to 1.7. Please follow the README instructions inside the zip.
* [[Development:NEWMODULE_Documentation]]

Using Moodle forum discussions:
*[http://moodle.org/mod/forum/discuss.php?d=66165 A new resource type: where do I put the language strings?]
*[http://moodle.org/mod/forum/discuss.php?d=65986 New Module Template Code for Moodle 1.7]
*[http://moodle.org/mod/forum/discuss.php?d=90154 LEGACY roles and capabilities]

[[Category:Developer|Modules]]
[[Category:Modules]]
[[Category:Tutorial]]

[[es:Módulos de actividades (desarrollador)]]
[[fr:Modules (développeur)]]
[[ja:モジュール (開発者)]]
[[zh:开发:模块_(开发者)]]
[[de:Entwickler:Module]]

Development:Developer FAQ

2009-06-02T23:45:25Z

Trick: block instance config

==Help for new coders==

===Where can I start?===

See [[Development:Finding your way into the Moodle code]].

===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.

===How do I create a patch?===

See [[Development:How to create a patch]].

===Is there any information on creating a new module or plugin?===

See [[Development:Modules]], [[Development:Blocks]] and [[Development:Authentication plugins]], or the [[Development:Developer_documentation#Make_a_new_plugin|full list of plugin types]].

===Is there any information on backup and restore?===

See [[Development:Backup]].

==I can't use one of the available plug-in points to make my change. What alternative is there?==

See [[Development:Local customisation]].

==Moodle's database==

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

[[Development:Database_schema_introduction]] gives a high level overview of the database schema.

Because of Moodle's modular nature, there is no single, detailed representation of the full database schema. Instead, the tables for each part of Moodle are defined in a database-neutral XML format, see [[XMLDB]], in each part of moodle. Look for files called install.xml in folders called db throughout the code. Alternatively, from Moodle 2.0 onwards, go to Administration -> Development -> XMLDB editor, and use the [Doc] links to see automatically generated documentation built form the comments in the install.xml files.

==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://phpdocs.moodle.org/19/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).

On top of those global configuration values, individual blocks may also have configuration "object" associated with it (the data is serialized and stored in the "block_instance" table). Within blocks, this data is automatically loaded into the <tt>config</tt> attribute of the block.

==See also==

*[[Contributed code FAQ]]
*Using Moodle [http://moodle.org/mod/forum/view.php?f=33 General developer forum]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=55719 How does date / time in DB convert to real Date / Time?] forum discussion

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

[[es:FAQ Desarrollador]]
[[fr:FAQ de développement]]
[[pl:Developer FAQ]]

Development talk:Navigation 2.0

2009-05-26T20:30:22Z

Trick: added tracker link

== Navigation menu ==

I'm the lead developer of the [[YUI menu]]. IMHO, it's the closest contender as far as actual written code goes. That's why I wrote it in the first place, because nothing else would work for us.

That said, the YUI menu as it is right now probably isn't good enough. Here are some caveats:

* At the moment, the code isn't bad, but it could be better. Some of this is due to compensating for stuff that should really be elsewhere. I'm currently working on a rewrite that will fix some of that.
* YUI's treeview has no form of non-javascript fallback and it uses HTML tables like there's no tomorrow. If we want accessibility (and I know I do), I'll have to throw out YUI all together and either find something else or write something myself.

I'm willing and able to do make these changes if it will help. See MDL-19300. -[[User:Alan Trick|Alan Trick]] 20:25, 26 May 2009 (UTC)

Development talk:Navigation 2.0

2009-05-26T20:25:35Z

Trick: Navigation menu

== Navigation menu ==

I'm the lead developer of the [[YUI menu]]. IMHO, it's the closest contender as far as actual written code goes. That's why I wrote it in the first place, because nothing else would work for us.

That said, the YUI menu as it is right now probably isn't good enough. Here are some caveats:

* At the moment, the code isn't bad, but it could be better. Some of this is due to compensating for stuff that should really be elsewhere. I'm currently working on a rewrite that will fix some of that.
* YUI's treeview has no form of non-javascript fallback and it uses HTML tables like there's no tomorrow. If we want accessibility (and I know I do), I'll have to throw out YUI all together and either find something else or write something myself.

I'm willing and able to do make these changes if it will help. -[[User:Alan Trick|Alan Trick]] 20:25, 26 May 2009 (UTC)

File:YUI Menu.png

2009-05-19T19:55:28Z

Trick:

Menu in 1.9.4 with a custom theme (twu). Taken from the [http://demo.mytwu.ca/moodle/course/view.php?id=2 demo site].

File:YUI Menu.png

2009-05-19T19:54:35Z

Trick: uploaded a new version of "Image:YUI Menu.png": menu in 1.9.4 with a custom theme (twu). Taken from [http://demo.mytwu.ca/moodle/course/view.php?id=2 demo site]

Original picture of the YUI menu. It's dated, but nothing has changed.

Development:Coding style

2009-05-19T17:30:04Z

Trick: /* String concatenation */ removed non-standard MySQL code.

==Overview==
===Scope===

This document describes '''style''' guidelines for developers working on or with Moodle code. It talks purely about the mechanics of code layout and the choices we have made for Moodle.

For details about using the Moodle API to get things done, see the [[Development:Coding|coding guidelines]].

===Goals===

Consistent coding style is important in any development project, and particularly when many developers are involved. A standard style helps to ensure that the code is easier to read and understand, which helps overall quality.

Abstract goals we strive for:

* simplicity
* readability
* tool friendliness, such as use of method signatures, constants, and patterns that support IDE tools and auto-completion of method, class, and constant names.

When considering the goals above, each situation requires an examination of the circumstances and balancing of various trade-offs.

Note that much of the existing Moodle code may not follow all of these guidelines - we continue to upgrade this code when we see it.

==File Formatting==

===PHP tags===

Always use "long" php tags. However, to avoid whitespace problems, DO NOT include the closing tag at the very end of the file.

<code php>
<?php

include('config.php');

</code>

===Indentation===

Use an indent of '''4 spaces''' with no tab characters. Editors should be configured to treat tabs as spaces in order to prevent injection of new tab characters into the source code.

Don't indent the main script level:

GOOD:
<code php>
<?php // $Id$
$a = required_param('a', PARAM_INT);
if ($a > 10) {
call_some_error($a);
} else {
do_something_with($a);
}
</code>

BAD:
<code php>
<?php // $Id$
$a = required_param('a', PARAM_INT);
if ($a > 10) {
call_some_error($a);
} else {
do_something_with($a);
}
</code>

===Maximum Line Length===

Aim for 80 characters if it is convenient.

However, you can go up to 120 characters if it helps overall readability.

===Line Termination===

Use standard '''Unix''' text format. Lines must end only with a linefeed (LF). Linefeeds are represented as ordinal 10, or hexadecimal 0x0A.

Do not use carriage returns (CR) like ''Macintosh'' computers (0x0D).

Do not use the carriage return/linefeed combination (CRLF) as ''Windows'' computers (0x0D, 0x0A).

Lines should not contain trailing spaces. In order to facilitate this convention, most editors can be configured to strip trailing spaces, such as upon a save operation.

==Naming Conventions==

===Filenames===

Filenames should :
* be whole english words
* be as short as possible
* use lowercase letters only
* end in .php, .html, .js, or .xml

===Classes===

Class names should always be lowercase english words, separated by underscores:

<code php>
class some_custom_class {
function class_method() {
echo "foo";
}
}
</code>

===Functions and Methods===

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.

Verbosity is encouraged: function names should be as illustrative as is practical to enhance understanding.

Note there is no space between the function name and the following (brackets).

<code php>
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;
}
}
</code>

====Function Parameters====

Parameters are always simple lowercase English words (sometimes more than one, like $initialvalue), and should always have sensible defaults if possible.

Use "null" as the default value instead of "false" for situations like this where a default value isn't needed.
<code php>
public function foo($required, $optional = null)
</code>

However, if an optional parameter is boolean, and its logical default value should be true, or false, then using true or false is acceptable.

===Variables===

Variable names should always be easy-to-read, meaningful lower-case 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: $camelCase
BAD: $aReallyLongVariableNameWithoutAGoodReason
BAD: $error_string

Core global variables in Moodle are identified using uppercase variables (ie $CFG, $SESSION, $USER, $COURSE, $SITE, $PAGE, $DB and $THEME). Don't create any more!

===Constants===

Constants should always be in upper case, and always start with the name of the module. They should have words separated by underscores.
<code php>
define("FORUM_MODE_FLATOLDEST", 1);
</code>

===Booleans and the NULL Value===

Use lower case for '''true''', '''false''' and '''null'''.

== Strings ==

Since string performance is not an issue in current versions of PHP, the main criteria for strings is readability.

===Single quotes===

Always use single quotes when a string is literal, or contains a lot of double quotes (like HTML):

<code php>
$a = 'Example String';
echo '<span class="'.s($class).'"></span>';
$html = '<a href="http://something" title="something">Link</a>';
</code>

===Double quotes===

These are a lot less useful in Moodle.

Use double quotes when you need to include plain variables or a lot of single quotes. In Moodle 2.0 or later you won't need to be doing a lot of single quotes for SQL so that's not an issue.

<code php>
echo "<span>$string</span>";
$statement = "You aren't serious!";
</code>

===Variable substitution===

Variable substitution can use either of these forms:

<code php>
$greeting = "Hello $name, welcome back!";

$greeting = "Hello {$name}, welcome back!";
</code>

===String concatenation===

Strings must be concatenated using the "." operator.

<code php>
$longstring = $several.$short.'strings';
</code>

If the lines are long, break the statement into multiple lines to improve readability. In these cases, put the "dot" at the end of each line.

<code php>
$sql = "SELECT id, username FROM user ".
"WHERE username = 'susan' ".
"ORDER BY id ASC ";
</code>

==Arrays==

===Numerically indexed arrays===

Negative numbers are not permitted as indices.

An indexed array may start with any non-negative number, however all base indices besides 0 are discouraged.

When declaring indexed arrays with the array function, a trailing space must be added after each comma delimiter to improve readability:

<code php>
$myarray = array(1, 2, 3, 'Stuff', 'Here');
</code>

Multi-line indexed arrays are fine, but pad each successive line with spaces so that the beginning of each line is aligned:

<code php>
$myarray = array(1, 2, 3, 'Stuff', 'Here',
$a, $b, $c,
56.44, $d, 500);
</code>

===Associative arrays===

Use multiple lines where possible, and pad the successive lines with spaces like this:

<code php>
$myarray = array('firstkey' => 'firstvalue',
'secondkey' => 'secondvalue');
</code>

==Classes==

=== Class declarations ===

* Classes must be named according to Moodle's naming conventions.
* The brace should always be written on the line beside the class name.
* Every class must have a documentation block that conforms to the PHPDocumentor standard.
* All code in a class must be indented with 4 spaces.
* Only one class is permitted in each PHP file.

* Placing additional code in class files is permitted but discouraged. In such files, two blank lines must separate the class from any additional PHP code in the class file.

: An example:

<code php>
/**
* Documentation Block Here
*/
class SampleClass {
// all contents of class
// must be indented 4 spaces
}
</code>

===Class member variables===

Member variables must be named according to Moodle's variable naming conventions.

Any variables declared in a class must be listed at the top of the class, above the declaration of any methods.

The var construct is not permitted. Member variables always declare their visibility by using one of the '''private''', '''protected''', or '''public''' modifiers. Giving access to member variables directly by declaring them as public is permitted but discouraged in favor of accessor methods (set/get).

==Functions and methods==
===Function and method declaration===

Functions must be named according to the Moodle function naming conventions.

Methods inside classes must always declare their visibility by using one of the private, protected, or public modifiers.

As with classes, the brace should always be written on same line as the function name.

Don't leave spaces between the function name and the opening parenthesis for the arguments.

Functions in the global scope are strongly discouraged.

The return value must not be enclosed in parentheses. This can hinder readability, in additional to breaking code if a method is later changed to return by reference.

<code php>
/**
* Documentation Block Here
*/
class sample_class {

/**
* Documentation Block Here
*/
public function sample_function () {
// all contents of function
// must be indented four spaces
return true;
}
}
</code>

===Function and method usage===

Function arguments should be separated by a single trailing space after the comma delimiter.

<code php>
threeArguments(1, 2, 3);
</code>

==Control statements==

In general, use white space liberally between lines and so on, to add clarity.

===If / else===

Put a space before and after the control statement in brackets, and separate the operators by spaces within the brackets. Use inner brackets to improve logical grouping if it helps.

Indent with four spaces.

Don't use elseif !

Always use braces (even if the block is one line and PHP doesn't require it).

<code php>
if ($x == $y) {
$a = $b;
} else if ($x == $z) {
$a = $c;
} else {
$a = $d;
}
</code>

===Switch===

Put a space before and after the control statement in brackets, and separate the operators by spaces within the brackets. Use inner brackets to improve logical grouping if it helps.

Always indent with four spaces. Content under each case statement should be indented a further four spaces.

<code php>
switch ($something) {
case 1:
break;

case 2:
break;

default:
break;
}
</code>

===Foreach===

As above, uses spaces like this:

<code php>
foreach ($objects as $key => $thing) {
process($thing);
}
</code>

==Require / include==

Each file should start by including the main config.php file.

<code php>
require_once('../config.php');
</code>

Any other include/require should use an absolute path beginning with $CFG->dirroot or $CFG->libdir, not relative includes, which [http://uk.php.net/manual/en/function.include.php sometimes behave strangely under PHP].

Includes should generally only be done at the top of files or inside functions/methods that need them, it's insecure to use include/require in the middle of file in global scope.

==Documentation and comments==

Inline documentation explains the code flow and the purpose of functions and variables. Use it whenever practical.

Moodle uses the [http://www.phpdoc.org/ phpDoc format]. This allows our code documentation to be generated automatically (see [http://phpdocs.moodle.org phpdocs.moodle.org].

===Inline comments===

Inline comments should use the // style, laid out neatly so that it fits among the code and lines up with it.

<code php>
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) {
...
}
// Do something else here
something_else();

... etc.
</code>

===Files===

All files that contain PHP code should contain a full GPL copyright statement at the top, plus a separate docblock right under it containing:
* A short one-line description of the file
* A longer description of the file
* A @package tag, describing the part of Moodle this part of
* A @copyright tag, with year and copyright holder (creator) of the original file
* A @license tag, which must contain "http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later"

<code php>
<?php

// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.

/**
* This is a one-line short description of the file
*
* You can have a rather longer description of the file as well,
* if you like, and it can span multiple lines.
*
* @package moodlecore
* @copyright 2008 Kim Bloggs
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
</code>

==== Packages ====

The package keyword MUST be included and tags a file as being part of a group of files. Conventions are:

# If it's part of Moodle core libraries, use '''moodlecore'''
# If it's part of a module, use the path of the module with hyphens: eg '''mod-forum''' or '''grade-report-visual'''

===Classes===

All classes should have a docblock with the following minimum information:

<code php>
/**
* Short description for class
*
* Long description for class (if any)...
*
* @copyright 2008 Kim Bloggs
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
</code>

===Functions===

All functions and methods should have a docblock like this:

<code php>
/**
* 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 and the return value 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
*/
</code>

==Exceptions==

Use exceptions to report errors, especially in library code.

Throwing an exception has almost exactly the same effect as calling print_error, but it is more flexible. For example, the caller can choose to catch the exception and handle it in some way. It also makes it easier to write unit tests.

Any exception that is not caught will trigger an appropriate call to print_error, to report the problem to the user.

Do not abuse exceptions for normal code flow. Exceptions should only be used in erroneous situations.

===Exception classes===

We have a set of custom exception classes. The base class is moodle_exception. You will see that the arguments you pass to new moodle_exception(...) are very similar to the ones you would pass to print_error. There are more specific subclasses for particular types of error.

To get the full list of exception types, search for the regular expression 'class +\w+_exception +extends' or ask your IDE to list all the subclasses of moodle_exception.

Where appropriate, you should create new subclasses of moodle_exception for use in your code.

A few notable exception types:
; moodle_exception : base class for exceptions in Moodle. Use this when a more specific type is not appropriate.
; coding_exception : thrown when the problem seems to be caused by a developer's mistake. Often thrown by core code that interacts with plugins. If you throw an exception of this type, try to make the error message helpful to the plugin author, so they know how to fix their code.
; dml_exception (and subclasses) : thrown when a database query fails.
; file_exception : thrown by the File API.

==Credits==

This document was drawn from the following sources:

# The original [https://docs.moodle.org/en/index.php?title=Development:Coding&oldid=53799 Coding guidelines] page
# The [http://framework.zend.com/manual/en/coding-standard.html Zend guidelines] and
# Feedback from all core Moodle developers

==See also==

[[Development:Coding]]

GNU General Public License

2009-05-11T18:23:56Z

Trick: short page with most relevant info

The '''GNU General Public License''' ('''GPL''') is the the [[License|software license used by Moodle]]. It is a widely used free software license, originally written by Richard Stallman for the GNU project. The GPL is designed to give users free use of their software and also make sure that freedom can not be taken away from them.

== Using the GPL ==

At the moment, there are 3 versions of the GPL, and this is unlikely to change any time soon. Version 3 is the current version and is the one recommended by the Free Software Foundation. Version 2 is usually used by software projects that started before the GPL 3 was available and have not made the effort to shift over. Version 1 is more or less completely gone.

These new versions of the GPL have been released in response to holes that people and companies have found and exploited in the older versions. For example, with the GPL 2 it was possible to create a product using DRM technology and deny its users the right to modify the software on it, even though the GPL was supposed to uphold this right. As a result, each version of the GPL must be incompatible with each other, otherwise the company could just make up some code under the old license, lock it down, and thus by pass the whole point of the new license.

As a result, the typical way to license is under ''GPL <version> or later''. For example, Moodle is licensed under the GPL 2 or later. In this case, the user can use it under the GPL 2 license or the GLP 3, thus the software is compatible with future GPL licenses. New software should probably use ''GPL 3 or later''.

== External Links ==

* [http://www.gnu.org/copyleft/gpl.html Official GPL page]
* [http://en.wikipedia.org/wiki/GNU_General_Public_License Wikipedia on the GPL]

Template:Plugin

2009-05-08T21:53:51Z

Trick: best to removed caption altogether if it's not going to be used

<table class="infobox" cellspacing="5" style="width: 22em; text-align: left; font-size: 88%; line-height: 1.5em; border: 1px solid #aaa; background-color: #f9f9f9; margin: 0.5em 0 0.5em 1em; padding: 0.2em; float: right; clear: right; vertical-align: top">
<tr><td colspan="2" style="text-align:center"> {{{screenshot}}} <br />
<span>{{{caption|}}}</span></td></tr>
<tr><th>Type</th><td>{{{type}}}</td></tr>
<tr><th>Download</th><td>{{{download}}}</td></tr>
<tr><th>Source Code</th><td>{{{source}}}</td></tr>
<tr><th>Bug Tracker</th><td>{{{tracker}}}</td></tr>
<tr><th>License</th><td>{{{license}}}</td></tr>
</table>

Template:Plugin

2009-05-08T21:53:03Z

Trick: using PAGENAME is redundant

<table class="infobox" cellspacing="5" style="width: 22em; text-align: left; font-size: 88%; line-height: 1.5em; border: 1px solid #aaa; background-color: #f9f9f9; margin: 0.5em 0 0.5em 1em; padding: 0.2em; float: right; clear: right; vertical-align: top">
<caption style="font-size: 125%; font-weight: bold;">{{{name|}}}</caption>
<tr><td colspan="2" style="text-align:center"> {{{screenshot}}} <br />
<span>{{{caption|}}}</span></td></tr>
<tr><th>Type</th><td>{{{type}}}</td></tr>
<tr><th>Download</th><td>{{{download}}}</td></tr>
<tr><th>Source Code</th><td>{{{source}}}</td></tr>
<tr><th>Bug Tracker</th><td>{{{tracker}}}</td></tr>
<tr><th>License</th><td>{{{license}}}</td></tr>
</table>

Template:Plugin

2009-05-08T20:35:44Z

Trick: moved license to the bottom

<table class="infobox" cellspacing="5" style="width: 22em; text-align: left; font-size: 88%; line-height: 1.5em; border: 1px solid #aaa; background-color: #f9f9f9; margin: 0.5em 0 0.5em 1em; padding: 0.2em; float: right; clear: right; vertical-align: top">
<caption style="font-size: 125%; font-weight: bold;">{{{name|{{PAGENAME}}}}}</caption>
<tr><td colspan="2" style="text-align:center"> {{{screenshot}}} <br />
<span>{{{caption|}}}</span></td></tr>
<tr><th>Type</th><td>{{{type}}}</td></tr>
<tr><th>Download</th><td>{{{download}}}</td></tr>
<tr><th>Source Code</th><td>{{{source}}}</td></tr>
<tr><th>Bug Tracker</th><td>{{{tracker}}}</td></tr>
<tr><th>License</th><td>{{{license}}}</td></tr>
</table>

Template:Plugin

2009-05-08T20:22:35Z

Trick: a wanabe infobox

<table class="infobox" cellspacing="5" style="width: 22em; text-align: left; font-size: 88%; line-height: 1.5em; border: 1px solid #aaa; background-color: #f9f9f9; margin: 0.5em 0 0.5em 1em; padding: 0.2em; float: right; clear: right; vertical-align: top">
<caption style="font-size: 125%; font-weight: bold;">{{{name|{{PAGENAME}}}}}</caption>
<tr><td colspan="2" style="text-align:center"> {{{screenshot}}} <br />
<span>{{{caption|}}}</span></td></tr>
<tr><th>Type</th><td>{{{type}}}</td></tr>
<tr><th>License</th><td>{{{license}}}</td></tr>
<tr><th>Download</th><td>{{{download}}}</td></tr>
<tr><th>Source Code</th><td>{{{source}}}</td></tr>
<tr><th>Bug Tracker</th><td>{{{tracker}}}</td></tr>
</table>

User:Alan Trick

2009-04-28T23:51:22Z

Trick: New page: I’m the lead developer for the online course system at Trinity Western University. I’m also a student in Computer Science and Linguistics. == Moodle Projects == * YUI menu — Le...

I’m the lead developer for the online course system at Trinity Western University. I’m also a student in Computer Science and Linguistics.

== Moodle Projects ==

* [[YUI menu]] — Lead developer

File:YUI Menu.png

2009-04-28T23:41:41Z

Trick: uploaded a new version of "Image:YUI Menu.png": cropped some of the background portion out

Original picture of the YUI menu. It's dated, but nothing has changed.

File:YUI Menu.png

2009-04-28T23:35:50Z

Trick: Original picture of the YUI menu. It's dated, but nothing has changed.

Original picture of the YUI menu. It's dated, but nothing has changed.

Installing MSSQL for PHP

2007-09-05T18:03:02Z

Trick: /* Installation overview */ added textlimit/size config for php.ini

{{Moodle 1.7}}
== Introduction ==

This short manual is suitable if you are trying to run Moodle 1.7 (and upwards) using the SQL*Server (MSSQL) RDBMS. Steps detailed below must be performed '''before''' installing Moodle itself.

First of all, minimum required version of MSSQL has been stabilised to MSSQL 2005 (v.9), although it '''might work with MSSQL 2000 (v.8) or newer'''. All the development process has been performed using MSSQL 2005 and there could be some '''unknown problems''' with previous releases.

While PHP comes with one, more or less, standard extension (mssql) that provides access to MSSQL databases, early we found some hard limits on it. Basically such default extension has some limits that prevent us to use it at all (you can find more info about this problems [[Development:XMLDB problems#MSSQL, PHP, UTF-8 and UCS-2|here]].

So, in order to allow PHP (i.e. Moodle) to access to MSSQL DBs properly we have to install a '''mssql extension alternative''' to save us from the problems related above. See the sections below for details about the various options.

== Installation overview ==

1. Get MSSQL Server installed and running.
:Make sure that you choose mixed authentication (Windows and local accounts) to keep things simpler later. You'll be asked to define the "sa" account password (it's the default System Administrator account which has full access to all databases by default).

2. Make sure MS SQL Server can accept incoming TCP/IP connections on port 1433 (the standard one).
:You might need to explicitly allow this in your Windows firewall (see the Control Panel). You may also need to edit options in the :'''SQL Server Configuration Manager''' -> '''Network Configuration''' -> '''Protocols''' -> '''TCP/IP enabled'''

3. Open the "SQL Server Management Studio" and create a new empty database. If you are using the "sa" account then you don't need to do anything else here.

4. Configure these settings in your created (and still empty) database:

:* ANSI NULLS Enabled = true
:* Quoted Identifiers Enabled = true

5. Get PHP installed with a web server. Unless you want to do it under IIS or some other way, the packages on the [http://download.moodle.org Moodle download page] are a good solution.

6. Choose one of the following specific sections for your server to install the '''mssql extension alternative''' installed and running properly on your PHP box.

7. Set the following settings in your php.ini file
:* mssql.textlimit = 20971520
:* mssql.textsize = 20971520
:Also, don't forget to set one of the following '''alternatives''', in order to get all the data properly "slashed":
:* magic_quotes_gpc = Off '''or'''
:* magic_quotes_gpc = On '''and''' magic_quotes_sybase = On

8. With all this properly configured, you can continue with a [[Installing Moodle|standard Moodle installation]].

== Using FreeTDS on Unix ==

If you web server is on Linux or some other flavour of Unix, try FreeTDS, http://www.freetds.org (documentation at http://www.freetds.org/docs.html)

Note that the download link above is a '''source download''', so you will need to install and compile it properly.

Once downloaded and uncompressed you must '''"configure, make, make install"''' it. This will deploy some stuff in the "/usr/local" directory of your machine, mainly:
* /usr/local/etc: where the freetds conf files will reside.
* /usr/local/lib: where compiled libraries will reside.
* /usr/local/bin: where some executables will reside.

Then, you must configure FreeTDS to point to your MSSQL DB server. To do so, edit (or create) the /usr/local/etc/freetds.conf file and put in there exclusively these lines:

[global]
host = xxx.xxx.xxx.xxx (ip of the MSSQL server)
port = 1433
client charset = UTF-8
tds version = 7.0
text size = 20971520

At this point, and previously to build the '''mssql extension alternative''', you can test conectivity with your MSSQL DB using the "/usr/local/bin/tsql" executable. Just do this:

tsql -S serverhost -U dbowner -P dbpassword

If everything is ok, you'll get this output:

locale is "es_ES.UTF-8"
locale charset is "UTF-8"
1>

just type, for example:

sp_help sysobjects

and you might get some output from DB. Finally type:

exit

and you'll be out from the "tsql" command line interpreter.

Now that you've successfully built, configured and tested FreeTDS it is time to create the '''mssql extension alternative''' that will provide us with the capacity of handling MSSQL DBs from within Moodle. To do so, you'll need configure your PHP server adding this new option to the usual ones:

--with-mssql=/usr/local/

then, after the standard "make and make install" steps, your PHP server will be built with MSSQL support provided by FreeTDS.

Finally, configure your Moodle config.php with this DB related info and continue with a normal Moodle install:

$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'xxx.xxx.xxx.xxx'; // IP of the MSSQL server (also proper hostname is allowed)
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but '''never''' leave it blank.

== Using FreeTDS on Windows ==

If your web server is on Windows, use '''php_dblib.dll''' from Frank Kromann ([http://kromann.info/article.php?Id=11062598797760000 original details here]). Despite the name, it's FreeTDS compiled for Windows. Assuming that you have PHP 5.1.x, here how to set it up:

1. [http://download.moodle.org/download.php/windows/php5.1/php_dblib.dll Download php_dblib.dll for PHP 5.1.x] and save it into your PHP extensions directory.

2. Edit your php.ini and add this line:

extension=php_dblib.dll

Make sure that any lines referring to the php_mssql.dll extension are DISABLED (commented out).

3. Create a file called C:\freetds.conf with:

[global]
host = xxx.xxx.xxx.xxx (ip of the MSSQL server)
port = 1433
client charset = UTF-8
tds version = 7.0
text size = 20971520

4. Your Moodle config.php should include lines like these:

$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but '''never''' leave it blank.

4. Restart or start your web server.

5. Install Moodle as usual. Good luck!

== Using ODBTP on Unix or Windows ==

You can download ODBTP from http://odbtp.sourceforge.net/. Also you will access to the documentation from the same page.

The downloaded package includes both the source code and some binaries to be installed in the server and some ready-to-use '''mssql extension alternatives''' for some platforms/PHP versions (so you won't need to compile it if your PHP server/version binary package is present).

First of all, we have to install the Win32 service that comes with the package. Let's assume that it's going to run in the same Win32 machine where your MSSQL server is running (although it can run in any other Win32 server in your network).

To do do, following the instructions present in http://odbtp.sourceforge.net/install.html, you must:

# Create a directory on the Windows host where the service program files will reside, i.e., md odbtp.
# Copy the files odbtpctl.exe, odbtpsrv.exe and odbtpsrv.ini files from the winservice directory into the directory created in step 1.
# Edit the file odbtpsrv.ini of the previous step and this line: <pre>MaxRequestSize=20971520</pre>
# Open a command prompt (cmd) window on the Windows host.
# Change to the directory to which the service program files were copied, i.e., cd odbtp.
# Run the following commands to install and start the service:
#* odbtpctl install
#* odbtpctl start
# With these steps you should have one new service running in your host called "odbtp". Verify it's present and running in the "Services" control panel.
# Don't forget to enable TCP/IP incoming connections to port 2799 in the host you have installed the service!

Now it's time to build the '''mssql extension alternative'''. First of all, verify if, in the downloaded package, under the "php" dir, there is one extension suitable for your PHP server/version. If it's present, you can simply copy it to the php/extensions dir in your PHP server and skip next points about compiling it from source. It's important to point that, inside each directory, you'll find '''two different''' libraries/dll files. The one that must be copied to the extensions dir is the one called '''"php_odbtp_mssql.xxx"'''!

If in the downloaded package isn't present the extension matching your PHP platform/version, you should build if from source files. To do that, just '''"configure, make, make install"'''. That will create some stuff under "/usr/local".

Now that you've successfully built ODBTP is time to create the '''mssql extension alternative''' that will provide us with the capacity of handling MSSQL DBs from within Moodle. To do so, just configure your PHP server adding this new option to the usual ones:

--with-odbtp-mssql

then, after the standard "make and make install" steps, your PHP server will be built with MSSQL support provided by ODBTP.

Finally, independently if we are using the binary extension provided in the download or if you have built it from source files, it's time to configure the extension. To do so, add this lines, if no present, to your php.ini file:

extension=php_odbtp.dll

(only for Win32 PHP servers!)

And, for all the server platforms:

[odbtp]
odbtp.interface_file = "/path/to/your/odbtp.conf"
odbtp.datetime_format = mdyhmsf
odbtp.detach_default_queries = yes

(where ''/path/to/your/odbtp.conf" is usually "/usr/local/etc/odbtp.conf"" for Unix systems and "C:\odbtp\odbtp.conf" for Windows systems)

Then, edit such "odbtp.conf" file and put there these contents:

[global]
odbtp host = xxx.xxx.xxx (ip or hostname of the Win32 box running the ODBTP service)
type = mssql
unicode sql = yes
use row cache = yes
right trim text = yes
var data size = 20971520

With this, your PHP server will be able to connect with the MSSQL DB server using ODBTP. From here, just continue with the installation.

Finally, if you find the ODBTP executables and '''mssql extension alternative''' in binary formats, it only will be necessary to install them in your server (binary packages...) without the need to recompile anything (just the php.ini and odbtp.conf edition steps above will be necessary). Of course, it will be really welcome to have all those binary alternatives documented here.

== Using ODBC on Windows ==

{{Not for production sites}}

1. Go to the '''Administrative Tools''' control panel, then the '''Data Sources (ODBC)''' panel.

2. Configure one new System/User DSN (call it, for example "moodle"). Dont forget to enable these options if the driver asks for them:

:* ANSI NULLS Enabled = true
:* Quoted Identifiers Enabled = true

3. Your Moodle config.php should include lines like these:

$CFG->dbtype = 'odbc_mssql'; // Note this is different to all the other configs on this page!
$CFG->dbhost = 'moodle'; // Where this matches the Data source name you chose above
$CFG->dbname = '''''''; // Keep it blank!!
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but '''never''' leave it blank.

4. Install Moodle as usual. Good luck!

== Related links ==

[[Installing Oracle for PHP]]

[[Category:Installation]]
[[Category:Developer]]
[[Category:XMLDB]]