MoodleDocs - User contributions [en]

Enrolment

2011-06-08T23:40:03Z

Azoltay:

Course Administration block>Settings>Enrolment

Enrolment is the process of assigning users to roles (usually student) in a course. There are 3 types: internal enrolment, manual enrolment and enrollment plugins.

==Internal enrolment==
By default, [[Internal enrolment|internal enrolment]] is where any student can enrol themselves into a course. A course can ask an student trying to enrol for an [[Enrolment key|enrolment key]], which can be set in the course settings.

Moodle also provides a number of other enrolment methods, called . Whilst internal enrolment is an effective and efficient way of managing course enrolment, particularly if you don't have a lot of courses, different enrolment

==Manual enrolment==

A user can be [[Assign_roles#Assigning_a_role|manually enrolled]] by [[Assign_roles|assigned a role]] in the course. Administrators and Teachers use this method to assign students or non-editing teachers from the list of site users to a specific course.

# Click on the "Assign roles" link in the course administration block.
# Click on student link.
# Select the user from the list of potential users on the right by clicking on the user.
##Multiple users may be selected by holding down the Apple or Ctrl key whilst clicking on the users' names.
# Use the left-facing arrow button to add the selected user to the list of existing users on the left.
[[Image:Roles Assign Student.JPG|thumb|center|Example of assigning users to a student role]]

==Enrolment plugins==
Enrolment plugins automate the enrolment process. Please see [[Enrolment plugins]] for more information. In general, they can use batch files or receive a verification outside of the course context, to enrol a student in a course. For example:

*There maybe a charge for a course and a student can be automatically enrolled after paying the required fee.
*The school has one non_Moodle database maintained by the registrar and the business office for enrolment of both on-line and classroom students.

==See also==
*[[Enrolment FAQ]]
*[[Unenrolment]]
*[[Enrolment plugins]]

[[Category:Enrolment]]

[[de:Kurseinschreibung]]

MNet

2011-01-28T17:38:45Z

Azoltay:

The network feature allows a Moodle administrator to establish a link with another Moodle, and to share some resources with the users of that Moodle. This features was introduced in Moodle 1.8.

==Overview==
The initial release of MNet is bundled with a Authentication Plugin, which makes single-sign-on between Moodles possible. A user with the username jody logs in to her Moodle server as normal, and clicks on a link that takes her to a page on another Moodle server. Normally, she would have only the privileges of a guest on the remote Moodle, but behind the scenes, single-sign-on has established a fully authenticated session for Jody on the remote site.

'''WARNING:''' MNet requires the use of '''xmlrpc'''. Please go to your phpinfo page if you are interested in using this and search for --with-xmlrpc. If your php has not been compiled with xmlrpc then you need to address that first! At present it appears that PEAR xmlrpc will not work.
[[Image:Administration Block Users Authentication MoodleNetwork.jpg|thumb|MNet setting in ''Admin > User > Authentication > Moodle Network]]

==Security==
The MNet feature requires that your server has the '''Curl''' and '''OpenSSL''' extensions installed. When you install or upgrade to Moodle 1.8, your system will generate a new OpenSSL certificate for encrypted communication with other Moodles, and will thereafter rotate encryption keys on a monthly basis (approx).

Communication takes place over an XML-RPC transport, and the XML-RPC documents are wrapped first in an XMLDSIG (XML digital signature) envelope, and then in an XMLENC (XML encryption) envelope. The encryption all happens within PHP, and does not require an https (Apache SSL) server.

References:
*[http://www.w3.org/TR/xmldsig-core/ XML Digital Signatures]
*[http://www.w3.org/TR/xmlenc-core/ XML Encryption]

A special mode can be enabled which would allow a machine with a specified IP address to make calls to the XML-RPC layer without using either encryption or signature envelopes. This mode is provided to enable Moodle to communicate with other software systems in which the integration of signatures and encryption might be prohibitively difficult. It is not envisioned that unencrypted inter-Moodle networking will ever be enabled.

==Peer to Peer Network==

This is the basic layout of the system. It can be very useful to run one Moodle per faculty or departments, each with its own user management, and yet permit users to roam across the Moodle installs... subject to permissions of course.

===Setup===

The instructions will cover 2 Moodle installations: MoodleA and MoodleB. Both are installed correctly and have never had a Moodle Network configuration.

Note: If you experience problems, ensure debugging is turned on in ''Site Administration > Server > Debugging''. Extra diagnostic messages may be displayed (particularly from Moodle 1.9.2)

For Moodle 2.0, you need to enable Networking (under the Site Administration > Advanced Features menu). This will add the "Networking" menu to the Site Administration menu.

# Get them to talk to each other
## Ensure ''Admin > Server > Environment'' indicates you have curl installed
## If MoodleA and MoodleB are hosted in the same domain, ensure they have a different cookie prefix. Note that changing the cookie prefix will log you out! You can change the cookie prefix via ''Admin > Server > Session Handling''.
## On both, go to ''Admin > Network > Settings'' and turn Networking ON.
## On MoodleA go to ''Admin > Network > Peers'' - put the URL of MoodleB under "Add New Host" and click Add. The URL should include the directory where your Moodle code is located, for example ''www.mymoodle.org/moodle''.
## Do the equivalent on MoodleB.
# Get user roaming going
## (skip this step for moodle 2.0 sites [http://moodle.org/mod/forum/discuss.php?d=141491] ) '' On both, go to ''Administration > Plugins > Authentication > Manage authentication'' in 2.0 onwards or ''Administration > Users > Authentication > Manage authentication'' in 1.9 and enable Moodle Network authentication plugin. Click on 'Settings' and enable auto_add_remote_users.''
## On MoodleA go to ''Admin > Networking > (Manage) Peers'', click on 'MoodleB', and click on 'Services'. Enable SSO-IDP publish and subscribe, and SSO-SP publish and subscribe.
## Do the equivalent on MoodleB.
## On both, go to ''Admin > Users > Permissions > Define Roles'', only roles that have "Roam to a remote Moodle moodle/site:mnetlogintoremote" will be allowed to roam. Grant the privilege as appropriate.
## On both, go to the homepage, and add the 'Network Servers' block.
## To test, it is recommended to use a different browser (even on a different machine) that is logged in to neither. Login to MoodleA with a non-administrator account that has the permissions to roam. You should see the Network Servers block, and clicking on it you should go to MoodleB with a newly autocreated account.
# Get remote enrolments going -- this is optional. It allows an administrator of MoodleB to enrol users that are "native" to MoodleB in remote courses in MoodleA, and viceversa.
## On both, go to ''Site administration > Plugins > Enrolments > Manage enrol plugins'' in 2.0 onwards or ''Administration > Courses > Enrolments'' pre-2.0 and enable Moodle Network enrolment plugin (click Save). Click on 'Edit' and enable 'allow_allcourses' or select some courses or categories to be remotely enrolled.
## On MoodleA go to ''Admin > Network > Peers'', click on 'MoodleB', and click on 'Services'. Enable Enrolment publish and subscribe.
## Do the equivalent on MoodleB.
## To use, in MoodleA go to ''Admin > Networking > Enrolments''. You will see MoodleB listed. Click on MoodleB and you will see a list of courses that MoodleB offers for remote enrolment. Select the course you want, and then enroll the users you want to that course.

===Using it===

==Connecting to a Mnet hub==
A Mnet hub (do not confuse it with the [[Community hub]] project of Moodle 2.0) is a Moodle server that is configured to accept connections from other Moodle servers, and to provide a set of services to users of these other servers. This guideline will direct you to connect to a Mnet hub, assess the services it has to offer, and enable those services for your users.

===Setup===
# Get talking to the Hub
## Ensure that the ''Admin > Server > Environment'' page indicates you have curl and openssl installed
## Go to ''Admin > Network > Settings'' and turn Networking on
## Go to ''Admin > Network > Peers'' and enter the URL of Mnet Hub under "Add New Host". Click Add
## The host details for the Mnet Hub should appear with the Site Name field already populated. Click Save changes
## The details will be written to your database and two new tabs will appear in this window: 'Services' and 'Logs'. Click Services
##A list of services will appear, each with a checkbox for 'publish' and 'subscribe'. Check the checkboxes for any services you want to publish or subscribe to

===Using it===
If the Mnet Hub has already enabled a service for you, there will be a tick alongside the appropriate checkbox, for example: if the Hub is publishing Moodle Networked Enrolment, then a tick will appear alongside the subscribe checkbox for this service. Note that in order to enable some functionality, prominently single-sign-on, you may have to publish a service, e.g. the Identity Provider service. The Mnet Hub will access this service on your Moodle, asking it to authenticate your users.
# Enable Roaming
## Subscribe to SSO (Service Provider) by checking the box
## Publish SSO (Identity Provider) by checking the box
## Click Save changes
## Go to ''Admin > Users > Permissions > Define Roles'', and grant the capability Roam to a remote Moodle moodle/site:mnetlogintoremote to an appropriate role
## Go to ''Administration > Plugins > Authentication > Manage authentication'' in 2.0 onwards or ''Administration > Users > Authentication > Manage authentication'' in 1.9 and enable the Moodle Network authentication plugin
## Go to your homepage, turn on editing, and add the 'Network Servers' block
## Using a different web-browser, log on as a non-admin user who inhabits the role you granted the roaming capability to
## Note that the Mnet Hub is listed in the Network Servers block on the homepage. Click on the link to that server
## Some of your user details will be transferred to the Mnet Hub server, and a browsing session will be started for you as if you had logged on there directly
# Enable Networked Enrolment
## Return to the web browser you've been using as the site administrator
## Go to ''Admin > Network > Peers'' and click on the entry for the Mnet Hub.
## Click on the Services tab
## Subscribe to Moodle Networked Enrolment
## Go to ''Site administration > Plugins > Enrolments > Manage enrol plugins'' in 2.0 onwards or ''Administration > Courses > Enrolments'' pre-2.0 and enable the Moodle Network enrolment plugin. Click Save changes
## Click on edit to view the details for networked enrolments.
## Go to ''Admin > Networking > Enrolments'' to see a list of Moodle servers that offer this service to you
## Click on a server name to view a list of courses that the server offers to your users
## Click on a course name, to view a list users that you can enrol in this course
## Enrol users
## Profit!

==Running a Mnet hub==
A Mnet hub is a regular Moodle site that runs in a special mode. As a Moodle Administrator, when you add another Moodle site to your list of network peers, your Moodle will contact that site to find out what it is called, and to request its public key for encrypted communication. Normally, the remote server will simply provide this information without making any record of the transaction.

A Mnet hub is different. As soon as you add an entry for a Mnet hub to your system, the Mnet hub will create an entry for your server in its list of hosts, and may immediately begin to offer services to the users of your site.

This section will guide you to set up a Mnet hub, and select services to offer to all comers.

===Setup===
# Enable Networking
## Ensure that the ''Admin > Server > Environment'' page indicates you have curl and openssl installed
## Go to ''Admin > Network > Settings'' and turn Networking on
## Go to ''Admin > Network > Peers'' and tick the checkbox for Register all hosts. Click on Save Changes
## On the same page, the first entry in your list of hosts should be All hosts. Click this link
## Click on Services and enable any services you want to offer to all comers

==See also==

* [[Moodle Network FAQ]]
* [[Development:Moodle Network|Moodle Network development notes]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=6976 MNet forum]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=92749 Examples of how people are using Moodle networks] forum discussion

[[Category:Authentication]]
[[Category:Enrolment]]
[[Category:MNet]]

[[fr:Réseau Moodle]]
[[ja:Moodleネットワーク]]
[[es:Red Moodle]]
[[cs:Síťové služby]]

Development:Local customisation

2010-11-02T22:17:15Z

Azoltay: /* 2.0 pre-upgrade script */

{{Infobox Project
|name = Local customisations
|state = Implemented
|tracker = MDL-17376, MDL-16438
|discussion = http://moodle.org/mod/forum/discuss.php?d=126017 http://moodle.org/mod/forum/discuss.php?d=86903
|assignee = [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]], some parts were originally proposed and implemented in 1.9 by Penny Leach
}}
{{Moodle 2.0}}

The recommended way to add new functionality to Moodle is to create a new standard plugin (module, block, auth, enrol, etc.).The /local/ plugins are mostly suitable for things that do not fit standard plugins.

=Custom /local/ plugins=

Local plugins are used in cases when no standard plugin fits, examples are:
* event consumers communicating with external systems
* custom definitions of web services and external functions
* applications that extend moodle at the system level (hub server, amos server, etc.)
* new database tables used in core hacks (discouraged)
* new capability definitions used in core hacks
* custom admin settings

Standard plugin features:
* /local/xxx/db/version.php - version of script (must be incremented after changes)
* /local/xxx/db/install.xml - executed during install (new version.php found)
* /local/xxx/db/install.php - executed right after install.xml
* /local/xxx/db/uninstall.php - executed during uninstallation
* /local/xxx/db/upgrade.php - executed after version.php change
* /local/xxx/db/access.php - definition of capabilities
* /local/xxx/db/events.php - event handlers and subscripts
* /local/xxx/db/messages.php - messaging registration
* /local/xxx/db/external.php - web services and external functions descriptions
* /local/xxx/lang/en/local_pluginname.php - language file

The ''xxx'' is used instead of your local plugin name, plugins of the same type are installed/upgraded in alphabetical order.

List of differences from normal plugins:
* always executed last during install/upgrade - guaranteed by order of plugins in <code>get_plugin_types()</code>
* are expected to use event handlers - events are intended for communication core-->plugins only, local plugins are the best candidates for event handlers
* can add admin settings to any settings page - loaded last when constructing admin tree
* do not need to have any UI - other plugins are usually visible somewhere
* some extra hooks (not implemented yet)

=Other /local/ customisation files=

==Customised site defaults==

Different default site settings can be stored in file /local/defaults.php.
These new defaults are used during installation, upgrade and later are
displayed as default values in admin settings. This means that the content
of the defaults files is usually updated BEFORE installation or upgrade.

These customised defaults are useful especially when using CLI tools
for installation and upgrade.

Sample /local/defaults.php file content:
<code php>
<?php
$defaults['moodle']['forcelogin'] = 1; // new default for $CFG->forcelogin
$defaults['scorm']['maxgrade'] = 20; // default for get_config('scorm', 'maxgrade')
$defaults['moodlecourse']['numsections'] = 11;
$defaults['moodle']['hiddenuserfields'] = array('city', 'country');
</code>
First bracket contains string from column plugin of config_plugins table.
Second bracket is the name of setting. In the admin settings UI the plugin and
name of setting is separated by "|".

The values usually correspond to the raw string in config table, with the exception
of comma separated lists that are usually entered as real arrays.

Please note that not all settings are converted to admin_tree,
they are mostly intended to be set directly in config.php.

==2.0 pre-upgrade script==

You can use /local/upgrade_pre20.php script for any code that needs to
be executed before the main upgrade to 2.0. Most probably this will
be used for undoing of old hacks that would otherwise break normal
2.0 upgrade.

This file is just included directly, there does not need to be any
function inside. If the execution stops the script is executed again
during the next upgrade. The first execution of lib/db/upgrade.php
increments the version number and the pre upgrade script is not
executed any more.

=Customisations outside of /local/ directory=

==Forced settings==

Sometimes it is useful to force some settings and prevent any changes of these settings via the standard admin UI. It is possible to hardcode these settings in config.php.

In case of course settings it is very simply, the values are assigned directly to $CFG properties. In case of plugins the values are specified in a multidimensional array in $CFG->force_plugin_settings.

Sample code in config.php
<code php>
$CFG->allowobjectembed = 0;
$CFG->forced_plugin_settings = array('page'=>array('displayoptions'=>5, 'requiremodintro'=>1), 'folder'=>'requiremodintro'=>1);
</code>

==Local language customisations==

Moodle supports other type of local customisation of standard language
packs. If you want to create your own language pack based on another
language create new dataroot directory with "_local" suffix, for example
following file with content changes string "Login" to "Sign in":
moodledata/lang/en_local
<code php>
<?php
$string['login'] = 'Sign in';
</code>
See also https://docs.moodle.org/en/Language_editing

==Custom script injection==

Very old customisation option that allows you to modify scripts by injecting
code right after the require 'config.php' call.

This setting is enabled by manually setting $CFG->customscripts variable
in config.php script. The value is expected to be full path to directory
with the same structure as dirroot. Please note this hack only affects
files that actually include the config.php!

Examples:
* disable one specific moodle page without code modification
* alter page parameters on the fly

==Direct code modifications==
This is usually the last resort, if possible do not do it. And if you still do it use some version control system (preferably git).

==Direct database modifications==
Very strongly discouraged! Sometimes field lengths may be modified without side effects. Adding or removing of db fields will most probably cause major problems during future upgrades. New database tables should be added only from plugins.

=Local customisations in previous versions=
Previous versions include only partial support for customisations in /local/ directory.

List of local customisations in 1.9.x:
* /local/cron.php - custom cron jobs
* /local/settings.php - custom admin settings
* /local/db/upgrade.php - general modifications
* /local/lang/* - custom strings
* /local/lib.php - local_delete_course()

Migration from old 1.9.x /local/:
* <code>local/*</code> needs to be copied to new directory
* <code>local/xxxx/db/install.php</code> is intended for first installation, originally everything was in upgrade.php
* events are used instead of hooks
* upgrade code needs to migrate old settings, events, etc. directly in core db tables - such as change component strings and capability names from db/install.php or manually before/after upgrade

==See also==

* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=86903 Local Customisations] forum discussion
* http://cvs.moodle.org/moodle/local/readme.txt?view=markup
* [[Local customisation (Moodle 1.9)]]

[[Category:Developer|Local customisation]]

Development:Unit tests

2010-01-21T00:32:16Z

Azoltay:

{{Moodle 1.7}}Location: ''Administration > Reports > Unit tests''

The purpose of Unit Tests is to evaluate the individual parts of a program (functions, and methods of classes) to make sure that each element individually does the right thing. Unit Tests can be one of the first steps in a quality control process for developing or tweaking Moodle code. The next steps will involve other forms of testing to ensure that these different parts work together properly.

The unit testing framework is based on the [http://www.simpletest.org/ SimpleTest] framework.

== Running the unit tests in Moodle ==

=== Running the basic tests ===

# Log in with an admin account.
# Administration ► Development ► Unit tests (moodle >= 2.0, Administration ► Reports ► Unit tests Moodle <= 1.9)
# Click on the '''Reports''' link near the bottom of the page.
# Click the '''Run tests''' button and wait.

This finds all the tests in Moodle and runs them. You can run a subset of the tests by entering a path (for example question/type) in the 'Only run tests in' box. Similarly, if a test fails, you get some links in the failure message to make it easy to re-run just those tests.

== Writing new tests ==

As an example, suppose we wanted to write some tests for the string_manager class in mod/quiz/editlib.php.

=== Where to put the tests ===

The unit test report finds tests by looking for files called 'test....php' inside folders called 'simpletest'.

So, for our example, we want to create called something like '''mod/quiz/simpletest/testeditlib.php'''. The skeleton of this file should look like:

<code php>
<?php
/**
* Unit tests for (some of) mod/quiz/editlib.php.
*
* @license http://www.gnu.org/copyleft/gpl.html GNU Public License
* @package question
*/

if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); // It must be included from a Moodle page
}

