MoodleDocs - User contributions [en]

PHPUnit

2018-06-01T16:50:47Z

F4bo: /* Running a single test quickly */

{{Moodle 2.3}}

=What is PHPUnit=
PHPUnit by Sebastian Bergmann is an advanced unit testing framework for PHP. It is installed as Composer dependency and is not part of Moodle installation. To run PHPUnit tests, you have to manually install it on your development computer or test server.

Read the excellent guide at
* [http://phpunit.de/manual/current/en/index.html PHPUnit Manual]

=Installation of PHPUnit via Composer=

* Install Composer

Instructions for installing composer on all platforms are here: https://getcomposer.org/download/

Install the composer.phar file to your moodle folder.

* Execute Composer installer

cd /your/moodle/dirroot

php composer.phar install

(If that gives you connection problems try...)

php composer.phar install --prefer-source

Troubleshooting:
* On Windows if you are behind a proxy you will need to setup an environment variable called HTTP_PROXY with a value detailing your HTTP Proxy address and port before composer will correctly download files.
* You may be prompted for github credentials when installing composer dependencies.
** This is used to generate an personal access token to avoid being rate limited by github.
** If you have Two Factor Authentication enabled on your github account, or do not wish to supply your own credentials you will need to generate a token manually:
*** Visit https://github.com/settings/applications and request personal access token
*** Copy this token and add it to your [https://gist.github.com/andrewnicols/c5377ed25a9df1006ce1 ~/.composer/config.json]
** ( See [https://github.com/composer/composer/issues/2280 composer issue #2280] for further details of this bug.)

Detailed instructions:
* [http://getcomposer.org/doc/00-intro.md Composer documentation]

Detailed instructions:
* [[PHPUnit installation in Windows]]
* [[PHPUnit installation in OS X]]

== Uninstalling previous PEAR based version ==

Before using composer, this page used to suggest to install phpunit via PEAR. If you did so, you may wish to uninstall that package now. This should work:

$ pear uninstall phpunit/DbUnit
$ pear uninstall phpunit/PHPUnit

=Initialisation of test environment=

Our PHPUnit integration requires a dedicated database and dataroot. First, add a new dataroot directory and prefix into your config.php, you can find examples in config-dist.php (scroll down to 'Section 9').

$CFG->phpunit_prefix = 'phpu_';
$CFG->phpunit_dataroot = '/home/example/phpu_moodledata';

Some PHPUnit tests require a live internet connection. If your system does not have a direct connection to the Internet, you also need to specify your proxy in config.php - even though you normally specify it by using the admin settings user interface. (If you do not use a proxy, you can skip this step.) Check the settings on the relevant admin settings page, or from the mdl_config table in your database, if you are unsure of the correct values.

// Normal proxy settings
$CFG->proxyhost = 'wwwcache.example.org';
$CFG->proxyport = 80;
$CFG->proxytype = 'HTTP';
$CFG->proxybypass = 'localhost, 127.0.0.1, .example.org';
// Omit the next lines if your proxy doesn't need a username/password:
$CFG->proxyuser = 'systemusername';
$CFG->proxypassword = 'systempassword';

From Moodle 2.8.5 onwards, you can also provide specific database settings for unit testing (if these are not provided, the standard database settings will be used):

<pre>$CFG->phpunit_dbtype = 'pgsql'; // 'pgsql', 'mariadb', 'mysqli', 'mssql', 'sqlsrv' or 'oci'
$CFG->phpunit_dblibrary = 'native'; // 'native' only at the moment
$CFG->phpunit_dbhost = '127.0.0.1'; // eg 'localhost' or 'db.isp.com' or IP
$CFG->phpunit_dbname = 'mytestdb'; // database name, eg moodle
$CFG->phpunit_dbuser = 'postgres'; // your database username
$CFG->phpunit_dbpass = 'some_password'; // your database password</pre>

Then you need to initialise the test environment using following command.

cd /home/example/moodle
php admin/tool/phpunit/cli/init.php

This command has to be repeated after any upgrade, plugin (un)installation or if you have added tests to a plugin you are developing:

'''NOTE:''' make sure that your php cli executable (or the one you want to use) is correctly on your path as the individual init scripts will call it repeatedly. Also, ensure en_AU locale is installed on your server.

== LDAP ==
If you want to run LDAP unit tests you must have a working, configured LDAP environment on your test server. There must be a basic LDAP tree structure in place or tests will fail with "Search: No such object". Build an LDAP tree structure in a new shell prompt:

<pre>
$ ldapadd -H ldap://127.0.0.1 -D "cn=admin,dc=yourcomputer,dc=local" -W
dn:dc=yourcomputer,dc=local
objectClass:dcObject
objectClass:organizationalUnit
dc:yourcomputer
ou:YOURCOMPUTER
</pre>

In config.php tell Moodle where to look for your test LDAP environment:

<pre>
// Constants for auth/ldap tests.
define('TEST_AUTH_LDAP_HOST_URL', 'ldap://127.0.0.1');
define('TEST_AUTH_LDAP_BIND_DN', 'cn=admin,dc=yourcomputer,dc=local');
define('TEST_AUTH_LDAP_BIND_PW', '*');
define('TEST_AUTH_LDAP_DOMAIN', 'dc=yourcomputer,dc=local');

// Constants for enrol/ldap tests.
define('TEST_ENROL_LDAP_HOST_URL', 'ldap://127.0.0.1');
define('TEST_ENROL_LDAP_BIND_DN', 'cn=admin,dc=yourcomputer,dc=local');
define('TEST_ENROL_LDAP_BIND_PW', '*');
define('TEST_ENROL_LDAP_DOMAIN', 'dc=yourcomputer,dc=local');

// Constants for lib/ldap tests.
define('TEST_LDAPLIB_HOST_URL', 'ldap://127.0.0.1');
define('TEST_LDAPLIB_BIND_DN', 'cn=admin,dc=yourcomputer,dc=local');
define('TEST_LDAPLIB_BIND_PW', '*');
define('TEST_LDAPLIB_DOMAIN', 'dc=yourcomputer,dc=local');
</pre>

=Test execution=

To execute all test suites from main configuration file execute the <code>vendor/bin/phpunit</code> script from your <code>$CFG->dirroot</code> directory.

cd /home/example/moodle
vendor/bin/phpunit

The rest of examples uses <code>phpunit</code>, please substitute it with <code>vendor/bin/phpunit</code> or create a shortcut in your dirroot.

In IDEs, you may need to specify the path to the PHPUnit configuration file. Use the absolute path to <code>phpunit.xml</code> from your <code>$CFG->dirroot</code>.

There is an alternative script for running of tests via web interface: <code>admin/tool/phpunit/webrunner.php</code>. Use this as the last resort only when you cannot use the command-line interface on your test server. It will most probably break due to permissions problems if you try to execute it both from command-line and from webrunner. This feature is not officially supported.

===How to run only some tests===

==== Running a single test quickly ====

The fastest way to run a single test is:

<code php>
vendor/bin/phpunit my_test_class_name my/tests/filename.php</code>
so, run this command in the CLI to see a real test in action:
<code php>
vendor/bin/phpunit core_cohort_cohortlib_testcase cohort/tests/cohortlib_test.php</code>

This is faster than other methods because it avoids the need to search for the test file, but you should be careful because it may be possible to run tests this way which are not included in the normal run. If you use this method, do at least one full test run (or --group run, as below) to ensure the test can be found.

Please note the path name is optional if the testcase class and file names are standardised as described in [[Writing PHPUnit tests]].

==== Using the @group annotation ====

If you add annotations like

<code php>
/**
* Unit tests for {@link stack_cas_keyval}.
* @group qtype_stack
*/
class qtype_stack_cas_keyval_exception_testcase extends basic_testcase {
</code>

to all the classes in your plugin, then you can run just the tests for your plugin by doing

phpunit --group qtype_stack

Therefore, it is suggested that you annotate all your tests with the Frankenstyle name of your plugin.

==== Using multiple phpunit.xml files ====

It's easy to create alternative phpunit.xml files defining which tests must be run together. For reference, take a look to the default /phpunit.xml available in your base directory once the testing environment has been initialised. After creating the custom file you will be able to run those tests with

vendor/bin/phpunit -c path/to/your/alternative/phpunit/file.xml

Also, for commodity, you can use this command:

php admin/tool/phpunit/cli/util.php --buildcomponentconfigs

It will, automatically, create one valid phpunit.xml file within each component (plugin or subsystem) and other important directories, so later you will be able to execute tests like

vendor/bin/phpunit -c mod/forum[/phpunit.xml] // Note that it's not needed to specify the name of the file (if it is 'phpunit.xml').
vendor/bin/phpunit -c question
vendor/bin/phpunit -c question/type/calculated
vendor/bin/phpunit -c backup
vendor/bin/phpunit -c lib/dml
...

or, also

cd directory/with/phpunit.xml
phpunit

=External test resources=
{{Moodle 2.6}}
By default Moodle phpunit tests contact http://download.moodle.org server when testing curl related functionality. Optionally you may checkout a local copy of the test scripts and access it instead:

# clone https://github.com/moodlehq/moodle-exttests to web directory
# add to your config.php or modify phpunit.xml file <code php>define('TEST_EXTERNAL_FILES_HTTP_URL', 'http://localhost/moodle-exttests');</code>

=Writing new tests=
* read [http://www.phpunit.de/manual/current/en/ official PHPUnit online documentation]
* see [[Writing PHPUnit tests]]

=Conversion of existing SimpleTests=
* see [[SimpleTest conversion]]

=PHPUnit support in IDEs=

* [[Setting up Eclipse]]
* [[Setting up Netbeans]]
* [[Setting up PhpStorm]]

=Common Unit Test Problems=
[[Common unit test problems]]

=Performance=

A typical run of full PHPUnit tests for Moodle 2.7 takes 10-20 minutes depending on the machine. If tests run slowly for you:

* Ensure you are using a database and filesystem running on the same machine that is running the tests (not on a remote server).
* Apply developer-only performance settings to your database: [[Postgres Tuning For Developers]]

=Command line tips=

* Run all tests for a plugin (mod_mymodule in this example): vendor/bin/phpunit --testsuite=mod_mymodule_testsuite
* Run only named test: vendor/bin/phpunit --filter=test_my_test_function_name
* Display each test name before running it (useful e.g. if it crashes before the end and you want to know which test it was running at that point) vendor/bin/phpunit --debug (you will probably want to redirect this to a file as it gets very long).

[[Category:Unit testing]]

Security

2018-06-01T13:57:40Z

F4bo: /* Check permissions */

This page describes how to write secure Moodle code that is not vulnerable to anything that evil people may try to throw at it.

The page is organised around the common types of security vulnerability. For each one, it explains
# what the danger is,
# how Moodle is designed to avoid the problem,
# what you need to do as a Moodle developer to keep your code secure, and
# what you can do as an administrator, to make your Moodle more secure.
The explanation of each vulnerability is on a separate page, linked to in the list below.

This page also summarises all the key guidelines.

==Security of web applications==

===Secure web app requirements===
Some companies require maximum level of security for web applications. You can often see similar general recommendations:
* separate administration backend
* no sensitive information stored in web application
* communication has to be encrypted using SSL
* log all user actions
* server applications have to be completely separated
* no files uploaded by users on server
* no rich text entered by users on server (limited plain text only)
* validate user identity and actions via separate channel
* always keep every software up-to-date
* no 3rd party browser extensions recommended
* use only one web page, do not open multiple windows with different sites, close/open browser before and after using the secure app

Web based banking systems are the best examples of these ''secure'' web applications. Security is the top most priority here, security incidents may cost money - either the customer, bank or insurance company, public image of the institution may be damaged too. Limiting factors may be cost of application development, maintenance, usability but also the cost of communication via the alternative channels.

===Balanced security===
As you can see many web applications today violate the security design rules. For example web based mail system have to accept rich text messages with file attachments, mail massages often contain very sensitive information. In fact the Web 2.0 idea goes directly agains the security design rules, everybody is submitting content - only app designer/administrator should be adding trusted content.

When designing web applications we have to find out what our users are supposed to be doing and then find some reasonable balance between features and security.

==Moodle security design==
The security of web application depends on the intended use and features available for each type of user.

===Types of users===

====Administrators====
Administrators have following privileges:
* change all settings
* create courses
* access all courses
* modify language packs
* modify all users

Indirectly administrators are allowed to execute shell and PHP code. Moodle administrators may be partially restricted by hardcoding settings in config.php.
Low level server administrators can not be restricted because they can read content of PHP files and may modify them.

All administrators have to be fully trusted.

====Teachers====
Teachers are usually creating course content, enrolling students and teaching. They usually need following privileges:
* upload files and submit html texts
* create and manage activities
* access student grades and other personal information

Uploading of files with javascript, flash and other scripted is often considered to be a security risk. Unfortunately we can not remove these risks from teacher roles because even basic SCORM packages consist of html and javascript which needs to use user session.

Browser trusts everything coming from one server, it does not know anything about our courses or origin of data. Once the file is uploaded to server it becomes part of the server application. It is not possible to differentiate between wanted and unwanted code stored on the server.

All teachers with risky capabilities have to be trusted, it is not possible to give teacher access to students. In theory teachers may use XSS attacks to gain administrator access.

Technically it would be possible to create system where teachers can not attack other users but it would prevent all javascript, flash, SCORM, java, html forms, SVG, etc.

====Students====
Students are participating in courses, they are not trusted. Students need following privileges:
* post formatted text with inline images and attachments
* upload binary documents

Uploaded files must not be opened directly in browser from the same server. Instead the files need to be served from different domain, or server has to force download of all files to local hard drive before opening them. Serving of untrusted files from different domain will be implemented in 2.0.

All student submitted text has to be sanitised before printing the text on any page, this prevent XSS attacks on other users but at the same time prevents flash, javascript, SVG and all other HTML scripting. There are two types of html cleaning - less reliable blacklisting (KSES) and more robust whitelisting (HTML Purifier).

====Guests====
For security reasons unregistered users can not be allowed to upload any files or submit any text that is stored in database. Guests could try to spam other users, exploit problems in html cleaning routines, abuse other vulnerabilities or try social engineering based attacks.

Sites with enabled user sign-up via email have to take extra care in order to prevent spamming and other types of attacks.

===Capability risks===

Moodle is very flexible system, administrators may define multiple roles. Each role is a set of capabilities defined at system level, roles may be modified via overrides at lower context levels. [[Risks]] are part of description of each capability, administrators have to make sure only trusted users get potentially dangerous capabilities.

==Common types of security vulnerability==

* [[Security:Unauthenticated access|Unauthenticated access]]
* [[Security:Unauthorised access|Unauthorised access]]
* [[Security:Cross-site_request_forgery|Cross-site request forgery]] (XSRF)
* [[Security:Cross-site scripting|Cross-site scripting]] (XSS)
* [[Security:SQL injection|SQL injection]]
* [[Security:Command-line injection|Command-line injection]]
* [[Security:Data-loss|Data-loss]]
* [[Security:Confidential information leakage|Confidential information leakage]]
* [[Security:Configuration information leakage|Configuration information leakage]]
* [[Security:Session fixation|Session fixation]]
* [[Security:Denial of service|Denial of service]]
* [[Security:Brute-forcing login|Brute-forcing login]]
* [[Security:Insecure configuration management|Insecure configuration management]]
* [[Security:Buffer overruns, and other platform weaknesses|Buffer overruns, and other platform weaknesses]]
* [[Security:Social engineering|Social engineering]]

==Summary of the guidelines==

===Authenticate the user===

* With very few exceptions, every script should call '''[[Access_API#require_login.28.29|require_login]]''' or '''[[Access_API#require_course_login.28.29|require_course_login]]''' as near the start as possible.

===Verify course and module access===
* all course areas have to be protected by "require_login" or "require_course_login" with correct $course parameter
* all module areas have to be protected by "require_login" or "require_course_login" with correct $course and $cm parameter

===Check permissions===

* Before allowing the user to see anything or do anything, call to '''[[Access_API#has_capability.28.29|has_capability]]''' or '''[[Access_API#require_capability.28.29|require_capability]]'''.
* Capabilities should be annotated with the appropriate '''[[Hardening_new_Roles_system#Basic_risks|risks]]'''.
* If appropriate, restrict what people can see according to '''groups'''.

===Don't trust any input from users===

* Use '''[[lib/formslib.php|moodleforms]]''' whenever possible, with an appropriate '''setType''' method call for each field.
* Before performing actions, use '''data_submitted() && confirm_sesskey()''' to check sesskey and that you are handling a POST request.
* Before destroying large amounts of data, add a confirmation step.
* If not using a moodleform, clean input using '''optional_param''' or '''required_param''' with an appropriate '''PARAM_...''' type.
** Do not access $_GET, $_POST or $_REQUEST directly.
** Group optional_param and required_param calls together at the top of the script, to make them easy to find.

Similarly, clean data from other external resources like RSS feeds before use.

===Clean and escape data before output===

* Use '''s''' or '''p''' to output plain text content.
* use '''format_string''' to output content with minimal HTML like multi-lang spans (for example, course and activity names).
* Use '''format_text''' to output all other content.
** Only use $options->noclean if it requires a capability with RISK_XSS to input that content (for example web page resources).
* Before Moodle 2.0, input from optional_param or required_param must have [[Developer:Slashes|'''stripslashes''' or '''stripslashes_recursive''']] applied if it is being output directly, rather than being stored in the database.
* Data destined for JavaScript should be escaped using '''$PAGE->requires->data_for_js''' (Moodle 2.0) or '''addslashes_js''' (Moodle 1.9).

See [[Output functions]] for more details.

===Escape data before storing it in the database===

* Use the XMLDB library. This takes care of most escaping issues for you.
* When you must use custom SQL code, '''use place-holders''' to insert values into the queries.
** Before Moodle 2.0, you have to build SQL by concatenating strings. Take particular care, especially with quoting values, to avoid SQL injection vulnerabilities.
* Before Moodle 2.0, data loaded from the database must have [[Developer:Slashes|'''addslashes''' or '''addslashes_object''']] applied to it before it can be written back to the database. (addslashes should no longer be use anywhere in Moodle 2.0 code.)
* In Moodle 2.0 variables must be passed to database queries through bound parameters

===Escape data before using it in shell commands===

* Avoid shell commands if at all possible.
** Look to see if there is a PHP library instead.
* If you can't avoid shell commands, use '''escapeshellcmd''' and '''escapeshellarg'''.

===Log every request===

* Every script should call '''add_to_log'''.

===Other good practice===

... that helps with security.

* Structure your code nicely, minimising the use of global variables. This makes the flow of data, and hence security, easier to verify.
* Initialise objects ($x = new stdClass;) and arrays ($x = array()) before you first use them.
* Test every input field with tricky input to ensure that it is escaped and un-escaped the right number of times everywhere, and that Unicode characters are not corrupted. My standard test input is:
<nowiki>< > & &lt; &gt; &amp; ' \' 碁 \ \\</nowiki>

==See also==

* [[Process#Security_issues|Security issue process]]
* [[Coding]]
* The [http://cwe.mitre.org/top25/ 2010 CWE/SANS Top 25 Most Dangerous Programming Errors] - this is a generic list of common security mistakes, produced by a group of security experts. The above Moodle-specific guidelines cover most of these general points.
* [https://www.owasp.org/index.php/PHP_Security_Cheat_Sheet PHP Security Cheat Sheet]
* [https://www.owasp.org/index.php/Main_Page The Open Web Application Security Project (OWASP)] - Large collection of documentation and code samples about preventing security issues while using web technologies.

[[Category:Security]]
[[Category:Coding guidelines|Security]]

Security

2018-06-01T13:53:19Z

F4bo: /* Authenticate the user */

This page describes how to write secure Moodle code that is not vulnerable to anything that evil people may try to throw at it.

The page is organised around the common types of security vulnerability. For each one, it explains
# what the danger is,
# how Moodle is designed to avoid the problem,
# what you need to do as a Moodle developer to keep your code secure, and
# what you can do as an administrator, to make your Moodle more secure.
The explanation of each vulnerability is on a separate page, linked to in the list below.

This page also summarises all the key guidelines.

==Security of web applications==

===Secure web app requirements===
Some companies require maximum level of security for web applications. You can often see similar general recommendations:
* separate administration backend
* no sensitive information stored in web application
* communication has to be encrypted using SSL
* log all user actions
* server applications have to be completely separated
* no files uploaded by users on server
* no rich text entered by users on server (limited plain text only)
* validate user identity and actions via separate channel
* always keep every software up-to-date
* no 3rd party browser extensions recommended
* use only one web page, do not open multiple windows with different sites, close/open browser before and after using the secure app

Web based banking systems are the best examples of these ''secure'' web applications. Security is the top most priority here, security incidents may cost money - either the customer, bank or insurance company, public image of the institution may be damaged too. Limiting factors may be cost of application development, maintenance, usability but also the cost of communication via the alternative channels.

===Balanced security===
As you can see many web applications today violate the security design rules. For example web based mail system have to accept rich text messages with file attachments, mail massages often contain very sensitive information. In fact the Web 2.0 idea goes directly agains the security design rules, everybody is submitting content - only app designer/administrator should be adding trusted content.

When designing web applications we have to find out what our users are supposed to be doing and then find some reasonable balance between features and security.

==Moodle security design==
The security of web application depends on the intended use and features available for each type of user.

===Types of users===

====Administrators====
Administrators have following privileges:
* change all settings
* create courses
* access all courses
* modify language packs
* modify all users

Indirectly administrators are allowed to execute shell and PHP code. Moodle administrators may be partially restricted by hardcoding settings in config.php.
Low level server administrators can not be restricted because they can read content of PHP files and may modify them.

All administrators have to be fully trusted.

====Teachers====
Teachers are usually creating course content, enrolling students and teaching. They usually need following privileges:
* upload files and submit html texts
* create and manage activities
* access student grades and other personal information

Uploading of files with javascript, flash and other scripted is often considered to be a security risk. Unfortunately we can not remove these risks from teacher roles because even basic SCORM packages consist of html and javascript which needs to use user session.

Browser trusts everything coming from one server, it does not know anything about our courses or origin of data. Once the file is uploaded to server it becomes part of the server application. It is not possible to differentiate between wanted and unwanted code stored on the server.

All teachers with risky capabilities have to be trusted, it is not possible to give teacher access to students. In theory teachers may use XSS attacks to gain administrator access.

Technically it would be possible to create system where teachers can not attack other users but it would prevent all javascript, flash, SCORM, java, html forms, SVG, etc.

====Students====
Students are participating in courses, they are not trusted. Students need following privileges:
* post formatted text with inline images and attachments
* upload binary documents

Uploaded files must not be opened directly in browser from the same server. Instead the files need to be served from different domain, or server has to force download of all files to local hard drive before opening them. Serving of untrusted files from different domain will be implemented in 2.0.

All student submitted text has to be sanitised before printing the text on any page, this prevent XSS attacks on other users but at the same time prevents flash, javascript, SVG and all other HTML scripting. There are two types of html cleaning - less reliable blacklisting (KSES) and more robust whitelisting (HTML Purifier).

====Guests====
For security reasons unregistered users can not be allowed to upload any files or submit any text that is stored in database. Guests could try to spam other users, exploit problems in html cleaning routines, abuse other vulnerabilities or try social engineering based attacks.

Sites with enabled user sign-up via email have to take extra care in order to prevent spamming and other types of attacks.

===Capability risks===

Moodle is very flexible system, administrators may define multiple roles. Each role is a set of capabilities defined at system level, roles may be modified via overrides at lower context levels. [[Risks]] are part of description of each capability, administrators have to make sure only trusted users get potentially dangerous capabilities.

==Common types of security vulnerability==

* [[Security:Unauthenticated access|Unauthenticated access]]
* [[Security:Unauthorised access|Unauthorised access]]
* [[Security:Cross-site_request_forgery|Cross-site request forgery]] (XSRF)
* [[Security:Cross-site scripting|Cross-site scripting]] (XSS)
* [[Security:SQL injection|SQL injection]]
* [[Security:Command-line injection|Command-line injection]]
* [[Security:Data-loss|Data-loss]]
* [[Security:Confidential information leakage|Confidential information leakage]]
* [[Security:Configuration information leakage|Configuration information leakage]]
* [[Security:Session fixation|Session fixation]]
* [[Security:Denial of service|Denial of service]]
* [[Security:Brute-forcing login|Brute-forcing login]]
* [[Security:Insecure configuration management|Insecure configuration management]]
* [[Security:Buffer overruns, and other platform weaknesses|Buffer overruns, and other platform weaknesses]]
* [[Security:Social engineering|Social engineering]]

==Summary of the guidelines==

===Authenticate the user===

* With very few exceptions, every script should call '''[[Access_API#require_login.28.29|require_login]]''' or '''[[Access_API#require_course_login.28.29|require_course_login]]''' as near the start as possible.

===Verify course and module access===
* all course areas have to be protected by "require_login" or "require_course_login" with correct $course parameter
* all module areas have to be protected by "require_login" or "require_course_login" with correct $course and $cm parameter

===Check permissions===

* Before allowing the user to see anything or do anything, call to '''has_capability''' or '''require_capability'''.
* Capabilities should be annotated with the appropriate '''[[Hardening_new_Roles_system#Basic_risks|risks]]'''.
* If appropriate, restrict what people can see according to '''groups'''.

===Don't trust any input from users===

* Use '''[[lib/formslib.php|moodleforms]]''' whenever possible, with an appropriate '''setType''' method call for each field.
* Before performing actions, use '''data_submitted() && confirm_sesskey()''' to check sesskey and that you are handling a POST request.
* Before destroying large amounts of data, add a confirmation step.
* If not using a moodleform, clean input using '''optional_param''' or '''required_param''' with an appropriate '''PARAM_...''' type.
** Do not access $_GET, $_POST or $_REQUEST directly.
** Group optional_param and required_param calls together at the top of the script, to make them easy to find.

Similarly, clean data from other external resources like RSS feeds before use.

===Clean and escape data before output===

* Use '''s''' or '''p''' to output plain text content.
* use '''format_string''' to output content with minimal HTML like multi-lang spans (for example, course and activity names).
* Use '''format_text''' to output all other content.
** Only use $options->noclean if it requires a capability with RISK_XSS to input that content (for example web page resources).
* Before Moodle 2.0, input from optional_param or required_param must have [[Developer:Slashes|'''stripslashes''' or '''stripslashes_recursive''']] applied if it is being output directly, rather than being stored in the database.
* Data destined for JavaScript should be escaped using '''$PAGE->requires->data_for_js''' (Moodle 2.0) or '''addslashes_js''' (Moodle 1.9).

See [[Output functions]] for more details.

===Escape data before storing it in the database===

* Use the XMLDB library. This takes care of most escaping issues for you.
* When you must use custom SQL code, '''use place-holders''' to insert values into the queries.
** Before Moodle 2.0, you have to build SQL by concatenating strings. Take particular care, especially with quoting values, to avoid SQL injection vulnerabilities.
* Before Moodle 2.0, data loaded from the database must have [[Developer:Slashes|'''addslashes''' or '''addslashes_object''']] applied to it before it can be written back to the database. (addslashes should no longer be use anywhere in Moodle 2.0 code.)
* In Moodle 2.0 variables must be passed to database queries through bound parameters

===Escape data before using it in shell commands===

* Avoid shell commands if at all possible.
** Look to see if there is a PHP library instead.
* If you can't avoid shell commands, use '''escapeshellcmd''' and '''escapeshellarg'''.

===Log every request===

* Every script should call '''add_to_log'''.

===Other good practice===

... that helps with security.

* Structure your code nicely, minimising the use of global variables. This makes the flow of data, and hence security, easier to verify.
* Initialise objects ($x = new stdClass;) and arrays ($x = array()) before you first use them.
* Test every input field with tricky input to ensure that it is escaped and un-escaped the right number of times everywhere, and that Unicode characters are not corrupted. My standard test input is:
<nowiki>< > & &lt; &gt; &amp; ' \' 碁 \ \\</nowiki>

==See also==

* [[Process#Security_issues|Security issue process]]
* [[Coding]]
* The [http://cwe.mitre.org/top25/ 2010 CWE/SANS Top 25 Most Dangerous Programming Errors] - this is a generic list of common security mistakes, produced by a group of security experts. The above Moodle-specific guidelines cover most of these general points.
* [https://www.owasp.org/index.php/PHP_Security_Cheat_Sheet PHP Security Cheat Sheet]
* [https://www.owasp.org/index.php/Main_Page The Open Web Application Security Project (OWASP)] - Large collection of documentation and code samples about preventing security issues while using web technologies.

[[Category:Security]]
[[Category:Coding guidelines|Security]]

Moodle architecture

2018-06-01T13:07:30Z

F4bo: /* An overview of Moodle core */

The aim of this document is to quickly give an overview of how the Moodle works at a technical level. Hopefully this will be helpful to Administrators and Developers. However, to actually do Moodle development you will have to study the code in much more detail than is provided here. See the [[Developer_documentation|developer documentation]].

==What is Moodle?==

Moodle is a Learning Management System, Course Management System, or Virtual Learning Environment, depending on which term you prefer. Its goal is to give teachers and students the tools they need to teach and learn. Moodle comes from a background of [[:en:Pedagogy|Social Constructionist pedagogy]], however, it can be used to support any style of teaching and learning.

There are other types of software systems that are important for educational institutions, for example ePortfolios, Student Information Systems and Content repositories. Generally, Moodle does not try to re-invent these areas of functionality. Instead, tries to be the best LMS possible, and then interoperate gracefully with other systems that provide the other areas of functionality. It is, however, perfectly possible to use Moodle as a stand-alone system, without integrating it with anything else.

Moodle is a web application written in PHP. Moodle is open source. Copyright is owned by individual contributors, not assigned to a single entity, although the company Moodle Pty Ltd in Perth Australia, owned by Moodle's founder Martin Dougiamas, manages the project.

==Overview of a Moodle installation==

A Moodle installation comprises the Moodle code executing in a PHP-capable web server; a database managed by MySQL, PostgreSQL, Microsoft SQL Server, MariaDB, or Oracle; and a file store for uploaded and generated files (the moodledata folder).

All three parts can run on a single server; or they can be separated with many load-balanced web-servers, a database cluster, and a file-server; or anywhere between those extremes.

Moodle is designed to be simple to install on any server that meets these basic requirements. Moodle self-installs once the code has been copied to the web server and a blank database created (see [[:en:Installing Moodle]]). Similarly, Moodle can always self-upgrade from one version to the next (see [[:en:Upgrading]]).

==Moodle as a modular system==

Like many successful open source systems, Moodle is structured as an application core, surrounded by numerous plugins to provide specific functionality. Moodle is designed to be highly extensible and customizable without modifying the core libraries, as doing so would create problems when upgrading Moodle to a newer version. So when customizing or extending your own Moodle install, always do so through the plugin architecture.

Plugins in Moodle are of specific types. That is, an authentication plugin and an activity module will communicate with Moodle core using different APIs, tailored to the type of functionality the plugin provides. Functionality common to all plugins (installation, upgrade, permissions, configuration, ...) are, however, handled consistently across all plugin types.

The standard Moodle distribution includes Moodle core and a number of plugins of each type, so that a new Moodle installation can immediately be used to start teaching and learning. After installation a Moodle site can be adapted for a particular purpose by changing the default configuration option, and by installing add-ons or removing standard plugins. Most add-ons that have been shared publicly are listed in the [http://moodle.org/plugins/index.php Moodle Plugins Directory].

Physically, a Moodle plugin is just a folder of PHP scripts (and CSS, JavaScript, etc. if necessary). Moodle core communicates with the plugin by looking for particular entry points, often defined in the file <tt>lib.php</tt> within the plugin.

* See [[Communication Between Components]] on how different Moodle components and plugins communicate with each other.

==An overview of Moodle core==

Moodle core provides all the infrastructure necessary to build a Learning Management System. It implements the key concepts that all the different plugins will need to work with. These include:

'''Courses and activities:'''
A Moodle course is a sequence of activities and resources grouped into sections. Courses themselves are organized into a hierarchical set of categories within a Moodle site.

'''Users:'''
In moodle, users are anyone who uses the moodle system. In order to participate in course users need to be enrolled into course with a given role, such as:

*Students
*Teachers

'''Course enrolment''':

*Enrolment gives user the possibility to participate in course as a student or teacher.

'''User functionality in moodle:'''

*User roles in moodle: Roles assigned to users give them a set of capabilities in given context. For example: Teacher, Student and Forum moderator are examples of roles.
*User's capabilities in moodle: A capability is a description of some particular Moodle feature. Capabilities are associated with roles. For example, mod/forum:replypost is a capability.
*Context: A context is a "space" in the Moodle, such as courses, activity modules, blocks etc.
*Permissions: A permission is some value that is assigned for a capability for a particular role. For example, allow or prevent.

'''Added facilities provided by moodle:'''

*Creation and editing of user profiles: In moodle, the moment an user creates his account, a profile is created for that user. The user needs to fill in his initial details for completing his profile. The user generally always have the permission to edit his own profile anytime on moodle.
*Groups and cohorts: Cohorts, or site-wide groups, enable all members of a cohort to be enrolled in a course in one action, either manually or synchronised automatically.
*Enrolments and access control: Users are generally enrolled into some courses and according to their permission settings and the groups to which they belong, they have limited access on moodle.

'''A bit more about moodle:'''

*Activity and course completion: The activity completion system allows activities such as Quizzes, SCORM modules, etc. to be marked complete when specified conditions are met.
*Navigation, settings and configuration: The Navigation block provide easy access to view various sections of the Moodle site and includes:
**My home - a personalised home page displaying links to the courses a user is associated with and activity information (such as unread forum posts and upcoming assignments)
**Site pages - links to site pages and resources from the front page of Moodle
**My profile - quick links allowing a user to view their profile, forums posts, blogs and messages as well as manage their private files
**My courses - lists (by course shortname) and links to courses the user is associated with. Click the course's shortname to view the front page of the course or use the arrows to navigate quickly to a specific section, resource or activity.

'''JavaScript library:'''
*Moodle has adopted the Yahoo User Interface library. There is also a nice system for loading the additional JavaScript files required by each page.

'''Upgrading moodle:'''
Moodle can be upgraded in four simple steps:

#Make sure that your server can run the latest Moodle version
#You should always be prepared to "roll back" if there's an issue with your data or some custom code you've added. So before committing, create a test install and always make backups.
#At this stage you can replace the Moodle code on your server with the version you downloaded and check for the plugins.
#Perform the upgrade by triggering the upgrade from the admin page.

(More information about upgrading can be found here : [[:en:Upgrade overview|Upgrade overview]])

'''Logs and statistics in moodle:'''
*Statistics in moodle: The statistics graphs and tables show how many hits there have been on various parts of your site during various time frames. They do not show how many distinct users there have been. They are processed daily at a time you specify. You must enable statistics before you will see anything.
*Log in moodle: Logs in Moodle are activity reports. Logs are available at site level and course level.

==The most important plugin types==

Please see the page [[Plugin types]] for the full list. A selection of the most common ones is highlighted here.

===Activities and resources===

Activities and resources are the most basic individual components that make up a course and are the main tools for teaching and learning. Some examples of resources are: pages, links and IMS content packages. Examples of activities include: forums, wikis, quizzes, and assignments.

Activities are by far the largest type of plugin in terms of amount of code. A forum or wiki system could be a software project in its own right. Both activities and resources are installed in the <tt>mod</tt> folder.

===Blocks===

Blocks are small bits of interface functionality that can be added to (normally the sides of) pages. Many blocks provide additional views of data stored and modified elsewhere. Blocks live in the <tt>blocks</tt> folder.

===Themes===

The overall visual style of a Moodle site, a particular course, or all courses in a category, can be changed by selecting a different theme at these different levels. Themes are the standard way of making aesthetic changes to your Moodle application, decoupling presentation from content and functionality.

Themes live in the <tt>theme</tt> folder, and published themes are listed in the [http://moodle.org/mod/data/view.php?id=6552 Themes database].

===Language packs===

Moodle is internationalised. That is, you can get language packs for many different languages. Language packs are normally downloaded and installed via the Moodle administration screens, but they can also be downloaded manually from [http://download.moodle.org/langpack/ Moodle.org: language packs].

Administrators can also manually change any of the standard user interface strings if the terms used in the installed language pack are not appropriate.

===Course formats===

control how the structure of the course, a sequence of activities grouped into sections, is presented to the users. Course formats live in the <tt>course/format</tt> folder.

===Authentication plugins===

control how users log in. Moodle can manage usernames and passwords itself, or use those stored in LDAP or another database. Alternatively, Moodle can use a number of single-sign-on schemes. Authentication plugins live in the <tt>auth</tt> folder.

===Enrolment plugins===

control which users are enrolled in which courses. Again this can be by synchronising with another system, perhaps a student information system, or it can be tracked internally by Moodle. Enrolment plugins live in the <tt>enrol</tt> folder. (Moodle was created by an Australian, so enrol is the correct spelling ;-).)

===Repository plugins===

Ways for users to get content (files) into Moodle, either by uploading from their hard drive, or by getting the file from another location on the Internet, perhaps Drop Box, Google Docs, or Flickr. Repository plugins live in the <tt>repository</tt> folder.

==How Moodle code is organised==

Moodle mostly follows a [http://martinfowler.com/eaaCatalog/transactionScript.html transaction script] approach. That is, suppose you are looking at a Forum. The URL will be <tt>.../mod/forum/view.php?id=1234</tt>. and <tt>mod/forum/view.php</tt> the PHP script that generates that page. One could argue that transaction script is not an appropriate pattern for an application as complex as Moodle. However, it is a very natural architecture for a PHP application, and Moodle is an aggregate of many different plugins, rather than a single complex application.

Behind that basic transaction script approach, a lot of the core functionality has been refactored out into libraries (mostly in the <tt>lib</tt> folder). This provides elements of a [http://martinfowler.com/eaaCatalog/domainModel.html domain model]. The Moodle project started before PHP could handle object-oriented code, however, so don't expect an object-oriented domain model except in some of the more recent parts of the Moodle code.

There are two layers used to separate presentation from the business logic. The outer layer is the theme (see above) which controls the more visual aspects of the Moodle interface. Then there are renderer classes which generate the HTML to be output from the data supplied by the transaction scripts and the domain model. Unfortunately, neither PHP, nor the Moodle architecture, enforces a clear separation of the UI layer. It is possible for sloppy developers to make a mess, and this has happened in the past. The code in the standard Moodle distribution is gradually being cleaned up.

==The Moodle database==

The Moodle database comprises many tables (more than 250) because the whole database is an aggregate of the core tables and the tables belonging to each plugin. Fortunately, this large structure is understandable, because the tables for one particular plugin typically only link to each other and a few core tables. See [[Database_schema_introduction|Database schema introduction]] for more information.

The Moodle database structure is defined in <tt>install.xml</tt> files inside the <tt>db</tt> folder in each plugin. For example <tt>mod/forum/db/install.xml</tt> contains the database definition for the forum module. <tt>lib/db/install.xml</tt> defines the tables used by Moodle core. The <tt>install.xml</tt> files contain comments that should explain the purpose of each table and column. These comments can be turned into human-readable documentation by going to Site administration -> Development -> XMLDB editor in your Moodle installation, and clicking on the [Doc] link.

==See also==

* [[:en:Administrator documentation]]
* [[Developer_documentation|Developer documentation]]
* [[Database_schema_introduction|Database schema introduction]]
* [http://moodle.org/mod/data/view.php?id=6009 Modules and plugins] and [http://moodle.org/mod/data/view.php?id=6552 themes] databases
* [http://moodle.org/mod/forum/discuss.php?d=64465 Forum thread with a vigorous argument about whether an architecture document is a good idea, which eventually lead to this page being rewritten]
* [http://www.aosabook.org/en/moodle.html The chapter of The Architecture of Open Source Applications about Moodle]

[[Category:Coding guidelines]]

Testing

2018-05-31T13:20:17Z

F4bo: /* QA regression testing */

This page is the top level page regarding all testing activities around the Moodle project. Testing is essential to make sure that developed code does what it is meant to do, without causing new problems.

==Manual testing==

===Code testing===

Code is tested as part of reviewing at some key parts of the [[Process|Moodle development process]].

* Development - the developer of some code should test their own work on a wide variety of environments for correctness and performance
* Peer review - developers often test each others work early in the development process
* Integration reviews - Our integration team tests code weekly while they are evaluating suitability for integration into Moodle.

===Integration functional testing===

On Wednesday (all timezones) our Moodle HQ developers spend the day to manually test the functionality of all the issues that have been integrated that week. Developers submitting patches should always cover the patch with unit tests and/or Behat behavioural tests. Still, all issues are tested by a human and it is usually worth it.

* [[Testing of integrated issues]]

===QA regression testing===

For versions up to 2.4 all the [[QA testing]] was conducted manually before each major release. This process will soon be replaced by a combination of automated systems (see below) and a more lightweight manual user acceptance testing (UAT) cycle involving the Moodle community prior to release.

* [[QA testing]]

==Automated testing==

===Unit tests===

Moodle 2.3 and later fully supports PHPUnit tests as part of the code. These are automated tests of very low-level code functionality that a developer should write as part of any new code.

* [[PHPUnit_integration]]

===Continuous integration testing===

As soon as code is added to the integration repository, our continuous integration server tests the new code for:

* Coding guidelines
* PHPUnit tests
* SimpleTest unit tests on older versions of Moodle
* Detect unresolved merge conflicts
* Compare databases upgraded from previous versions
* Check the version.php is correct

A failure here notifies the integrators that the build has failed.

===QA regression testing===

Every day, an automated build in a test server runs a large number of tests concerning key functions of Moodle, to make sure that everything still works and that some new fix in Moodle hasn't caused problems elsewhere.

These tests must pass completely before a new release can be made.

* [[Acceptance testing]] using the Behat framework
* Performance testing using JMeter.

Moodle uses a sponsored version of [https://www.browserstack.com BrowserStack] for testing on multiple browsers.

[[Category:Quality Assurance]]