// Make sure the code being tested is accessible.
require_once($CFG->dirroot . '/mod/quiz/editlib.php'); // Include the code to test

/** This class contains the test cases for the functions in editlib.php. */
class quiz_editlib_test extends UnitTestCase {
function test_something() {
// Do the test here.
}

// ... more test methods.
}
?>
</code>

That is, you have a class called something_test, and in that class you have lots of methods called test_something. Normally, you have one test method for each particular thing you want to test, and you should try to name the function to describe what is being tested - without making the name too ridiculously long!

=== A test function ===

The a test function typically looks like

<code php>
function test_move_question_up() {
// Setup fixture

// Exercise SUT
$newlayout = quiz_move_question_up('1,2,0', 2);

// Validate outcome
$this->assertEqual($newlayout, '2,1,0');

// Teardown fixture

}
</code>

This is the [http://xunitpatterns.com/Four%20Phase%20Test.html four phase test pattern]. Those comments use a lot of testing jargon. The fixture is the background situation that needs to be set up before the test runs. SUT is short for 'situation under test'. This is where you call the function or method that you want to test. Then you check to see if the function did the right thing. Finally, you have to clean up the fixture you created. With luck there is nothing to do here

In this simple example, there is no setup or teardown to do. We just call the function we are testing with some sample input, and check that the return value is what we expect.

=== Shared setUp and tearDown methods ===

If all your test cases relate to the same area of code, then they may all need to same bit of fixture set up. For example, all the tests in lib/simpletest/teststringmanager.php need an instance of the string_manager class to test.

To avoid duplicating code, you can override a method called <code>setUp()</code> that sets up the test data. If present, this method will be called before each test method. You can write a matching <code>tearDown()</code> method if there is any clean-up that needs to be done after each test case has run. For example, in lib/simpletest/teststringmanager.php there are setUp and tearDown methods that do something like:
<code php>
public function setUp() {
// ...
$this->stringmanager = new string_manager(...);
}

public function tearDown() {
$this->stringmanager = null;
}
</code>
Then, each test can use $this->stringmanager without having to worry about the details of how it is set up.

=== Further information ===

The ''SimpleTest'' documentation is at: http://www.simpletest.org/.

== Changes to your existing code to make it work with unit testing ==

The whole point of unit testing is to test each piece of functionality separately. You can only do this is by isolating that function and call it individually, perhaps after setting up a few other things.

Therefore, it is good if you can write your code to depend on as few other things as possible.

=== Include paths ===

Includes like

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

won't work. Instead, the more robust option is

<code php>
require_once(dirname(__FILE__) . '/../../config.php'); // Do this.
</code>

=== Access to global variables ===

Because your code was included from within a function, you can't access global variables until you have done a global statement.

<code php>
require_once(dirname(__FILE__) . '/../../config.php');
require_once($CFG->libdir . '/moodlelib.php'); // Won't work.
</code>

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

global $CFG; // You need this.
require_once($CFG->libdir . '/moodlelib.php'); // Will work now.
</code>

=== Calls to global functions ===
Testing a class method that calls global functions can be problematic. At least, it's always complex, because we can't control what goes on in the global functions. We can't override the global functions or mock them in our unit tests. If the global functions themselves are well tested, this may not be a big problem, but most global functions are not well tested.

==== Bridge Pattern ====
If your code needs to rely extensively on some public API, you could use the [http://en.wikipedia.org/wiki/Bridge_pattern bridge pattern] to decouple your code from that API. This way, when you write unit tests, you can override the bridging class or mock it, and control its outputs while you focus exclusively on testing your code.

An basic example follows: Imagine that I do not trust the ''get_string()'' global function, but my code needs to use it. Initially my code has strong coupling with ''get_string()'':

<code php>
class myclass {
public function print_stuff($stuff) {
echo get_string($stuff);
}
}
</code>

Now let's write a bridging class to solve this coupling issue and use it instead of ''get_string()'':

<code php>
class languageBridge {
public function get_string($stuff,$module='moodle') {
echo get_string($stuff, $module);
}
}

class myclass {
public $lang_bridge;
public function __construct() {
$this->lang_bridge = new languageBridge();
}
public function print_stuff($stuff) {
echo $this->lang_bridge->get_string($stuff);
}
}
</code>

The following is yet another example using a bridging method to decouple from the Moodle core API.

<code php>
class workshop_api {
/**
* This is a method we want to unittest
*/
public function get_peer_reviewers($context) {
static $users=null;
if (is_null($users)) {
$users = $this->get_users_by_capability($context, 'mod/workshop:peerassess',
'u.id, u.lastname, u.firstname', 'u.lastname,u.firstname', '', '', '', '', false, false, true);
}
return $users;
}

/**
* Bridging method to decouple from Moodle core API
*/
protected function get_users_by_capability() {
$args = func_get_args();
return call_user_func_array('get_users_by_capability', $args);
}
}
</code>

'''Warning:''' Here are some comments on the examples above expressing that the bridge pattern should be used very carefully.

* "I think that is a case of unit tests leading to worse software design, in that you are not using the standard API for something. But if you really want to unit test, I can't think of a better solution."
* "I think this can be OK if used very selectively. Unfortunately I don't think it's the solution if you want to decouple the very complex and deeply nested Moodle functions from each other"
* "...your code is designed to be part of Moodle, so decoupling from a standard Moodle API is perverse."

== Unit testing in 2.0 ==

{{Moodle 2.0}}
With the Objectification of the Database libraries in Moodle 2.0, new and better approaches to Unit testing can be used. Here is a sample of a simple test case: (in course/simpletest)

<code php>
require_once($CFG->dirroot . '/course/lib.php');

global $DB;
Mock::generate(get_class($DB), 'mockDB');

class courselib_test extends UnitTestCase {
var $realDB;

function setUp() {
global $DB;
$this->realDB = $DB;
$DB = new mockDB();
}

function tearDown() {
global $DB;
$DB = $this->realDB;
}

function testMoveSection() {
global $DB;
$course = new stdClass();
$course->id = 1;

$sections = array();
for ($i = 1; $i < 11; $i++) {
$sections[$i] = new stdClass();
$sections[$i]->id = $i;
$sections[$i]->section = $i - 1;
}

$DB->expectOnce('get_records', array('course_sections', array('course' => $course->id)));
$DB->setReturnValue('get_records', $sections);
$this->assertFalse(move_section($course, 2, 3));
}
}
</code>

See also '''UnitTestCaseUsingDatabase''' in lib/simpletestlib.php.

=== Testing HTML output ===

(work in progress - to be documented properly once the API stabilizes)

* ContainsTagWithAttribute($tag, $attribute, $value)
* ContainsTagWithAttributes($tag, $attributes)
* ContainsTagWithContents($tag, $content)
* ContainsEmptyTag($tag)

The syntax is
<code php>
$this->assert(new ContainsTagWithAttribute($tag, $attribute, $value), $html);
</code>

== Code coverage analysis==
'''Note:''' This section is a work in progress. Please use the [[{{TALKPAGENAME}}|page comments]] or an appropriate [http://moodle.org/course/view.php?id=5 moodle.org forum] for any recommendations/suggestions for improvement.{{{info|}}}

{{Moodle 2.0}}

'''[[Wikipedia:Code_coverage|Code coverage]]''' is a technique, strongly tied with software testing, that allows to '''check and improve the quality of the tests''' by measuring the degree of source code that is being covered by them. With Moodle supporting more and more tests each day (slowly towards a '''Test Driven Development''' model) we need to integrate some tool into our development process helping to analyse the quality of ours tests.

Right now (in Moodle 2.0) we are using [http://www.simpletest.org/ SimpleTest], one simple and great tool to perform all the tests. Unluckily, it doesn't support code coverage analysis at all. In the other hand, other PHP unit testing products like [http://www.phpunit.de/ PHPUnit], more complex and powerful, have built-in support for that technique, but switching to a new product is out from our current [[Roadmap]] plans.

So, after some readings and comparisons, Moodle will implement its own extensions to SimpleTest, in order to fulfil the main goal of having statement/line code coverage analysis working under Moodle 2.0 onwards. To achieve this, also [http://developer.spikesource.com/projects/phpcoverage Spike PHPCoverage], a basic code-coverage tool, will be used and extended. You can find the details of the implementation of this tool at MDL-19579.

=== Changes ===

To enable code coverage in your tests, only a few modifications need to be performed to your current code:

# Change your test classes by adding two (public static) attributes: '''$includecoverage''' and '''$excludecoverage''', both arrays, being used to inform to the code coverage tool (via reflection) about which source code files and dirs must be covered/skipped by the analysis.
# Use '''[http://cvs.moodle.org/moodle/lib/simpletestcoveragelib.php?view=markup simpletestcoveragelib.php]''' instead of simpletestlib.php in your caller scripts.
# Use the '''autogroup_test_coverage''' class instead of the AutoGroupTest one (see below for details) in your caller scripts.

(note that only the 1st point above is needed for new unit tests being created because both 2 and 3 (changes in caller scripts) are already implemented in Moodle and awaiting your cool unit tests.

That's all! With those 3 basic changes, you will end with a complete code coverage report available for further analysis.

=== API ===

When using code coverage within Moodle there are two alternative APIs available, both providing the same code coverage reports at the end, but doing that in a different way. Here they are:

* '''Internal (hidden) coverage API''': This API is completely hidden beyond the Unit testing API and you won't need to know the details about it. Just perform the 1-2-3 changes described above and, after running the tests you'll get the final report available for being used immediately, without needing to perform anything in your code. His major drawback: it only can perform '''one''' "code coverage session" (a.k.a. instrumentation), so it's only suitable for testing scripts using only one unit test execution. One example of this type of unit testing is [http://cvs.moodle.org/moodle/admin/report/unittest/index.php?view=markup admin/report/unittest/index.php] where only one (big) test-group is executed.
* '''External (explicit) coverage API''': This API needs extra coding as long as coverage instantiating, configuration and report generation happens in the main script. It's a bit more complex but, in the other hand, it support '''multiple''' instrumentations to be performed, and gives you more control about the code coverage process. One example of this type of unit testing is [http://cvs.moodle.org/moodle/admin/report/unittest/dbtest.php?view=markup admin/report/unittest/dbtest.php] where multiple (one for each DB being tested) test-group are executed.

So, first of all (point 1 in prev section - usage), we need to define, for each unit test, which files / directories (relative to dirroot) we want to analyse with the tool. Here it's one example, for the '''dml_test''' unit test ([http://cvs.moodle.org/moodle/lib/dml/simpletest/testdml.php?view=markup /lib/dml/simpletest/testdml.php]), all we need to add to these lines to the class declaration :

<code php>
public static $includecoverage = array('lib/dml');
public static $excludecoverage = array('lib/dml/somedir');
</code>

By doing so, the code coverage tool will know which are the target files to perform coverage analysis/reporting and will do that for all the files (recursively) in the ''lib/dml''' dir but excluding the ''lib/dml/somedir'' directory (recursively too). Note that both attributes are arrays so multiple paths can be specified in any of them. Also note that the dir where the UnitTest is stored is automatically excluded (usually ''simpletest'' dirs).

And, as said, that's all you need to fulfil in order to get current/new unit tests being analysed by the code coverage tool by current Moodle scripts. The documentation below is only interesting for developers wanting to create new scripts able to perform unit testing with code coverage (points 2 and 3 in prev section - usage).

==== Internal coverage API ====
<code php>
$test = new autogroup_test_coverage($showsearch, $test_name, $performcoverage, $coveragename, $coveragedir);
</code>
Create one new autogroup test object with code coverage support, there you can specify if you want to perform coverage (true/false), the name of the report (title) and the directory where the final report will be created (under moodledata/codecoverage).
Optionally you can add more files and directories (relative to dirroot) to the list of files to be covered / ignored by using these functions (in case the defined in point 1 aren't enough).
<code php>
$test->add_coverage_include_path($path);
$test->add_coverage_exclude_path($path);
</code>
And then, affter adding a bunch of unit tests to the group, you simply invoke the test execution with code coverage support to end with a nice code coverage report under ''dataroot/codecoverage/$coveragedir'':
<code php>
$test->run($unit_test_reporter);
</code>
(don't forget that this API supports only '''one''' instrumentation to be performed)

And that's all!

==== External coverage API ====
<code php>
$covreporter = new moodle_coverage_reporter($coveragename, $coveragedir);
$covrecorder = new moodle_coverage_recorder($covreporter);
</code>
Create one coverage reporter, by passing its title and output directory as parameters.
<code php>
$test = new autogroup_test_coverage($showsearch, $test_name, $performcoverage);
</code>
Create one new autogroup test object with code coverage support, you don't need to specify the title and dir here (as already have been defined by the moodle_coverage_reporter object).
Optionally you can add more files and directories (relative to dirroot) to the list of files to be covered / ignored by using these functions (in case the defined in point 1 aren't enough).
<code php>
$test->add_coverage_include_path($path);
$test->add_coverage_exclude_path($path);
</code>
Then, after adding a bunch of unit tests to the group, you simply invoke the test execution with code coverage support with:
<code php>
$test->run_with_external_coverage($unit_test_reporter, $covrecorder);
</code>
(don't forget that this API supports '''multiple''' instrumentations to be performed)

And finally, you generate the code coverage report (under ''dataroot/codecoverage/$coveragedir'') using:
<code php>
$covrecorder->generate_report();
</code>
Once more, that's all!

==== Final notes ====
* Note that there are some more methods available in the moodle_coverage_recorder class. They will allow to control starting/stopping instrumentations by hand and other minor things but they shouldn't really be used. The run() and run_with_external_coverage() methods should be enough in 99% of cases.
* Not being part of the API, but used by it, there is one '''[http://cvs.moodle.org/moodle/admin/report/unittest/coveragefile.php?view=markup overagefile.php]''' script under ''admin/report/unittest'' responsible for serving the coverage report files from within Moodle. See current scripts in that dir to see how can be used.
* All the test execution / reporting / coverage utilities must be protected with the 'moodle/site:config' permission.

== A warning ==

In 'xUnit Test Patterns' there is a [http://xunitpatterns.com/TestAutomationRoadmap.html scale of testing difficulty] that goes from 1. to 6. Moodle is definitely at number 6. on that scale 'Non-object-oriented legacy software'. It then goes recommend that you don't start to learn about unit testing with that sort of software :-(

== Further reading about unit testing ==

[http://manning.com/reiersol/ PHP in Action] has an excellent chapter explaining unit testing in PHP with ''simpletest''. (Although the rest of that book advocates a style of programming that is very different from the style used in Moodle.)

[http://www.pragprog.com/titles/utj/pragmatic-unit-testing-in-java-with-junit Pragmatic Unit Testing in Java with JUnit] is also a very good introduction, despite being in the wrong programming language. JUnit and Simpletest are very similar.

[http://xunitpatterns.com/ xUnit Test Patterns] is the ultimate unit test book. I think it teaches you everything you could learn about unit testing by reading a book. The only way to learn more would be years of experience. It has really great advice for dealing with the kind of messy problems you get in a big, real project like Moodle.

[[Category:Coding guidelines|Unit tests]]
[[Category:Quality Assurance]]

PHP settings by Moodle version

2009-12-01T00:51:00Z

Azoltay:

{{stub}}
and
{{Review}}{{Template:Installing Moodle}}
Moodle has different PHP requirements for different versions:
* Moodle 2.0 will require PHP 5.2.8 or later.
* Moodle 1.6 to 1.9 requires PHP 4.3.0 or later
* Moodle 1.0 to 1.5 requires PHP 4.1.0 or later

==Other information==
** For Moodle version 1.4 or later: PHP4 (version 4.1.0 or later) or PHP5 (version 5.1.0 or later) are supported.
** For Moodle version 1.6 or later: the PHP4 (version 4.3.0 or later) or PHP5 (version 5.1.0 or later) are supported.
** Future Moodle versions 2.0 or later will require PHP5 (version 5.2.8 or later).
** PHP Settings. Check these settings in your php.ini or .htaccess file (if you're using Apache). For settings which use ON/OFF as their values, you can substitute 1 for ON and 0 for OFF if you prefer.
*** ''register_globals'' '''MUST''' be OFF
*** ''safe_mode'' needs to be OFF.
*** ''memory_limit'' should be at least 16M (32M is recommended for Moodle 1.7 and 40M for Moodle 1.8 or later). Large sites may need more than 128M. PHP 5.2.x requires higher memory_limit values than previous versions of PHP. 64bit operating systems require even more memory.
*** ''session.save_handler'' needs to be set to FILES.
*** ''magic_quotes_gpc'' should be ON. (It will be recommended to turn it off in 2.0.)
*** ''magic_quotes_runtime'' needs to be OFF.
*** ''file_uploads'' needs to be ON.
*** ''session.auto_start'' needs to be OFF.
*** ''session.bug_compat_warn'' needs to be OFF.
** PHP Extensions and libraries
*** The mbstring extension is recommended for Moodle 1.6 or later.
*** The iconv extension is recommended for Moodle 1.6 or later.
*** [http://www.libgd.org/ GD library] and the [http://www.freetype.org/ FreeType 2] library and extensions are needed to be able to look at the dynamic graphs that the logs pages make. (Freetype support is available as part of the GD extension for the 5.x versions of PHP)
*** The mysql extension is required if you are using the MySQL database. Note that in some Linux distributions (notably Red Hat) this is an optional installation.
*** The pgsql extension is required if you are using the PostgreSQL database.
*** The zlib extension is required for zip/unzip functionality.
*** The pdo and pdo_sqlite extensions are required for the (experimental) SQLite 3 database support.
*** The curl extension is recommended for Moodle 1.8 or later.
*** The tokenizer extension is recommended for Moodle 1.8 or later.
*** The curl and openssl extensions are required for the Moodle network functionality (Moodle 1.8 or later).
*** The xmlrpc extension is required for the Moodle network functionality (Moodle 1.8 or later).
*** The ctype extension is recommended for Moodle 1.8 or later.
*** Other PHP extensions may be required to support optional Moodle functionality, especially external authentication and/or enrolment (e.g. LDAP extension for LDAP authentication and the sockets extension for Chat server).
* A working database server: [[MySQL]] or [[PostgreSQL]] are completely supported and recommended for use with any version of Moodle. Support for Microsoft SQL Server and Oracle has been added in Moodle 1.7. MySQL is ''the'' choice for many people because it is very popular, but there are some [[Arguments in favour of PostgreSQL|arguments in favour of PostgreSQL]], especially if you are planning a large deployment.
** For Moodle 1.5, MySQL (version 3.23 or later) or PostgreSQL (7.4 or later).
** For Moodle 1.6, MySQL (version 4.1.12 or later) or PostgreSQL (7.4 or later).
** For Moodle 1.7, MySQL (version 4.1.12 or later), PostgreSQL (7.4 or later) or Microsoft SQL Server 2005 (version 9 or [http://moodle.org/mod/forum/discuss.php?d=59284 SQL Server Express 2005])
** For Moodle 1.8 or later, MySQL (version 4.1.12 or later), PostgreSQL (8.0 or later) or Microsoft SQL Server 2005 (version 9 or [http://moodle.org/mod/forum/discuss.php?d=59284 SQL Server Express 2005])
: MySQL Notes: For Moodle 1.6 or later, If you use latin languages only you can use MySQL 4.1.12. If you are using non-latin languages you require MySQL 4.1.16 or later. Currently the MySQL setting "strict mode" must be OFF (set to "" or "MYSQL40") in the MySQL configuration file.
: PostgreSQL Notes: PostgreSQL 7.4 is recommended for earlier Moodle versions, since Moodle 1.8 only PostgreSQL 8.0 and above are supported.
* For showcases or low to medium-sized installations, Moodle 2.0 also includes (experimental) support for SQLite 3 database. This setup requires no database server, as the database file is stored in a local directory on the server.

==See also==
[[Installing Moodle]]

[[de:PHP-Versionen für Moodle]]
[[ru:Настройки PHP для разных версий Moodle]]