<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en">
	<id>https://docs.moodle.org/dev/api.php?action=feedcontributions&amp;feedformat=atom&amp;user=Tmuras</id>
	<title>MoodleDocs - User contributions [en]</title>
	<link rel="self" type="application/atom+xml" href="https://docs.moodle.org/dev/api.php?action=feedcontributions&amp;feedformat=atom&amp;user=Tmuras"/>
	<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/Special:Contributions/Tmuras"/>
	<updated>2026-11-19T19:17:31Z</updated>
	<subtitle>User contributions</subtitle>
	<generator>MediaWiki 1.43.5</generator>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62273</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62273"/>
		<updated>2022-05-04T14:53:24Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: /* Outstanding tasks */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Initial stage - project proposal.&lt;br /&gt;
&lt;br /&gt;
Working proof of concept is implemented: https://github.com/enovation/moodle/tree/MDL-74644_password_policy_new_check&lt;br /&gt;
&lt;br /&gt;
Moodle tracker ticket: https://tracker.moodle.org/browse/MDL-74644&lt;br /&gt;
&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
== Technical details ==&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
&lt;br /&gt;
The default database shipped with the Moodle can be delivered as part of the code - lib/knownpasswords.bin.&lt;br /&gt;
&lt;br /&gt;
==== How to create passwords database ====&lt;br /&gt;
&lt;br /&gt;
# Download password hashes ordered by prevalence from https://haveibeenpwned.com/Passwords&lt;br /&gt;
# Extract&lt;br /&gt;
# Get top 1000000 entries, remove prevalence counts, sort them and convert to binary&lt;br /&gt;
&lt;br /&gt;
 head -n 1000000 pwned-passwords-sha1-ordered-by-count-v8.txt | cut -d: -f1 | sort | xxd -r -p &amp;gt; knownpasswords.bin&lt;br /&gt;
&lt;br /&gt;
==== How to test passwords database ====&lt;br /&gt;
There passwords are stored as SHA-1 hashes, there are no plain-text passwords. However, for testing purposes you can easily guess or search for the most common passwords and be sure that you will find them in the top 1 000 000. For example, the passwords that will sure be there:&lt;br /&gt;
* test&lt;br /&gt;
* password&lt;br /&gt;
* Password1!&lt;br /&gt;
&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
=== Configurable path to the hashes database (file) ===&lt;br /&gt;
Optionally site administrator will be able to upload custom file with SHA-1 hashes data. Such a database could contain much more know hashes and have significant size (tens of gigabytes).&lt;br /&gt;
&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
=== Replace binary search with interpolation search ===&lt;br /&gt;
For big databases, [https://en.wikipedia.org/wiki/Binary_search_algorithm#Interpolation_search interpolation search] should be faster than binary search.&lt;br /&gt;
== Implementation ==&lt;br /&gt;
The core implementation means extending [https://github.com/moodle/moodle/blob/81e5d425c4f17310844d424f0c64e3c9be34ff99/lib/moodlelib.php#L4940 function check_password_policy()] from lib/moodlelib.php with the new check.&lt;br /&gt;
&lt;br /&gt;
The alternative is to implement it as a local plugin and https://docs.moodle.org/dev/Login_callbacks#check_password_policy callback.&lt;br /&gt;
== Risks / negative consequences ==&lt;br /&gt;
=== Performance ===&lt;br /&gt;
If passwordpolicycheckonlogin is enabled, then this check may affect the performance of the site.&lt;br /&gt;
=== Installer size ===&lt;br /&gt;
The size of the Moodle installation package will increase (for example form about 60MB to 80MB).&lt;br /&gt;
== New installations ==&lt;br /&gt;
In the new Moodle installs, known password check should be enabled by default.&lt;br /&gt;
== Upgrading ==&lt;br /&gt;
When upgrading, known password check should be:&lt;br /&gt;
* Enabled if passwordpolicycheckonlogin is false&lt;br /&gt;
* Disabled if passwordpolicycheckonlogin is true&lt;br /&gt;
== Outstanding tasks ==&lt;br /&gt;
* Implement validation when enabling knownpasswordscheck :&lt;br /&gt;
** knownpasswordsdb must be valid hash database. It means: file size % 20 == 0. Hashes should be sorted - so read read first, second, N-th and last hash and check if they are ordered.&lt;br /&gt;
* Implement logic when upgrading Moodle&lt;br /&gt;
* Write unit tests&lt;br /&gt;
* Update documentation - https://docs.moodle.org/400/en/Site_security_settings&lt;br /&gt;
&lt;br /&gt;
[[Category:Project]]&lt;br /&gt;
&lt;br /&gt;
== Mockups ==&lt;br /&gt;
&lt;br /&gt;
=== New settings ===&lt;br /&gt;
[[File:pass policy settings.png]]&lt;br /&gt;
&lt;br /&gt;
=== Error when adding new user ===&lt;br /&gt;
[[File:pass policy add new user.png]]&lt;br /&gt;
&lt;br /&gt;
=== Error during password change ===&lt;br /&gt;
[[File:pass policy password change.png]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62272</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62272"/>
		<updated>2022-05-04T14:53:12Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: /* Outstanding tasks */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Initial stage - project proposal.&lt;br /&gt;
&lt;br /&gt;
Working proof of concept is implemented: https://github.com/enovation/moodle/tree/MDL-74644_password_policy_new_check&lt;br /&gt;
&lt;br /&gt;
Moodle tracker ticket: https://tracker.moodle.org/browse/MDL-74644&lt;br /&gt;
&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
== Technical details ==&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
&lt;br /&gt;
The default database shipped with the Moodle can be delivered as part of the code - lib/knownpasswords.bin.&lt;br /&gt;
&lt;br /&gt;
==== How to create passwords database ====&lt;br /&gt;
&lt;br /&gt;
# Download password hashes ordered by prevalence from https://haveibeenpwned.com/Passwords&lt;br /&gt;
# Extract&lt;br /&gt;
# Get top 1000000 entries, remove prevalence counts, sort them and convert to binary&lt;br /&gt;
&lt;br /&gt;
 head -n 1000000 pwned-passwords-sha1-ordered-by-count-v8.txt | cut -d: -f1 | sort | xxd -r -p &amp;gt; knownpasswords.bin&lt;br /&gt;
&lt;br /&gt;
==== How to test passwords database ====&lt;br /&gt;
There passwords are stored as SHA-1 hashes, there are no plain-text passwords. However, for testing purposes you can easily guess or search for the most common passwords and be sure that you will find them in the top 1 000 000. For example, the passwords that will sure be there:&lt;br /&gt;
* test&lt;br /&gt;
* password&lt;br /&gt;
* Password1!&lt;br /&gt;
&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
=== Configurable path to the hashes database (file) ===&lt;br /&gt;
Optionally site administrator will be able to upload custom file with SHA-1 hashes data. Such a database could contain much more know hashes and have significant size (tens of gigabytes).&lt;br /&gt;
&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
=== Replace binary search with interpolation search ===&lt;br /&gt;
For big databases, [https://en.wikipedia.org/wiki/Binary_search_algorithm#Interpolation_search interpolation search] should be faster than binary search.&lt;br /&gt;
== Implementation ==&lt;br /&gt;
The core implementation means extending [https://github.com/moodle/moodle/blob/81e5d425c4f17310844d424f0c64e3c9be34ff99/lib/moodlelib.php#L4940 function check_password_policy()] from lib/moodlelib.php with the new check.&lt;br /&gt;
&lt;br /&gt;
The alternative is to implement it as a local plugin and https://docs.moodle.org/dev/Login_callbacks#check_password_policy callback.&lt;br /&gt;
== Risks / negative consequences ==&lt;br /&gt;
=== Performance ===&lt;br /&gt;
If passwordpolicycheckonlogin is enabled, then this check may affect the performance of the site.&lt;br /&gt;
=== Installer size ===&lt;br /&gt;
The size of the Moodle installation package will increase (for example form about 60MB to 80MB).&lt;br /&gt;
== New installations ==&lt;br /&gt;
In the new Moodle installs, known password check should be enabled by default.&lt;br /&gt;
== Upgrading ==&lt;br /&gt;
When upgrading, known password check should be:&lt;br /&gt;
* Enabled if passwordpolicycheckonlogin is false&lt;br /&gt;
* Disabled if passwordpolicycheckonlogin is true&lt;br /&gt;
== Outstanding tasks ==&lt;br /&gt;
* Implement validation when enabling knownpasswordscheck :&lt;br /&gt;
** knownpasswordsdb must be valid hash database. It means: file size % 20 == 0. Hashes should be sorted - so read read first, second, N-th and last hashes and check if they are ordered.&lt;br /&gt;
* Implement logic when upgrading Moodle&lt;br /&gt;
* Write unit tests&lt;br /&gt;
* Update documentation - https://docs.moodle.org/400/en/Site_security_settings&lt;br /&gt;
&lt;br /&gt;
[[Category:Project]]&lt;br /&gt;
&lt;br /&gt;
== Mockups ==&lt;br /&gt;
&lt;br /&gt;
=== New settings ===&lt;br /&gt;
[[File:pass policy settings.png]]&lt;br /&gt;
&lt;br /&gt;
=== Error when adding new user ===&lt;br /&gt;
[[File:pass policy add new user.png]]&lt;br /&gt;
&lt;br /&gt;
=== Error during password change ===&lt;br /&gt;
[[File:pass policy password change.png]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62251</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62251"/>
		<updated>2022-05-04T10:30:33Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: /* Outstanding tasks */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Initial stage - project proposal.&lt;br /&gt;
&lt;br /&gt;
Working proof of concept is implemented: https://github.com/enovation/moodle/tree/MDL-74644_password_policy_new_check&lt;br /&gt;
&lt;br /&gt;
Moodle tracker ticket: https://tracker.moodle.org/browse/MDL-74644&lt;br /&gt;
&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
== Technical details ==&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
&lt;br /&gt;
The default database shipped with the Moodle can be delivered as part of the code - lib/knownpasswords.bin.&lt;br /&gt;
&lt;br /&gt;
==== How to create passwords database ====&lt;br /&gt;
&lt;br /&gt;
# Download password hashes ordered by prevalence from https://haveibeenpwned.com/Passwords&lt;br /&gt;
# Extract&lt;br /&gt;
# Get top 1000000 entries, remove prevalence counts, sort them and convert to binary&lt;br /&gt;
&lt;br /&gt;
 head -n 1000000 pwned-passwords-sha1-ordered-by-count-v8.txt | cut -d: -f1 | sort | xxd -r -p &amp;gt; knownpasswords.bin&lt;br /&gt;
&lt;br /&gt;
==== How to test passwords database ====&lt;br /&gt;
There passwords are stored as SHA-1 hashes, there are no plain-text passwords. However, for testing purposes you can easily guess or search for the most common passwords and be sure that you will find them in the top 1 000 000. For example, the passwords that will sure be there:&lt;br /&gt;
* test&lt;br /&gt;
* password&lt;br /&gt;
* Password1!&lt;br /&gt;
&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
=== Configurable path to the hashes database (file) ===&lt;br /&gt;
Optionally site administrator will be able to upload custom file with SHA-1 hashes data. Such a database could contain much more know hashes and have significant size (tens of gigabytes).&lt;br /&gt;
&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
=== Replace binary search with interpolation search ===&lt;br /&gt;
For big databases, [https://en.wikipedia.org/wiki/Binary_search_algorithm#Interpolation_search interpolation search] should be faster than binary search.&lt;br /&gt;
== Implementation ==&lt;br /&gt;
The core implementation means extending [https://github.com/moodle/moodle/blob/81e5d425c4f17310844d424f0c64e3c9be34ff99/lib/moodlelib.php#L4940 function check_password_policy()] from lib/moodlelib.php with the new check.&lt;br /&gt;
&lt;br /&gt;
The alternative is to implement it as a local plugin and https://docs.moodle.org/dev/Login_callbacks#check_password_policy callback.&lt;br /&gt;
== Risks / negative consequences ==&lt;br /&gt;
=== Performance ===&lt;br /&gt;
If passwordpolicycheckonlogin is enabled, then this check may affect the performance of the site.&lt;br /&gt;
=== Installer size ===&lt;br /&gt;
The size of the Moodle installation package will increase (for example form about 60MB to 80MB).&lt;br /&gt;
== New installations ==&lt;br /&gt;
In the new Moodle installs, known password check should be enabled by default.&lt;br /&gt;
== Upgrading ==&lt;br /&gt;
When upgrading, known password check should be:&lt;br /&gt;
* Enabled if passwordpolicycheckonlogin is false&lt;br /&gt;
* Disabled if passwordpolicycheckonlogin is true&lt;br /&gt;
== Outstanding tasks ==&lt;br /&gt;
* Implement validation when enabling knownpasswordscheck :&lt;br /&gt;
** knownpasswordsdb must be valid hash database&lt;br /&gt;
* Implement logic when upgrading Moodle&lt;br /&gt;
* Write unit tests&lt;br /&gt;
* Update documentation - https://docs.moodle.org/400/en/Site_security_settings&lt;br /&gt;
&lt;br /&gt;
[[Category:Project]]&lt;br /&gt;
&lt;br /&gt;
== Mockups ==&lt;br /&gt;
&lt;br /&gt;
=== New settings ===&lt;br /&gt;
[[File:pass policy settings.png]]&lt;br /&gt;
&lt;br /&gt;
=== Error when adding new user ===&lt;br /&gt;
[[File:pass policy add new user.png]]&lt;br /&gt;
&lt;br /&gt;
=== Error during password change ===&lt;br /&gt;
[[File:pass policy password change.png]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62250</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62250"/>
		<updated>2022-05-04T10:29:00Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: /* Tasks */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Initial stage - project proposal.&lt;br /&gt;
&lt;br /&gt;
Working proof of concept is implemented: https://github.com/enovation/moodle/tree/MDL-74644_password_policy_new_check&lt;br /&gt;
&lt;br /&gt;
Moodle tracker ticket: https://tracker.moodle.org/browse/MDL-74644&lt;br /&gt;
&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
== Technical details ==&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
&lt;br /&gt;
The default database shipped with the Moodle can be delivered as part of the code - lib/knownpasswords.bin.&lt;br /&gt;
&lt;br /&gt;
==== How to create passwords database ====&lt;br /&gt;
&lt;br /&gt;
# Download password hashes ordered by prevalence from https://haveibeenpwned.com/Passwords&lt;br /&gt;
# Extract&lt;br /&gt;
# Get top 1000000 entries, remove prevalence counts, sort them and convert to binary&lt;br /&gt;
&lt;br /&gt;
 head -n 1000000 pwned-passwords-sha1-ordered-by-count-v8.txt | cut -d: -f1 | sort | xxd -r -p &amp;gt; knownpasswords.bin&lt;br /&gt;
&lt;br /&gt;
==== How to test passwords database ====&lt;br /&gt;
There passwords are stored as SHA-1 hashes, there are no plain-text passwords. However, for testing purposes you can easily guess or search for the most common passwords and be sure that you will find them in the top 1 000 000. For example, the passwords that will sure be there:&lt;br /&gt;
* test&lt;br /&gt;
* password&lt;br /&gt;
* Password1!&lt;br /&gt;
&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
=== Configurable path to the hashes database (file) ===&lt;br /&gt;
Optionally site administrator will be able to upload custom file with SHA-1 hashes data. Such a database could contain much more know hashes and have significant size (tens of gigabytes).&lt;br /&gt;
&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
=== Replace binary search with interpolation search ===&lt;br /&gt;
For big databases, [https://en.wikipedia.org/wiki/Binary_search_algorithm#Interpolation_search interpolation search] should be faster than binary search.&lt;br /&gt;
== Implementation ==&lt;br /&gt;
The core implementation means extending [https://github.com/moodle/moodle/blob/81e5d425c4f17310844d424f0c64e3c9be34ff99/lib/moodlelib.php#L4940 function check_password_policy()] from lib/moodlelib.php with the new check.&lt;br /&gt;
&lt;br /&gt;
The alternative is to implement it as a local plugin and https://docs.moodle.org/dev/Login_callbacks#check_password_policy callback.&lt;br /&gt;
== Risks / negative consequences ==&lt;br /&gt;
=== Performance ===&lt;br /&gt;
If passwordpolicycheckonlogin is enabled, then this check may affect the performance of the site.&lt;br /&gt;
=== Installer size ===&lt;br /&gt;
The size of the Moodle installation package will increase (for example form about 60MB to 80MB).&lt;br /&gt;
== New installations ==&lt;br /&gt;
In the new Moodle installs, known password check should be enabled by default.&lt;br /&gt;
== Upgrading ==&lt;br /&gt;
When upgrading, known password check should be:&lt;br /&gt;
* Enabled if passwordpolicycheckonlogin is false&lt;br /&gt;
* Disabled if passwordpolicycheckonlogin is true&lt;br /&gt;
== Outstanding tasks ==&lt;br /&gt;
* Implement validation when enabling knownpasswordscheck :&lt;br /&gt;
** knownpasswordsdb must be valid hash database&lt;br /&gt;
* Write unit tests&lt;br /&gt;
&lt;br /&gt;
[[Category:Project]]&lt;br /&gt;
&lt;br /&gt;
== Mockups ==&lt;br /&gt;
&lt;br /&gt;
=== New settings ===&lt;br /&gt;
[[File:pass policy settings.png]]&lt;br /&gt;
&lt;br /&gt;
=== Error when adding new user ===&lt;br /&gt;
[[File:pass policy add new user.png]]&lt;br /&gt;
&lt;br /&gt;
=== Error during password change ===&lt;br /&gt;
[[File:pass policy password change.png]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62249</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62249"/>
		<updated>2022-05-04T10:28:23Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: /* Status */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Initial stage - project proposal.&lt;br /&gt;
&lt;br /&gt;
Working proof of concept is implemented: https://github.com/enovation/moodle/tree/MDL-74644_password_policy_new_check&lt;br /&gt;
&lt;br /&gt;
Moodle tracker ticket: https://tracker.moodle.org/browse/MDL-74644&lt;br /&gt;
&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
== Technical details ==&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
&lt;br /&gt;
The default database shipped with the Moodle can be delivered as part of the code - lib/knownpasswords.bin.&lt;br /&gt;
&lt;br /&gt;
==== How to create passwords database ====&lt;br /&gt;
&lt;br /&gt;
# Download password hashes ordered by prevalence from https://haveibeenpwned.com/Passwords&lt;br /&gt;
# Extract&lt;br /&gt;
# Get top 1000000 entries, remove prevalence counts, sort them and convert to binary&lt;br /&gt;
&lt;br /&gt;
 head -n 1000000 pwned-passwords-sha1-ordered-by-count-v8.txt | cut -d: -f1 | sort | xxd -r -p &amp;gt; knownpasswords.bin&lt;br /&gt;
&lt;br /&gt;
==== How to test passwords database ====&lt;br /&gt;
There passwords are stored as SHA-1 hashes, there are no plain-text passwords. However, for testing purposes you can easily guess or search for the most common passwords and be sure that you will find them in the top 1 000 000. For example, the passwords that will sure be there:&lt;br /&gt;
* test&lt;br /&gt;
* password&lt;br /&gt;
* Password1!&lt;br /&gt;
&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
=== Configurable path to the hashes database (file) ===&lt;br /&gt;
Optionally site administrator will be able to upload custom file with SHA-1 hashes data. Such a database could contain much more know hashes and have significant size (tens of gigabytes).&lt;br /&gt;
&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
=== Replace binary search with interpolation search ===&lt;br /&gt;
For big databases, [https://en.wikipedia.org/wiki/Binary_search_algorithm#Interpolation_search interpolation search] should be faster than binary search.&lt;br /&gt;
== Implementation ==&lt;br /&gt;
The core implementation means extending [https://github.com/moodle/moodle/blob/81e5d425c4f17310844d424f0c64e3c9be34ff99/lib/moodlelib.php#L4940 function check_password_policy()] from lib/moodlelib.php with the new check.&lt;br /&gt;
&lt;br /&gt;
The alternative is to implement it as a local plugin and https://docs.moodle.org/dev/Login_callbacks#check_password_policy callback.&lt;br /&gt;
== Risks / negative consequences ==&lt;br /&gt;
=== Performance ===&lt;br /&gt;
If passwordpolicycheckonlogin is enabled, then this check may affect the performance of the site.&lt;br /&gt;
=== Installer size ===&lt;br /&gt;
The size of the Moodle installation package will increase (for example form about 60MB to 80MB).&lt;br /&gt;
== New installations ==&lt;br /&gt;
In the new Moodle installs, known password check should be enabled by default.&lt;br /&gt;
== Upgrading ==&lt;br /&gt;
When upgrading, known password check should be:&lt;br /&gt;
* Enabled if passwordpolicycheckonlogin is false&lt;br /&gt;
* Disabled if passwordpolicycheckonlogin is true&lt;br /&gt;
== Tasks ==&lt;br /&gt;
* Implement function for validating hash database:&lt;br /&gt;
** File size &amp;gt; 0&lt;br /&gt;
** File size is multiplication of 20 bytes&lt;br /&gt;
* Implement validation when enabling knownpasswordscheck :&lt;br /&gt;
** knownpasswordsdb must be valid hash database&lt;br /&gt;
* Write unit tests&lt;br /&gt;
[[Category:Project]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
== Mockups ==&lt;br /&gt;
&lt;br /&gt;
=== New settings ===&lt;br /&gt;
[[File:pass policy settings.png]]&lt;br /&gt;
&lt;br /&gt;
=== Error when adding new user ===&lt;br /&gt;
[[File:pass policy add new user.png]]&lt;br /&gt;
&lt;br /&gt;
=== Error during password change ===&lt;br /&gt;
[[File:pass policy password change.png]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62248</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62248"/>
		<updated>2022-05-04T09:31:06Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: /* Technical details */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Very initial stage - project proposal.&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
== Technical details ==&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
&lt;br /&gt;
The default database shipped with the Moodle can be delivered as part of the code - lib/knownpasswords.bin.&lt;br /&gt;
&lt;br /&gt;
==== How to create passwords database ====&lt;br /&gt;
&lt;br /&gt;
# Download password hashes ordered by prevalence from https://haveibeenpwned.com/Passwords&lt;br /&gt;
# Extract&lt;br /&gt;
# Get top 1000000 entries, remove prevalence counts, sort them and convert to binary&lt;br /&gt;
&lt;br /&gt;
 head -n 1000000 pwned-passwords-sha1-ordered-by-count-v8.txt | cut -d: -f1 | sort | xxd -r -p &amp;gt; knownpasswords.bin&lt;br /&gt;
&lt;br /&gt;
==== How to test passwords database ====&lt;br /&gt;
There passwords are stored as SHA-1 hashes, there are no plain-text passwords. However, for testing purposes you can easily guess or search for the most common passwords and be sure that you will find them in the top 1 000 000. For example, the passwords that will sure be there:&lt;br /&gt;
* test&lt;br /&gt;
* password&lt;br /&gt;
* Password1!&lt;br /&gt;
&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
=== Configurable path to the hashes database (file) ===&lt;br /&gt;
Optionally site administrator will be able to upload custom file with SHA-1 hashes data. Such a database could contain much more know hashes and have significant size (tens of gigabytes).&lt;br /&gt;
&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
=== Replace binary search with interpolation search ===&lt;br /&gt;
For big databases, [https://en.wikipedia.org/wiki/Binary_search_algorithm#Interpolation_search interpolation search] should be faster than binary search.&lt;br /&gt;
== Implementation ==&lt;br /&gt;
The core implementation means extending [https://github.com/moodle/moodle/blob/81e5d425c4f17310844d424f0c64e3c9be34ff99/lib/moodlelib.php#L4940 function check_password_policy()] from lib/moodlelib.php with the new check.&lt;br /&gt;
&lt;br /&gt;
The alternative is to implement it as a local plugin and https://docs.moodle.org/dev/Login_callbacks#check_password_policy callback.&lt;br /&gt;
== Risks / negative consequences ==&lt;br /&gt;
=== Performance ===&lt;br /&gt;
If passwordpolicycheckonlogin is enabled, then this check may affect the performance of the site.&lt;br /&gt;
=== Installer size ===&lt;br /&gt;
The size of the Moodle installation package will increase (for example form about 60MB to 80MB).&lt;br /&gt;
== New installations ==&lt;br /&gt;
In the new Moodle installs, known password check should be enabled by default.&lt;br /&gt;
== Upgrading ==&lt;br /&gt;
When upgrading, known password check should be:&lt;br /&gt;
* Enabled if passwordpolicycheckonlogin is false&lt;br /&gt;
* Disabled if passwordpolicycheckonlogin is true&lt;br /&gt;
== Tasks ==&lt;br /&gt;
* Implement function for validating hash database:&lt;br /&gt;
** File size &amp;gt; 0&lt;br /&gt;
** File size is multiplication of 20 bytes&lt;br /&gt;
* Implement validation when enabling knownpasswordscheck :&lt;br /&gt;
** knownpasswordsdb must be valid hash database&lt;br /&gt;
* Write unit tests&lt;br /&gt;
[[Category:Project]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
== Mockups ==&lt;br /&gt;
&lt;br /&gt;
=== New settings ===&lt;br /&gt;
[[File:pass policy settings.png]]&lt;br /&gt;
&lt;br /&gt;
=== Error when adding new user ===&lt;br /&gt;
[[File:pass policy add new user.png]]&lt;br /&gt;
&lt;br /&gt;
=== Error during password change ===&lt;br /&gt;
[[File:pass policy password change.png]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62247</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62247"/>
		<updated>2022-05-04T09:12:36Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: /* How to create passwords database */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Very initial stage - project proposal.&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
== Technical details ==&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
&lt;br /&gt;
The default database shipped with the Moodle can be delivered as part of the code - lib/knownpasswords.bin.&lt;br /&gt;
&lt;br /&gt;
==== How to create passwords database ====&lt;br /&gt;
&lt;br /&gt;
# Download password hashes ordered by prevalence from https://haveibeenpwned.com/Passwords&lt;br /&gt;
# Extract&lt;br /&gt;
# Get top 1000000 entries, remove prevalence counts, sort them and convert to binary&lt;br /&gt;
&lt;br /&gt;
 head -n 1000000 pwned-passwords-sha1-ordered-by-count-v8.txt | cut -d: -f1 | sort | xxd -r -p &amp;gt; knownpasswords.bin&lt;br /&gt;
&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
=== Configurable path to the hashes database (file) ===&lt;br /&gt;
Optionally site administrator will be able to upload custom file with SHA-1 hashes data. Such a database could contain much more know hashes and have significant size (tens of gigabytes).&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
=== Replace binary search with interpolation search ===&lt;br /&gt;
For big databases, [https://en.wikipedia.org/wiki/Binary_search_algorithm#Interpolation_search interpolation search] should be faster than binary search.&lt;br /&gt;
== Implementation ==&lt;br /&gt;
The core implementation means extending [https://github.com/moodle/moodle/blob/81e5d425c4f17310844d424f0c64e3c9be34ff99/lib/moodlelib.php#L4940 function check_password_policy()] from lib/moodlelib.php with the new check.&lt;br /&gt;
&lt;br /&gt;
The alternative is to implement it as a local plugin and https://docs.moodle.org/dev/Login_callbacks#check_password_policy callback.&lt;br /&gt;
== Risks / negative consequences ==&lt;br /&gt;
=== Performance ===&lt;br /&gt;
If passwordpolicycheckonlogin is enabled, then this check may affect the performance of the site.&lt;br /&gt;
=== Installer size ===&lt;br /&gt;
The size of the Moodle installation package will increase (for example form about 60MB to 80MB).&lt;br /&gt;
== New installations ==&lt;br /&gt;
In the new Moodle installs, known password check should be enabled by default.&lt;br /&gt;
== Upgrading ==&lt;br /&gt;
When upgrading, known password check should be:&lt;br /&gt;
* Enabled if passwordpolicycheckonlogin is false&lt;br /&gt;
* Disabled if passwordpolicycheckonlogin is true&lt;br /&gt;
== Tasks ==&lt;br /&gt;
* Implement function for validating hash database:&lt;br /&gt;
** File size &amp;gt; 0&lt;br /&gt;
** File size is multiplication of 20 bytes&lt;br /&gt;
* Implement validation when enabling knownpasswordscheck :&lt;br /&gt;
** knownpasswordsdb must be valid hash database&lt;br /&gt;
* Write unit tests&lt;br /&gt;
[[Category:Project]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
== Mockups ==&lt;br /&gt;
&lt;br /&gt;
=== New settings ===&lt;br /&gt;
[[File:pass policy settings.png]]&lt;br /&gt;
&lt;br /&gt;
=== Error when adding new user ===&lt;br /&gt;
[[File:pass policy add new user.png]]&lt;br /&gt;
&lt;br /&gt;
=== Error during password change ===&lt;br /&gt;
[[File:pass policy password change.png]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62246</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62246"/>
		<updated>2022-05-04T09:10:58Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: /* How to create passwords database */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Very initial stage - project proposal.&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
== Technical details ==&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
&lt;br /&gt;
The default database shipped with the Moodle can be delivered as part of the code - lib/knownpasswords.bin.&lt;br /&gt;
&lt;br /&gt;
==== How to create passwords database ====&lt;br /&gt;
&lt;br /&gt;
# Download password hashes ordered by prevalence from https://haveibeenpwned.com/Passwords&lt;br /&gt;
# Extract&lt;br /&gt;
# Get top 1000000 entries, sort them and convert to binary&lt;br /&gt;
&lt;br /&gt;
 head -n 1000000 pwned-passwords-sha1-ordered-by-count-v8.txt | cut -d: -f1 | sort | xxd -r -p &amp;gt; knownpasswords.bin&lt;br /&gt;
&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
=== Configurable path to the hashes database (file) ===&lt;br /&gt;
Optionally site administrator will be able to upload custom file with SHA-1 hashes data. Such a database could contain much more know hashes and have significant size (tens of gigabytes).&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
=== Replace binary search with interpolation search ===&lt;br /&gt;
For big databases, [https://en.wikipedia.org/wiki/Binary_search_algorithm#Interpolation_search interpolation search] should be faster than binary search.&lt;br /&gt;
== Implementation ==&lt;br /&gt;
The core implementation means extending [https://github.com/moodle/moodle/blob/81e5d425c4f17310844d424f0c64e3c9be34ff99/lib/moodlelib.php#L4940 function check_password_policy()] from lib/moodlelib.php with the new check.&lt;br /&gt;
&lt;br /&gt;
The alternative is to implement it as a local plugin and https://docs.moodle.org/dev/Login_callbacks#check_password_policy callback.&lt;br /&gt;
== Risks / negative consequences ==&lt;br /&gt;
=== Performance ===&lt;br /&gt;
If passwordpolicycheckonlogin is enabled, then this check may affect the performance of the site.&lt;br /&gt;
=== Installer size ===&lt;br /&gt;
The size of the Moodle installation package will increase (for example form about 60MB to 80MB).&lt;br /&gt;
== New installations ==&lt;br /&gt;
In the new Moodle installs, known password check should be enabled by default.&lt;br /&gt;
== Upgrading ==&lt;br /&gt;
When upgrading, known password check should be:&lt;br /&gt;
* Enabled if passwordpolicycheckonlogin is false&lt;br /&gt;
* Disabled if passwordpolicycheckonlogin is true&lt;br /&gt;
== Tasks ==&lt;br /&gt;
* Implement function for validating hash database:&lt;br /&gt;
** File size &amp;gt; 0&lt;br /&gt;
** File size is multiplication of 20 bytes&lt;br /&gt;
* Implement validation when enabling knownpasswordscheck :&lt;br /&gt;
** knownpasswordsdb must be valid hash database&lt;br /&gt;
* Write unit tests&lt;br /&gt;
[[Category:Project]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
== Mockups ==&lt;br /&gt;
&lt;br /&gt;
=== New settings ===&lt;br /&gt;
[[File:pass policy settings.png]]&lt;br /&gt;
&lt;br /&gt;
=== Error when adding new user ===&lt;br /&gt;
[[File:pass policy add new user.png]]&lt;br /&gt;
&lt;br /&gt;
=== Error during password change ===&lt;br /&gt;
[[File:pass policy password change.png]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62245</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62245"/>
		<updated>2022-05-04T07:40:57Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: /* How to create passwords database */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Very initial stage - project proposal.&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
== Technical details ==&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
&lt;br /&gt;
The default database shipped with the Moodle can be delivered as part of the code - lib/knownpasswords.bin.&lt;br /&gt;
&lt;br /&gt;
==== How to create passwords database ====&lt;br /&gt;
&lt;br /&gt;
# Download password hashes ordered by prevalence from https://haveibeenpwned.com/Passwords&lt;br /&gt;
# Extract&lt;br /&gt;
# Get top 1000000 entries, sort them and convert to binary&lt;br /&gt;
&lt;br /&gt;
 head -n 1000000 pwned-passwords-sha1-ordered-by-count-v8.txt | cut -d: -f1 | sort | xxd -r -p &amp;gt; pwned-top-million-by-count-v8.sha1&lt;br /&gt;
&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
=== Configurable path to the hashes database (file) ===&lt;br /&gt;
Optionally site administrator will be able to upload custom file with SHA-1 hashes data. Such a database could contain much more know hashes and have significant size (tens of gigabytes).&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
=== Replace binary search with interpolation search ===&lt;br /&gt;
For big databases, [https://en.wikipedia.org/wiki/Binary_search_algorithm#Interpolation_search interpolation search] should be faster than binary search.&lt;br /&gt;
== Implementation ==&lt;br /&gt;
The core implementation means extending [https://github.com/moodle/moodle/blob/81e5d425c4f17310844d424f0c64e3c9be34ff99/lib/moodlelib.php#L4940 function check_password_policy()] from lib/moodlelib.php with the new check.&lt;br /&gt;
&lt;br /&gt;
The alternative is to implement it as a local plugin and https://docs.moodle.org/dev/Login_callbacks#check_password_policy callback.&lt;br /&gt;
== Risks / negative consequences ==&lt;br /&gt;
=== Performance ===&lt;br /&gt;
If passwordpolicycheckonlogin is enabled, then this check may affect the performance of the site.&lt;br /&gt;
=== Installer size ===&lt;br /&gt;
The size of the Moodle installation package will increase (for example form about 60MB to 80MB).&lt;br /&gt;
== New installations ==&lt;br /&gt;
In the new Moodle installs, known password check should be enabled by default.&lt;br /&gt;
== Upgrading ==&lt;br /&gt;
When upgrading, known password check should be:&lt;br /&gt;
* Enabled if passwordpolicycheckonlogin is false&lt;br /&gt;
* Disabled if passwordpolicycheckonlogin is true&lt;br /&gt;
== Tasks ==&lt;br /&gt;
* Implement function for validating hash database:&lt;br /&gt;
** File size &amp;gt; 0&lt;br /&gt;
** File size is multiplication of 20 bytes&lt;br /&gt;
* Implement validation when enabling knownpasswordscheck :&lt;br /&gt;
** knownpasswordsdb must be valid hash database&lt;br /&gt;
* Write unit tests&lt;br /&gt;
[[Category:Project]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
== Mockups ==&lt;br /&gt;
&lt;br /&gt;
=== New settings ===&lt;br /&gt;
[[File:pass policy settings.png]]&lt;br /&gt;
&lt;br /&gt;
=== Error when adding new user ===&lt;br /&gt;
[[File:pass policy add new user.png]]&lt;br /&gt;
&lt;br /&gt;
=== Error during password change ===&lt;br /&gt;
[[File:pass policy password change.png]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62244</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62244"/>
		<updated>2022-05-04T07:37:25Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: /* Password database */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Very initial stage - project proposal.&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
== Technical details ==&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
&lt;br /&gt;
The default database shipped with the Moodle can be delivered as part of the code - lib/knownpasswords.bin.&lt;br /&gt;
&lt;br /&gt;
==== How to create passwords database ====&lt;br /&gt;
&lt;br /&gt;
# Download password hashes ordered by prevalence from https://haveibeenpwned.com/Passwords&lt;br /&gt;
# Extract&lt;br /&gt;
# Get top 1000000 entries and sort them&lt;br /&gt;
&lt;br /&gt;
 head -n 1000000 pwned-passwords-sha1-ordered-by-count-v8.txt | cut -d: -f1 | sort &amp;gt; pwned-top-million-by-count-v8.sha1&lt;br /&gt;
&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
=== Configurable path to the hashes database (file) ===&lt;br /&gt;
Optionally site administrator will be able to upload custom file with SHA-1 hashes data. Such a database could contain much more know hashes and have significant size (tens of gigabytes).&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
=== Replace binary search with interpolation search ===&lt;br /&gt;
For big databases, [https://en.wikipedia.org/wiki/Binary_search_algorithm#Interpolation_search interpolation search] should be faster than binary search.&lt;br /&gt;
== Implementation ==&lt;br /&gt;
The core implementation means extending [https://github.com/moodle/moodle/blob/81e5d425c4f17310844d424f0c64e3c9be34ff99/lib/moodlelib.php#L4940 function check_password_policy()] from lib/moodlelib.php with the new check.&lt;br /&gt;
&lt;br /&gt;
The alternative is to implement it as a local plugin and https://docs.moodle.org/dev/Login_callbacks#check_password_policy callback.&lt;br /&gt;
== Risks / negative consequences ==&lt;br /&gt;
=== Performance ===&lt;br /&gt;
If passwordpolicycheckonlogin is enabled, then this check may affect the performance of the site.&lt;br /&gt;
=== Installer size ===&lt;br /&gt;
The size of the Moodle installation package will increase (for example form about 60MB to 80MB).&lt;br /&gt;
== New installations ==&lt;br /&gt;
In the new Moodle installs, known password check should be enabled by default.&lt;br /&gt;
== Upgrading ==&lt;br /&gt;
When upgrading, known password check should be:&lt;br /&gt;
* Enabled if passwordpolicycheckonlogin is false&lt;br /&gt;
* Disabled if passwordpolicycheckonlogin is true&lt;br /&gt;
== Tasks ==&lt;br /&gt;
* Implement function for validating hash database:&lt;br /&gt;
** File size &amp;gt; 0&lt;br /&gt;
** File size is multiplication of 20 bytes&lt;br /&gt;
* Implement validation when enabling knownpasswordscheck :&lt;br /&gt;
** knownpasswordsdb must be valid hash database&lt;br /&gt;
* Write unit tests&lt;br /&gt;
[[Category:Project]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
== Mockups ==&lt;br /&gt;
&lt;br /&gt;
=== New settings ===&lt;br /&gt;
[[File:pass policy settings.png]]&lt;br /&gt;
&lt;br /&gt;
=== Error when adding new user ===&lt;br /&gt;
[[File:pass policy add new user.png]]&lt;br /&gt;
&lt;br /&gt;
=== Error during password change ===&lt;br /&gt;
[[File:pass policy password change.png]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62192</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62192"/>
		<updated>2022-04-29T14:25:05Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: /* Mockups */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Very initial stage - project proposal.&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
== Technical details ==&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
&lt;br /&gt;
The default database shipped with the Moodle can be delivered as part of the code - lib/knownpasswords.bin.&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
=== Configurable path to the hashes database (file) ===&lt;br /&gt;
Optionally site administrator will be able to upload custom file with SHA-1 hashes data. Such a database could contain much more know hashes and have significant size (tens of gigabytes).&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
=== Replace binary search with interpolation search ===&lt;br /&gt;
For big databases, [https://en.wikipedia.org/wiki/Binary_search_algorithm#Interpolation_search interpolation search] should be faster than binary search.&lt;br /&gt;
== Implementation ==&lt;br /&gt;
The core implementation means extending [https://github.com/moodle/moodle/blob/81e5d425c4f17310844d424f0c64e3c9be34ff99/lib/moodlelib.php#L4940 function check_password_policy()] from lib/moodlelib.php with the new check.&lt;br /&gt;
&lt;br /&gt;
The alternative is to implement it as a local plugin and https://docs.moodle.org/dev/Login_callbacks#check_password_policy callback.&lt;br /&gt;
== Risks / negative consequences ==&lt;br /&gt;
=== Performance ===&lt;br /&gt;
If passwordpolicycheckonlogin is enabled, then this check may affect the performance of the site.&lt;br /&gt;
=== Installer size ===&lt;br /&gt;
The size of the Moodle installation package will increase (for example form about 60MB to 80MB).&lt;br /&gt;
== New installations ==&lt;br /&gt;
In the new Moodle installs, known password check should be enabled by default.&lt;br /&gt;
== Upgrading ==&lt;br /&gt;
When upgrading, known password check should be:&lt;br /&gt;
* Enabled if passwordpolicycheckonlogin is false&lt;br /&gt;
* Disabled if passwordpolicycheckonlogin is true&lt;br /&gt;
== Tasks ==&lt;br /&gt;
* Implement function for validating hash database:&lt;br /&gt;
** File size &amp;gt; 0&lt;br /&gt;
** File size is multiplication of 20 bytes&lt;br /&gt;
* Implement validation when enabling knownpasswordscheck :&lt;br /&gt;
** knownpasswordsdb must be valid hash database&lt;br /&gt;
* Write unit tests&lt;br /&gt;
[[Category:Project]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
== Mockups ==&lt;br /&gt;
&lt;br /&gt;
=== New settings ===&lt;br /&gt;
[[File:pass policy settings.png]]&lt;br /&gt;
&lt;br /&gt;
=== Error when adding new user ===&lt;br /&gt;
[[File:pass policy add new user.png]]&lt;br /&gt;
&lt;br /&gt;
=== Error during password change ===&lt;br /&gt;
[[File:pass policy password change.png]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62191</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62191"/>
		<updated>2022-04-29T14:23:03Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: /* Mockups */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Very initial stage - project proposal.&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
== Technical details ==&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
&lt;br /&gt;
The default database shipped with the Moodle can be delivered as part of the code - lib/knownpasswords.bin.&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
=== Configurable path to the hashes database (file) ===&lt;br /&gt;
Optionally site administrator will be able to upload custom file with SHA-1 hashes data. Such a database could contain much more know hashes and have significant size (tens of gigabytes).&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
=== Replace binary search with interpolation search ===&lt;br /&gt;
For big databases, [https://en.wikipedia.org/wiki/Binary_search_algorithm#Interpolation_search interpolation search] should be faster than binary search.&lt;br /&gt;
== Implementation ==&lt;br /&gt;
The core implementation means extending [https://github.com/moodle/moodle/blob/81e5d425c4f17310844d424f0c64e3c9be34ff99/lib/moodlelib.php#L4940 function check_password_policy()] from lib/moodlelib.php with the new check.&lt;br /&gt;
&lt;br /&gt;
The alternative is to implement it as a local plugin and https://docs.moodle.org/dev/Login_callbacks#check_password_policy callback.&lt;br /&gt;
== Risks / negative consequences ==&lt;br /&gt;
=== Performance ===&lt;br /&gt;
If passwordpolicycheckonlogin is enabled, then this check may affect the performance of the site.&lt;br /&gt;
=== Installer size ===&lt;br /&gt;
The size of the Moodle installation package will increase (for example form about 60MB to 80MB).&lt;br /&gt;
== New installations ==&lt;br /&gt;
In the new Moodle installs, known password check should be enabled by default.&lt;br /&gt;
== Upgrading ==&lt;br /&gt;
When upgrading, known password check should be:&lt;br /&gt;
* Enabled if passwordpolicycheckonlogin is false&lt;br /&gt;
* Disabled if passwordpolicycheckonlogin is true&lt;br /&gt;
== Tasks ==&lt;br /&gt;
* Implement function for validating hash database:&lt;br /&gt;
** File size &amp;gt; 0&lt;br /&gt;
** File size is multiplication of 20 bytes&lt;br /&gt;
* Implement validation when enabling knownpasswordscheck :&lt;br /&gt;
** knownpasswordsdb must be valid hash database&lt;br /&gt;
* Write unit tests&lt;br /&gt;
[[Category:Project]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
== Mockups ==&lt;br /&gt;
[[File:pass policy settings.png|New settings|alt=]]&lt;br /&gt;
&lt;br /&gt;
[[File:pass policy add new user.png||Error when adding new user]]&lt;br /&gt;
&lt;br /&gt;
[[File:pass policy password change.png||Error during password change]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62190</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62190"/>
		<updated>2022-04-29T14:22:09Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: /* Mockups */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Very initial stage - project proposal.&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
== Technical details ==&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
&lt;br /&gt;
The default database shipped with the Moodle can be delivered as part of the code - lib/knownpasswords.bin.&lt;br /&gt;
&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
=== Configurable path to the hashes database (file) ===&lt;br /&gt;
Optionally site administrator will be able to upload custom file with SHA-1 hashes data. Such a database could contain much more know hashes and have significant size (tens of gigabytes).&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
=== Replace binary search with interpolation search ===&lt;br /&gt;
For big databases, [https://en.wikipedia.org/wiki/Binary_search_algorithm#Interpolation_search interpolation search] should be faster than binary search.&lt;br /&gt;
== Implementation ==&lt;br /&gt;
The core implementation means extending [https://github.com/moodle/moodle/blob/81e5d425c4f17310844d424f0c64e3c9be34ff99/lib/moodlelib.php#L4940 function check_password_policy()] from lib/moodlelib.php with the new check.&lt;br /&gt;
&lt;br /&gt;
The alternative is to implement it as a local plugin and https://docs.moodle.org/dev/Login_callbacks#check_password_policy callback.&lt;br /&gt;
== Risks / negative consequences ==&lt;br /&gt;
=== Performance ===&lt;br /&gt;
If passwordpolicycheckonlogin is enabled, then this check may affect the performance of the site.&lt;br /&gt;
=== Installer size ===&lt;br /&gt;
The size of the Moodle installation package will increase (for example form about 60MB to 80MB).&lt;br /&gt;
== New installations ==&lt;br /&gt;
In the new Moodle installs, known password check should be enabled by default.&lt;br /&gt;
== Upgrading ==&lt;br /&gt;
When upgrading, known password check should be:&lt;br /&gt;
* Enabled if passwordpolicycheckonlogin is false&lt;br /&gt;
* Disabled if passwordpolicycheckonlogin is true&lt;br /&gt;
== Tasks ==&lt;br /&gt;
* Implement function for validating hash database:&lt;br /&gt;
** File size &amp;gt; 0&lt;br /&gt;
** File size is multiplication of 20 bytes&lt;br /&gt;
* Implement validation when enabling knownpasswordscheck :&lt;br /&gt;
** knownpasswordsdb must be valid hash database&lt;br /&gt;
* Write unit tests&lt;br /&gt;
[[Category:Project]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
== Mockups ==&lt;br /&gt;
&lt;br /&gt;
[[File:pass policy settings.png||New settings]]&lt;br /&gt;
&lt;br /&gt;
[[File:pass policy add new user.png||Error when adding new user]]&lt;br /&gt;
&lt;br /&gt;
[[File:pass policy password change.png||Error during password change]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62189</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62189"/>
		<updated>2022-04-29T14:21:04Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Very initial stage - project proposal.&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
== Technical details ==&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
&lt;br /&gt;
The default database shipped with the Moodle can be delivered as part of the code - lib/knownpasswords.bin.&lt;br /&gt;
&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
=== Configurable path to the hashes database (file) ===&lt;br /&gt;
Optionally site administrator will be able to upload custom file with SHA-1 hashes data. Such a database could contain much more know hashes and have significant size (tens of gigabytes).&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
=== Replace binary search with interpolation search ===&lt;br /&gt;
For big databases, [https://en.wikipedia.org/wiki/Binary_search_algorithm#Interpolation_search interpolation search] should be faster than binary search.&lt;br /&gt;
== Implementation ==&lt;br /&gt;
The core implementation means extending [https://github.com/moodle/moodle/blob/81e5d425c4f17310844d424f0c64e3c9be34ff99/lib/moodlelib.php#L4940 function check_password_policy()] from lib/moodlelib.php with the new check.&lt;br /&gt;
&lt;br /&gt;
The alternative is to implement it as a local plugin and https://docs.moodle.org/dev/Login_callbacks#check_password_policy callback.&lt;br /&gt;
== Risks / negative consequences ==&lt;br /&gt;
=== Performance ===&lt;br /&gt;
If passwordpolicycheckonlogin is enabled, then this check may affect the performance of the site.&lt;br /&gt;
=== Installer size ===&lt;br /&gt;
The size of the Moodle installation package will increase (for example form about 60MB to 80MB).&lt;br /&gt;
== New installations ==&lt;br /&gt;
In the new Moodle installs, known password check should be enabled by default.&lt;br /&gt;
== Upgrading ==&lt;br /&gt;
When upgrading, known password check should be:&lt;br /&gt;
* Enabled if passwordpolicycheckonlogin is false&lt;br /&gt;
* Disabled if passwordpolicycheckonlogin is true&lt;br /&gt;
== Tasks ==&lt;br /&gt;
* Implement function for validating hash database:&lt;br /&gt;
** File size &amp;gt; 0&lt;br /&gt;
** File size is multiplication of 20 bytes&lt;br /&gt;
* Implement validation when enabling knownpasswordscheck :&lt;br /&gt;
** knownpasswordsdb must be valid hash database&lt;br /&gt;
* Write unit tests&lt;br /&gt;
[[Category:Project]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
== Mockups ==&lt;br /&gt;
&lt;br /&gt;
[[File:pass policy add new user.png]]&lt;br /&gt;
[[File:pass policy settings.png]]&lt;br /&gt;
[[File:pass policy password change.png]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62188</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62188"/>
		<updated>2022-04-29T14:19:59Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Very initial stage - project proposal.&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
== Technical details ==&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
&lt;br /&gt;
The default database shipped with the Moodle can be delivered as part of the code - lib/knownpasswords.bin.&lt;br /&gt;
&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
=== Configurable path to the hashes database (file) ===&lt;br /&gt;
Optionally site administrator will be able to upload custom file with SHA-1 hashes data. Such a database could contain much more know hashes and have significant size (tens of gigabytes).&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
=== Replace binary search with interpolation search ===&lt;br /&gt;
For big databases, [https://en.wikipedia.org/wiki/Binary_search_algorithm#Interpolation_search interpolation search] should be faster than binary search.&lt;br /&gt;
== Implementation ==&lt;br /&gt;
The core implementation means extending [https://github.com/moodle/moodle/blob/81e5d425c4f17310844d424f0c64e3c9be34ff99/lib/moodlelib.php#L4940 function check_password_policy()] from lib/moodlelib.php with the new check.&lt;br /&gt;
&lt;br /&gt;
The alternative is to implement it as a local plugin and https://docs.moodle.org/dev/Login_callbacks#check_password_policy callback.&lt;br /&gt;
== Risks / negative consequences ==&lt;br /&gt;
=== Performance ===&lt;br /&gt;
If passwordpolicycheckonlogin is enabled, then this check may affect the performance of the site.&lt;br /&gt;
=== Installer size ===&lt;br /&gt;
The size of the Moodle installation package will increase (for example form about 60MB to 80MB).&lt;br /&gt;
== New installations ==&lt;br /&gt;
In the new Moodle installs, known password check should be enabled by default.&lt;br /&gt;
== Upgrading ==&lt;br /&gt;
When upgrading, known password check should be:&lt;br /&gt;
* Enabled if passwordpolicycheckonlogin is false&lt;br /&gt;
* Disabled if passwordpolicycheckonlogin is true&lt;br /&gt;
== Tasks ==&lt;br /&gt;
* Implement function for validating hash database:&lt;br /&gt;
** File size &amp;gt; 0&lt;br /&gt;
** File size is multiplication of 20 bytes&lt;br /&gt;
* Implement validation when enabling knownpasswordscheck :&lt;br /&gt;
** knownpasswordsdb must be valid hash database&lt;br /&gt;
* Write unit tests&lt;br /&gt;
[[Category:Project]]&lt;br /&gt;
&lt;br /&gt;
[[File:pass policy add new user.png]]&lt;br /&gt;
[[File:pass policy settings.png]]&lt;br /&gt;
[[File:pass policy password change.png]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62187</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62187"/>
		<updated>2022-04-29T14:19:17Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: /* Password database */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Very initial stage - project proposal.&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
== Technical details ==&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
&lt;br /&gt;
The default database shipped with the Moodle can be delivered as part of the code - lib/knownpasswords.bin.&lt;br /&gt;
&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
=== Configurable path to the hashes database (file) ===&lt;br /&gt;
Optionally site administrator will be able to upload custom file with SHA-1 hashes data. Such a database could contain much more know hashes and have significant size (tens of gigabytes).&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
=== Replace binary search with interpolation search ===&lt;br /&gt;
For big databases, [https://en.wikipedia.org/wiki/Binary_search_algorithm#Interpolation_search interpolation search] should be faster than binary search.&lt;br /&gt;
== Implementation ==&lt;br /&gt;
The core implementation means extending [https://github.com/moodle/moodle/blob/81e5d425c4f17310844d424f0c64e3c9be34ff99/lib/moodlelib.php#L4940 function check_password_policy()] from lib/moodlelib.php with the new check.&lt;br /&gt;
&lt;br /&gt;
The alternative is to implement it as a local plugin and https://docs.moodle.org/dev/Login_callbacks#check_password_policy callback.&lt;br /&gt;
== Risks / negative consequences ==&lt;br /&gt;
=== Performance ===&lt;br /&gt;
If passwordpolicycheckonlogin is enabled, then this check may affect the performance of the site.&lt;br /&gt;
=== Installer size ===&lt;br /&gt;
The size of the Moodle installation package will increase (for example form about 60MB to 80MB).&lt;br /&gt;
== New installations ==&lt;br /&gt;
In the new Moodle installs, known password check should be enabled by default.&lt;br /&gt;
== Upgrading ==&lt;br /&gt;
When upgrading, known password check should be:&lt;br /&gt;
* Enabled if passwordpolicycheckonlogin is false&lt;br /&gt;
* Disabled if passwordpolicycheckonlogin is true&lt;br /&gt;
== Tasks ==&lt;br /&gt;
* Implement function for validating hash database:&lt;br /&gt;
** File size &amp;gt; 0&lt;br /&gt;
** File size is multiplication of 20 bytes&lt;br /&gt;
* Implement validation when enabling knownpasswordscheck :&lt;br /&gt;
** knownpasswordsdb must be valid hash database&lt;br /&gt;
* Write unit tests&lt;br /&gt;
[[Category:Project]]&lt;br /&gt;
[[File:pass policy add new user.png|thumb|pass policy add new user]]&lt;br /&gt;
[[File:pass policy settings.png|thumb]]&lt;br /&gt;
[[File:pass policy password change.png|thumb|pass policy password change]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62180</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62180"/>
		<updated>2022-04-29T11:00:30Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Very initial stage - project proposal.&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
== Technical details ==&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
=== Configurable path to the hashes database (file) ===&lt;br /&gt;
Optionally site administrator will be able to upload custom file with SHA-1 hashes data. Such a database could contain much more know hashes and have significant size (tens of gigabytes).&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
=== Replace binary search with interpolation search ===&lt;br /&gt;
For big databases, [https://en.wikipedia.org/wiki/Binary_search_algorithm#Interpolation_search interpolation search] should be faster than binary search.&lt;br /&gt;
== Implementation ==&lt;br /&gt;
The core implementation means extending [https://github.com/moodle/moodle/blob/81e5d425c4f17310844d424f0c64e3c9be34ff99/lib/moodlelib.php#L4940 function check_password_policy()] from lib/moodlelib.php with the new check.&lt;br /&gt;
&lt;br /&gt;
The alternative is to implement it as a local plugin and https://docs.moodle.org/dev/Login_callbacks#check_password_policy callback.&lt;br /&gt;
== Risks / negative consequences ==&lt;br /&gt;
=== Performance ===&lt;br /&gt;
If passwordpolicycheckonlogin is enabled, then this check may affect the performance of the site.&lt;br /&gt;
=== Installer size ===&lt;br /&gt;
The size of the Moodle installation package will increase (for example form about 60MB to 80MB).&lt;br /&gt;
== New installations ==&lt;br /&gt;
In the new Moodle installs, known password check should be enabled by default.&lt;br /&gt;
== Upgrading ==&lt;br /&gt;
When upgrading, known password check should be:&lt;br /&gt;
* Enabled if passwordpolicycheckonlogin is false&lt;br /&gt;
* Disabled if passwordpolicycheckonlogin is true&lt;br /&gt;
== Tasks ==&lt;br /&gt;
* Implement function for validating hash database:&lt;br /&gt;
** File size &amp;gt; 0&lt;br /&gt;
** File size is multiplication of 20 bytes&lt;br /&gt;
* Implement validation when enabling knownpasswordscheck :&lt;br /&gt;
** knownpasswordsdb must be valid hash database&lt;br /&gt;
* Write unit tests&lt;br /&gt;
[[Category:Project]]&lt;br /&gt;
[[File:pass policy add new user.png|thumb|pass policy add new user]]&lt;br /&gt;
[[File:pass policy settings.png|thumb]]&lt;br /&gt;
[[File:pass policy password change.png|thumb|pass policy password change]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=File:pass_policy_settings.png&amp;diff=62179</id>
		<title>File:pass policy settings.png</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=File:pass_policy_settings.png&amp;diff=62179"/>
		<updated>2022-04-29T11:00:21Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;pass policy settings&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=File:pass_policy_add_new_user.png&amp;diff=62178</id>
		<title>File:pass policy add new user.png</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=File:pass_policy_add_new_user.png&amp;diff=62178"/>
		<updated>2022-04-29T11:00:02Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;pass policy add new user&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=File:pass_policy_password_change.png&amp;diff=62177</id>
		<title>File:pass policy password change.png</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=File:pass_policy_password_change.png&amp;diff=62177"/>
		<updated>2022-04-29T10:59:36Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;pass policy password change&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62176</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62176"/>
		<updated>2022-04-29T10:31:10Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: /* Tasks */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Very initial stage - project proposal.&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
&lt;br /&gt;
== Technical details ==&lt;br /&gt;
&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
&lt;br /&gt;
=== Configurable path to the hashes database (file) ===&lt;br /&gt;
Optionally site administrator will be able to upload custom file with SHA-1 hashes data. Such a database could contain much more know hashes and have significant size (tens of gigabytes).&lt;br /&gt;
&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
&lt;br /&gt;
=== Replace binary search with interpolation search ===&lt;br /&gt;
For big databases, [https://en.wikipedia.org/wiki/Binary_search_algorithm#Interpolation_search interpolation search] should be faster than binary search.&lt;br /&gt;
&lt;br /&gt;
== Implementation ==&lt;br /&gt;
&lt;br /&gt;
The core implementation means extending [https://github.com/moodle/moodle/blob/81e5d425c4f17310844d424f0c64e3c9be34ff99/lib/moodlelib.php#L4940 function check_password_policy()] from lib/moodlelib.php with the new check.&lt;br /&gt;
&lt;br /&gt;
The alternative is to implement it as a local plugin and https://docs.moodle.org/dev/Login_callbacks#check_password_policy callback.&lt;br /&gt;
&lt;br /&gt;
== Risks / negative consequences ==&lt;br /&gt;
&lt;br /&gt;
=== Performance ===&lt;br /&gt;
&lt;br /&gt;
If passwordpolicycheckonlogin is enabled, then this check may affect the performance of the site.&lt;br /&gt;
&lt;br /&gt;
=== Installer size ===&lt;br /&gt;
&lt;br /&gt;
The size of the Moodle installation package will increase (for example form about 60MB to 80MB).&lt;br /&gt;
&lt;br /&gt;
== New installations ==&lt;br /&gt;
&lt;br /&gt;
In the new Moodle installs, known password check should be enabled by default.&lt;br /&gt;
&lt;br /&gt;
== Upgrading ==&lt;br /&gt;
&lt;br /&gt;
When upgrading, known password check should be:&lt;br /&gt;
&lt;br /&gt;
* Enabled if passwordpolicycheckonlogin is false&lt;br /&gt;
* Disabled if passwordpolicycheckonlogin is true&lt;br /&gt;
&lt;br /&gt;
== Tasks ==&lt;br /&gt;
* Implement function for validating hash database:&lt;br /&gt;
** File size &amp;gt; 0&lt;br /&gt;
** File size is multiplication of 20 bytes&lt;br /&gt;
* Implement validation when enabling knownpasswordscheck :&lt;br /&gt;
** knownpasswordsdb must be valid hash database&lt;br /&gt;
* Write unit tests&lt;br /&gt;
&lt;br /&gt;
[[Category:Project]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62175</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62175"/>
		<updated>2022-04-29T10:22:42Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: /* Tasks */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Very initial stage - project proposal.&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
&lt;br /&gt;
== Technical details ==&lt;br /&gt;
&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
&lt;br /&gt;
=== Configurable path to the hashes database (file) ===&lt;br /&gt;
Optionally site administrator will be able to upload custom file with SHA-1 hashes data. Such a database could contain much more know hashes and have significant size (tens of gigabytes).&lt;br /&gt;
&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
&lt;br /&gt;
=== Replace binary search with interpolation search ===&lt;br /&gt;
For big databases, [https://en.wikipedia.org/wiki/Binary_search_algorithm#Interpolation_search interpolation search] should be faster than binary search.&lt;br /&gt;
&lt;br /&gt;
== Implementation ==&lt;br /&gt;
&lt;br /&gt;
The core implementation means extending [https://github.com/moodle/moodle/blob/81e5d425c4f17310844d424f0c64e3c9be34ff99/lib/moodlelib.php#L4940 function check_password_policy()] from lib/moodlelib.php with the new check.&lt;br /&gt;
&lt;br /&gt;
The alternative is to implement it as a local plugin and https://docs.moodle.org/dev/Login_callbacks#check_password_policy callback.&lt;br /&gt;
&lt;br /&gt;
== Risks / negative consequences ==&lt;br /&gt;
&lt;br /&gt;
=== Performance ===&lt;br /&gt;
&lt;br /&gt;
If passwordpolicycheckonlogin is enabled, then this check may affect the performance of the site.&lt;br /&gt;
&lt;br /&gt;
=== Installer size ===&lt;br /&gt;
&lt;br /&gt;
The size of the Moodle installation package will increase (for example form about 60MB to 80MB).&lt;br /&gt;
&lt;br /&gt;
== New installations ==&lt;br /&gt;
&lt;br /&gt;
In the new Moodle installs, known password check should be enabled by default.&lt;br /&gt;
&lt;br /&gt;
== Upgrading ==&lt;br /&gt;
&lt;br /&gt;
When upgrading, known password check should be:&lt;br /&gt;
&lt;br /&gt;
* Enabled if passwordpolicycheckonlogin is false&lt;br /&gt;
* Disabled if passwordpolicycheckonlogin is true&lt;br /&gt;
&lt;br /&gt;
== Tasks ==&lt;br /&gt;
&lt;br /&gt;
* Implement validation when enabling knownpasswordscheck :&lt;br /&gt;
** knownpasswordsdb must be valid hash database&lt;br /&gt;
* Write unit tests&lt;br /&gt;
&lt;br /&gt;
[[Category:Project]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62171</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62171"/>
		<updated>2022-04-29T10:19:33Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Very initial stage - project proposal.&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
&lt;br /&gt;
== Technical details ==&lt;br /&gt;
&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
&lt;br /&gt;
=== Configurable path to the hashes database (file) ===&lt;br /&gt;
Optionally site administrator will be able to upload custom file with SHA-1 hashes data. Such a database could contain much more know hashes and have significant size (tens of gigabytes).&lt;br /&gt;
&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
&lt;br /&gt;
=== Replace binary search with interpolation search ===&lt;br /&gt;
For big databases, [https://en.wikipedia.org/wiki/Binary_search_algorithm#Interpolation_search interpolation search] should be faster than binary search.&lt;br /&gt;
&lt;br /&gt;
== Implementation ==&lt;br /&gt;
&lt;br /&gt;
The core implementation means extending [https://github.com/moodle/moodle/blob/81e5d425c4f17310844d424f0c64e3c9be34ff99/lib/moodlelib.php#L4940 function check_password_policy()] from lib/moodlelib.php with the new check.&lt;br /&gt;
&lt;br /&gt;
The alternative is to implement it as a local plugin and https://docs.moodle.org/dev/Login_callbacks#check_password_policy callback.&lt;br /&gt;
&lt;br /&gt;
== Risks / negative consequences ==&lt;br /&gt;
&lt;br /&gt;
=== Performance ===&lt;br /&gt;
&lt;br /&gt;
If passwordpolicycheckonlogin is enabled, then this check may affect the performance of the site.&lt;br /&gt;
&lt;br /&gt;
=== Installer size ===&lt;br /&gt;
&lt;br /&gt;
The size of the Moodle installation package will increase (for example form about 60MB to 80MB).&lt;br /&gt;
&lt;br /&gt;
== New installations ==&lt;br /&gt;
&lt;br /&gt;
In the new Moodle installs, known password check should be enabled by default.&lt;br /&gt;
&lt;br /&gt;
== Upgrading ==&lt;br /&gt;
&lt;br /&gt;
When upgrading, known password check should be:&lt;br /&gt;
&lt;br /&gt;
* Enabled if passwordpolicycheckonlogin is false&lt;br /&gt;
* Disabled if passwordpolicycheckonlogin is true&lt;br /&gt;
&lt;br /&gt;
== Tasks ==&lt;br /&gt;
&lt;br /&gt;
* Implement validation when enabling knownpasswordscheck :&lt;br /&gt;
** knownpasswordsdb must be valid hash database&lt;br /&gt;
&lt;br /&gt;
[[Category:Project]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62170</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62170"/>
		<updated>2022-04-29T10:00:56Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Very initial stage - project proposal.&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
&lt;br /&gt;
== Technical details ==&lt;br /&gt;
&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
&lt;br /&gt;
=== Configurable path to the hashes database (file) ===&lt;br /&gt;
Optionally site administrator will be able to upload custom file with SHA-1 hashes data. Such a database could contain much more know hashes and have significant size (tens of gigabytes).&lt;br /&gt;
&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
&lt;br /&gt;
=== Replace binary search with interpolation search ===&lt;br /&gt;
For big databases, [https://en.wikipedia.org/wiki/Binary_search_algorithm#Interpolation_search interpolation search] should be faster than binary search.&lt;br /&gt;
&lt;br /&gt;
== Implementation ==&lt;br /&gt;
&lt;br /&gt;
The core implementation means extending [https://github.com/moodle/moodle/blob/81e5d425c4f17310844d424f0c64e3c9be34ff99/lib/moodlelib.php#L4940 function check_password_policy()] from lib/moodlelib.php with the new check.&lt;br /&gt;
&lt;br /&gt;
The alternative is to implement it as a local plugin and https://docs.moodle.org/dev/Login_callbacks#check_password_policy callback.&lt;br /&gt;
&lt;br /&gt;
== Risks / negative consequences ==&lt;br /&gt;
&lt;br /&gt;
=== Performance ===&lt;br /&gt;
&lt;br /&gt;
If passwordpolicycheckonlogin is enabled, then this check may affect the performance of the site.&lt;br /&gt;
&lt;br /&gt;
=== Installer size ===&lt;br /&gt;
&lt;br /&gt;
The size of the Moodle installation package will increase (for example form about 60MB to 80MB).&lt;br /&gt;
&lt;br /&gt;
== New installations ==&lt;br /&gt;
&lt;br /&gt;
In the new Moodle installs, known password check should be enabled by default.&lt;br /&gt;
&lt;br /&gt;
== Upgrading ==&lt;br /&gt;
&lt;br /&gt;
When upgrading, known password check should be:&lt;br /&gt;
&lt;br /&gt;
* Enabled if passwordpolicycheckonlogin is false&lt;br /&gt;
* Disabled if passwordpolicycheckonlogin is true&lt;br /&gt;
&lt;br /&gt;
== Tasks ==&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
[[Category:Project]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62169</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62169"/>
		<updated>2022-04-29T09:53:38Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: /* Upgrading = */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Very initial stage - project proposal.&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
&lt;br /&gt;
== Technical details ==&lt;br /&gt;
&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
&lt;br /&gt;
=== Configurable path to the hashes database (file) ===&lt;br /&gt;
Optionally site administrator will be able to upload custom file with SHA-1 hashes data. Such a database could contain much more know hashes and have significant size (tens of gigabytes).&lt;br /&gt;
&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
&lt;br /&gt;
=== Replace binary search with interpolation search ===&lt;br /&gt;
For big databases, [https://en.wikipedia.org/wiki/Binary_search_algorithm#Interpolation_search interpolation search] should be faster than binary search.&lt;br /&gt;
&lt;br /&gt;
== Implementation ==&lt;br /&gt;
&lt;br /&gt;
The core implementation means extending [https://github.com/moodle/moodle/blob/81e5d425c4f17310844d424f0c64e3c9be34ff99/lib/moodlelib.php#L4940 function check_password_policy()] from lib/moodlelib.php with the new check.&lt;br /&gt;
&lt;br /&gt;
The alternative is to implement it as a local plugin and https://docs.moodle.org/dev/Login_callbacks#check_password_policy callback.&lt;br /&gt;
&lt;br /&gt;
== Risks ==&lt;br /&gt;
&lt;br /&gt;
=== Performance ===&lt;br /&gt;
&lt;br /&gt;
If passwordpolicycheckonlogin is enabled, then this check may affect the performance of the site.&lt;br /&gt;
&lt;br /&gt;
== New installations ==&lt;br /&gt;
&lt;br /&gt;
In the new Moodle installs, known password check should be enabled by default.&lt;br /&gt;
&lt;br /&gt;
== Upgrading ==&lt;br /&gt;
&lt;br /&gt;
When upgrading, known password check should be:&lt;br /&gt;
&lt;br /&gt;
* Enabled if passwordpolicycheckonlogin is false&lt;br /&gt;
* Disabled if passwordpolicycheckonlogin is true&lt;br /&gt;
&lt;br /&gt;
== Tasks ==&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
[[Category:Project]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62168</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62168"/>
		<updated>2022-04-29T09:53:32Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: /* New installations = */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Very initial stage - project proposal.&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
&lt;br /&gt;
== Technical details ==&lt;br /&gt;
&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
&lt;br /&gt;
=== Configurable path to the hashes database (file) ===&lt;br /&gt;
Optionally site administrator will be able to upload custom file with SHA-1 hashes data. Such a database could contain much more know hashes and have significant size (tens of gigabytes).&lt;br /&gt;
&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
&lt;br /&gt;
=== Replace binary search with interpolation search ===&lt;br /&gt;
For big databases, [https://en.wikipedia.org/wiki/Binary_search_algorithm#Interpolation_search interpolation search] should be faster than binary search.&lt;br /&gt;
&lt;br /&gt;
== Implementation ==&lt;br /&gt;
&lt;br /&gt;
The core implementation means extending [https://github.com/moodle/moodle/blob/81e5d425c4f17310844d424f0c64e3c9be34ff99/lib/moodlelib.php#L4940 function check_password_policy()] from lib/moodlelib.php with the new check.&lt;br /&gt;
&lt;br /&gt;
The alternative is to implement it as a local plugin and https://docs.moodle.org/dev/Login_callbacks#check_password_policy callback.&lt;br /&gt;
&lt;br /&gt;
== Risks ==&lt;br /&gt;
&lt;br /&gt;
=== Performance ===&lt;br /&gt;
&lt;br /&gt;
If passwordpolicycheckonlogin is enabled, then this check may affect the performance of the site.&lt;br /&gt;
&lt;br /&gt;
== New installations ==&lt;br /&gt;
&lt;br /&gt;
In the new Moodle installs, known password check should be enabled by default.&lt;br /&gt;
&lt;br /&gt;
== Upgrading ===&lt;br /&gt;
&lt;br /&gt;
When upgrading, known password check should be:&lt;br /&gt;
&lt;br /&gt;
* Enabled if passwordpolicycheckonlogin is false&lt;br /&gt;
* Disabled if passwordpolicycheckonlogin is true&lt;br /&gt;
&lt;br /&gt;
== Tasks ==&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
[[Category:Project]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62167</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62167"/>
		<updated>2022-04-29T09:53:23Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Very initial stage - project proposal.&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
&lt;br /&gt;
== Technical details ==&lt;br /&gt;
&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
&lt;br /&gt;
=== Configurable path to the hashes database (file) ===&lt;br /&gt;
Optionally site administrator will be able to upload custom file with SHA-1 hashes data. Such a database could contain much more know hashes and have significant size (tens of gigabytes).&lt;br /&gt;
&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
&lt;br /&gt;
=== Replace binary search with interpolation search ===&lt;br /&gt;
For big databases, [https://en.wikipedia.org/wiki/Binary_search_algorithm#Interpolation_search interpolation search] should be faster than binary search.&lt;br /&gt;
&lt;br /&gt;
== Implementation ==&lt;br /&gt;
&lt;br /&gt;
The core implementation means extending [https://github.com/moodle/moodle/blob/81e5d425c4f17310844d424f0c64e3c9be34ff99/lib/moodlelib.php#L4940 function check_password_policy()] from lib/moodlelib.php with the new check.&lt;br /&gt;
&lt;br /&gt;
The alternative is to implement it as a local plugin and https://docs.moodle.org/dev/Login_callbacks#check_password_policy callback.&lt;br /&gt;
&lt;br /&gt;
== Risks ==&lt;br /&gt;
&lt;br /&gt;
=== Performance ===&lt;br /&gt;
&lt;br /&gt;
If passwordpolicycheckonlogin is enabled, then this check may affect the performance of the site.&lt;br /&gt;
&lt;br /&gt;
== New installations ===&lt;br /&gt;
&lt;br /&gt;
In the new Moodle installs, known password check should be enabled by default.&lt;br /&gt;
&lt;br /&gt;
== Upgrading ===&lt;br /&gt;
&lt;br /&gt;
When upgrading, known password check should be:&lt;br /&gt;
&lt;br /&gt;
* Enabled if passwordpolicycheckonlogin is false&lt;br /&gt;
* Disabled if passwordpolicycheckonlogin is true&lt;br /&gt;
&lt;br /&gt;
== Tasks ==&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
[[Category:Project]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62166</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62166"/>
		<updated>2022-04-29T07:56:35Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Very initial stage - project proposal.&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
&lt;br /&gt;
== Technical details ==&lt;br /&gt;
&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
&lt;br /&gt;
=== Configurable path to the hashes database (file) ===&lt;br /&gt;
Optionally site administrator will be able to upload custom file with SHA-1 hashes data. Such a database could contain much more know hashes and have significant size (tens of gigabytes).&lt;br /&gt;
&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
&lt;br /&gt;
=== Replace binary search with interpolation search ===&lt;br /&gt;
For big databases, [https://en.wikipedia.org/wiki/Binary_search_algorithm#Interpolation_search interpolation search] should be faster than binary search.&lt;br /&gt;
&lt;br /&gt;
== Implementation ==&lt;br /&gt;
&lt;br /&gt;
The core implementation means extending [https://github.com/moodle/moodle/blob/81e5d425c4f17310844d424f0c64e3c9be34ff99/lib/moodlelib.php#L4940 function check_password_policy()] from lib/moodlelib.php with the new check.&lt;br /&gt;
&lt;br /&gt;
The alternative is to implement it as a local plugin and https://docs.moodle.org/dev/Login_callbacks#check_password_policy callback.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
== Tasks ==&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
[[Category:Project]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62165</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62165"/>
		<updated>2022-04-29T07:54:36Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Very initial stage - project proposal.&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
&lt;br /&gt;
== Technical details ==&lt;br /&gt;
&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
&lt;br /&gt;
=== Configurable path to the hashes database (file) ===&lt;br /&gt;
Optionally site administrator will be able to upload custom file with SHA-1 hashes data. Such a database could contain much more know hashes and have significant size (tens of gigabytes).&lt;br /&gt;
&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
&lt;br /&gt;
=== Replace binary search with interpolation search ===&lt;br /&gt;
For big databases, [https://en.wikipedia.org/wiki/Binary_search_algorithm#Interpolation_search interpolation search] should be faster than binary search.&lt;br /&gt;
&lt;br /&gt;
== Implementation ==&lt;br /&gt;
&lt;br /&gt;
The core implementation means extending function check_password_policy() from lib/moodlelib.php with the new check.&lt;br /&gt;
&lt;br /&gt;
The alternative is to implement it as a local plugin and https://docs.moodle.org/dev/Login_callbacks#check_password_policy callback.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
== Tasks ==&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
[[Category:Project]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62164</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62164"/>
		<updated>2022-04-29T07:16:49Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Very initial stage - project proposal.&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
&lt;br /&gt;
== Technical details ==&lt;br /&gt;
&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
&lt;br /&gt;
=== Configurable path to the hashes database (file) ===&lt;br /&gt;
Optionally site administrator will be able to upload custom file with SHA-1 hashes data. Such a database could contain much more know hashes and have significant size (tens of gigabytes).&lt;br /&gt;
&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
&lt;br /&gt;
=== Replace binary search with interpolation search ===&lt;br /&gt;
For big databases, [https://en.wikipedia.org/wiki/Binary_search_algorithm#Interpolation_search interpolation search] should be faster than binary search.&lt;br /&gt;
&lt;br /&gt;
== Tasks ==&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
[[Category:Project]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62140</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62140"/>
		<updated>2022-04-29T07:07:55Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Very initial stage - project proposal.&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
&lt;br /&gt;
== Technical details ==&lt;br /&gt;
&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
&lt;br /&gt;
=== Configurable path to the hashes database (file) ===&lt;br /&gt;
Optionally site administrator will be able to upload custom file with SHA-1 hashes data. Such a database could contain much more know hashes and have significant size (tens of gigabytes).&lt;br /&gt;
&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
&lt;br /&gt;
=== Replace binary search with interpolation search ===&lt;br /&gt;
For big databases, [https://en.wikipedia.org/wiki/Binary_search_algorithm#Interpolation_search interpolation search] should be faster than binary search.&lt;br /&gt;
&lt;br /&gt;
== Tasks ==&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62112</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62112"/>
		<updated>2022-04-27T15:31:39Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: /* Approach */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Status ==&lt;br /&gt;
Very initial stage - project proposal.&lt;br /&gt;
== Introduction ==&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
== Approach ==&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
&lt;br /&gt;
# A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle.&lt;br /&gt;
# Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
# A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached/known passwords.&lt;br /&gt;
&lt;br /&gt;
== Technical details ==&lt;br /&gt;
&lt;br /&gt;
=== Password database ===&lt;br /&gt;
Each password is a SHA-1 hash and the full data can be downloaded from https://haveibeenpwned.com/Passwords .&lt;br /&gt;
&lt;br /&gt;
Instead of shipping big, over 30GB file (uncompressed), we will:&lt;br /&gt;
&lt;br /&gt;
# Extract and ship by default top (most common) 1 million password hashes&lt;br /&gt;
# Change SHA-1 from text to binary format&lt;br /&gt;
# Order SHA-1 hashes by their value.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Storing SHA-1 as binary means using 20 bytes per hash. 1 million entries means file size below 20 MB.&lt;br /&gt;
&lt;br /&gt;
=== Database search ===&lt;br /&gt;
Because the hashes are per-ordered (in the ascending order) and each entry is the same size, then quick, binary search may be used to check if given hash exists in the database.&lt;br /&gt;
&lt;br /&gt;
== Unresolved issues/ideas ==&lt;br /&gt;
== Tasks ==&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62094</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62094"/>
		<updated>2022-04-27T15:21:25Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;= Status =&lt;br /&gt;
Very initial stage - project proposal.&lt;br /&gt;
&lt;br /&gt;
= Introduction =&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
 &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
This proposal suggest the implementation of the &amp;quot;known password&amp;quot; check above.&lt;br /&gt;
&lt;br /&gt;
= Approach =&lt;br /&gt;
&lt;br /&gt;
The standard way to check if the password is one of the known ones is to use https://haveibeenpwned.com/Passwords service. An API request can be sent to haveibeenpwned to check the password.&lt;br /&gt;
It&#039;s implemented in a nice way - the original password is not sent to the service, as per https://haveibeenpwned.com/Privacy :&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;The Pwned Passwords feature searches previous data breaches for the presence of a user-provided password. The password is hashed client-side with the SHA-1 algorithm then only the first 5 characters of the hash are sent to HIBP per the Cloudflare k-anonymity implementation. HIBP never receives the original password nor enough information to discover what the original password was.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
However, using haveibeenpwned.com adds external dependency to Moodle installation.&lt;br /&gt;
&lt;br /&gt;
Instead, I&#039;m suggesting the stand-alone approach for the check, with no dependency on the external service:&lt;br /&gt;
&lt;br /&gt;
A number (say top 1 million) of the most common, known password hashes is shipped with standard Moodle. &lt;br /&gt;
Password hashes are stored in a binary file that allows for quick search.&lt;br /&gt;
A path to the hashes file (this file is really a database) is configurable in Site Administration. This will allow administrators to upload bigger collection of the breached passwords.&lt;br /&gt;
&lt;br /&gt;
= Unresolved issues/ideas =&lt;br /&gt;
= Tasks =&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62093</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62093"/>
		<updated>2022-04-27T15:12:23Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;= Status =&lt;br /&gt;
Very initial stage - project proposal.&lt;br /&gt;
= Introduction =&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
 &lt;br /&gt;
NIST Special Publication 800-63B, [https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver Digital Identity Guidelines] advises on another check: &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;For example, the list MAY include, but is not limited to:&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;Passwords obtained from previous breach corpuses.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Dictionary words.&#039;&#039;&lt;br /&gt;
* &#039;&#039;Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&#039;&#039;&lt;br /&gt;
* &#039;&#039;Context-specific words, such as the name of the service, the username, and derivatives thereof.&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&#039;&#039;&lt;br /&gt;
= Approach =&lt;br /&gt;
= Unresolved issues/ideas =&lt;br /&gt;
= Tasks =&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62092</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62092"/>
		<updated>2022-04-27T15:04:27Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;= Status =&lt;br /&gt;
&lt;br /&gt;
Very initial stage - project proposal.&lt;br /&gt;
&lt;br /&gt;
= Introduction =&lt;br /&gt;
&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
The following checks can be applied to measure the password quality:&lt;br /&gt;
&lt;br /&gt;
* Password length&lt;br /&gt;
* Digits &lt;br /&gt;
* Lowercase letters &lt;br /&gt;
* Uppercase letters &lt;br /&gt;
* Non-alphanumeric characters &lt;br /&gt;
* Consecutive identical characters&lt;br /&gt;
* Password rotation limit &lt;br /&gt;
&lt;br /&gt;
NIST Special Publication 800-63B, &amp;quot;Digital Identity Guidelines&amp;quot; &lt;br /&gt;
&lt;br /&gt;
https://pages.nist.gov/800-63-3/sp800-63b.html#memsecretver&lt;br /&gt;
&lt;br /&gt;
When processing requests to establish and change memorized secrets, verifiers SHALL compare the prospective secrets against a list that contains values known to be commonly-used, expected, or compromised. For example, the list MAY include, but is not limited to:&lt;br /&gt;
&lt;br /&gt;
    Passwords obtained from previous breach corpuses.&lt;br /&gt;
    Dictionary words.&lt;br /&gt;
    Repetitive or sequential characters (e.g. ‘aaaaaa’, ‘1234abcd’).&lt;br /&gt;
    Context-specific words, such as the name of the service, the username, and derivatives thereof.&lt;br /&gt;
&lt;br /&gt;
If the chosen secret is found in the list, the CSP or verifier SHALL advise the subscriber that they need to select a different secret, SHALL provide the reason for rejection, and SHALL require the subscriber to choose a different value.&lt;br /&gt;
&lt;br /&gt;
= Approach =&lt;br /&gt;
&lt;br /&gt;
= Unresolved issues/ideas =&lt;br /&gt;
&lt;br /&gt;
= Tasks =&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62091</id>
		<title>Password Policy: Known Passwords Check Proposal</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Password_Policy:_Known_Passwords_Check_Proposal&amp;diff=62091"/>
		<updated>2022-04-27T14:43:17Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: Created page with &amp;quot;= Status =  Very initial stage - project proposal.  = Introduction =  Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security...&amp;quot;&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;= Status =&lt;br /&gt;
&lt;br /&gt;
Very initial stage - project proposal.&lt;br /&gt;
&lt;br /&gt;
= Introduction =&lt;br /&gt;
&lt;br /&gt;
Moodle 4.0 supports &amp;quot;Password policy&amp;quot; configurable in Site Administration under Security -&amp;gt; Site security settings.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
= Approach =&lt;br /&gt;
&lt;br /&gt;
= Unresolved issues/ideas =&lt;br /&gt;
&lt;br /&gt;
= Tasks =&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=The_Moodle_Universal_Cache_(MUC)&amp;diff=53703</id>
		<title>The Moodle Universal Cache (MUC)</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=The_Moodle_Universal_Cache_(MUC)&amp;diff=53703"/>
		<updated>2018-02-14T10:33:00Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;{{Infobox Project&lt;br /&gt;
|name = The Moodle Universal Cache (MUC)&lt;br /&gt;
|state = Stage 1 completed, stage 2 in progress&lt;br /&gt;
|tracker = MDL-25290 and MDL-34224&lt;br /&gt;
|discussion = &lt;br /&gt;
|assignee = [[User:Sam Hemelryk|Sam Hemelryk]]&lt;br /&gt;
}}&lt;br /&gt;
{{Moodle 2.4}}&lt;br /&gt;
&lt;br /&gt;
==Foreword==&lt;br /&gt;
Over the past couple of weeks I have used my available time to look into a caching solution for Moodle.&amp;lt;br /&amp;gt;&lt;br /&gt;
The concept is not a new one and for the past years people have constantly come back to the need for a proper caching solution, particularly one that allows for a shared cache.&amp;lt;br /&amp;gt;&lt;br /&gt;
The tracker issue MDL-25290 has been set up to follow progress on finding a solution, and in fact Tony Levi plus others have written a community proposal and made initial headway in code [[Caching_system_%28proposed%29|Caching_system_(proposed)]].&lt;br /&gt;
&lt;br /&gt;
I&#039;ve now read through their proposal and solution, looked into the different caching systems that are available, looking into what other web solutions are doing, and researched the needs that we have in Moodle and have now planned the solution that will make up this proposal.&lt;br /&gt;
&lt;br /&gt;
==The existing proposal==&lt;br /&gt;
Having read through the current proposal and having looked at the code created by Tony I can tell you right now that they are off to a very good start. In my research into this I think that we need to take it further again however if you look at the existing solution you will notice that this proposal takes a lot of what they already have and expands upon it.&lt;br /&gt;
&lt;br /&gt;
==Requirements==&lt;br /&gt;
The following are the requirements that this new solution hopes to satisfy.&lt;br /&gt;
* Add a shared (application) cache.&lt;br /&gt;
* Add a static cache to replace static variables presently in use.&lt;br /&gt;
* Suitable to replace existing cache solutions with equal or better performance. (the lang string cache will be the primary test case).&lt;br /&gt;
* Integrate with and support existing cache products.&lt;br /&gt;
* Some mind to support future caching products.&lt;br /&gt;
* Have a relatively simple, self explanatory nature to aid developers in making the most of it.&lt;br /&gt;
* The cache product integration should also be relatively simple and self explanatory to ensure now cache produce integrations are easy to write.&lt;br /&gt;
* Have suitable fail over systems so that things continue to work even when the caches are unavailable.&lt;br /&gt;
* Able to be initialized early on in system initialization (before config for example so that we can cache that)&lt;br /&gt;
* Support a time to live on data where applicable to ensure developers can determine how long information can live in the cache before deemed out of date and needs to be generated again.&lt;br /&gt;
&lt;br /&gt;
==Outline==&lt;br /&gt;
The section contains information on the key ideas and structures that will form the basis for the cache solution.&lt;br /&gt;
&lt;br /&gt;
===Cache types===&lt;br /&gt;
The first thing to understand is that there are three cache types that have been defined and will be addressed by this solution. Each cache type represents a separate way in which information can be cached, and each while being operated identically will function completely differently.&lt;br /&gt;
&lt;br /&gt;
These cache types are one of the few things that developers will need to understand about the cache solution. When defining every cache a cache type needs to be selected for it. That cache type will determine who the cached information is available to and for how long the cache instance will live.&lt;br /&gt;
&lt;br /&gt;
For each type there will be a representative class that the developer can instantiate for a cache and work with to retrieve and set data. This is as far as the developer will usually need to be familiar with the Cache API, everything they require to work with a cache will be made available through the cache type objects.&lt;br /&gt;
&lt;br /&gt;
The three cache types are details below:&lt;br /&gt;
&lt;br /&gt;
====Request cache====&lt;br /&gt;
You can think of the request cache type like a static property. It is alive for the duration of the request and cleared at the end of every request. It is also important to point out that this cache is of course user specific, so information stored in the cache will only be accessible to the user who put it there in the first place.&lt;br /&gt;
&lt;br /&gt;
This cache type will be used to replace static caches currently used through Moodle (think static variables, static properties, and global variables).&lt;br /&gt;
&lt;br /&gt;
By default, if either not cache instance has been assigned to the request cache type, or if the data can not be stored in the defined cache instance then a static memory based cache will be used by default.&lt;br /&gt;
&lt;br /&gt;
====Session cache====&lt;br /&gt;
The session cache is exactly as the name suggests similar to the session made available through PHP. It is alive for the duration of the users session and of course user specific. At the end of the users session information will be purged (by means of cron or similar).&lt;br /&gt;
&lt;br /&gt;
This is probably the most limited cache type, however the idea behind it is to separate out information that would be blowing out the current session size and allow an installation to specify an instance dedicated to its storage.&lt;br /&gt;
&lt;br /&gt;
====Application====&lt;br /&gt;
This is the most prominent and beneficial cache type as there is nothing like it presently within Moodle. The application cache type is a shared cache that all users can access making common data accessible to all without the need for every user to generate it for every request or generate once and store in a user specific cache.&lt;br /&gt;
&lt;br /&gt;
The life time of information within the cache will be determined by a time to live that will be specified by the developer, and will default when not specified to a configuration setting.&lt;br /&gt;
&lt;br /&gt;
===Cache plugins===&lt;br /&gt;
This is the second most important thing to understand is that there will be a new plugin type introduced into Moodle, the Cache plugin. The Cache plugins base directory will be $CFG-&amp;gt;dirroot/cache and each plugin will have its own sub directory there. Initially we are planning to produce plugins for APC, Memcache, XCache, Database, Static, and File each of which will of have its own sub directory.&lt;br /&gt;
&lt;br /&gt;
Each plugin will define its own cache plugin class that will be required to extend an abstract class or interface that will map out all of the required methods of the plugin.&lt;br /&gt;
&lt;br /&gt;
Also be aware that there can be multiple instances of a plugin. For example you could have two instances of a cache product set up, one a limited set up on the web server, and another running on remote machines. You could then map each instance to particular cache type, or in the future perhaps even a specific cache.&lt;br /&gt;
&lt;br /&gt;
This is important for a couple of reasons, first that it will allow load balancing and/or prioritization to occur, and second that it will allow us to further what we can do with the cache solution in the future (after initial integration).&lt;br /&gt;
&lt;br /&gt;
===The cache manager===&lt;br /&gt;
The cache manager will tie everything together. It will be responsible for initializing cache instances when required, making generalistic information available, and publishing static methods to interact with the cache solution as a whole.&amp;lt;br /&amp;gt;&lt;br /&gt;
This will include publishing events for the following:&lt;br /&gt;
* Available cache plugins&lt;br /&gt;
* Available configured cache instances&lt;br /&gt;
* Maximum data and/or cache size&lt;br /&gt;
* Setting and creating the configuration file&lt;br /&gt;
* Retrieving and processing the configuration file&lt;br /&gt;
&lt;br /&gt;
Although the cache_manager will be tieing everything together a developer wishing to use the cache API will not in fact need to know anything about it, to keep the cache API straight forward and simple to most common functionality will be wrapped for convenience into several controlling classes, one for each cache type, that will make storing and retrieving data from a cache a very simple task.&lt;br /&gt;
&lt;br /&gt;
In this way the uses of the cache manager within core code will likely be internal use by the cache API itself, and core code where the advanced parts of the API will be required such as configuring instances, or purging caches on cron or through the existing admin interface.&lt;br /&gt;
&lt;br /&gt;
===Logic separation===&lt;br /&gt;
The logic for the cache API will be separated into three very clear, separate sections. These sections are API use, core logic, and plugin development. These three highlight the very important idea that when using, or working with this API the developer need only know about the seccion they are working with.&lt;br /&gt;
&lt;br /&gt;
; API use : When using the API the developer will not know, or need to know anything at all about cache plugins that have been installed, what instances are available for each of those plugins, or even where their information is going to be stored. The developer will work with a cache type class (more on those later) that gets initialized with the details of the cache and can then be interacted with simply. All the developer needs to know is which cache type they should be making use of. Everything else will be taken care of internally by the core logic, and actual caching and retrieving by the cache plugin (that the developer knows nothing about).&lt;br /&gt;
; Core logic : The core logic refers to whatever is controlling the cache (the cache_manager) which will be aware of what plugins are available, and what instances exist for each plugin. It is responsible for managing those plugins, the plugin instances, and any cache events (such as purging all caches). This may sound like a very significant part of the cache solution, and that is because it is. However its very important to recognise that all of those management and general features are going to be rarely used by the developer. In fact I would very few people ever having to utilise the cache manager and this section of the API. It is more for internal, and edge case core use than anything else.&lt;br /&gt;
; Plugin development : This is a very essential part of both the solution and the API, the development of cache plugins. In developing a plugin the developer will not need to pay heed to the cache types, or the cache_manager controller. In fact the plugin their develop will only need to publish methods for the essential interaction with the cache, get, set, delete etc. It will be provided with only the required, already parsed and ready information required for those operations, and will not need to do anything but interact with the cache. Everything else will be taken care of internally by the core logic.&lt;br /&gt;
&lt;br /&gt;
===Controlling interaction===&lt;br /&gt;
As mentioned above for convenience and ease of use of the cache API access to it will be controlled by several classes, one for each cache type. All of these classes will operate in the same means (extending the same parent) and will make any allowances required for the cache type internally.&lt;br /&gt;
&lt;br /&gt;
The cache type classes will be designed to be initialized for each bit of data the developer wishes to be cached. Once initialized simple methods are available on the object to get, set, check whether the cache has the information, and delete information from the cache.&amp;lt;br /&amp;gt;&lt;br /&gt;
As this is something more easily understood through code example take a peak at the following snippet of code that illustrates how I see interaction occurring.&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$courseid = required_param(&#039;courseid&#039;, PARAM_INT);&lt;br /&gt;
$cache = new cache_application(&#039;core_course&#039;, &#039;modinfo&#039;, array(&#039;id&#039; =&amp;gt; $courseid));&lt;br /&gt;
if (!$modinfo = $cache-&amp;gt;get($courseid)) {&lt;br /&gt;
    $course = $DB-&amp;gt;get_record(&#039;course&#039;, array(&#039;id&#039; =&amp;gt; $courseid), &#039;*&#039;, MUST_EXIST);&lt;br /&gt;
    $modinfo = get_fast_modinfo($course);&lt;br /&gt;
    $cache-&amp;gt;set($courseid, $modinfo);&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
As you can see once the object has been initialized for the cache its as simple as calling &#039;&#039;&#039;get()&#039;&#039;&#039; to retrieve the information, or &#039;&#039;&#039;set($data)&#039;&#039;&#039; to set it.&lt;br /&gt;
&lt;br /&gt;
As there are three cache types purposed the following classes will be created to control interaction:&lt;br /&gt;
; cache_request : For working with a request cache.&lt;br /&gt;
; cache_session : For working with a session cache.&lt;br /&gt;
; cache_application : For working with an application wide cache.&lt;br /&gt;
&lt;br /&gt;
===Configuration===&lt;br /&gt;
In discussing this proposal with Eloy this was one area we highlighted as small but critical area of the cache solution. Initially I had planned to make use of the main database introducing new tables to record information on plugin instances and their mappings to cache types.&amp;lt;br /&amp;gt;&lt;br /&gt;
However in discussing this we decided that there was three problems with this, first it would introduce overhead as we would need to execute a couple of queries to build the required information, second the information being stored would itself be a candidate for caching, and third it would require the setup code for Moodle to be initialized past the point of loading configuration before the code would be usable preventing us for caching the configuration which is one of the candidates for caching.&lt;br /&gt;
&lt;br /&gt;
Our solution to this: the configuration for the caches will be stored in the dataroot as a PHP file, similar to what we do with the current lang cache.&amp;lt;br /&amp;gt;&lt;br /&gt;
From there it will be included by the cache API and parsed when the API is first used in a page.&lt;br /&gt;
&lt;br /&gt;
This negates the requirement for additional database tables and interaction, and will allow us to utilize the cache solution much earlier during setup, early enough to allow us to cache configuration.&lt;br /&gt;
&lt;br /&gt;
===The cacheable interface===&lt;br /&gt;
There will also be a new cacheable interface, much like the rendererable interface, which can be given to a class to mark it as having special cache methods.&amp;lt;br /&amp;gt;&lt;br /&gt;
The interface will have two required methods, the first method will be called when the data is being parsed before being cached and will require the method to return a simple type (stdClass, or array) containing information that will be used to reinitialize the object when it is reawakened. The second method will be a static method and will be given the cached data and expected to reinitialize the object.&lt;br /&gt;
&lt;br /&gt;
A couple of things about this approach:&lt;br /&gt;
# This has been done so that objects can take control of what gets cached when they get cached. This allows them to ensure nothing dynamic will be cached and that they don&#039;t clutter thing if they are large structures.&lt;br /&gt;
# The interface and specific methods will be used rather than utilizing serialization etc because each cache plugin should have its own say on how to process data right before storing it and there will be no requirement to serialize data. This simplification of data happens automatically by some cache programs so there is no way we could ever rely on the magic serialize methods.&lt;br /&gt;
# It also has the advantage of clearly marking the object as cacheable when other developers are looking at the code.&lt;br /&gt;
&lt;br /&gt;
==Code specific information==&lt;br /&gt;
Basic details on my early thoughts of about the code.&lt;br /&gt;
&lt;br /&gt;
First up please note from the very start I had intended in my thinking and design contruct this design purely in an object orientated fashion. There will be no global functions introduced, everything will be made available through class static methods, or through object instance methods.&lt;br /&gt;
&lt;br /&gt;
===Directories and files===&lt;br /&gt;
The following unless otherwise stated make use of $CFG-&amp;gt;dirroot. Obvious requirements such as a plugins version and lang files have not been included in this list.&lt;br /&gt;
&lt;br /&gt;
; /cache : The cache plugin directory, and the home of the files that are essential to the cache solution.&lt;br /&gt;
; /cache/lib.php : Will contain all of the cache API core classes, and will be included in the list of requires presently happening within /lib/setup.php.&lt;br /&gt;
; /cache/settings.php : All of the general settings (and inclusion of external pages) for the cache solution. It will also be responsible for including plugin settings pages if they exist.&lt;br /&gt;
; /cache/pluginname : A directory used to house a cache plugin, pluginname will of course be the name of the plugin. It&#039;s component will be cache_pluginname.&lt;br /&gt;
; /cache/pluginname/lib.php : Will contain the plugin class and be included upon initialisation of cache_manager (its first use).&lt;br /&gt;
&lt;br /&gt;
===Essential classes and public methods===&lt;br /&gt;
&lt;br /&gt;
{| class=&amp;quot;nicetable&amp;quot;&lt;br /&gt;
|-&lt;br /&gt;
! colspan=&amp;quot;3&amp;quot; | cache_manager&lt;br /&gt;
|-&lt;br /&gt;
| static&lt;br /&gt;
| instance&lt;br /&gt;
| Will return an instance of the cache_manager. This instance will be statically stored within the method as only one cache_manager will ever be required under normal circumstances. However an override may be required to force a re-initialisation such as for configuration changes.&lt;br /&gt;
|-&lt;br /&gt;
| static&lt;br /&gt;
| prepare_data_for_caching&lt;br /&gt;
| Helper method to parse data removing references and interacting with cacheable objects.&lt;br /&gt;
|-&lt;br /&gt;
| static&lt;br /&gt;
| parse_cached_data&lt;br /&gt;
| When data is brought out of the cache it should be run through this.&lt;br /&gt;
|-&lt;br /&gt;
| static&lt;br /&gt;
| early_get_cache_plugins&lt;br /&gt;
| Gets all of the cache plugins that are available without using any core functions so that it can be called early before setup is finished.&lt;br /&gt;
|-&lt;br /&gt;
|&lt;br /&gt;
| add_plugin_instance&lt;br /&gt;
| For internal use to add a plugin instance to the configuration.&lt;br /&gt;
|-&lt;br /&gt;
|&lt;br /&gt;
| edit_plugin_instance&lt;br /&gt;
| For internal use to edit a plugin instance already in the configuration.&lt;br /&gt;
|-&lt;br /&gt;
|&lt;br /&gt;
| delete_plugin_instance&lt;br /&gt;
| For internal use to delete a plugin instance from the configuration.&lt;br /&gt;
|-&lt;br /&gt;
|&lt;br /&gt;
| add_instance_mapping&lt;br /&gt;
| For internal use to map a plugin instance to a cache type.&lt;br /&gt;
|-&lt;br /&gt;
|&lt;br /&gt;
| delete_instance_mapping&lt;br /&gt;
| For internal use to remove an instance =&amp;gt; cache type mapping.&lt;br /&gt;
|-&lt;br /&gt;
| &lt;br /&gt;
| get_cache_type_default&lt;br /&gt;
| Returns a cache instance that is the default for a given type&lt;br /&gt;
|-&lt;br /&gt;
|&lt;br /&gt;
| get_cache_type_instance&lt;br /&gt;
| Returns the cache instance to use for a given type. Returns the default is none is configured or ready.&lt;br /&gt;
|-&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
{| class=&amp;quot;nicetable&amp;quot;&lt;br /&gt;
|-&lt;br /&gt;
! abstract&lt;br /&gt;
! colspan=&amp;quot;2&amp;quot; | cache_type&lt;br /&gt;
|-&lt;br /&gt;
|&lt;br /&gt;
| get_type&lt;br /&gt;
| Returns the type of this cache type&lt;br /&gt;
|-&lt;br /&gt;
|&lt;br /&gt;
| is_user_specific&lt;br /&gt;
| Returns true if the cache type is user specific (request or session).&lt;br /&gt;
|-&lt;br /&gt;
|&lt;br /&gt;
| get&lt;br /&gt;
| Retrieves data from the cache for the instance&lt;br /&gt;
|-&lt;br /&gt;
|&lt;br /&gt;
| set&lt;br /&gt;
| Sends data to the cache for the instance.&lt;br /&gt;
|-&lt;br /&gt;
|&lt;br /&gt;
| has&lt;br /&gt;
| Checks if data exists in the cache for the instance.&lt;br /&gt;
|-&lt;br /&gt;
|&lt;br /&gt;
| delete&lt;br /&gt;
| Deletes the data for cache for the instance.&lt;br /&gt;
|-&lt;br /&gt;
|&lt;br /&gt;
| purge&lt;br /&gt;
| Purges all information from the entrie cache (not just the data specific to an instance).&lt;br /&gt;
|-&lt;br /&gt;
|&lt;br /&gt;
| uses_simple_types_only&lt;br /&gt;
| If called a flag is set to guarantee simple types only (scalars and array or stdClass instances containing scalars). This can be called to avoid the overhead of data parsing which is not required for simple types under most circumstances.&lt;br /&gt;
|-&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
{| class=&amp;quot;nicetable&amp;quot;&lt;br /&gt;
|-&lt;br /&gt;
! abstract&lt;br /&gt;
! colspan=&amp;quot;2&amp;quot; | cache_plugin&lt;br /&gt;
|-&lt;br /&gt;
| static&lt;br /&gt;
| is_supported&lt;br /&gt;
| Returns true if the plugin is supported (required things installed).&lt;br /&gt;
|-&lt;br /&gt;
| static&lt;br /&gt;
| is_supported_cache_type&lt;br /&gt;
| Returns true if the plugin can be used for the given cache type.&lt;br /&gt;
|-&lt;br /&gt;
| static&lt;br /&gt;
| supports_native_ttl&lt;br /&gt;
| Returns true if the plugin nativily supports ttl. If it doesn&#039;t then ttl will have to be managed internally.&lt;br /&gt;
|-&lt;br /&gt;
|&lt;br /&gt;
| initialise&lt;br /&gt;
| Initialises the plugin instance upon its first use.&lt;br /&gt;
|-&lt;br /&gt;
|&lt;br /&gt;
| is_ready&lt;br /&gt;
| Returns true if this plugin is properly configured and ready to be used.&lt;br /&gt;
|-&lt;br /&gt;
|&lt;br /&gt;
| supports_multikey&lt;br /&gt;
| Returns true if the plugin supports multiple keys, or if it wants to perform its own key handling.&lt;br /&gt;
|-&lt;br /&gt;
|&lt;br /&gt;
| get&lt;br /&gt;
| Retrieves the data for the given key from the cache.&lt;br /&gt;
|-&lt;br /&gt;
|&lt;br /&gt;
| set&lt;br /&gt;
| Adds the given key =&amp;gt; value pair to the cache program.&lt;br /&gt;
|-&lt;br /&gt;
|&lt;br /&gt;
| has&lt;br /&gt;
| Checks if there is data for the given key in the cache.&lt;br /&gt;
|-&lt;br /&gt;
|&lt;br /&gt;
| delete&lt;br /&gt;
| Deletes the data associated with the given key.&lt;br /&gt;
|-&lt;br /&gt;
|&lt;br /&gt;
| purge&lt;br /&gt;
| Purges all information from the cache.&lt;br /&gt;
|-&lt;br /&gt;
|&lt;br /&gt;
| close&lt;br /&gt;
| Gets called when the cache variable is destroyed (e.g. at the end of the request) and allows the plugin to perform and closing tasks and cleanup (closing connections, saving files etc).&lt;br /&gt;
|-&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
==Whats to be done==&lt;br /&gt;
The following is what needs to be done for before this can be put up for integration into core, hopefully in time for the release of 2.3&lt;br /&gt;
* Implement the Cache API&lt;br /&gt;
* Implement two special cache instances &amp;quot;static&amp;quot; and &amp;quot;dataroot&amp;quot; to serve as defaults and fall over systems when nothing has been configured or data being cached is unsuitable for the selected solution.&lt;br /&gt;
* Implement cache plugins for the following products&lt;br /&gt;
** APC&lt;br /&gt;
** Memcache&lt;br /&gt;
** XCache&lt;br /&gt;
** Database&lt;br /&gt;
** Static&lt;br /&gt;
** File&lt;br /&gt;
* Conversion of the following three areas in order or priority&lt;br /&gt;
*# Lang string cache. This will be be the first point of testing for the new system as the string requirements are predictable and should be significant enough to easily measure and quantify.&lt;br /&gt;
*# Database meta information, particularly focused around get_table, and get_column.&lt;br /&gt;
*# Config data, this will be a test of the system to ensure it can be initialized early on in overall system initialization.&lt;br /&gt;
* Create an admin tool that can create/edit/delete plugin instances as well as map them to cache types.&lt;br /&gt;
* Document the whole system and create tutorials in the docs wiki.&lt;br /&gt;
&lt;br /&gt;
==Whats to be done after the initial integration==&lt;br /&gt;
The following are things that can and or need to be done after integration:&lt;br /&gt;
* Convert existing cache and static variables/properties to make use of MUC instead [where applicable]&lt;br /&gt;
* Implement support for xxx/db/caches.php files that detail where caches are used and what for (read the next to do to see why)&lt;br /&gt;
* Expand the admin tool so that cache instances can be mapped to caches specified in xxx/db/caches.php files.&lt;br /&gt;
&lt;br /&gt;
==Proof of concept==&lt;br /&gt;
I&#039;ve created a proof of concept that implements the proposal as at the time of writing.&amp;lt;br/ &amp;gt;&lt;br /&gt;
This can be found on my github account: https://github.com/samhemelryk/moodle/compare/ba3e7df265...poc_cache_1&lt;br /&gt;
&lt;br /&gt;
While the proof of concept doesn&#039;t have the admin interfaces for configuring plugin instances it is largely functional and there a a couple of hundred PHPunit tests for it already.&lt;br /&gt;
&lt;br /&gt;
==Cache terminology==&lt;br /&gt;
; Cache : A cache is a collection of data that is kept on hand and made readily available in order to avoid costly fetching and molding upon every request. In this document when I refer to a cache I am referring to an area in code where such information is being dealt with.&lt;br /&gt;
; Cache solution : The solution refers the the MUC implementation and everything it embodies, the API, all of the plugins, the milestones etc.&lt;br /&gt;
; Cache API : The cache API consists of the cache manager, its supporting classes, and methods both public and private (Where I mention public API or outwards API I am referring to the public methods that developers will be able to make use of).&lt;br /&gt;
; Cache product : A 3rd party product that handles the actual caching on information such as APC, or memcache.&lt;br /&gt;
; Cache type: There are three cache types defined in this proposal, each is representative of one way of storing information.&lt;br /&gt;
; Cache plugin : A cache plugin is code that is reponsible for bridging the cache API and a particular cache product. For instance we expect to have an APC cache plugin.&lt;br /&gt;
; Cache instance : A cache instance is single instance of a cache plugin that has been configured to for a specific system. You can have multiple instances of a cache plugin, this is done so that you can direct different cache types to different memcache systems for instance.&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Contributing_to_Moodle&amp;diff=52689</id>
		<title>Contributing to Moodle</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Contributing_to_Moodle&amp;diff=52689"/>
		<updated>2017-07-12T12:29:31Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: /* Plugins */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;There are lots of ways you can contribute to the Moodle project:&lt;br /&gt;
&lt;br /&gt;
==User support==&lt;br /&gt;
&lt;br /&gt;
Join in with the international discussions in [http://moodle.org/course/view.php?id=5 Moodle in English] or [https://moodle.org/community/ community discussions in many other languages].&lt;br /&gt;
&lt;br /&gt;
==Documentation==&lt;br /&gt;
&lt;br /&gt;
Help write and edit our [https://docs.moodle.org/overview/ user documentation in various languages] or our [[Main_Page|developer docs]].&lt;br /&gt;
&lt;br /&gt;
==Plugins==&lt;br /&gt;
Is there a plugin that you use? [[Plugin_reviews|Write a review]] for it.&lt;br /&gt;
&lt;br /&gt;
==Testing==&lt;br /&gt;
&lt;br /&gt;
Help test and report bugs via the [http://tracker.moodle.org/ Moodle Tracker] (see the [[Tracker introduction|introduction to the Tracker]]) and participate in [[QA testing]].&lt;br /&gt;
&lt;br /&gt;
==Usability==&lt;br /&gt;
&lt;br /&gt;
Do some usability testing and report your results in [http://moodle.org/course/view.php?id=5 Moodle in English] or as suggested improvements in the [http://tracker.moodle.org/ Tracker].&lt;br /&gt;
&lt;br /&gt;
==Development==&lt;br /&gt;
&lt;br /&gt;
[[Process#Fixing_a_bug|Fix a bug]] in Moodle core.&lt;br /&gt;
&lt;br /&gt;
Help [http://moodle.org/development develop new code for Moodle] or share your code in the [https://moodle.org/plugins Plugins directory].&lt;br /&gt;
&lt;br /&gt;
Adopt a [https://moodle.org/plugins/browse.php?list=set&amp;amp;id=61 plugin seeking a new maintainer] and help many users. See the [https://moodle.org/mod/forum/discuss.php?d=260354 Plugins adoption programme].&lt;br /&gt;
&lt;br /&gt;
See the [[Moodle Wishlist]] for ideas that people have been brainstorming there, and start [[Working with the Community]].&lt;br /&gt;
&lt;br /&gt;
See also [https://docs.moodle.org/dev/Projects_for_new_developers projects for new developers] and [https://docs.moodle.org/dev/Tutorial a developer tutorial] to help you learn how to write plugins for Moodle from start to finish.&lt;br /&gt;
&lt;br /&gt;
==Themes==&lt;br /&gt;
&lt;br /&gt;
Share your theme in the [https://moodle.org/plugins/browse.php?list=category&amp;amp;id=3 Themes section of the plugins directory].&lt;br /&gt;
&lt;br /&gt;
==Translation==&lt;br /&gt;
&lt;br /&gt;
Assist with the [[Translation|translation]] of Moodle, including [[Contributing a translation|contributing a translation/correction]], [[Translating plugins|translating a plugin]], [[Translating Moodle video subtitles|translating Moodle 3.2 screencasts subtitles]] or [[Improving English language strings|suggesting an improvement to an English language string]].&lt;br /&gt;
&lt;br /&gt;
==Social media==&lt;br /&gt;
&lt;br /&gt;
Help [https://moodle.org/social/ raise awareness of the Moodle project and share the latest news and happenings] in the Moodle world&lt;br /&gt;
&lt;br /&gt;
==Books and video courses==&lt;br /&gt;
&lt;br /&gt;
A percentage of all sales from [https://moodle.org/mod/data/view.php?id=7246 books or video courses] goes to Moodle Pty Ltd to help support Moodle development.&lt;br /&gt;
&lt;br /&gt;
==Shop Official Merchandise==&lt;br /&gt;
&lt;br /&gt;
Moodle receives a percentage from each item purchased from our official merchandise store. [http://www.zazzle.com/moodle_hq Shop now] &lt;br /&gt;
&lt;br /&gt;
==Vote for future Moodle improvements==&lt;br /&gt;
&lt;br /&gt;
See the [https://docs.moodle.org/dev/New_feature_ideas new feature ideas]. [https://tracker.moodle.org/issues/?filter=10512 Check the Moodle tracker and vote] for the issues that you think will improve Moodle the most.&lt;br /&gt;
&lt;br /&gt;
==Moodle Partners==&lt;br /&gt;
&lt;br /&gt;
A certified network of Moodle Partners contribute to the Moodle Trust. With over 60 organisations, Moodle Partners offer services such as hosting, support, installation, custom coding, course development and consulting, amongst others. Find our full listing of [http://moodle.com/partners/  Moodle Partners here.] &lt;br /&gt;
&lt;br /&gt;
==Moodle Users Association==&lt;br /&gt;
&lt;br /&gt;
The [https://moodleassociation.org/ Moodle Users Association] is a not-for-profit incorporated association which helps to drive the Moodle project. It is a separate entity from Moodle Pty Ltd or any other entity involved in the Moodle open source project. The Association extends the global Moodle community to complement Moodle Partner provision of services to their clients, Moodle project development by Moodle HQ, and existing various community engagement formats and forums, including individual developments for non-Core installations.&lt;br /&gt;
&lt;br /&gt;
==More ways to contribute==&lt;br /&gt;
&lt;br /&gt;
Do you want to help but don&#039;t have the time? Do you want to give something back to the project to help pay the developers who make it happen? Then make a [http://moodle.org/donations donation] to the project, or contribute to a specific [https://moodle.org/mod/data/view.php?id=8090 crowdfunded project]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Contributing_to_Moodle&amp;diff=52688</id>
		<title>Contributing to Moodle</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Contributing_to_Moodle&amp;diff=52688"/>
		<updated>2017-07-12T12:29:06Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;There are lots of ways you can contribute to the Moodle project:&lt;br /&gt;
&lt;br /&gt;
==User support==&lt;br /&gt;
&lt;br /&gt;
Join in with the international discussions in [http://moodle.org/course/view.php?id=5 Moodle in English] or [https://moodle.org/community/ community discussions in many other languages].&lt;br /&gt;
&lt;br /&gt;
==Documentation==&lt;br /&gt;
&lt;br /&gt;
Help write and edit our [https://docs.moodle.org/overview/ user documentation in various languages] or our [[Main_Page|developer docs]].&lt;br /&gt;
&lt;br /&gt;
==Plugins==&lt;br /&gt;
Is there a plugin that you use? [[https://docs.moodle.org/dev/Plugin_reviews|Write a review]] for it.&lt;br /&gt;
&lt;br /&gt;
==Testing==&lt;br /&gt;
&lt;br /&gt;
Help test and report bugs via the [http://tracker.moodle.org/ Moodle Tracker] (see the [[Tracker introduction|introduction to the Tracker]]) and participate in [[QA testing]].&lt;br /&gt;
&lt;br /&gt;
==Usability==&lt;br /&gt;
&lt;br /&gt;
Do some usability testing and report your results in [http://moodle.org/course/view.php?id=5 Moodle in English] or as suggested improvements in the [http://tracker.moodle.org/ Tracker].&lt;br /&gt;
&lt;br /&gt;
==Development==&lt;br /&gt;
&lt;br /&gt;
[[Process#Fixing_a_bug|Fix a bug]] in Moodle core.&lt;br /&gt;
&lt;br /&gt;
Help [http://moodle.org/development develop new code for Moodle] or share your code in the [https://moodle.org/plugins Plugins directory].&lt;br /&gt;
&lt;br /&gt;
Adopt a [https://moodle.org/plugins/browse.php?list=set&amp;amp;id=61 plugin seeking a new maintainer] and help many users. See the [https://moodle.org/mod/forum/discuss.php?d=260354 Plugins adoption programme].&lt;br /&gt;
&lt;br /&gt;
See the [[Moodle Wishlist]] for ideas that people have been brainstorming there, and start [[Working with the Community]].&lt;br /&gt;
&lt;br /&gt;
See also [https://docs.moodle.org/dev/Projects_for_new_developers projects for new developers] and [https://docs.moodle.org/dev/Tutorial a developer tutorial] to help you learn how to write plugins for Moodle from start to finish.&lt;br /&gt;
&lt;br /&gt;
==Themes==&lt;br /&gt;
&lt;br /&gt;
Share your theme in the [https://moodle.org/plugins/browse.php?list=category&amp;amp;id=3 Themes section of the plugins directory].&lt;br /&gt;
&lt;br /&gt;
==Translation==&lt;br /&gt;
&lt;br /&gt;
Assist with the [[Translation|translation]] of Moodle, including [[Contributing a translation|contributing a translation/correction]], [[Translating plugins|translating a plugin]], [[Translating Moodle video subtitles|translating Moodle 3.2 screencasts subtitles]] or [[Improving English language strings|suggesting an improvement to an English language string]].&lt;br /&gt;
&lt;br /&gt;
==Social media==&lt;br /&gt;
&lt;br /&gt;
Help [https://moodle.org/social/ raise awareness of the Moodle project and share the latest news and happenings] in the Moodle world&lt;br /&gt;
&lt;br /&gt;
==Books and video courses==&lt;br /&gt;
&lt;br /&gt;
A percentage of all sales from [https://moodle.org/mod/data/view.php?id=7246 books or video courses] goes to Moodle Pty Ltd to help support Moodle development.&lt;br /&gt;
&lt;br /&gt;
==Shop Official Merchandise==&lt;br /&gt;
&lt;br /&gt;
Moodle receives a percentage from each item purchased from our official merchandise store. [http://www.zazzle.com/moodle_hq Shop now] &lt;br /&gt;
&lt;br /&gt;
==Vote for future Moodle improvements==&lt;br /&gt;
&lt;br /&gt;
See the [https://docs.moodle.org/dev/New_feature_ideas new feature ideas]. [https://tracker.moodle.org/issues/?filter=10512 Check the Moodle tracker and vote] for the issues that you think will improve Moodle the most.&lt;br /&gt;
&lt;br /&gt;
==Moodle Partners==&lt;br /&gt;
&lt;br /&gt;
A certified network of Moodle Partners contribute to the Moodle Trust. With over 60 organisations, Moodle Partners offer services such as hosting, support, installation, custom coding, course development and consulting, amongst others. Find our full listing of [http://moodle.com/partners/  Moodle Partners here.] &lt;br /&gt;
&lt;br /&gt;
==Moodle Users Association==&lt;br /&gt;
&lt;br /&gt;
The [https://moodleassociation.org/ Moodle Users Association] is a not-for-profit incorporated association which helps to drive the Moodle project. It is a separate entity from Moodle Pty Ltd or any other entity involved in the Moodle open source project. The Association extends the global Moodle community to complement Moodle Partner provision of services to their clients, Moodle project development by Moodle HQ, and existing various community engagement formats and forums, including individual developments for non-Core installations.&lt;br /&gt;
&lt;br /&gt;
==More ways to contribute==&lt;br /&gt;
&lt;br /&gt;
Do you want to help but don&#039;t have the time? Do you want to give something back to the project to help pay the developers who make it happen? Then make a [http://moodle.org/donations donation] to the project, or contribute to a specific [https://moodle.org/mod/data/view.php?id=8090 crowdfunded project]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Gradebook_export&amp;diff=52557</id>
		<title>Gradebook export</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Gradebook_export&amp;diff=52557"/>
		<updated>2017-06-08T09:06:00Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Introduction ==&lt;br /&gt;
&lt;br /&gt;
This document is for developers wanting to allow users to export Moodle grade information in a new export format. Here is another document if you are looking for [https://docs.moodle.org/en/Grade_export an introduction to exporting grades from Moodle]&lt;br /&gt;
&lt;br /&gt;
Moodle allows authorised users to export grade information. This can be used to to provide a teacher with a copy of their gradebook at a particular point in time or to extract student assessment data from Moodle so that it can be loaded into a piece of software other than Moodle.&lt;br /&gt;
&lt;br /&gt;
Since 1.9 the Moodle gradebook has provided support for the addition of plug-in export modules to allow Moodle to export grade information in new or custom formats. Moodle includes several default gradebook export modules that produce formats like Excel or CSV that will work in most situations.&lt;br /&gt;
&lt;br /&gt;
This document describes how to implement a custom gradebook export plug-in in case you need gradebook data in a format that is not available using the provided export modules.&lt;br /&gt;
&lt;br /&gt;
== Getting started ==&lt;br /&gt;
&lt;br /&gt;
The gradebook export modules are located in the &#039;&#039;&#039;grade/export&#039;&#039;&#039; directory.  To create a new gradebook export, complete the steps listed below.&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;Note&#039;&#039;&#039;: For the remainder of this topic when you see [newexport], replace it with the short name you have choosen for your export, do not include the [].  Moodle comes with the following exports: ods, txt, xls, and xml so you cannot use those names.&lt;br /&gt;
&lt;br /&gt;
== New Gradebook Export Module Creation Steps ==&lt;br /&gt;
&lt;br /&gt;
* Decide on a short name for this new export.  This name will be referred to as [newexport] the remainder of this topic.&lt;br /&gt;
* Create a new directory in Moodle&#039;s grade/export directory for your files.&lt;br /&gt;
* Review the export formats that ship with Moodle and choose the export format most like the one you wish to develop.  Refer to that export&#039;s files as needed.&lt;br /&gt;
* Copy the files from the export format you selected into your newly created directory of grade/export/[newexport]&lt;br /&gt;
* Alter each of the files listed below so they produce the data you desire.&lt;br /&gt;
* Click on Notifications in the Site Administration menu to go through the upgrade process and set up the permissions for your export format.&lt;br /&gt;
* Test, test, test - until your export performs properly.&lt;br /&gt;
&lt;br /&gt;
=== Files That Need Special Attention ===&lt;br /&gt;
&lt;br /&gt;
==== /grade/export/[newexport]/db/access.php ====&lt;br /&gt;
&lt;br /&gt;
The access.php file makes your gradebook export available to teachers and allows the security administrator to decide who can and cannot access this export module.  See the &amp;quot;View role details&amp;quot; page in Site Administration &amp;gt; Users &amp;gt; Permissions &amp;gt; Define roles for more details.&lt;br /&gt;
&lt;br /&gt;
For your export to have the same set of permissions as the other exports, change the lines listed below replacing the old export format name with [newexport].&lt;br /&gt;
 &lt;br /&gt;
         &#039;gradeexport/[newexport]:view&#039; =&amp;gt; array(&lt;br /&gt;
 &lt;br /&gt;
         &#039;gradeexport/[newexport]:publish&#039; =&amp;gt; array(&lt;br /&gt;
&lt;br /&gt;
The new security role entries will be available after an upgrade has been completed (click the Notifications link in Site Administration).  This should not be done until you have worked through each of the files listed in this section.&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;Note&#039;&#039;&#039;: The gradeexport_[newexport].php file in the lang directory works with the :view and :publish settings to provide a description.  See the information about that file for more details.&lt;br /&gt;
&lt;br /&gt;
==== /grade/export/[newexport]/dump.php ====&lt;br /&gt;
&lt;br /&gt;
The only change needed in this file is the following capability checks:&lt;br /&gt;
&lt;br /&gt;
   require_capability(&#039;gradeexport/[newexport]:publish&#039;, $context);&lt;br /&gt;
   require_capability(&#039;gradeexport/[newexport]:view&#039;, $context);&lt;br /&gt;
&lt;br /&gt;
==== /grade/export/[newexport]/export.php ====&lt;br /&gt;
&lt;br /&gt;
The following lines need to be changed to reflect your new export&#039;s name.&lt;br /&gt;
&lt;br /&gt;
   require_once &#039;grade_export_[newexport].php&#039;;&lt;br /&gt;
   require_capability(&#039;gradeexport/[newexport]:view&#039;, $context);&lt;br /&gt;
   $export = new grade_export_[newexport]($course, $groupid, $itemids, $export_feedback, $updatedgradesonly, $displaytype, $decimalpoints, $separator);&lt;br /&gt;
&lt;br /&gt;
==== /grade/export/[newexport]/grade_export_[newexport].php ====&lt;br /&gt;
&lt;br /&gt;
The following lines need to be changed to reflect your new export&#039;s name.&lt;br /&gt;
&lt;br /&gt;
   class grade_export_[newexport] extends grade_export {&lt;br /&gt;
   var $plugin = &#039;[newexport]&#039;;&lt;br /&gt;
   function grade_export_[newexport]($course, $groupid=0, $itemlist=&#039;&#039;, ...&lt;br /&gt;
&lt;br /&gt;
==== /grade/export/[newexport]/index.php ====&lt;br /&gt;
&lt;br /&gt;
The following lines need to be changed to reflect your new export&#039;s name.&lt;br /&gt;
&lt;br /&gt;
   require_once &#039;grade_export_[newexport].php&#039;;&lt;br /&gt;
   require_capability(&#039;gradeexport/[newexport]:view&#039;, $context);&lt;br /&gt;
   print_grade_page_head($COURSE-&amp;gt;id, &#039;export&#039;, &#039;[newexport]&#039;, get_string(&#039;exportto&#039;, &#039;grades&#039;) . &#039; &#039; . get_string(&#039;modulename&#039;, &#039;gradeexport_[newexport]&#039;));&lt;br /&gt;
   $CFG-&amp;gt;gradepublishing = has_capability(&#039;gradeexport/[newexport]:publish&#039;, $context);&lt;br /&gt;
   $export = new grade_export_[newexport]($course, $currentgroup, &#039;&#039;, false, false, $data-&amp;gt;display, $data-&amp;gt;decimals);&lt;br /&gt;
&lt;br /&gt;
==== /grade/export/[newexport]/version.php ====&lt;br /&gt;
&lt;br /&gt;
Use the current dates for your export module.  If any adjustments are made to your security or if any database changes are needed (see the db/access.php file above) the version will need to be incremented and an upgrade will be performed (log in as admin and click the Notifications link on the Site Administration causes Moodle to check if an upgrade is necessary).&lt;br /&gt;
&lt;br /&gt;
Your version.php will look something like this ...&lt;br /&gt;
&lt;br /&gt;
     $plugin-&amp;gt;version  = 2007092700;&lt;br /&gt;
     $plugin-&amp;gt;requires = 2007101000;&lt;br /&gt;
&lt;br /&gt;
==== /lang/en_utf8/gradeexport_[newexport].php  ====&lt;br /&gt;
&#039;&#039;&#039;Note:&#039;&#039;&#039; Replace en_utf8 with your language directory if using multiple languages or a language other than English.  Copy one of the existing files (i.e. gradeexport_txt.php) to create your new gradebook export language file.&lt;br /&gt;
&lt;br /&gt;
When you first create your gradebook export directory and look in the Action menu of the Moodle gradebook, your new export module will be listed as &amp;lt;nowiki&amp;gt;[[modulename]]&amp;lt;/nowiki&amp;gt;.  The &#039;&#039;&#039;modulename&#039;&#039;&#039; string in this file will provide the Action menu with the name specified. &lt;br /&gt;
&lt;br /&gt;
The :view and the :publish strings are used to display a meaningful description on the security roles for users.  These two descriptions work in conjunction with the db/access.php file.  See the information about the db/access.php file for more details.&lt;br /&gt;
&lt;br /&gt;
The gradeexport_txt.php (Plain text file export) is shown below without the PHP tags.  Change &amp;quot;Plain text file&amp;quot; to the name of the new export and replace &amp;quot;txt&amp;quot; with the [newexport] value.  Change the comments after the &amp;quot;:view&amp;quot; and &amp;quot;:publish&amp;quot; to descriptions that should appear on the role details page for your new export.&lt;br /&gt;
&lt;br /&gt;
     $string[&#039;modulename&#039;] = &#039;Plain text file&#039;;&lt;br /&gt;
     $string[&#039;txt:view&#039;] = &#039;Use text grade export&#039;;&lt;br /&gt;
     $string[&#039;txt:publish&#039;] = &#039;Publish TXT grade export&#039;;&lt;br /&gt;
&lt;br /&gt;
To better illustrate, if your module had a short name of &amp;quot;sis&amp;quot; and a description of &amp;quot;My Student Info System&amp;quot;, then this file would like something like the following ...&lt;br /&gt;
&lt;br /&gt;
     $string[&#039;modulename&#039;] = &#039;My Student Info System&#039;;&lt;br /&gt;
     $string[&#039;sis:view&#039;] = &#039;Use My SIS grade export&#039;;&lt;br /&gt;
     $string[&#039;sis:publish&#039;] = &#039;Publish SIS grade export&#039;;&lt;br /&gt;
&lt;br /&gt;
=== A Safety Check For References to the Original Export Module ===&lt;br /&gt;
To make sure no references to the original export format have been missed you can use grep (in Linux) or an equivalent command in Windows or Mac. For example, if you copied &amp;quot;txt&amp;quot; when creating your export module you could use a command similar to the following.&lt;br /&gt;
&lt;br /&gt;
     grep -R &amp;quot;txt&amp;quot; ./grade/export/[newexport]/&lt;br /&gt;
&lt;br /&gt;
=== Customizing Your Export Module ===&lt;br /&gt;
&lt;br /&gt;
At this point your export is in its own directory, has its own security identifiers, and has its own name but it behaves just like the export you copied from.  In this section we will look at how to customize the behavior of your export.&lt;br /&gt;
&lt;br /&gt;
==== Changing the Grade Export Form Options ====&lt;br /&gt;
&lt;br /&gt;
The grade export form (used to select options when exporting) can be altered by opening the grade/export/[newexport]/index.php file and finding the line similar to the one shown below:&lt;br /&gt;
&lt;br /&gt;
   $mform = new grade_export_form(null, array(&#039;includeseparator&#039;=&amp;gt;true, &#039;publishing&#039; =&amp;gt; true));&lt;br /&gt;
&lt;br /&gt;
The part of that statement starting with &#039;&#039;&#039;array(&#039;&#039;&#039; can be altered to pass feature parameters into the grade_export_form class.  Refer to the file grade/export/grade_export_form.php for the details of the available feature parameters and how they affect the grade export form.  The grade_export_form.php file should not be altered as it is part of the Moodle core code and will affect the other exports as well.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
==== Changing the Format and Fields in the Export File ====&lt;br /&gt;
&lt;br /&gt;
To change the format of the export file and the fields in the export file, edit the grade/export/[newexport]/grade_export_[newexport].php file.  The echo statements in the print_grades() function determine what will be included in the export file.  Make whatever adjustments to the echo statements in this function that your new export needs.&lt;br /&gt;
&lt;br /&gt;
The [[Grades]] documentation referenced in the See Also section below will help in understanding the gradebook and what values are available for use in your export.  The variables can also be dumped to see their structure and contents.&lt;br /&gt;
&lt;br /&gt;
For example, the following two statements will show you what is in the $userdata-&amp;gt;grades and $this-&amp;gt;columns structures.  If you include these statements in the print_grades() function then you will see the results in your export file.&lt;br /&gt;
&lt;br /&gt;
   var_dump($userdata-&amp;gt;grades);&lt;br /&gt;
   var_dump($this-&amp;gt;columns);&lt;br /&gt;
&lt;br /&gt;
== See also ==&lt;br /&gt;
* [[Grades]]&lt;br /&gt;
* [[Gradebook_import]]&lt;br /&gt;
&lt;br /&gt;
[[Category:Grades]]&lt;br /&gt;
[[Category:Plugins]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Javascript_FAQ&amp;diff=52464</id>
		<title>Javascript FAQ</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Javascript_FAQ&amp;diff=52464"/>
		<updated>2017-05-21T16:48:26Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: /* How is JavaScript used by Moodle? */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== What is JavaScript? ==&lt;br /&gt;
&lt;br /&gt;
JavaScript is a scripting language widely used for client-side web development. It is also known by a number of other names including ECMAScript, and JScript (these are all the same thing but exist due to issues over the licensing of these names).&lt;br /&gt;
&lt;br /&gt;
If you have a spare 27 minutes and would like a quick background on JavaScript and it&#039;s origins, see this video from Douglas Crockford &#039;[http://www.youtube.com/watch?v=gz7KL7ZirZc JSeverywhere: Douglas Crockford - JavaScript, The World&#039;s Most Misunderstood Language]&#039;.&lt;br /&gt;
&lt;br /&gt;
== Where do I find general information about JavaScript? ==&lt;br /&gt;
&lt;br /&gt;
=== Online resources: ===&lt;br /&gt;
* [http://en.wikipedia.org/wiki/JavaScript JavaScript (Wikipedia)]&lt;br /&gt;
* [http://articles.sitepoint.com/category/javascript Sitepoint JavaScript tutorials]&lt;br /&gt;
&lt;br /&gt;
=== Books: ===&lt;br /&gt;
* [http://shop.oreilly.com/product/9780596517748.do JavaScript: The Good Parts] by Douglas Crockford&lt;br /&gt;
* [http://oreilly.com/catalog/9780596101992 JavaScript: The Definitive Guide, Fifth Edition] by David Flanagan - Really the ultimate reference guide (nearly 1000 pages).&lt;br /&gt;
* [http://www.sitepoint.com/books/jsant1/ The JavaScript Anthology: 101 Essential Tips, Tricks &amp;amp; Hacks] by James Edwards &amp;amp; Cameron Adams - Promotes accessible JavaScript solutions by following the principles of [[Progressive enhancement| progressive enhancement]] and [[Unobtrusive_Javascript| unobtrusive scripting]].&lt;br /&gt;
&lt;br /&gt;
== How is JavaScript used by Moodle? ==&lt;br /&gt;
&lt;br /&gt;
* See [[Javascript]].&lt;br /&gt;
&lt;br /&gt;
== Where do I find more information about JavaScript in Moodle? ==&lt;br /&gt;
&lt;br /&gt;
* [[JavaScript_guidelines|JavaScript Guidelines]] by Tim Hunt (work in progress)&lt;br /&gt;
* [http://moodle.org/mod/forum/discuss.php?d=106312 Use of JavaScript in Moodle] discussion in the General developer forum&lt;br /&gt;
&lt;br /&gt;
== What JavaScript library does Moodle use? ==&lt;br /&gt;
=== JQuery ===&lt;br /&gt;
As of Moodle 2.9, [[jQuery]] is the preferred javascript library. Most of the code is still using YUI though as we are only beginning to transition to [[jQuery]].&lt;br /&gt;
&lt;br /&gt;
==== Online resources: ====&lt;br /&gt;
* [http://addyosmani.com/writing-modular-js/ Writing Modular Javascript]&lt;br /&gt;
* [http://jqueryenlightenment.com/jquery_enlightenment.pdf JQuery Enlightenment]&lt;br /&gt;
* [[jQuery]] in Moodle&lt;br /&gt;
* [http://jquery.com/ jQuery] &lt;br /&gt;
* [http://visualjquery.com Visual jQuery]&lt;br /&gt;
* [http://jqueryfordesigners.com jQuery for Designers]&lt;br /&gt;
&lt;br /&gt;
==== Books: ====&lt;br /&gt;
* [http://www.manning.com/bibeault/ jQuery in Action] by Bear Bibeault and Yehuda Katz&lt;br /&gt;
* [http://www.packtpub.com/jQuery/book Learning jQuery] by Karl Swedberg and Jonathan Chaffer&lt;br /&gt;
* [http://www.packtpub.com/jquery-reference-guide-Open-Source/book jQuery Reference Guide] by Jonathan Chaffer and Karl Swedberg&lt;br /&gt;
&lt;br /&gt;
=== Yahoo! User Interface Library (YUI) === &lt;br /&gt;
Until Moodle 2.9, the Yahoo! User Interface Library (YUI) was the preferred javascript library. From Moodle 2.9 onwards, jQuery is the preferred javascript library. &lt;br /&gt;
&lt;br /&gt;
==== Online resources: ====&lt;br /&gt;
* [http://yuilibrary.com Yahoo! User Interface Library (YUI)]&lt;br /&gt;
* [[YUI]] in the Moodle documentation&lt;br /&gt;
&lt;br /&gt;
==== Books: ====&lt;br /&gt;
* [http://shop.oreilly.com/product/0636920013303.do YUI 3 Cookbook] by Evan Goer&lt;br /&gt;
* [http://shop.oreilly.com/product/0636920025245.do Maintainable JavaScript] by Nicholas C. Zakas&lt;br /&gt;
&lt;br /&gt;
==== Why are we moving away from YUI ? ====&lt;br /&gt;
The decision to begin the transition from YUI to JQuery was made here:&lt;br /&gt;
&lt;br /&gt;
https://tracker.moodle.org/browse/MDL-47036&lt;br /&gt;
&lt;br /&gt;
This is in response to Yahoos announcement that they will be ceasing all further development on YUI (although it is still maintained). &lt;br /&gt;
http://yahooeng.tumblr.com/post/96098168666/important-announcement-regarding-yui&lt;br /&gt;
&lt;br /&gt;
== What does AJAX mean? ==&lt;br /&gt;
AJAX means &amp;quot;Asynchronous JavaScript and XML&amp;quot;. It is a group of interrelated web development techniques used to create interactive web applications or rich Internet applications.&lt;br /&gt;
Although XML is included in the acronym, AJAX is not a single technology but a group of technologies. In reality with modern JS, this tends to be JSON which is much more lightweight and easy to produce in PHP than XML.&lt;br /&gt;
&lt;br /&gt;
See [http://en.wikipedia.org/wiki/Ajax_(programming) AJAX (Wikipedia)] for general information and [[AJAX]] for information on AJAX and Moodle.&lt;br /&gt;
&lt;br /&gt;
See also [[Firebug#Debugging AJAX_with_Firebug|Firebug &amp;gt; Debugging AJAX with Firebug]].&lt;br /&gt;
&lt;br /&gt;
== See also ==&lt;br /&gt;
&lt;br /&gt;
* [[jQuery]]&lt;br /&gt;
* [[Javascript and YUI 3 FAQ]]&lt;br /&gt;
&lt;br /&gt;
[[Category:FAQ]]&lt;br /&gt;
[[Category:Javascript]]&lt;br /&gt;
[[Category:AJAX]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Acceptance_testing/Browsers/Working_combinations_of_OS%2BBrowser%2Bselenium&amp;diff=51998</id>
		<title>Acceptance testing/Browsers/Working combinations of OS+Browser+selenium</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Acceptance_testing/Browsers/Working_combinations_of_OS%2BBrowser%2Bselenium&amp;diff=51998"/>
		<updated>2017-03-07T08:32:04Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: /* Moodle 3.1 */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;= Working combinations of OS+Browser+selenium =&lt;br /&gt;
As OS, Browsers and Selenium keeps updating, some combination might fail on different Moodle releases.&lt;br /&gt;
&lt;br /&gt;
Following combinations have been tested at the time of release of Moodle version and will be supported for that combination. &lt;br /&gt;
NOTE:  Chromedriver &amp;gt;= 2.17 is required for behat to capture exceptions&lt;br /&gt;
&lt;br /&gt;
== Moodle 3.2 and master ==&lt;br /&gt;
{| class=&amp;quot;wikitable&amp;quot;&lt;br /&gt;
|OS&lt;br /&gt;
|Browser&lt;br /&gt;
|Selenium Server&lt;br /&gt;
|Chrome Driver&lt;br /&gt;
|IE Driver&lt;br /&gt;
|-&lt;br /&gt;
| Linux - Ubuntu 16.04&lt;br /&gt;
| Firefox 47.0.1&lt;br /&gt;
| [http://selenium-release.storage.googleapis.com/2.53/selenium-server-standalone-2.53.1.jar 2.53.1]&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
|Linux - Ubuntu 16.04&lt;br /&gt;
|[https://www.googleapis.com/download/storage/v1/b/chromium-browser-snapshots/o/Linux_x64%2F386249%2Fchrome-linux.zip?generation=1460160957434000&amp;amp;alt=media Chrome 53.0]&lt;br /&gt;
| [http://selenium-release.storage.googleapis.com/index.html?path=3.0/ 3.0.1]&lt;br /&gt;
| [http://chromedriver.storage.googleapis.com/index.html?path=2.25/ 2.25]&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
| Linux - Ubuntu 16.04&lt;br /&gt;
| Phantomjs 2.1.1&lt;br /&gt;
| 2.53.1&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
| Windows 7/10&lt;br /&gt;
| Firefox 47.0.1&lt;br /&gt;
| 2.53.1&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
| Windows 7/10&lt;br /&gt;
| Chrome v53.0&lt;br /&gt;
| [http://selenium-release.storage.googleapis.com/index.html?path=3.0/ 3.0.1]&lt;br /&gt;
| [http://chromedriver.storage.googleapis.com/index.html?path=2.25/ 2.25]&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
| MacOS X&lt;br /&gt;
| Firefox 47.0.1&lt;br /&gt;
| 2.53.1&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
| MacOS X&lt;br /&gt;
| [http://www.slimjet.com/chrome/google-chrome-old-version.php Chrome v53.0]&lt;br /&gt;
| [http://selenium-release.storage.googleapis.com/index.html?path=3.0/ 3.0.1]&lt;br /&gt;
| [http://chromedriver.storage.googleapis.com/index.html?path=2.25/ 2.25]&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
| MacOS X&lt;br /&gt;
| PhantomJS 2.1.1&lt;br /&gt;
| 2.53.1&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
== Moodle 3.1 ==&lt;br /&gt;
{| class=&amp;quot;wikitable&amp;quot;&lt;br /&gt;
|OS&lt;br /&gt;
|Browser&lt;br /&gt;
|Selenium Server&lt;br /&gt;
|Chrome Driver&lt;br /&gt;
|IE Driver&lt;br /&gt;
|-&lt;br /&gt;
| Linux - Ubuntu 16.04&lt;br /&gt;
| [https://download.mozilla.org/?product=firefox-47.0.1-SSL&amp;amp;os=linux64&amp;amp;lang=en-GB Firefox 47.0.1]&lt;br /&gt;
| [http://selenium-release.storage.googleapis.com/2.53/selenium-server-standalone-2.53.1.jar 2.53.1]&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
|Linux - Ubuntu 16.04&lt;br /&gt;
|[https://www.googleapis.com/download/storage/v1/b/chromium-browser-snapshots/o/Linux_x64%2F386249%2Fchrome-linux.zip?generation=1460160957434000&amp;amp;alt=media Chrome 51.0]&lt;br /&gt;
| 2.53.1&lt;br /&gt;
| 2.22&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
| Linux - Ubuntu 16.04&lt;br /&gt;
| Phantomjs 2.1.1&lt;br /&gt;
| 2.53.1&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
| Windows 7/10&lt;br /&gt;
| Firefox 47.0.1&lt;br /&gt;
| 2.53.1&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
| Windows 7/10&lt;br /&gt;
| Chrome v51.0&lt;br /&gt;
| 2.53.1&lt;br /&gt;
| 2.22&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
| MacOS X&lt;br /&gt;
| Firefox 47.0.1&lt;br /&gt;
| 2.53.1&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
| MacOS X&lt;br /&gt;
| Chrome v51.0&lt;br /&gt;
| 2.53.1&lt;br /&gt;
| 2.22&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
| MacOS X&lt;br /&gt;
| PhantomJS 2.1.1&lt;br /&gt;
| 2.53.1&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
== Moodle 3.0 and lower ==&lt;br /&gt;
{| class=&amp;quot;wikitable&amp;quot;&lt;br /&gt;
|OS&lt;br /&gt;
|Browser&lt;br /&gt;
|Selenium Server&lt;br /&gt;
|Chrome Driver&lt;br /&gt;
|IE Driver&lt;br /&gt;
|-&lt;br /&gt;
|Linux - Ubuntu 14.10&lt;br /&gt;
|Firefox 42.0&lt;br /&gt;
|2.47.1&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
|Linux - Ubuntu 14.10&lt;br /&gt;
|Chrome 46.0&lt;br /&gt;
|2.47.1&lt;br /&gt;
| 2.19.346067&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
|Linux - Ubuntu 14.10&lt;br /&gt;
|Phantomjs 2.0.0&lt;br /&gt;
|2.47.1&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
|Windows 7/10&lt;br /&gt;
|Firefox 41.0&lt;br /&gt;
|2.47.1&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
|Windows 7/10&lt;br /&gt;
|Chrome 47.0&lt;br /&gt;
|2.47.1&lt;br /&gt;
| 2.20&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
|MacOS X&lt;br /&gt;
|Firefox 41.0&lt;br /&gt;
|2.47.1&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
|MacOS X&lt;br /&gt;
|Chrome 46.0&lt;br /&gt;
|2.47.1&lt;br /&gt;
| 2.20&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
|MacOS X&lt;br /&gt;
|Chrome 48.0&lt;br /&gt;
|2.51.0&lt;br /&gt;
| 2.21&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
|MacOS X&lt;br /&gt;
|PhantomJS - 2.0.0 &amp;amp; 2.1.1&lt;br /&gt;
|2.48.2&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
[[Category:Behat]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Acceptance_testing/Browsers&amp;diff=51994</id>
		<title>Acceptance testing/Browsers</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Acceptance_testing/Browsers&amp;diff=51994"/>
		<updated>2017-03-03T16:00:06Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: /* Working combinations of OS+Browser+selenium */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;This page complements [[Acceptance testing]] providing info about how to run the acceptance tests suite in different browsers.&lt;br /&gt;
&lt;br /&gt;
== Drivers ==&lt;br /&gt;
&lt;br /&gt;
There are Selenium drivers (http://docs.seleniumhq.org/projects/webdriver/) to run acceptance tests in different browsers:&lt;br /&gt;
&lt;br /&gt;
* Firefox - https://code.google.com/p/selenium/wiki/FirefoxDriver&lt;br /&gt;
* Chrome - https://code.google.com/p/selenium/wiki/ChromeDriver&lt;br /&gt;
* Safari - https://code.google.com/p/selenium/wiki/SafariDriver&lt;br /&gt;
* Internet Explorer - https://code.google.com/p/selenium/wiki/InternetExplorerDriver&lt;br /&gt;
* Microsoft Edge - https://www.microsoft.com/en-us/download/details.aspx?id=48212&lt;br /&gt;
* PhantomJS (Webkit) - http://phantomjs.org/&lt;br /&gt;
* IPhone - https://code.google.com/p/selenium/wiki/IPhoneDriver&lt;br /&gt;
&lt;br /&gt;
Each driver should be downloaded and Selenium .jar should be started specifying the path to the driver; depending on the driver there could be other requirements. &lt;br /&gt;
&lt;br /&gt;
=== PhantomJS ===&lt;br /&gt;
&lt;br /&gt;
PhantomJS is different as it is a headless browser as it is quite faster than other drivers, it doesn&#039;t need a GUI to run and can execute JS, it doesn&#039;t even need to be used through Selenium (you can do it though, but it&#039;s not officially supported) and you can do it&lt;br /&gt;
&lt;br /&gt;
* Download PhantomJS: http://phantomjs.org/download.html&lt;br /&gt;
* /path/to/your/phantomjs/bin/phantomjs --webdriver=4444&lt;br /&gt;
&lt;br /&gt;
Note that 4444 is the default port used by Selenium so you must specify another one if you want to run them together and specify the port in $CFG-&amp;gt;behat_config.&lt;br /&gt;
&lt;br /&gt;
=== Examples ===&lt;br /&gt;
&lt;br /&gt;
  # Selenium in Linux (firefox by default + chrome)&lt;br /&gt;
  java -jar /opt/selenium-server-standalone.jar -Dwebdriver.chrome.driver=/opt/chromedriver&lt;br /&gt;
&lt;br /&gt;
  # Selenium in OSx (firefox &amp;amp; safari by default + chrome)&lt;br /&gt;
  java -jar /Users/moodle/Downloads/selenium-server-standalone.jar -Dwebdriver.chrome.driver=/Users/moodle/Downloads/chromedriver&lt;br /&gt;
&lt;br /&gt;
  # Selenium in Windows (started using git bash) (firefox by default + chrome + internet explorer)&lt;br /&gt;
  java -jar /c/seleniumdrivers/selenium-server-standalone.jar -Dwebdriver.chrome.driver=/c/seleniumdrivers/chromedriver.exe -Dwebdriver.ie.driver=/c/seleniumdrivers/IEDriverServer.exe&lt;br /&gt;
&lt;br /&gt;
  # PhantomJS&lt;br /&gt;
  /path/to/your/phantomjs/bin/phantomjs --webdriver=4444&lt;br /&gt;
&lt;br /&gt;
== Compatibility ==&lt;br /&gt;
Not all the drivers can execute all of Moodle&#039;s step definitions; we tagged the step definitions that are using features not supported by all browsers and also limitations that some browsers have; refer to the following table to know which browsers can run which tags:&lt;br /&gt;
&lt;br /&gt;
{| class=&amp;quot;wikitable&amp;quot;&lt;br /&gt;
|&lt;br /&gt;
|File uploads (@_file_upload)&lt;br /&gt;
|Browser dialogs (@_alert)&lt;br /&gt;
|Switch window (@_switch_window)&lt;br /&gt;
|Switch frame (@_switch_iframe)&lt;br /&gt;
|Bug in phantomjs (@_bug_phantomjs)&lt;br /&gt;
|-&lt;br /&gt;
|Firefox&lt;br /&gt;
|&amp;lt;span style=&amp;quot;color:#0f0&amp;quot;&amp;gt;Yes&amp;lt;/span&amp;gt;&lt;br /&gt;
|&amp;lt;span style=&amp;quot;color:#0f0&amp;quot;&amp;gt;Yes&amp;lt;/span&amp;gt;&lt;br /&gt;
|&amp;lt;span style=&amp;quot;color:#0f0&amp;quot;&amp;gt;Yes&amp;lt;/span&amp;gt;&lt;br /&gt;
|&amp;lt;span style=&amp;quot;color:#0f0&amp;quot;&amp;gt;Yes&amp;lt;/span&amp;gt;&lt;br /&gt;
|&amp;lt;span style=&amp;quot;color:#0f0&amp;quot;&amp;gt;Yes&amp;lt;/span&amp;gt;&lt;br /&gt;
|-&lt;br /&gt;
|Chrome&lt;br /&gt;
|&amp;lt;span style=&amp;quot;color:#0f0&amp;quot;&amp;gt;Yes&amp;lt;/span&amp;gt;&lt;br /&gt;
|&amp;lt;span style=&amp;quot;color:#0f0&amp;quot;&amp;gt;Yes&amp;lt;/span&amp;gt;&lt;br /&gt;
|&amp;lt;span style=&amp;quot;color:#0f0&amp;quot;&amp;gt;Yes&amp;lt;/span&amp;gt;&lt;br /&gt;
|&amp;lt;span style=&amp;quot;color:#0f0&amp;quot;&amp;gt;Yes&amp;lt;/span&amp;gt;&lt;br /&gt;
|&amp;lt;span style=&amp;quot;color:#0f0&amp;quot;&amp;gt;Yes&amp;lt;/span&amp;gt;&lt;br /&gt;
|-&lt;br /&gt;
|Internet Explorer&lt;br /&gt;
|&amp;lt;span style=&amp;quot;color:#0f0&amp;quot;&amp;gt;Yes&amp;lt;/span&amp;gt;&lt;br /&gt;
|&amp;lt;span style=&amp;quot;color:#0f0&amp;quot;&amp;gt;Yes&amp;lt;/span&amp;gt;&lt;br /&gt;
|&amp;lt;span style=&amp;quot;color:red&amp;quot;&amp;gt;No&amp;lt;/span&amp;gt;&lt;br /&gt;
|&amp;lt;span style=&amp;quot;color:#0f0&amp;quot;&amp;gt;Yes&amp;lt;/span&amp;gt;&lt;br /&gt;
|&amp;lt;span style=&amp;quot;color:#0f0&amp;quot;&amp;gt;Yes&amp;lt;/span&amp;gt;&lt;br /&gt;
|-&lt;br /&gt;
|Safari&lt;br /&gt;
|&amp;lt;span style=&amp;quot;color:#0f0&amp;quot;&amp;gt;Yes&amp;lt;/span&amp;gt;&lt;br /&gt;
|&amp;lt;span style=&amp;quot;color:red&amp;quot;&amp;gt;No&amp;lt;/span&amp;gt;&lt;br /&gt;
|&amp;lt;span style=&amp;quot;color:red&amp;quot;&amp;gt;No&amp;lt;/span&amp;gt;&lt;br /&gt;
|&amp;lt;span style=&amp;quot;color:#0f0&amp;quot;&amp;gt;Yes&amp;lt;/span&amp;gt;&lt;br /&gt;
|&amp;lt;span style=&amp;quot;color:#0f0&amp;quot;&amp;gt;Yes&amp;lt;/span&amp;gt;&lt;br /&gt;
|-&lt;br /&gt;
|PhantomJS&lt;br /&gt;
|&amp;lt;span style=&amp;quot;color:red&amp;quot;&amp;gt;No&amp;lt;/span&amp;gt;&lt;br /&gt;
|&amp;lt;span style=&amp;quot;color:red&amp;quot;&amp;gt;No&amp;lt;/span&amp;gt;&lt;br /&gt;
|&amp;lt;span style=&amp;quot;color:#0f0&amp;quot;&amp;gt;Yes&amp;lt;/span&amp;gt;&lt;br /&gt;
|&amp;lt;span style=&amp;quot;color:#0f0&amp;quot;&amp;gt;Yes&amp;lt;/span&amp;gt;&lt;br /&gt;
|&amp;lt;span style=&amp;quot;color:red&amp;quot;&amp;gt;No&amp;lt;/span&amp;gt;&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
== Working combinations of OS+Browser+selenium ==&lt;br /&gt;
As OS, Browsers and Selenium keeps updating, some combination of OS+Browser+Selenium will not work on specific moodle version.&lt;br /&gt;
&lt;br /&gt;
We try to support the latest version of these combinations but they are not always BC and hence may not work with older releases. Please refer to [[Acceptance testing/Browsers/Working combinations of OS+Browser+selenium]] to ensure you have correct combination of them to run acceptance test.&lt;br /&gt;
&lt;br /&gt;
== Moodle configuration ==&lt;br /&gt;
You need to tell behat what browser do you want to run and where it is. The best option could be to use behat profiles (http://docs.behat.org/guides/7.config.html#profiles).&lt;br /&gt;
&lt;br /&gt;
The profiles can be specified in config.php through $CFG-&amp;gt;behat_config like all other behat.yml specific configurations. &lt;br /&gt;
&lt;br /&gt;
This is an example of $CFG-&amp;gt;behat_config to run behat in multiple environments (Windows, Linux and OSx) to cover all the supported browsers. Note that we are using multiple servers so we skip the tests that involves files uploads when using a remote server.&lt;br /&gt;
&lt;br /&gt;
    // Note that in this case $linuxip is the local server.&lt;br /&gt;
    // Set servers IPs.&lt;br /&gt;
    $linuxip = &#039;127.0.0.1&#039;;&lt;br /&gt;
    $windowsip = &#039;192.168.xxx.xxx&#039;;&lt;br /&gt;
    $osxip = &#039;192.168.xxx.xxx&#039;;&lt;br /&gt;
    $CFG-&amp;gt;behat_config = array(&lt;br /&gt;
        &#039;phantomjs-linux&#039; =&amp;gt; array(&lt;br /&gt;
            &#039;filters&#039; =&amp;gt; array(&lt;br /&gt;
                &#039;tags&#039; =&amp;gt; &#039;~@_bug_phantomjs&amp;amp;&amp;amp;~@_file_upload&amp;amp;&amp;amp;~@_alert&#039;&lt;br /&gt;
            ),&lt;br /&gt;
           &#039;extensions&#039; =&amp;gt; array(&lt;br /&gt;
               &#039;Behat\MinkExtension\Extension&#039; =&amp;gt; array(&lt;br /&gt;
                   &#039;selenium2&#039; =&amp;gt; array(&lt;br /&gt;
                       &#039;browser&#039; =&amp;gt; &#039;phantomjs&#039;,&lt;br /&gt;
                       &#039;wd_host&#039; =&amp;gt; &#039;http://&#039; . $linuxip . &#039;:4444/wd/hub&#039;&lt;br /&gt;
                   )&lt;br /&gt;
               )&lt;br /&gt;
           )&lt;br /&gt;
        ),&lt;br /&gt;
        &#039;chrome-linux&#039; =&amp;gt; array(&lt;br /&gt;
            &#039;extensions&#039; =&amp;gt; array(&lt;br /&gt;
                &#039;Behat\MinkExtension\Extension&#039; =&amp;gt; array(&lt;br /&gt;
                    &#039;selenium2&#039; =&amp;gt; array(&lt;br /&gt;
                        &#039;browser&#039; =&amp;gt; &#039;chrome&#039;,&lt;br /&gt;
                        &#039;wd_host&#039; =&amp;gt; &#039;http://&#039; . $linuxip . &#039;:4444/wd/hub&#039;&lt;br /&gt;
                    )&lt;br /&gt;
                )&lt;br /&gt;
            )&lt;br /&gt;
        ),&lt;br /&gt;
        &#039;chrome-osx&#039; =&amp;gt; array(&lt;br /&gt;
            &#039;filters&#039; =&amp;gt; array(&lt;br /&gt;
                &#039;tags&#039; =&amp;gt; &#039;~@_file_upload&#039;&lt;br /&gt;
            ),&lt;br /&gt;
            &#039;extensions&#039; =&amp;gt; array(&lt;br /&gt;
                &#039;Behat\MinkExtension\Extension&#039; =&amp;gt; array(&lt;br /&gt;
                    &#039;selenium2&#039; =&amp;gt; array(&lt;br /&gt;
                        &#039;browser&#039; =&amp;gt; &#039;chrome&#039;,&lt;br /&gt;
                        &#039;wd_host&#039; =&amp;gt; &#039;http://&#039; . $osxip . &#039;:4444/wd/hub&#039;&lt;br /&gt;
                    )&lt;br /&gt;
                )&lt;br /&gt;
            )&lt;br /&gt;
        ),&lt;br /&gt;
        &#039;chrome-win&#039; =&amp;gt; array(&lt;br /&gt;
            &#039;filters&#039; =&amp;gt; array(&lt;br /&gt;
                &#039;tags&#039; =&amp;gt; &#039;~@_file_upload&#039;&lt;br /&gt;
            ),&lt;br /&gt;
            &#039;extensions&#039; =&amp;gt; array(&lt;br /&gt;
                &#039;Behat\MinkExtension\Extension&#039; =&amp;gt; array(&lt;br /&gt;
                    &#039;selenium2&#039; =&amp;gt; array(&lt;br /&gt;
                        &#039;browser&#039; =&amp;gt; &#039;chrome&#039;,&lt;br /&gt;
                        &#039;wd_host&#039; =&amp;gt; &#039;http://&#039; . $windowsip . &#039;:4444/wd/hub&#039;&lt;br /&gt;
                    )&lt;br /&gt;
                )&lt;br /&gt;
            )&lt;br /&gt;
        ),&lt;br /&gt;
        &#039;firefox-linux&#039; =&amp;gt; array(&lt;br /&gt;
            &#039;extensions&#039; =&amp;gt; array(&lt;br /&gt;
                &#039;Behat\MinkExtension\Extension&#039; =&amp;gt; array(&lt;br /&gt;
                    &#039;selenium2&#039; =&amp;gt; array(&lt;br /&gt;
                        &#039;browser&#039; =&amp;gt; &#039;firefox&#039;,&lt;br /&gt;
                        &#039;wd_host&#039; =&amp;gt; &#039;http://&#039; . $linuxip . &#039;:4444/wd/hub&#039;&lt;br /&gt;
                    )&lt;br /&gt;
                )&lt;br /&gt;
            )&lt;br /&gt;
        ),&lt;br /&gt;
        &#039;firefox-osx&#039; =&amp;gt; array(&lt;br /&gt;
            &#039;filters&#039; =&amp;gt; array(&lt;br /&gt;
                &#039;tags&#039; =&amp;gt; &#039;~@_file_upload&#039;&lt;br /&gt;
            ),&lt;br /&gt;
            &#039;extensions&#039; =&amp;gt; array(&lt;br /&gt;
                &#039;Behat\MinkExtension\Extension&#039; =&amp;gt; array(&lt;br /&gt;
                    &#039;selenium2&#039; =&amp;gt; array(&lt;br /&gt;
                        &#039;browser&#039; =&amp;gt; &#039;firefox&#039;,&lt;br /&gt;
                        &#039;wd_host&#039; =&amp;gt; &#039;http://&#039; . $osxip . &#039;:4444/wd/hub&#039;&lt;br /&gt;
                    )&lt;br /&gt;
                )&lt;br /&gt;
            )&lt;br /&gt;
        ),&lt;br /&gt;
        &#039;firefox-win&#039; =&amp;gt; array(&lt;br /&gt;
            &#039;filters&#039; =&amp;gt; array(&lt;br /&gt;
                &#039;tags&#039; =&amp;gt; &#039;~@_file_upload&#039;&lt;br /&gt;
            ),&lt;br /&gt;
            &#039;extensions&#039; =&amp;gt; array(&lt;br /&gt;
                &#039;Behat\MinkExtension\Extension&#039; =&amp;gt; array(&lt;br /&gt;
                    &#039;selenium2&#039; =&amp;gt; array(&lt;br /&gt;
                        &#039;browser&#039; =&amp;gt; &#039;firefox&#039;,&lt;br /&gt;
                        &#039;wd_host&#039; =&amp;gt; &#039;http://&#039; . $windowsip . &#039;:4444/wd/hub&#039;&lt;br /&gt;
                    )&lt;br /&gt;
                )&lt;br /&gt;
            )&lt;br /&gt;
        ),&lt;br /&gt;
        &#039;safari-osx&#039; =&amp;gt; array(&lt;br /&gt;
            &#039;filters&#039; =&amp;gt; array(&lt;br /&gt;
                &#039;tags&#039; =&amp;gt; &#039;~@_alert&amp;amp;&amp;amp;~@_switch_window&amp;amp;&amp;amp;~@_file_upload&#039;&lt;br /&gt;
            ),&lt;br /&gt;
            &#039;extensions&#039; =&amp;gt; array(&lt;br /&gt;
                &#039;Behat\MinkExtension\Extension&#039; =&amp;gt; array(&lt;br /&gt;
                    &#039;selenium2&#039; =&amp;gt; array(&lt;br /&gt;
                        &#039;browser&#039; =&amp;gt; &#039;safari&#039;,&lt;br /&gt;
                        &#039;wd_host&#039; =&amp;gt; &#039;http://&#039; . $osxip . &#039;:4444/wd/hub&#039;&lt;br /&gt;
                    )&lt;br /&gt;
                )&lt;br /&gt;
            )&lt;br /&gt;
        ),&lt;br /&gt;
        &#039;ie-win&#039; =&amp;gt; array(&lt;br /&gt;
            &#039;filters&#039; =&amp;gt; array(&lt;br /&gt;
                &#039;tags&#039; =&amp;gt; &#039;~@_switch_window&amp;amp;&amp;amp;~@_file_upload&#039;&lt;br /&gt;
            ),&lt;br /&gt;
            &#039;extensions&#039; =&amp;gt; array(&lt;br /&gt;
                &#039;Behat\MinkExtension\Extension&#039; =&amp;gt; array(&lt;br /&gt;
                    &#039;selenium2&#039; =&amp;gt; array(&lt;br /&gt;
                        &#039;browser&#039; =&amp;gt; &#039;internet explorer&#039;,&lt;br /&gt;
                        &#039;wd_host&#039; =&amp;gt; &#039;http://&#039; . $windowsip . &#039;:4444/wd/hub&#039;&lt;br /&gt;
                    )&lt;br /&gt;
                )&lt;br /&gt;
            )&lt;br /&gt;
        ),&lt;br /&gt;
       &#039;edge-win&#039; =&amp;gt; array(&lt;br /&gt;
            &#039;filters&#039; =&amp;gt; array(&lt;br /&gt;
                &#039;tags&#039; =&amp;gt; &#039;~@_switch_window&amp;amp;&amp;amp;~@_file_upload&#039;&lt;br /&gt;
            ),&lt;br /&gt;
            &#039;extensions&#039; =&amp;gt; array(&lt;br /&gt;
                &#039;Behat\MinkExtension\Extension&#039; =&amp;gt; array(&lt;br /&gt;
                    &#039;selenium2&#039; =&amp;gt; array(&lt;br /&gt;
                        &#039;browser&#039; =&amp;gt; &#039;MicrosoftEdge&#039;,&lt;br /&gt;
                        &#039;wd_host&#039; =&amp;gt; &#039;http://&#039; . $windowsip . &#039;:4444/wd/hub&#039;&lt;br /&gt;
                    )&lt;br /&gt;
                )&lt;br /&gt;
            )&lt;br /&gt;
        )&lt;br /&gt;
    );&lt;br /&gt;
&lt;br /&gt;
[[Category:Quality Assurance]]&lt;br /&gt;
[[Category:Behat]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Acceptance_testing/Browsers/Working_combinations_of_OS%2BBrowser%2Bselenium&amp;diff=51993</id>
		<title>Acceptance testing/Browsers/Working combinations of OS+Browser+selenium</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Acceptance_testing/Browsers/Working_combinations_of_OS%2BBrowser%2Bselenium&amp;diff=51993"/>
		<updated>2017-03-03T15:53:07Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;= Working combinations of OS+Browser+selenium =&lt;br /&gt;
As OS, Browsers and Selenium keeps updating, some combination might fail on different Moodle releases.&lt;br /&gt;
&lt;br /&gt;
Following combinations have been tested at the time of release of Moodle version and will be supported for that combination. &lt;br /&gt;
NOTE:  Chromedriver &amp;gt;= 2.17 is required for behat to capture exceptions&lt;br /&gt;
&lt;br /&gt;
== Moodle 3.2 and master ==&lt;br /&gt;
{| class=&amp;quot;wikitable&amp;quot;&lt;br /&gt;
|OS&lt;br /&gt;
|Browser&lt;br /&gt;
|Selenium Server&lt;br /&gt;
|Chrome Driver&lt;br /&gt;
|IE Driver&lt;br /&gt;
|-&lt;br /&gt;
| Linux - Ubuntu 16.04&lt;br /&gt;
| Firefox 47.0.1&lt;br /&gt;
| [http://selenium-release.storage.googleapis.com/2.53/selenium-server-standalone-2.53.1.jar 2.53.1]&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
|Linux - Ubuntu 16.04&lt;br /&gt;
|[https://www.googleapis.com/download/storage/v1/b/chromium-browser-snapshots/o/Linux_x64%2F386249%2Fchrome-linux.zip?generation=1460160957434000&amp;amp;alt=media Chrome 53.0]&lt;br /&gt;
| [http://selenium-release.storage.googleapis.com/index.html?path=3.0/ 3.0.1]&lt;br /&gt;
| [http://chromedriver.storage.googleapis.com/index.html?path=2.25/ 2.25]&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
| Linux - Ubuntu 16.04&lt;br /&gt;
| Phantomjs 2.1.1&lt;br /&gt;
| 2.53.1&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
| Windows 7/10&lt;br /&gt;
| Firefox 47.0.1&lt;br /&gt;
| 2.53.1&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
| Windows 7/10&lt;br /&gt;
| Chrome v53.0&lt;br /&gt;
| [http://selenium-release.storage.googleapis.com/index.html?path=3.0/ 3.0.1]&lt;br /&gt;
| [http://chromedriver.storage.googleapis.com/index.html?path=2.25/ 2.25]&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
| MacOS X&lt;br /&gt;
| Firefox 47.0.1&lt;br /&gt;
| 2.53.1&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
| MacOS X&lt;br /&gt;
| [http://www.slimjet.com/chrome/google-chrome-old-version.php Chrome v53.0]&lt;br /&gt;
| [http://selenium-release.storage.googleapis.com/index.html?path=3.0/ 3.0.1]&lt;br /&gt;
| [http://chromedriver.storage.googleapis.com/index.html?path=2.25/ 2.25]&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
| MacOS X&lt;br /&gt;
| PhantomJS 2.1.1&lt;br /&gt;
| 2.53.1&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
== Moodle 3.1 ==&lt;br /&gt;
{| class=&amp;quot;wikitable&amp;quot;&lt;br /&gt;
|OS&lt;br /&gt;
|Browser&lt;br /&gt;
|Selenium Server&lt;br /&gt;
|Chrome Driver&lt;br /&gt;
|IE Driver&lt;br /&gt;
|-&lt;br /&gt;
| Linux - Ubuntu 16.04&lt;br /&gt;
| Firefox 47.0.1&lt;br /&gt;
| [http://selenium-release.storage.googleapis.com/2.53/selenium-server-standalone-2.53.1.jar 2.53.1]&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
|Linux - Ubuntu 16.04&lt;br /&gt;
|[https://www.googleapis.com/download/storage/v1/b/chromium-browser-snapshots/o/Linux_x64%2F386249%2Fchrome-linux.zip?generation=1460160957434000&amp;amp;alt=media Chrome 51.0]&lt;br /&gt;
| 2.53.1&lt;br /&gt;
| 2.22&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
| Linux - Ubuntu 16.04&lt;br /&gt;
| Phantomjs 2.1.1&lt;br /&gt;
| 2.53.1&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
| Windows 7/10&lt;br /&gt;
| Firefox 47.0.1&lt;br /&gt;
| 2.53.1&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
| Windows 7/10&lt;br /&gt;
| Chrome v51.0&lt;br /&gt;
| 2.53.1&lt;br /&gt;
| 2.22&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
| MacOS X&lt;br /&gt;
| Firefox 47.0.1&lt;br /&gt;
| 2.53.1&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
| MacOS X&lt;br /&gt;
| Chrome v51.0&lt;br /&gt;
| 2.53.1&lt;br /&gt;
| 2.22&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
| MacOS X&lt;br /&gt;
| PhantomJS 2.1.1&lt;br /&gt;
| 2.53.1&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
== Moodle 3.0 and lower ==&lt;br /&gt;
{| class=&amp;quot;wikitable&amp;quot;&lt;br /&gt;
|OS&lt;br /&gt;
|Browser&lt;br /&gt;
|Selenium Server&lt;br /&gt;
|Chrome Driver&lt;br /&gt;
|IE Driver&lt;br /&gt;
|-&lt;br /&gt;
|Linux - Ubuntu 14.10&lt;br /&gt;
|Firefox 42.0&lt;br /&gt;
|2.47.1&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
|Linux - Ubuntu 14.10&lt;br /&gt;
|Chrome 46.0&lt;br /&gt;
|2.47.1&lt;br /&gt;
| 2.19.346067&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
|Linux - Ubuntu 14.10&lt;br /&gt;
|Phantomjs 2.0.0&lt;br /&gt;
|2.47.1&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
|Windows 7/10&lt;br /&gt;
|Firefox 41.0&lt;br /&gt;
|2.47.1&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
|Windows 7/10&lt;br /&gt;
|Chrome 47.0&lt;br /&gt;
|2.47.1&lt;br /&gt;
| 2.20&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
|MacOS X&lt;br /&gt;
|Firefox 41.0&lt;br /&gt;
|2.47.1&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
|MacOS X&lt;br /&gt;
|Chrome 46.0&lt;br /&gt;
|2.47.1&lt;br /&gt;
| 2.20&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
|MacOS X&lt;br /&gt;
|Chrome 48.0&lt;br /&gt;
|2.51.0&lt;br /&gt;
| 2.21&lt;br /&gt;
| N/A&lt;br /&gt;
|-&lt;br /&gt;
|MacOS X&lt;br /&gt;
|PhantomJS - 2.0.0 &amp;amp; 2.1.1&lt;br /&gt;
|2.48.2&lt;br /&gt;
| N/A&lt;br /&gt;
| N/A&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
[[Category:Behat]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Acceptance_testing&amp;diff=50738</id>
		<title>Acceptance testing</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Acceptance_testing&amp;diff=50738"/>
		<updated>2016-08-01T11:53:38Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: /* Examples */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Introduction ==&lt;br /&gt;
This page describes how we describe Moodle&#039;s functionalities and automatically test them.&lt;br /&gt;
&lt;br /&gt;
Behat is a behavioural driven development (BDD) tool written in PHP, it can parse a human-readable list of sentences (called steps) and execute actions in a browser using Selenium or other tools to simulate user interactions.&lt;br /&gt;
&lt;br /&gt;
For technical info: [[Behat integration]]&lt;br /&gt;
&lt;br /&gt;
=== How it works ===&lt;br /&gt;
Behat parses and executes features files which describe Moodle&#039;s features (for example &#039;&#039;Post in a forum&#039;&#039;). Each feature file is composed of many scenarios (for example &#039;&#039;Add a post to a discussion&#039;&#039; or &#039;&#039;Create a new discussion&#039;&#039;), and finally each scenario is composed of steps (for example  &#039;&#039;I press &amp;quot;Post to forum&amp;quot;&#039;&#039; or &#039;&#039;I should see &amp;quot;My post title&amp;quot;&#039;&#039;). When the feature file is executed, every step internally is translated into a PHP method and is executed.&lt;br /&gt;
&lt;br /&gt;
These features are executed nightly on the HQ servers using all the supported databases (MySQL, PostgreSQL, MSSQL and Oracle) and with different browsers (Firefox, Internet Explorer, Safari and Chrome) to avoid regressions and to test new functionalities.&lt;br /&gt;
&lt;br /&gt;
=== Examples ===&lt;br /&gt;
&lt;br /&gt;
Note that these snippets are only examples and may not work.&lt;br /&gt;
&lt;br /&gt;
* There is a closed list of steps to use in the features, a feature written with the basic (or low-level) steps looks like this:&lt;br /&gt;
  @auth&lt;br /&gt;
  &#039;&#039;&#039;Feature&#039;&#039;&#039;: Login&lt;br /&gt;
    In order to login&lt;br /&gt;
    As a moodle user&lt;br /&gt;
    I need to be able to validate the username and password against moodle&lt;br /&gt;
    &lt;br /&gt;
    &#039;&#039;&#039;Scenario&#039;&#039;&#039;: Login as an existing user&lt;br /&gt;
      Given I am on &amp;quot;login/index.php&amp;quot;&lt;br /&gt;
      When I fill in &amp;quot;username&amp;quot; with &amp;quot;admin&amp;quot;&lt;br /&gt;
      And I fill in &amp;quot;password&amp;quot; with &amp;quot;moodle&amp;quot;&lt;br /&gt;
      And I press &amp;quot;loginbtn&amp;quot;&lt;br /&gt;
      Then I should see &amp;quot;Moodle 101: Course Name&amp;quot;&lt;br /&gt;
    &lt;br /&gt;
    &#039;&#039;&#039;Scenario&#039;&#039;&#039;: Login as an unexisting user&lt;br /&gt;
      Given I am on &amp;quot;login/index.php&amp;quot;&lt;br /&gt;
      When I fill in &amp;quot;username&amp;quot; with &amp;quot;admin&amp;quot;&lt;br /&gt;
      And I fill in &amp;quot;password&amp;quot; with &amp;quot;moodle&amp;quot;&lt;br /&gt;
      And I press &amp;quot;loginbtn&amp;quot;&lt;br /&gt;
      Then I should see &amp;quot;Moodle 101: Course Name&amp;quot;&lt;br /&gt;
&lt;br /&gt;
Note that The 3 sentences below &#039;&#039;Feature: Login&#039;&#039; are only information about what we want to test.&lt;br /&gt;
&lt;br /&gt;
These are simple scenarios, but most of Moodle&#039;s functionalities would require a huge list of this steps to test a scenario, imagine a &#039;&#039;Add a post to a discussion&#039;&#039; scenario; you need to login, create a course, create a user and enrol it in the course... Most of this steps is not what we intend to test in a &#039;&#039;Post in a forum&#039;&#039; feature, Moodle provides extra steps to quickly set up the context required to test a Moodle feature, for example:&lt;br /&gt;
&lt;br /&gt;
  @mod @mod_forum&lt;br /&gt;
  &#039;&#039;&#039;Feature&#039;&#039;&#039;: Add forum activities and discussions&lt;br /&gt;
    In order to discuss topics with other users&lt;br /&gt;
    As a moodle teacher&lt;br /&gt;
    I need to add forum activities to moodle courses&lt;br /&gt;
    &lt;br /&gt;
    &#039;&#039;&#039;Scenario&#039;&#039;&#039;: Add a forum and a discussion&lt;br /&gt;
      &#039;&#039;&#039;Given&#039;&#039;&#039; the following &amp;quot;users&amp;quot; exist:&lt;br /&gt;
        | username | firstname | lastname | email |&lt;br /&gt;
        | teacher1 | Teacher | 1 | teacher1@asd.com |&lt;br /&gt;
      &#039;&#039;&#039;And&#039;&#039;&#039; the following &amp;quot;courses&amp;quot; exist:&lt;br /&gt;
        | fullname | shortname | category |&lt;br /&gt;
        | Course 1 | C1 | 0 |&lt;br /&gt;
      &#039;&#039;&#039;And&#039;&#039;&#039; the following &amp;quot;course enrolments&amp;quot; exist:&lt;br /&gt;
        | user | course | role |&lt;br /&gt;
        | teacher1 | C1 | editingteacher |&lt;br /&gt;
      &#039;&#039;&#039;And&#039;&#039;&#039; I log in as &amp;quot;teacher1&amp;quot;&lt;br /&gt;
      &#039;&#039;&#039;And&#039;&#039;&#039; I follow &amp;quot;Course 1&amp;quot;&lt;br /&gt;
      &#039;&#039;&#039;And&#039;&#039;&#039; I turn editing mode on&lt;br /&gt;
      &#039;&#039;&#039;And&#039;&#039;&#039; I add a &amp;quot;Forum&amp;quot; to section &amp;quot;1&amp;quot; and I fill the form with:&lt;br /&gt;
        | Forum name | Test forum name |&lt;br /&gt;
        | Forum type | Standard forum for general use |&lt;br /&gt;
        | Description | Test forum description |&lt;br /&gt;
      &#039;&#039;&#039;When&#039;&#039;&#039; I add a new discussion to &amp;quot;Test forum name&amp;quot; forum with:&lt;br /&gt;
        | Subject | Forum post subject |&lt;br /&gt;
        | Message | This is the body |&lt;br /&gt;
      &#039;&#039;&#039;Then&#039;&#039;&#039; I should see &amp;quot;Test forum name&amp;quot;&lt;br /&gt;
&lt;br /&gt;
Note that:&lt;br /&gt;
&lt;br /&gt;
* Each scenario is executed in an isolated testing environment, so the first step begins with an empty moodle site and what you set up in an scenario (like the &#039;&#039;Test forum name&#039;&#039; forum in the example above) is cleaned up after the scenario execution&lt;br /&gt;
* The prefixes &amp;quot;Given&amp;quot;, &amp;quot;When&amp;quot; and &amp;quot;Then&amp;quot; are only informative and they are used to define the context (Given), specify the action (When) and check the results (Then), using them properly helps to understand what the scenario is testing.&lt;br /&gt;
&lt;br /&gt;
== Quick start ==&lt;br /&gt;
&lt;br /&gt;
This is a quick introduction to write a functional test (acceptance tests) using steps in a development/testing site, please DON&#039;T USE THIS IN A PRODUCTION SITE.&lt;br /&gt;
&lt;br /&gt;
To let you experience the pleasure of watching a feature file doing &amp;quot;your work&amp;quot; automatically in a real browser, this guide includes 2 optional steps to download Selenium and run it in another CLI.&lt;br /&gt;
&lt;br /&gt;
# Open a command line interface (you might need to run as administrator to get curl to work - one windows, right click the command prompt and &#039;choose run as administrator&#039;)&lt;br /&gt;
# &#039;&#039;&#039;cd /to/your/moodle/dirroot&#039;&#039;&#039;&lt;br /&gt;
# Edit config.php adding the following lines before the lib/setup.php include&lt;br /&gt;
#: &amp;lt;code language=&amp;quot;text&amp;quot;&amp;gt;$CFG-&amp;gt;behat_prefix = &#039;b_&#039;;&lt;br /&gt;
$CFG-&amp;gt;behat_dataroot = &#039;/path/to/your/behat/dataroot/directory&#039;;&lt;br /&gt;
$CFG-&amp;gt;behat_wwwroot = &#039;http://127.0.0.1&#039;; // must be different from wwwroot&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
# &#039;&#039;&#039;curl http://getcomposer.org/installer | php&#039;&#039;&#039; (If you get a curl error saying &#039;curl is not recognized as an internal or external command&#039; run the command line as administrator. In case you still have problems read https://docs.moodle.org/dev/Acceptance_testing#Installation)&lt;br /&gt;
# &#039;&#039;&#039;php admin/tool/behat/cli/init.php&#039;&#039;&#039; (If you get a curl error saying &#039;curl is not recognized as an internal or external command&#039; run the command line as administrator.)&lt;br /&gt;
# Download selenium-server-standalone-2.NN.N.jar from http://seleniumhq.org/download/, under &amp;quot;Selenium server (formerly the Selenium RC Server)&amp;quot;&lt;br /&gt;
# Open another command line interface and run &#039;&#039;&#039;java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar&#039;&#039;&#039;&lt;br /&gt;
# &#039;&#039;&#039;vendor/bin/behat --config /path/to/your/behat/dataroot/directory/behat/behat.yml&#039;&#039;&#039;&lt;br /&gt;
# You just ran the current Moodle tests, now let&#039;s add your own test, add a blog entry for example&lt;br /&gt;
# Browse to your $CFG-&amp;gt;behat_wwwroot, this is an empty test site and it is reset before each test (called scenario)&lt;br /&gt;
# From this point follow the steps you would follow to add manually a blog entry (login credentials are admin/admin)&lt;br /&gt;
# When you are done go to &#039;Site administration&#039; -&amp;gt; &#039;Development&#039; -&amp;gt; &#039;Acceptance testing&#039;, you will find the list of &amp;quot;actions&amp;quot; that can be run automatically, you can filter them to find what do you need to do (more steps can be added if you need, more info in https://docs.moodle.org/dev/Acceptance_testing#Adding_steps_definitions)&lt;br /&gt;
# To &#039;add a blog entry&#039; we need to:&lt;br /&gt;
## Log in the system as a valid user&lt;br /&gt;
## Expand &#039;My profile&#039; node of the navigation block&lt;br /&gt;
## Expand the &#039;Blogs&#039; node of the navigation block&lt;br /&gt;
## Follow he &#039;Add a new entry&#039; link&lt;br /&gt;
## Fill the moodle form with values for &#039;Entry title&#039; and &#039;Blog entry body&#039;&lt;br /&gt;
## Press the &#039;Save changes&#039; button&lt;br /&gt;
## Verify you see the values you entered in the form and verify you are not in the form page&lt;br /&gt;
# This translated to steps is:&lt;br /&gt;
#: &amp;lt;code language=&amp;quot;text&amp;quot;&amp;gt;Given I log in as &amp;quot;admin&amp;quot;&lt;br /&gt;
And I expand &amp;quot;My profile&amp;quot; node&lt;br /&gt;
And I expand &amp;quot;Blogs&amp;quot; node&lt;br /&gt;
And I follow &amp;quot;Add a new entry&amp;quot;&lt;br /&gt;
And I set the following fields to these values:&lt;br /&gt;
  | Entry title | I&#039;m the name |&lt;br /&gt;
  | Blog entry body | I&#039;m the description |&lt;br /&gt;
When I press &amp;quot;Save changes&amp;quot;&lt;br /&gt;
Then I should see &amp;quot;User Blog&amp;quot;&lt;br /&gt;
And I should see &amp;quot;I&#039;m the description&amp;quot;&lt;br /&gt;
And I should not see &amp;quot;Required&amp;quot;&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
# We need to wrap this steps following the behavior driven development guidelines (more info in https://docs.moodle.org/dev/Acceptance_testing#Writing_features)&lt;br /&gt;
#: &amp;lt;code language=&amp;quot;text&amp;quot;&amp;gt;&lt;br /&gt;
@core @core_blog&lt;br /&gt;
Feature: Add a blog entry&lt;br /&gt;
  In order to let the world know about me&lt;br /&gt;
  As a user&lt;br /&gt;
  I need to write blog entries&lt;br /&gt;
&lt;br /&gt;
  @javascript&lt;br /&gt;
  Scenario: Add a blog entry with valid data&lt;br /&gt;
    Given I log in as &amp;quot;admin&amp;quot;&lt;br /&gt;
    And I expand &amp;quot;My profile&amp;quot; node&lt;br /&gt;
    And I expand &amp;quot;Blogs&amp;quot; node&lt;br /&gt;
    And I follow &amp;quot;Add a new entry&amp;quot;&lt;br /&gt;
    And I fill the moodle form with:&lt;br /&gt;
      | Entry title | I&#039;m the name |&lt;br /&gt;
      | Blog entry body | I&#039;m the description |&lt;br /&gt;
    When I press &amp;quot;Save changes&amp;quot;&lt;br /&gt;
    Then I should see &amp;quot;View all of my entries&amp;quot;&lt;br /&gt;
    And I should see &amp;quot;I&#039;m a description&amp;quot;&lt;br /&gt;
    And I should not see &amp;quot;Required&amp;quot;&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
# And save it into a file, in this case &#039;&#039;&#039;blog/tests/behat/add_entry.feature&#039;&#039;&#039;&lt;br /&gt;
# &#039;&#039;&#039;php admin/tool/behat/cli/util.php --enable&#039;&#039;&#039;  (This will update the available tests and steps definitions)&lt;br /&gt;
# &#039;&#039;&#039;vendor/bin/behat --config /path/to/your/behat/dataroot/directory/behat/behat.yml --tags @core_blog&#039;&#039;&#039;&lt;br /&gt;
# Selenium will open a browser (firefox by default) and you will see how the steps you have been writting are executed&lt;br /&gt;
&lt;br /&gt;
You can also try to expand non existing nodes or change the &#039;Then&#039; assertions to get a beautiful failure.&lt;br /&gt;
&lt;br /&gt;
For detailed steps and/or troubleshooting:&lt;br /&gt;
* https://docs.moodle.org/dev/Acceptance_testing#Running_tests&lt;br /&gt;
* https://docs.moodle.org/dev/Acceptance_testing#Writing_features&lt;br /&gt;
&lt;br /&gt;
== Requirements ==&lt;br /&gt;
* PHP 5.4 (see https://docs.moodle.org/dev/Acceptance_testing#Advanced_usage for PHP 5.3, only for non-production sites)&lt;br /&gt;
* Other dependencies are managed by the composer installer&lt;br /&gt;
&lt;br /&gt;
== Installation ==&lt;br /&gt;
* Edit config.php&lt;br /&gt;
** Use $CFG-&amp;gt;behat_dataroot to set the directory where behat test environment dataroot will be stored, something like &#039;&#039;&#039;$CFG-&amp;gt;behat_dataroot = &#039;/your/directory/path&#039;;&#039;&#039;&#039;. Ensure the directory can be created or have write permissions&lt;br /&gt;
** Use $CFG-&amp;gt;behat_prefix to set the database prefix of the behat test environment database tables, something like &#039;&#039;&#039;$CFG-&amp;gt;behat_prefix = &#039;behat_&#039;;&#039;&#039;&#039;&lt;br /&gt;
** Use $CFG-&amp;gt;behat_wwwroot to set address to be used to access behat instance. It has to be different from $CFG-&amp;gt;wwwroot, you can use for example localhost, 127.0.0.1 or any custom local host name specified in you /etc/hosts. If you use the built-in PHP server use &amp;quot;http://localhost:8000&amp;quot; or the value you set when you started it.&lt;br /&gt;
* Download composer&lt;br /&gt;
** &#039;&#039;&#039;cd /your/moodle/dirroot&#039;&#039;&#039;&lt;br /&gt;
** &#039;&#039;&#039;curl http://getcomposer.org/installer | php&#039;&#039;&#039;&lt;br /&gt;
*** If you don&#039;t have curl installed or you have problems running &#039;&#039;&#039;curl http://getcomposer.org/installer | php&#039;&#039;&#039;:&lt;br /&gt;
**** Download &#039;&#039;&#039;http://getcomposer.org/installer&#039;&#039;&#039;&lt;br /&gt;
**** Store it in /your/moodle/dirroot/composerinstaller.php for example&lt;br /&gt;
**** Run it from /your/moodle/dirroot with &#039;&#039;&#039;php composerinstaller.php&#039;&#039;&#039;, you can delete this file after running the next step (&#039;&#039;&#039;php composer.phar update --dev&#039;&#039;&#039;)&lt;br /&gt;
* Install behat dependencies and enable the test environment&lt;br /&gt;
** &#039;&#039;&#039;cd /your/moodle/dirroot&#039;&#039;&#039;&lt;br /&gt;
** &#039;&#039;&#039;php admin/tool/behat/cli/init.php&#039;&#039;&#039;&lt;br /&gt;
* (Optional) If you want to run tests that involves Javascript (most of them) you will also need Selenium&lt;br /&gt;
** Download it from http://seleniumhq.org/download/, named &amp;quot;Selenium server (formerly the Selenium RC Server).&lt;br /&gt;
&lt;br /&gt;
== Verify your installation ==&lt;br /&gt;
* Test your installation by browsing your /admin/tool/behat/index.php page.&lt;br /&gt;
If you are using MAMP/WAMP/XAMPP and don&#039;t get the report working... then you need to ensure that your web servers knows where the PHP executable (commad line) is. To do that, edit the &amp;quot;envvars&amp;quot; file (usually under library/bin) and add to $PATH the path to your php executable. Then restart the apache server and try again.&lt;br /&gt;
For example, for MAMP you probably need to add:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
# Adding MAMP binaries communicate where CLI is&lt;br /&gt;
PATH=&amp;quot;/Applications/MAMP/bin/php/php5.x.y/bin:$PATH&amp;quot;; export PATH &lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
at the end of MAMP/Library/bin/envvars.&lt;br /&gt;
&lt;br /&gt;
== Running tests ==&lt;br /&gt;
# (Optional) Start the PHP built-in web server if you configured the $CFG-&amp;gt;behat_wwwroot to use it:&lt;br /&gt;
#* Open a command line interface and &#039;&#039;&#039;cd /to/your/moodle/dirroot&#039;&#039;&#039;&lt;br /&gt;
#* &#039;&#039;&#039;php -S localhost:8000&#039;&#039;&#039; (This is the test site URL that moodle uses by default, if you want to use another one you can override it in config.php with $CFG-&amp;gt;behat_wwwroot attribute; more info in https://docs.moodle.org/dev/Acceptance_testing#Advanced_usage or config-dist.php)&lt;br /&gt;
# (Optional) Start the Selenium server (in case you want to run tests that involves Javascript)&lt;br /&gt;
#* (See http://www.installationpage.com/selenium/how-to-run-selenium-headless-firefox-in-ubuntu/ for running &#039;headless&#039; Firefox and xvfm in a server environment)&lt;br /&gt;
#* Open another command line interface and &#039;&#039;&#039;java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar&#039;&#039;&#039;&lt;br /&gt;
# Initialise Behat environment&lt;br /&gt;
#* To initialise behat use following command with optional parameters.&lt;br /&gt;
#** &#039;&#039;&#039;php admin/tool/behat/cli/init.php&#039;&#039;&#039;&lt;br /&gt;
#* Following options can be passed to initialisation command&lt;br /&gt;
#** &#039;&#039;&#039;-j, --parallel&#039;&#039;&#039;      Number of parallel behat run to initialise&lt;br /&gt;
#** &#039;&#039;&#039;-m, --maxruns&#039;&#039;&#039;  Max parallel processes to be executed at one time.&lt;br /&gt;
#** &#039;&#039;&#039;--fromrun&#039;&#039;&#039;         Execute run starting from (Used for parallel runs on different vms)&lt;br /&gt;
#** &#039;&#039;&#039;--torun&#039;&#039;&#039;             Execute run till (Used for parallel runs on different vms)&lt;br /&gt;
#** &#039;&#039;&#039;-h, --help&#039;&#039;&#039;         Print out this help&lt;br /&gt;
#* Example to initialise behat to run 4 process (Moodle CLI only supports {option}={value}, and not spaces) &lt;br /&gt;
#** &#039;&#039;&#039;php admin/tool/behat/cli/init.php -j=4&#039;&#039;&#039;&lt;br /&gt;
# Run Behat&lt;br /&gt;
#*  If behat site is initialise without parallel options then use following command:  &lt;br /&gt;
#** &#039;&#039;&#039;vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behat/behat.yml&#039;&#039;&#039; (For more options &#039;&#039;&#039;vendor/bin/behat --help&#039;&#039;&#039; or http://docs.behat.org/guides/6.cli.html)&lt;br /&gt;
#* If behat site is initialise with parallel options then use following command:&lt;br /&gt;
#** &#039;&#039;&#039;php admin/tool/behat/cli/run.php&#039;&#039;&#039; (For more options &#039;&#039;&#039;php admin/tool/behat/cli/run.php --help&#039;&#039;&#039;)&lt;br /&gt;
#* With slow systems or parallel run you might see some random failures, to rerun only failed scenarios (to eliminate random failures), use --rerun option&lt;br /&gt;
#** &#039;&#039;&#039;Single run:&#039;&#039;&#039; --run=&amp;quot;absolute_path_to_empty_file&amp;quot; (Behat will record failed scenarios in this file, and when run again only failed scenarios will be run)&lt;br /&gt;
#** &#039;&#039;&#039;Parallel run:&#039;&#039;&#039; --rerun=&amp;quot;absolute_path_to_empty_file_{runprocess}.txt --replace=&amp;quot;{runprocess}&amp;quot; ({runprocess} will be replaced with the process number for recording fails in the specific run process).&lt;br /&gt;
#* In case you don&#039;t want to run Javascript tests, use the Behat tags option to skip them, &#039;&#039;&#039;--tags=&amp;quot;~@javascript&amp;quot;&#039;&#039;&#039;&lt;br /&gt;
#* In case you want to run specific scenario, use the Behat name option to run it, &#039;&#039;&#039;--name=&amp;quot;Filter user accounts by role and cohort&amp;quot;&#039;&#039;&#039;&lt;br /&gt;
#* In case you want to run specific feature file, use the Behat feature option to run it, &#039;&#039;&#039;--feature=&amp;quot;/PATH/TO/MOODLE/admin/tests/behat/filter_users.feature&amp;quot;&#039;&#039;&#039;&lt;br /&gt;
#* If you followed all the steps and you receive an unknown weird error probably your system&#039;s Firefox version is not compatible with the Selenium version you are running, try downloading the latest Selenium release from it&#039;s website as explained above&lt;br /&gt;
# (Optional) If you are adding new tests or steps definitions update the tests list:&lt;br /&gt;
#* &#039;&#039;&#039;php admin/tool/behat/cli/util.php --enable&#039;&#039;&#039;&lt;br /&gt;
# (Optional) Disable test environment (if you want to prevent access to test environment)&lt;br /&gt;
#* &#039;&#039;&#039;php admin/tool/behat/cli/util.php --disable&#039;&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;Note that if you have the HTTP_PROXY environment variable set, which you may have had to do to run composer, then you also need to set NO_PROXY=localhost.&#039;&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
=== Tests filters ===&lt;br /&gt;
With the &#039;&#039;&#039;--tags&#039;&#039;&#039; or the &#039;&#039;&#039;-name&#039;&#039;&#039; Behat options you can filter which tests are going to run or which ones are going to be skipped. There are a few tags that you might be interested in:&lt;br /&gt;
* &#039;&#039;&#039;@javascript&#039;&#039;&#039;: All the tests that runs in a browser using Javascript; they require Selenium to be running, otherwise an exception will be thrown.&lt;br /&gt;
* &#039;&#039;&#039;@_file_upload&#039;&#039;&#039;: All the tests that involves file uploading or any OS feature that is not 100% part of the browser. They should only be executed when Selenium is running in the same machine where the tests are running.&lt;br /&gt;
* &#039;&#039;&#039;@_alert&#039;&#039;&#039;: All the tests that involves Javascript dialogs (alerts, confirms...) are using a feature that is OS-dependant and out of the browser scope, so they should be tag appropriately as not all browsers manage them properly.&lt;br /&gt;
* &#039;&#039;&#039;@_switch_window&#039;&#039;&#039;: All the tests that are using the &#039;&#039;&#039;I switch to &amp;quot;NAME&amp;quot; window&#039;&#039;&#039; step should be tagged as not all browsers manage them properly.&lt;br /&gt;
* &#039;&#039;&#039;@_switch_iframe&#039;&#039;&#039;: All the tests that are using the &#039;&#039;&#039;I switch to &amp;quot;NAME&amp;quot; window&#039;&#039;&#039; steps should be tagged as it is an advanced feature and some browsers may have problems dealing with them&lt;br /&gt;
* &#039;&#039;&#039;@_cross_browser&#039;&#039;&#039;: All the tests that should run against multiple combinations of browsers + OS in a regular basis. The features that are sensitive to different combinations of OS and browsers should be tagges as @_cross_browser.&lt;br /&gt;
* &#039;&#039;&#039;@componentname&#039;&#039;&#039;: Moodle features uses the [https://docs.moodle.org/dev/Frankenstyle Frankenstyle] component name to tag the features according to the Moodle subsystem they belong to.&lt;br /&gt;
&lt;br /&gt;
=== Output formats ===&lt;br /&gt;
&lt;br /&gt;
If you want to see the failures immediately (rather than waiting ~3 hours for all the tests to finish) then either use the -v option to output a bit more information, or change the output format using --format. Format &#039;pretty&#039; (&#039;&#039;&#039;-f pretty&#039;&#039;&#039;) is sufficient for most cases, as it outputs each step outcomes in the command line making easier to see the progress.&lt;br /&gt;
&lt;br /&gt;
== Run behat using different browsers ==&lt;br /&gt;
&lt;br /&gt;
Following these instructions you can run behat in Firefox browser through Selenium, but you can run behat using different browsers through Selenium and even use phantomjs (Webkit). [[Acceptance_testing/Browsers|More info]]&lt;br /&gt;
&lt;br /&gt;
== Advanced usage ==&lt;br /&gt;
There are a few settings for advanced use of Behat and execution in continuous integration systems, by default all this options are disabled, use this settings only if you know what you are doing.&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;Different test server URL&#039;&#039;&#039;. If for example your are interested in allowing accesses from your local network because your Jenkins server is there you can set $CFG-&amp;gt;behat_wwwroot to &#039;&#039;&#039;http://my.computer.local.ip:8000&#039;&#039;&#039;&lt;br /&gt;
* &#039;&#039;&#039;Behat configuration&#039;&#039;&#039;, Moodle writes a behat.yml config file with info about the available tests and steps definitions along with other Behat parameters, you can override the Behat parameters we set and add your new parameters, your parameters will be merged with the Moodle ones giving priority to your values in case of conflict. This is useful for an advanced use of Behat, with multiple profiles, output formats, integration with continuous servers... &lt;br /&gt;
* &#039;&#039;&#039;Save screenshots of failures&#039;&#039;&#039;. You can use $CFG-&amp;gt;behat_faildump_path to specify a directory where behat will generate a screenshot with the browser state each time a scenario fails. This is useful to detect where the problem was and work on a solution.&lt;br /&gt;
* &#039;&#039;&#039;Running with a browser other than Firefox&#039;&#039;&#039;, by adding the following code to your config.php you can change the selected browser that is run when behat is invoked. In this case Chrome is selected, but internet explorer, firefox, iphone, android, chrome, htmlunit should be valid options. You will need to run &#039;&#039;&#039;php admin/tool/behat/cli/init.php&#039;&#039;&#039; for changes to take effect.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code language=&amp;quot;php&amp;quot;&amp;gt;&lt;br /&gt;
$CFG-&amp;gt;behat_profiles = array(&lt;br /&gt;
   &#039;chrome&#039; =&amp;gt; array(&lt;br /&gt;
       &#039;browser&#039; =&amp;gt; &#039;chrome&#039;,&lt;br /&gt;
       &#039;tags&#039; =&amp;gt; &#039;@javascript&#039;,&lt;br /&gt;
       &#039;wd_host&#039; =&amp;gt; &#039;http://127.0.0.1:4444/wd/hub&#039;,&lt;br /&gt;
       &#039;capabilities&#039; =&amp;gt; array(&lt;br /&gt;
           &#039;platform&#039; =&amp;gt; &#039;Linux&#039;&lt;br /&gt;
       )&lt;br /&gt;
   )&lt;br /&gt;
);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
:Note that for Chrome, you will need the Selenium Chrome Driver (https://code.google.com/p/selenium/wiki/ChromeDriver), and it will need to be installed in the command search path.&lt;br /&gt;
* &#039;&#039;&#039;Switch completely to test environment&#039;&#039;&#039; option was removed in 2.7, it is recommended to always set $CFG-&amp;gt;behat_wwwroot even in older versions instead.&lt;br /&gt;
* Note that when using cloud-based systems that can make use of non-standard capabilities like Saucelabs, you might want to provide configuration attributes containing the &#039;&#039;&#039;&#039;-&#039;&#039;&#039;&#039; character, which is automatically converted to &#039;&#039;&#039;&#039;_&#039;&#039;&#039;&#039; by the Symfony configuration manager that Behat is making use of (@see Symfony\Component\Config\Definition\Processor::normalizeKeys()) a way to avoid this restriction is to, adding to the vars you set like &#039;&#039;&#039;&#039;max-duration&#039;&#039;&#039;&#039; add the same var replacing dashes for underscores, this way the configuration manager will maintain the attribute containing dashes.&lt;br /&gt;
* &#039;&#039;&#039;Extra allowed settings&#039;&#039;&#039;, moodle allows users to define many settings in config.php (see config-dist.php) when running the behat test site those settings are skipped to avoid interaction with the production environment, in case you are interested in allowing some of those extra settings to run the tests using a configuration similar to the one you are using in your production environment you can whitelist them adding them to $CFG-&amp;gt;behat_extraallowedsettings (see config-dist.php for examples).&lt;br /&gt;
You can find more info and examples of how to use this settings in the config-dist.php file included in the Moodle codebase.&lt;br /&gt;
* &#039;&#039;&#039;Setting different parameters for parallel behat run&#039;&#039;&#039;, by adding the following code to your config.php you can specify parameters for each parallel run. $CFG-&amp;gt;behat_parallel_run is an array with first set of array params applied to first behat run and so on.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code language=&amp;quot;php&amp;quot;&amp;gt;&lt;br /&gt;
$CFG-&amp;gt;behat_parallel_run = array (&lt;br /&gt;
       array (&lt;br /&gt;
           &#039;dbtype&#039; =&amp;gt; &#039;mysqli&#039;,&lt;br /&gt;
           &#039;dblibrary&#039; =&amp;gt; &#039;native&#039;,&lt;br /&gt;
           &#039;dbhost&#039; =&amp;gt; &#039;localhost&#039;,&lt;br /&gt;
           &#039;dbname&#039; =&amp;gt; &#039;moodletest&#039;,&lt;br /&gt;
           &#039;dbuser&#039; =&amp;gt; &#039;moodle&#039;,&lt;br /&gt;
           &#039;dbpass&#039; =&amp;gt; &#039;moodle&#039;,&lt;br /&gt;
           &#039;behat_prefix&#039; =&amp;gt; &#039;mdl_&#039;,&lt;br /&gt;
           &#039;wd_host&#039; =&amp;gt; &#039;http://127.0.0.1:4444/wd/hub&#039;,&lt;br /&gt;
           &#039;behat_wwwroot&#039; =&amp;gt; &#039;http://127.0.0.1/moodle&#039;,&lt;br /&gt;
           &#039;behat_dataroot&#039; =&amp;gt; &#039;/home/example/bht_moodledata&#039;&lt;br /&gt;
       ),&lt;br /&gt;
   );&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
:Note: If you are running 2 runs and copy/paste above code in config.php then 2nd behat run will use default behat values like $CFG-&amp;gt;dbtype, $CFG-&amp;gt;behat_prefix etc.&lt;br /&gt;
&lt;br /&gt;
== Contributing ==&lt;br /&gt;
&lt;br /&gt;
You can contribute the effort to automatically test all of Moodle&#039;s functionalities, as described in the [[Acceptance_testing/Contributing_automated_tests| guide to contributing automated tests]]. Here you can find information about [[Acceptance_testing#Writing_features|how to write new features]] and [[Acceptance_testing#Adding_steps_definitions|how to write new step definitions]] if your changes requires a base change in the [https://github.com/moodlehq/moodle-behat-extension Moodle behat extension] you can find here how to do it following the integration workflow: [[Acceptance_testing/Contributing_to_Moodle_behat_extension]].&lt;br /&gt;
&lt;br /&gt;
== Writing features ==&lt;br /&gt;
&lt;br /&gt;
All Moodle components and plugins (including 3rd party plugins) can specify their tests in .feature files using all the available steps.&lt;br /&gt;
&lt;br /&gt;
Once you decided which functionality you want to specify as a feature you should:&lt;br /&gt;
# Select the most appropriate Moodle component to include your test and create a COMPONENTNAME/tests/behat/FEATURENAME.feature file&lt;br /&gt;
# Add a tag with the component name in Frankenstyle format (https://docs.moodle.org/dev/Frankenstyle) on the first line along with the plugin type or @core if it&#039;s a core subsystem&lt;br /&gt;
# Begin writing the user story of the feature, including in the &#039;As a ...&#039; statement the main beneficiary of the feature:&lt;br /&gt;
#: &amp;lt;code lang=&amp;quot;yaml&amp;quot;&amp;gt;@plugintype @plugintype_pluginname&lt;br /&gt;
Feature: FEATURENAME&lt;br /&gt;
  In order to ...    // Why this feature is useful&lt;br /&gt;
  As ...    // It can be &#039;an admin&#039;, &#039;a teacher&#039;, &#039;a student&#039;, &#039;a guest&#039;, &#039;a user&#039;, &#039;a tests writer&#039; and &#039;a developer&#039;&lt;br /&gt;
  I need to ...      // The feature we want&amp;lt;/code&amp;gt;&lt;br /&gt;
# From the beneficiary point of view, think of different scenarios to ensure the feature works as expected&lt;br /&gt;
# For each scenario you thought:&lt;br /&gt;
## Think of the initial context you need, for example &#039;&#039;1 course with 2 students on it and an assignment&#039;&#039;, and which steps do you need to follow (interacting with the browser) to verify the scenario works as expected&lt;br /&gt;
## What you are testing requires Javascript? Think only on the feature you are testing (for example if you want to test that you can view your profile you don&#039;t need Javascript to click on a link and assert against plain HTML, but if you want to test something related with the course&#039;s gradebook you might want to test it with Javascript)&lt;br /&gt;
## Check the steps list (more info in https://docs.moodle.org/dev/Acceptance_testing#Available_steps) and set the initial context data (see https://docs.moodle.org/dev/Acceptance_testing#Fixtures for more info) and the steps to follow to verify all works as it should work. &lt;br /&gt;
## The prefixes &#039;&#039;Given&#039;&#039;, &#039;&#039;When&#039;&#039; and &#039;&#039;Then&#039;&#039; separates the scenario in 3 parts, the initial context setup (&#039;&#039;Given&#039;&#039;), the action that provokes a change in the system (&#039;&#039;When&#039;&#039;) and the validation of that change outcomes (&#039;&#039;Then&#039;&#039;) So with a quick view at the scenario you can see what it is testing as the prefixes will be something like Given -&amp;gt; And -&amp;gt; And -&amp;gt; When -&amp;gt; And -&amp;gt; And -&amp;gt; Then -&amp;gt; And -&amp;gt; And -&amp;gt; And. Once we begin with the first &#039;&#039;Then&#039;&#039; we can consider that we are checking the outcomes so all the steps from there should be prefixed with &#039;&#039;Then&#039;&#039;&lt;br /&gt;
## Copy the list of steps to the .feature file with the Scenario header:&lt;br /&gt;
##: &amp;lt;code lang=&amp;quot;yaml&amp;quot;&amp;gt;Scenario: Short description of the scenario&lt;br /&gt;
  Given step 1&lt;br /&gt;
  And step 2&lt;br /&gt;
  And step 3&lt;br /&gt;
  When step 4&lt;br /&gt;
  And step 5&lt;br /&gt;
  Then step 6&amp;lt;/code&amp;gt;&lt;br /&gt;
## If the steps you are using requires Javascript add the @javascript tag above the &amp;quot;Scenario:&amp;quot; headline&lt;br /&gt;
##:    &amp;lt;code lang=&amp;quot;yaml&amp;quot;&amp;gt;@javascript&lt;br /&gt;
Scenario: Short description of the scenario&lt;br /&gt;
  ...&lt;br /&gt;
  ...&amp;lt;/code&amp;gt;&lt;br /&gt;
# Run the tests, when creating your new features/scenarios you can specify a &#039;@wip&#039; (work in progress) tag in both the line above the Scenario description and the tests runner (vendor/bin/behat) to execute only the new scenario instead of running the whole set of tests.&lt;br /&gt;
# Add extra tags to the scenario or the feature if required according to https://docs.moodle.org/dev/Acceptance_testing#Tests_filters&lt;br /&gt;
&lt;br /&gt;
=== Available steps ===&lt;br /&gt;
&lt;br /&gt;
Moodle provides a interface to list and filter the steps you can use when writing features. You can access it through the Administration block, following &#039;&#039;&#039;Site Administration&#039;&#039;&#039; -&amp;gt; &#039;&#039;&#039;Development&#039;&#039;&#039; -&amp;gt; &#039;&#039;&#039;Acceptance testing&#039;&#039;&#039;. It allows filtering by keyword, by the Moodle component or by the type of step:&lt;br /&gt;
* Processes to set up the environment&lt;br /&gt;
* Actions that provokes an event&lt;br /&gt;
* Checkings to ensure the outcomes are the expected ones&lt;br /&gt;
&lt;br /&gt;
[[File:Acceptance_testing_UI_2.5.png]]&lt;br /&gt;
&lt;br /&gt;
* This interface only works on sites where Behat is installed. If you are using the local PHP server, for example, you can access it on that site at http://localhost:8000 (log in as admin/admin).&lt;br /&gt;
&lt;br /&gt;
=== Tips ===&lt;br /&gt;
* You can use a &#039;&#039;&#039;Background&#039;&#039;&#039; section before the &#039;&#039;&#039;Scenario&#039;&#039;&#039; sections, this steps will be executed before the steps of each scenario (http://docs.behat.org/guides/1.gherkin.html#backgrounds)&lt;br /&gt;
* You can use &#039;&#039;&#039;Scenario outlines&#039;&#039;&#039; if your scenarios are nearly the same and depends on a few vars; check out the link for an explicative example (http://docs.behat.org/guides/1.gherkin.html#scenario-outlines)&lt;br /&gt;
** If your scenario outline consists of many steps it may be useful to add a comment with the number of steps. If the the test fails behat will tell you in which step overall and you will have to divide by the number of steps of the scenario to know in which example. &lt;br /&gt;
* Is better to test the outcomes against the given data than against language strings, which are depending on the selected language.&lt;br /&gt;
* In case you need to interact with popup windows you need to switch to the window you want to interact with after opening it using the &#039;&#039;&#039;I switch to &amp;quot;popupwindowname&amp;quot; window&#039;&#039;&#039;, close it when you finish interacting with it and return to the main window using &#039;&#039;&#039;I switch to main window&#039;&#039;&#039;&lt;br /&gt;
* The format of the .feature files is YAML which finds out the data hierarchy from the indentation of it&#039;s elements, so be sure that the elements are correctly nested and the indentation is correct using spaces when necessary&lt;br /&gt;
&lt;br /&gt;
=== Providing values to steps ===&lt;br /&gt;
Most of the steps requires values, there are five methods to provide values to steps, the method depends on the step specification, you can know when a steps requires a value because you will see a drop down menu with a closed list of options that the step accepts as argument or an upper case string between double quotes, something like &#039;&#039;&#039;I press &amp;quot;BUTTON_STRING&amp;quot;&#039;&#039;&#039; or it ends with a &#039;&#039;&#039;:&#039;&#039;&#039; . The five methods are:&lt;br /&gt;
* &#039;&#039;&#039;A string/text&#039;&#039;&#039;; is the most common case, the texts are wrapped between double quotes (&amp;quot; character) you have to replace the info about the expected value for your value; for example something like &#039;&#039;&#039;I press &amp;quot;BUTTON_STRING&amp;quot;&#039;&#039;&#039; should become &#039;&#039;&#039;I press &amp;quot;Save and return to course&amp;quot;&#039;&#039;&#039;. If you want to add a string which contains a &amp;quot; character, you can escape it with \&amp;quot;, for example &#039;&#039;&#039;I fill the &amp;quot;Name&amp;quot; field with &amp;quot;Alan alias \&amp;quot;the legend\&amp;quot;&amp;quot;&#039;&#039;&#039;. You can identify this steps because they ends with &#039;&#039;&#039;_STRING&#039;&#039;&#039;&lt;br /&gt;
* &#039;&#039;&#039;A number&#039;&#039;&#039;; some steps requires numbers as values, to be more specific an undetermined number of digits from 0 to 9 (Natural numbers + 0) you can identify them because the expected value info string ends with &#039;&#039;&#039;_NUMBER&#039;&#039;&#039;&lt;br /&gt;
* &#039;&#039;&#039;A table&#039;&#039;&#039;; is a relation between values, the most common use of it is to fill forms. The steps which requires tables are easily identifiable because they finish with &#039;&#039;&#039;:&#039;&#039;&#039; The steps description gives info about what the table columns must contain, for example &#039;&#039;&#039;Fills a moodle form with field/value data&#039;&#039;&#039;. Here you don&#039;t need to escape the double quotes if you want to include them as part of the value.&lt;br /&gt;
* &#039;&#039;&#039;A PyString&#039;&#039;&#039;; is a multiline string, most commonly used to fill out forms when a newline is required. Like steps with tables, steps which require PyStrings will end with &amp;quot;:&amp;quot;&lt;br /&gt;
* &#039;&#039;&#039;A field value&#039;&#039;&#039;; There are many different field types, if an argument requires a field value the expected value will depend on the field type:&lt;br /&gt;
** Text-based fields: It expects the text. This includes textareas, input type text, input type password...&lt;br /&gt;
** Checkbox: It expects 1 to check and for checked and &amp;quot;&amp;quot; to uncheck or for unchecked&lt;br /&gt;
** Select: It expects the option text or the option value. In case you interact with a multi-select you should specify the options separating them with commas. For example: &#039;&#039;&#039;option1, option2, option3&#039;&#039;&#039;&lt;br /&gt;
** Radio: The text of the radio option&lt;br /&gt;
* &#039;&#039;&#039;A selector&#039;&#039;&#039;; there are steps that can be used with different kinds of elements, for example &#039;&#039;&#039;I click on &amp;quot;User Name&amp;quot; &amp;quot;link&amp;quot;&#039;&#039;&#039; or &#039;&#039;&#039;I click on &amp;quot;User Name&amp;quot; &amp;quot;button&amp;quot;&#039;&#039;&#039; this is a closed list of elements, they always works together with another argument, where you specify the locator (eg. the link text in a link) In the &#039;Acceptance testing&#039; interface you can see a drop-down menu to select one of these options:&lt;br /&gt;
** field - for searching a field by its id, name, value or label&lt;br /&gt;
** link - for searching a link by its href, id, title, img alt or value&lt;br /&gt;
** button - for searching a button by its name, id, value, img alt or title&lt;br /&gt;
** link_or_button - for searching for both, links and buttons&lt;br /&gt;
** select - for searching a select field by its id, name or label&lt;br /&gt;
** checkbox - for searching a checkbox by its id, name, or label&lt;br /&gt;
** radio - for searching a radio button by its id, name, or label&lt;br /&gt;
** file - for searching a file input by its id, name, or label&lt;br /&gt;
** optgroup - for searching optgroup by its label&lt;br /&gt;
** option - for searching an option by its content&lt;br /&gt;
** dialogue - for searching a dialogue with the specified header text&lt;br /&gt;
** filemanager - for searching a filemanager by it&#039;s id or label&lt;br /&gt;
** block - for searching a Moodle block by it&#039;s English name or it&#039;s frankenstyle name&lt;br /&gt;
** section - for searching for a section on a course page by it&#039;s title or its written out date (e.g. &amp;quot;1 January - 7 January&amp;quot;). Use &amp;quot;frontpage&amp;quot; &amp;quot;section&amp;quot; for the frontpage section if it has no title (default)&lt;br /&gt;
** activity - for searching for an activity module in a course list by it&#039;s title&lt;br /&gt;
** region - for searching a Moodle page region with that id, in fact it works with all the page&#039;s ids&lt;br /&gt;
** table_row - for searching a table row which contains the specified text&lt;br /&gt;
** table - for searching a table by its id or caption&lt;br /&gt;
** fieldset - for searching a fieldset by it&#039;s id or legend&lt;br /&gt;
** css_element - for searching an element by its CSS selector&lt;br /&gt;
** xpath_element - for searching an element by its XPath&lt;br /&gt;
* &#039;&#039;&#039;A text selector&#039;&#039;&#039;; similar to a selector but those are the elements that returns an area of the DOM, they are useful in steps following the format &#039;&#039;&#039;... in the &amp;quot;Community finder&amp;quot; &amp;quot;block&amp;quot;&#039;&#039;&#039; where you are clicking or looking for some text inside a specific area. In the &#039;Acceptance testing&#039; interface you can see a drop-down menu to select one of these options:&lt;br /&gt;
** dialogue - for searching a dialogue with the specified header text&lt;br /&gt;
** block - for searching a Moodle block by it&#039;s English name or it&#039;s frankenstyle name&lt;br /&gt;
** section - for searching for a section on a course page by it&#039;s title or its written out date (e.g. &amp;quot;1 January - 7 January&amp;quot;). Use &amp;quot;frontpage&amp;quot; &amp;quot;section&amp;quot; for the frontpage section if it has no title (default)&lt;br /&gt;
** activity - for searching for an activity module in a course list by it&#039;s title&lt;br /&gt;
** region - for searching a Moodle page region with that id, in fact it works with all the page&#039;s ids&lt;br /&gt;
** table_row - for searching a table row which contains the specified text&lt;br /&gt;
** table - for searching a table by its id or caption&lt;br /&gt;
** fieldset - for searching a fieldset by it&#039;s id or legend&lt;br /&gt;
** css_element - for searching an element by its CSS selector&lt;br /&gt;
** xpath_element - for searching an element by its XPath&lt;br /&gt;
&lt;br /&gt;
==== Uploading files ====&lt;br /&gt;
Note than some tests requires files to be uploaded, in this case&lt;br /&gt;
* The &#039;&#039;&#039;I upload &amp;quot;FILEPATH_STRING&amp;quot; file to &amp;quot;FILEPICKER_FIELD_STRING&amp;quot; filepicker&#039;&#039;&#039; step can be used when located in the form page&lt;br /&gt;
* The file to upload should be included along with the Moodle codebase in COMPONENTNAME/tests/fixtures/*&lt;br /&gt;
* The file to upload is specified by it&#039;s path, which should be relative to the codebase root (&#039;&#039;&#039;lib/tests/fixtures/users.csv&#039;&#039;&#039; for example) &lt;br /&gt;
* &#039;&#039;&#039;/&#039;&#039;&#039; should be used as directory separator and the file names can not include this &#039;&#039;&#039;/&#039;&#039;&#039; character as all of them would be converted to the OS-dependant directory separator to maintain the compatibility with Windows systems.&lt;br /&gt;
* The scenarios that includes files uploading should be tagged using the &#039;&#039;&#039;@_file_upload&#039;&#039;&#039; tag&lt;br /&gt;
&lt;br /&gt;
==== Checking table values ====&lt;br /&gt;
You can check if specific value exists or not in a table row/column by using:&lt;br /&gt;
* Then &amp;quot;STRING_IN_ROW&amp;quot; row &amp;quot;COLUMN_HEADER&amp;quot; column of &amp;quot;TABLE_ID&amp;quot; table should contain &amp;quot;VALUE_TO_CHECK&amp;quot;&lt;br /&gt;
* Then the following should exist in the &amp;quot;TABLE_ID&amp;quot; table:&lt;br /&gt;
    | COLUMN_HEADER1 | COLUMN_HEADER2 |&lt;br /&gt;
    | VALUE_IN_ROW_1 | VALUE_IN_ROW_1 |&lt;br /&gt;
    | VALUE_IN_ROW_2 | VALUE_IN_ROW_2 |&lt;br /&gt;
&lt;br /&gt;
=== Fixtures ===&lt;br /&gt;
&lt;br /&gt;
As seen in [[https://docs.moodle.org/dev/Acceptance_testing#Examples examples]] Moodle provides a way to quickly set up the contextual data (courses, users, enrolments...) that you need to properly test scenarios, this can be done using one of the site templates (TODO) or creating entities in the background section (common for all the steps) or in the &amp;quot;Given&amp;quot; part of your scenario. Note that this steps can only be used to set up the contextual data required to test the feature but they don&#039;t test what they are doing; for example, the &amp;quot;Given the following &amp;quot;users&amp;quot; exists&amp;quot; is not testing that Moodle is able to create a user, but to test that a user can add a blog entry you might want to use this step. For further info, acceptance tests are supposed to be black-boxed tests (the tester don&#039;t know about the internals of the application) and this steps are using internal Moodle data generators instead of running all the steps required to create a user or to create a course, which speeds up the test execution. There are other features to test that all this elements can be properly created.&lt;br /&gt;
&lt;br /&gt;
==== Available elements ====&lt;br /&gt;
Most of the available elements can only be created in relation to other elements, to hide the complexity of the Moodle internals (references by contexts, ids...) the references can be done using more human-friendly mappings. &lt;br /&gt;
&lt;br /&gt;
The examples below shows how to add elements referencing other elements, there are required fields to reference the elements, other attributes will be filled with random data if they are not specified.&lt;br /&gt;
&lt;br /&gt;
* Course categories&lt;br /&gt;
** The required field is idnumber&lt;br /&gt;
** References between parent/children by their idnumber, using the &amp;quot;category&amp;quot; field&lt;br /&gt;
  Given the following &amp;quot;categories&amp;quot; exist:&lt;br /&gt;
    | name       | category | idnumber |&lt;br /&gt;
    | Category 1 | 0        | CAT1     |&lt;br /&gt;
    | Category 2 | CAT1     | CAT2     |&lt;br /&gt;
&lt;br /&gt;
* Courses&lt;br /&gt;
** The required field is shortname&lt;br /&gt;
** Uses the category idnumber as category reference&lt;br /&gt;
  Given the following &amp;quot;courses&amp;quot; exist:&lt;br /&gt;
    | fullname | shortname | category | format | &lt;br /&gt;
    | Course 1 | COURSE1   | CAT1     | topics |&lt;br /&gt;
    | Course 2 | COURSE2   | CAT2     |        |&lt;br /&gt;
&lt;br /&gt;
* Activities *(note that this step does not work with all kind of activities, only the ones that have data generators)*&lt;br /&gt;
** The required fields are activity, course and idnumber&lt;br /&gt;
** Uses activity to specify the activity type&lt;br /&gt;
** Uses the course shortname as course reference&lt;br /&gt;
** Other activity-dependant fields can be specified by it&#039;s field name&lt;br /&gt;
  Given the following &amp;quot;activities&amp;quot; exist:&lt;br /&gt;
    | activity | course | idnumber | name                 | intro                       |&lt;br /&gt;
    | assign   | C1     | assign1  | Test assignment name | Test assignment description |&lt;br /&gt;
    | data     | C1     | data1    | Test database name   | Test database description   |&lt;br /&gt;
&lt;br /&gt;
* Groups&lt;br /&gt;
** The required fields are course and idnumber&lt;br /&gt;
** Uses the course shortname as course reference&lt;br /&gt;
  Given the following &amp;quot;groups&amp;quot; exist:&lt;br /&gt;
    | name    | description | course  | idnumber |&lt;br /&gt;
    | Group 1 | Anything    | COURSE1 | GROUP1   |&lt;br /&gt;
&lt;br /&gt;
* Groupings&lt;br /&gt;
** The required fields are course and idnumber&lt;br /&gt;
** Uses the course shortname as course reference&lt;br /&gt;
  Given the following &amp;quot;groupings&amp;quot; exist:&lt;br /&gt;
    | name       | course  | idnumber  |&lt;br /&gt;
    | Grouping 1 | COURSE1 | GROUPING1 |&lt;br /&gt;
    | Grouping 2 | COURSE1 | GROUPING2 |&lt;br /&gt;
&lt;br /&gt;
* Users&lt;br /&gt;
** The required field is username (if password is not set username value will be used as password too)&lt;br /&gt;
  Given the following &amp;quot;users&amp;quot; exist:&lt;br /&gt;
    | username | email       | firstname | lastname |&lt;br /&gt;
    | testuser | asd@asd.com | Test      | User     |&lt;br /&gt;
&lt;br /&gt;
* Course enrolments&lt;br /&gt;
** The required fields are user, course and role&lt;br /&gt;
** Uses the course shortname as course reference&lt;br /&gt;
** Uses the user username as user reference&lt;br /&gt;
** Uses the role shortname as role reference&lt;br /&gt;
** Uses the enrolment name as enrol reference&lt;br /&gt;
  Given the following &amp;quot;course enrolments&amp;quot; exist:&lt;br /&gt;
    | user     | course  | role           | enrol  |&lt;br /&gt;
    | testuser | COURSE1 | editingteacher | manual |&lt;br /&gt;
&lt;br /&gt;
* Roles&lt;br /&gt;
** The required field is shortname&lt;br /&gt;
** Uses a one of the following roles as archetype: manager, coursecreator, editingteacher, teacher, student, guest, user and frontpage&lt;br /&gt;
  Given the following &amp;quot;roles&amp;quot; exist:&lt;br /&gt;
    | shortname | name          | description | archetype      |&lt;br /&gt;
    | custom1   | Custom Role 1 |             | editingteacher |&lt;br /&gt;
&lt;br /&gt;
* Role assigns&lt;br /&gt;
** The required fields are user, role, contextlevel and reference&lt;br /&gt;
** Uses the user username as user reference&lt;br /&gt;
** Uses the role shortname as role reference&lt;br /&gt;
** Uses contextlevel + reference to specify the context. See [[#Referencing_contexts]] for more info.&lt;br /&gt;
  Given the following &amp;quot;role assigns&amp;quot; exist:&lt;br /&gt;
    | user  | role           | contextlevel | reference |&lt;br /&gt;
    | user1 | manager        | System       |           |&lt;br /&gt;
    | user2 | editingteacher | Category     | CATEGORY1 |&lt;br /&gt;
    | user3 | editingteacher | Course       | COURSE1   |&lt;br /&gt;
&lt;br /&gt;
* System role assigns (deprecated in favour of role assigns, see item right above this one)&lt;br /&gt;
** The required fields are user and role&lt;br /&gt;
** Uses the user username as user reference&lt;br /&gt;
** Uses the role shortname as role reference&lt;br /&gt;
  Given the following &amp;quot;system role assigns&amp;quot; exist:&lt;br /&gt;
    | user     | role    |&lt;br /&gt;
    | testuser | manager |&lt;br /&gt;
&lt;br /&gt;
* Permission overrides&lt;br /&gt;
** The required fields are capability, permissions, role, and the contextlevel + it&#039;s reference&lt;br /&gt;
** Uses contextlevel + reference to specify the context. See [[#Referencing_contexts]] for more info.&lt;br /&gt;
  Given the following &amp;quot;permission overrides&amp;quot; exist:&lt;br /&gt;
    | capability            | permission | role           | contextlevel | reference |&lt;br /&gt;
    | mod/forum:editanypost | Allow      | student        | Course       | C1        |&lt;br /&gt;
    | mod/forum:replynews   | Prevent    | editingteacher | Course       | C1        |&lt;br /&gt;
    | mod/paquiro:sings     | Prohibit   | student        | System       |           |&lt;br /&gt;
&lt;br /&gt;
* Group members&lt;br /&gt;
** The required fields are user and group&lt;br /&gt;
** Uses the group idnumber as group reference&lt;br /&gt;
** Uses the user username as user reference&lt;br /&gt;
  Given the following &amp;quot;group members&amp;quot; exist:&lt;br /&gt;
    | user     | group  |&lt;br /&gt;
    | testuser | GROUP1 |&lt;br /&gt;
&lt;br /&gt;
* Grouping groups&lt;br /&gt;
** The required fields are grouping and group&lt;br /&gt;
** Uses the group idnumber as group reference&lt;br /&gt;
** Uses the grouping idnumber as grouping reference&lt;br /&gt;
  Given the following &amp;quot;grouping groups&amp;quot; exist:&lt;br /&gt;
    | grouping  | group  |&lt;br /&gt;
    | GROUPING1 | GROUP1 |&lt;br /&gt;
&lt;br /&gt;
* Cohorts&lt;br /&gt;
** The required field is idnumber&lt;br /&gt;
  Given the following &amp;quot;cohorts&amp;quot; exist:&lt;br /&gt;
    | name     | idnumber |&lt;br /&gt;
    | Cohort 1 | COHORT1  |&lt;br /&gt;
&lt;br /&gt;
==== Referencing contexts ====&lt;br /&gt;
&lt;br /&gt;
Moodle has different context levels, internally they have an identifier, but to reference them from steps we can use a more human way, using the level of the context (as specified below) and the reference, which will depend on the contextlevel we are using:&lt;br /&gt;
* contextlevel: &#039;&#039;&#039;System&#039;&#039;&#039;, &#039;&#039;&#039;User&#039;&#039;&#039;, &#039;&#039;&#039;Category&#039;&#039;&#039;, &#039;&#039;&#039;Course&#039;&#039;&#039; or &#039;&#039;&#039;Activity module&#039;&#039;&#039;&lt;br /&gt;
* reference:&lt;br /&gt;
** System: Nothing, just leave the the cell empty&lt;br /&gt;
** User: The user &#039;&#039;&#039;username&#039;&#039;&#039;&lt;br /&gt;
** Category: The category &#039;&#039;&#039;idnumber&#039;&#039;&#039;&lt;br /&gt;
** Course: The course &#039;&#039;&#039;shortname&#039;&#039;&#039;&lt;br /&gt;
** Activity module: The activity &#039;&#039;&#039;idnumber&#039;&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
The data generators which makes use of these format are pointing to here.&lt;br /&gt;
&lt;br /&gt;
=== Features check list ===&lt;br /&gt;
* It&#039;s a new feature or a new scenario of an existing feature&lt;br /&gt;
* Is using the &#039;&#039;&#039;Background&#039;&#039;&#039; section or &#039;&#039;&#039;Scenario Outlines&#039;&#039;&#039; instead of duplicating steps (only when applicable)&lt;br /&gt;
* Are using the appropriate Moodle component tag according to https://docs.moodle.org/dev/Acceptance_testing#Tests_filters&lt;br /&gt;
* The user story of the feature includes a valid stakeholder and makes sense according to https://docs.moodle.org/dev/Acceptance_testing#Writing_features&lt;br /&gt;
* Covers both JS and non-JS environments&lt;br /&gt;
&lt;br /&gt;
== Adding steps definitions ==&lt;br /&gt;
&lt;br /&gt;
Each Moodle component and plugin (including 3rd party plugins) can add new steps definitions. If you are writing tests and you notice that you are repeating the same group of steps you might want to create a new step definition that allows you to substitute the group of steps for one single step, something like &#039;&#039;I add a forum post with &amp;quot;blablabla&amp;quot; as description&#039;&#039; for example; also you can create whole new steps using the APIs provided by Behat and Mink if what you need to do is not covered by any of the available steps.&lt;br /&gt;
&lt;br /&gt;
As commented in https://docs.moodle.org/dev/Acceptance_testing#Fixtures, this are black box tests, so we are not supposed to know about Moodle internals; translated to developer language it means don&#039;t use Moodle internals API calls, for example you should not try to cheat using a set_config() call, you should follow Moodle&#039;s user interface to reach the setting page and change it&#039;s value.&lt;br /&gt;
&lt;br /&gt;
=== Example ===&lt;br /&gt;
&lt;br /&gt;
You can use this example below or any of the existing steps definitions as a template.&lt;br /&gt;
&lt;br /&gt;
* auth/tests/behat/behat_auth.php&lt;br /&gt;
  class behat_auth extends behat_base {&lt;br /&gt;
      /**&lt;br /&gt;
       * Logs in the user. There should exist a user with the same value as username and password&lt;br /&gt;
       *&lt;br /&gt;
       * This second comment line will be not shown in the steps definitions list as it is only&lt;br /&gt;
       * reading the first line in the comment block.&lt;br /&gt;
       *&lt;br /&gt;
       * @Given /^I log in as &amp;quot;(?P&amp;lt;username_string&amp;gt;(?:[^&amp;quot;]|\\&amp;quot;)*)&amp;quot;$/&lt;br /&gt;
       */&lt;br /&gt;
      public function i_log_in_as($username) {&lt;br /&gt;
          return array(new Given(&#039;I am on homepage&#039;),&lt;br /&gt;
              new Given(&#039;I follow &amp;quot;&#039; . get_string(&#039;login&#039;) . &#039;&amp;quot;&#039;),&lt;br /&gt;
              new Given(&#039;I fill in &amp;quot;&#039; . get_string(&#039;username&#039;) . &#039;&amp;quot; with &amp;quot;&#039; . $this-&amp;gt;escape($username) . &#039;&amp;quot;&#039;),&lt;br /&gt;
              new Given(&#039;I fill in &amp;quot;&#039; . get_string(&#039;password&#039;) . &#039;&amp;quot; with &amp;quot;&#039;. $this-&amp;gt;escape($username) . &#039;&amp;quot;&#039;),&lt;br /&gt;
              new Given(&#039;I press &amp;quot;&#039; . get_string(&#039;login&#039;) . &#039;&amp;quot;&#039;)&lt;br /&gt;
          );&lt;br /&gt;
      }&lt;br /&gt;
  }&lt;br /&gt;
&lt;br /&gt;
=== Tips ===&lt;br /&gt;
&lt;br /&gt;
If you are creating a completely new step definition there are also a few things to consider:&lt;br /&gt;
* Steps definitions should be compatible with both Javascript and non-Javascript tests, you can use $this-&amp;gt;running_javascript() to deal with both&lt;br /&gt;
* The definition code will be executed by Behat, not by Moodle, you have to keep this in mind for example when throwing exceptions, Behat exceptions will give more info to the user about where is the problem&lt;br /&gt;
** You can find these exceptions in &#039;&#039;&#039;vendor/behat/mink/src/Behat/Mink/Exception/*&#039;&#039;&#039;&lt;br /&gt;
* Selenium is fast, sometimes it tries to interact with DOM elements or tries to execute actions that requires JS that are not loaded or ready to used; this is why, sometimes and randomly, you can see an &amp;quot;element not found&amp;quot; failure&lt;br /&gt;
** The quickest way to solve this problem is using behat_base::find*() methods (where the * corresponds to &#039;&#039;&#039;&amp;lt;nowiki&amp;gt;&#039;&#039;&amp;lt;/nowiki&amp;gt;&#039;&#039;&#039;, &#039;&#039;&#039;_all&#039;&#039;&#039;, or to a named selector preceded by &#039;&#039;&#039;_&#039;&#039;&#039;, http://mink.behat.org/#named-selectors) which only requires the locator as argument. This methods will wait for the requested element to be ready or return an exception if the element is not found after the timeout value expires, you can also force the timeout value, which defaults to 6 seconds. An example of a named selector use is &#039;&#039;&#039;$button = $this-&amp;gt;find_button(&amp;quot;Save changes&amp;quot;);&#039;&#039;&#039; if you are not sure about the element being available you always can wrap the find*() call in a try &amp;amp; catch.&lt;br /&gt;
** For advanced usages, the spin method is defined in &#039;&#039;&#039;lib/behat/behat_base::spin&#039;&#039;&#039;, consider that all the contents of the closures passed to spin() can be executed more than once, so don&#039;t use irreversible actions that can invalidate the tests results (for example use find() methods but don&#039;t use click() methods)&lt;br /&gt;
* If a test should be skipped under certain circumstances you can trigger a &#039;&#039;&#039;\Moodle\BehatExtension\Exception\SkippedException&#039;&#039;&#039; exception, it will get caught and the scenario using that step will be reported as skipped.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
If you create new steps definitions or tests you must run &#039;&#039;&#039;php admin/tool/behat/cli/util.php --enable&#039;&#039;&#039; to update the Behat config file before running &#039;&#039;&#039;vendor/bin/behat&#039;&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
=== Check list ===&lt;br /&gt;
&lt;br /&gt;
New steps should be/have:&lt;br /&gt;
* Implemented as public methods of a PHP class whose name must begin with &#039;behat_&#039; prefix and with &#039;.php extension&lt;br /&gt;
* Using the class name as filename (adding the &#039;.php&#039; extension) and extending MOODLEDIRROOT/lib/behat/behat_base.php (or MOODLEDIRROOT/lib/behat/behat_files.php if it&#039;s a repository or is files-related)&lt;br /&gt;
* With a descriptive class name, for example the component name (it will be used when filtering steps definitions)&lt;br /&gt;
* Stored in COMPONENTNAME/tests/behat/ directory or lib/tests/behat/ if is not part of any other component&lt;br /&gt;
* Describe it&#039;s purpose in a single line inside the method doc comment, the size of the comment is not a problem&lt;br /&gt;
* Describe the regular expression with the most appropriate tag inside the method doc comment:&lt;br /&gt;
** &#039;&#039;&#039;@Given&#039;&#039;&#039; - A step to set up the initial context (for example &#039;&#039;the following &amp;quot;courses&amp;quot; exists&#039;&#039;)&lt;br /&gt;
** &#039;&#039;&#039;@When&#039;&#039;&#039; - An action that provokes an event (for example &#039;&#039;I press the button &amp;quot;buttonname&amp;quot;&#039;&#039;)&lt;br /&gt;
** &#039;&#039;&#039;@Then&#039;&#039;&#039; - Checkings to ensure the outcomes are the expected (for example &#039;&#039;I should see &amp;quot;whatever&amp;quot;&#039;&#039;)&lt;br /&gt;
* Depending on the inputs your definition expects you must use a different regular expression:&lt;br /&gt;
** &#039;&#039;&#039;If you expect a number:&#039;&#039;&#039; &amp;quot;(?P&amp;lt;info_about_what_you_expect_number&amp;gt;\d+)&amp;quot; (note that the regular expression is quoted between &#039;&#039;&#039;&amp;quot;&#039;&#039;&#039;)&lt;br /&gt;
** &#039;&#039;&#039;If you expect a string or a text:&#039;&#039;&#039; &amp;quot;(?P&amp;lt;info_about_what_you_expect_string&amp;gt;(?:[^&amp;quot;]|\\&amp;quot;)*)&amp;quot; Don&#039;t use &#039;&#039;&#039;text_selector_string&#039;&#039;&#039; and &#039;&#039;&#039;selector_string&#039;&#039;&#039; as info strings, they are reserved to selector types (note that the regular expression is quoted between &#039;&#039;&#039;&amp;quot;&#039;&#039;&#039;)&lt;br /&gt;
** &#039;&#039;&#039;If you expect a table with key/value pairs (for example to fill a form):&#039;&#039;&#039; Finish your regular expression with &#039;&#039;&#039;:&#039;&#039;&#039; and provide info in the description about the contents of the table&lt;br /&gt;
** &#039;&#039;&#039;If you expect a selector type:&#039;&#039;&#039; &amp;quot;(?P&amp;lt;selector_string&amp;gt;[^&amp;quot;]*)&amp;quot; or &amp;quot;(?P&amp;lt;text_selector_string&amp;gt;[^&amp;quot;]*)&amp;quot; depending on whether you want to use any selector or you want a text-based selector (more info about selectors in https://docs.moodle.org/dev/Acceptance_testing#Providing_values_to_steps)&lt;br /&gt;
** &#039;&#039;&#039;If you expect a value from a closed list:&#039;&#039;&#039; &#039;&#039;(?P&amp;lt;info&amp;gt;firstchoice|secondchoice|asmanyasyouwant)&#039;&#039;&lt;br /&gt;
* To make test writer&#039;s life better is good to include explicative info in the subexpressions of the regular expression about what the test writer is supposed to put in there (for example &#039;&#039;I expand &amp;quot;(?P&amp;lt;nodetext&amp;gt;(?:[^&amp;quot;]|\\&amp;quot;)*)&amp;quot; node&#039;&#039;)&lt;br /&gt;
* Is recommended to use the static part of the regular expression as the name of the method, using underscores instead of spaces (see current steps definitions)&lt;br /&gt;
&lt;br /&gt;
== Troubleshooting ==&lt;br /&gt;
&lt;br /&gt;
=== How can you tell if Selenium is running? ===&lt;br /&gt;
&lt;br /&gt;
Try going to http://localhost:4444/selenium-server/. If Selenium is not running, nothing will happen. You will get a time-out. If selenium is running, you will get a 404 error page saying powered by Jetty at the bottom.&lt;br /&gt;
&lt;br /&gt;
=== How can I stop Selenium? ===&lt;br /&gt;
&lt;br /&gt;
Go to the URL http://localhost:4444/selenium-server/driver/?cmd=shutDownSeleniumServer. I think when it works it outputs &amp;quot;OKOK&amp;quot;.&lt;br /&gt;
&lt;br /&gt;
=== How to pause behat to check browser html ===&lt;br /&gt;
&lt;br /&gt;
You can use following step to pause behat execution. To resume execution, press Enter/Return key in console.&lt;br /&gt;
&amp;lt;pre&amp;gt;And I pause scenario execution&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Behat tells me that lots of steps are undefined ===&lt;br /&gt;
&lt;br /&gt;
* You probably forgot the --config option in the behat command.&lt;br /&gt;
* With opcache enabled, definitions are not loaded properly. Try a run with opcache disabled.&lt;br /&gt;
&lt;br /&gt;
=== Behat is showing no output ===&lt;br /&gt;
With opcache enabled, definitions are not loaded properly. Try a run with opcache disabled.&lt;br /&gt;
&lt;br /&gt;
=== Behat is running slow ===&lt;br /&gt;
Independent of machine speed, Behat can be slow because of internet speed, as MathJax filter is enabled by default and points to cdn.&lt;br /&gt;
To use a local installation of MathJax, first download the full MathJax library from http://www.mathjax.org/. Then install it on a web server. Finally add following to config.php&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$CFG-&amp;gt;forced_plugin_settings = array(&#039;filter_mathjaxloader&#039; =&amp;gt;&lt;br /&gt;
    array(&#039;httpurl&#039; =&amp;gt; &#039;http://localhost/MathJax/MathJax.js&#039;,&lt;br /&gt;
          &#039;httpsurl&#039; =&amp;gt; &#039;https://localhost/MathJax/MathJax.js&#039;),&lt;br /&gt;
);&lt;br /&gt;
$CFG-&amp;gt;behat_extraallowedsettings = array(&#039;forced_plugin_settings&#039;);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Uncheck checkbox without javascript ===&lt;br /&gt;
Uncheck a checkbox doesn&#039;t work in non-javascript scenario. This is a known issue with [https://github.com/minkphp/MinkGoutteDriver/issues/65 MinkGoutteDriver], please use tag @javascript for the scenarios where you need to uncheck a checkbox.&lt;br /&gt;
&lt;br /&gt;
== Browser specific fixes ==&lt;br /&gt;
&lt;br /&gt;
If you are interested in running behat in other browsers you might be interested on https://docs.moodle.org/dev/Acceptance_testing/Browsers&lt;br /&gt;
&lt;br /&gt;
When running acceptance tests in conjunction with Selenium there is a fix for the navigation bar that gets applied in order to avoid errors arising from a bug in the webdrivers for those browsers.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;b&amp;gt;The issue&amp;lt;/b&amp;gt;: When an acceptance test goes to interact with an element on the page it first ensures that the element in the view-port and if not scrolls the browser to get the element into the view-port. The browser scrolls the element only just inside the view-port. It doesn&#039;t however allow for any fixed position elements such as the navigation bar.&lt;br /&gt;
What happens: In some situations these browsers scroll up to reach a button, however not enough as the button ends up behind the navigation bar and cannot be interacted with.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;b&amp;gt;Our solution&amp;lt;/b&amp;gt;: We can not change browser driver behaviour so we have integrated a work around. When running acceptance tests we change the position attribute of the navigation bar from fixed to absolute. This is not ideal as it is not how the user experiences the site, however it allows us to run the full acceptance test suite against all browsers so we allowed it. A notice will be displayed when you start an acceptance test run if the browser specific fixes have been applied. See MDL-54589 / MDL-51881 / MDL-47734 / MDL-45231 for more details.&lt;br /&gt;
&lt;br /&gt;
== See also == &lt;br /&gt;
&lt;br /&gt;
* Migrating from Behat 2.5 to 3.x in Moodle [[Acceptance_testing/Migrating_from_Behat_2.5_to_3.x_in_Moodle]]&lt;br /&gt;
* Guidelines for contributors: [[Acceptance_testing/Contributing_automated_tests|Contributing automated tests]]&lt;br /&gt;
* Technical info: [[Behat integration]]&lt;br /&gt;
* Behat CLI command options: http://docs.behat.org/guides/6.cli.html&lt;br /&gt;
* How to use selectors to interact with the site elements: http://mink.behat.org/#traverse-the-page-selectors&lt;br /&gt;
* Vagrant profile with Moodle and Behat preconfigured: https://github.com/mackensen/moodle-hat&lt;br /&gt;
&lt;br /&gt;
[[Category:Behat]][[Category:Quality Assurance]][[Category:Coding guidelines]]&lt;br /&gt;
&lt;br /&gt;
[[es:Prueba de aceptación]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Behat_integration&amp;diff=50737</id>
		<title>Behat integration</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Behat_integration&amp;diff=50737"/>
		<updated>2016-08-01T08:31:30Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: /* How Behat works */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;== Introduction ==&lt;br /&gt;
&lt;br /&gt;
This page describes the internals of Behat and the integration with Moodle. For the functional description, how to install it, run the suite and add more features, see [[Acceptance_testing]].&lt;br /&gt;
&lt;br /&gt;
Behat is a framework for behaviour driven development (BDD) allows us to specify Moodle functionalities (aka features) as a human-readable list of steps and parse this steps to execute actions to simulate user interaction, it executes the actions against a headless browsers (without javascript support, only curl-kind requests) or user simulation tools like Selenium, which interacts with browsers and allows Javascript events simulation.&lt;br /&gt;
&lt;br /&gt;
== Objective ==&lt;br /&gt;
The aim of this integration is to allow Moodle components to have its own set of features and steps definitions, this allows BDD in Moodle and allows us to execute periodically the whole set of tests to detect regressions and test the Moodle features in different environments (browsers, DBs engines, web servers...). The Moodle QA tests will be progressively rewritten according to this format to run automatically.&lt;br /&gt;
&lt;br /&gt;
== How Behat works ==&lt;br /&gt;
This section aims to explain the basics about BDD and Behat and a quick view of how Behat internally works from the CLI command execution to the results output.&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;Note that all those examples are not necessarily real nor part of the suite, they are meant to help understand the concepts, see [[Acceptance_testing]] for real examples&#039;&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
Some terms used:&lt;br /&gt;
* &#039;&#039;&#039;Features&#039;&#039;&#039;: Human-readable list of scenarios that describes a feature&lt;br /&gt;
&lt;br /&gt;
  @auth&lt;br /&gt;
  &#039;&#039;&#039;Feature&#039;&#039;&#039;: Login&lt;br /&gt;
    In order to login&lt;br /&gt;
    As a moodle user&lt;br /&gt;
    I need to be able to validate the username and password against moodle&lt;br /&gt;
    &lt;br /&gt;
    &#039;&#039;&#039;Scenario&#039;&#039;&#039;: Login as an existing user&lt;br /&gt;
      Given I am on &amp;quot;login/index.php&amp;quot;&lt;br /&gt;
      When I fill in &amp;quot;username&amp;quot; with &amp;quot;admin&amp;quot;&lt;br /&gt;
      And I fill in &amp;quot;password&amp;quot; with &amp;quot;admin&amp;quot;&lt;br /&gt;
      And I press &amp;quot;loginbtn&amp;quot;&lt;br /&gt;
      Then I should see &amp;quot;Moodle 101: Course Name&amp;quot;&lt;br /&gt;
    &lt;br /&gt;
    &#039;&#039;&#039;Scenario&#039;&#039;&#039;: Login as an non-existing user&lt;br /&gt;
      Given I am on &amp;quot;login/index.php&amp;quot;&lt;br /&gt;
      When I fill in &amp;quot;username&amp;quot; with &amp;quot;admin&amp;quot;&lt;br /&gt;
      And I fill in &amp;quot;password&amp;quot; with &amp;quot;admin&amp;quot;&lt;br /&gt;
      And I press &amp;quot;loginbtn&amp;quot;&lt;br /&gt;
      Then I should see &amp;quot;Invalid login&amp;quot;&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;Scenario&#039;&#039;&#039;: Human-readable list of steps to describe an expected behaviour&lt;br /&gt;
  &#039;&#039;&#039;Scenario&#039;&#039;&#039;: Login as an existing user&lt;br /&gt;
    Given I am on &amp;quot;login/index.php&amp;quot;&lt;br /&gt;
    When I fill in &amp;quot;username&amp;quot; with &amp;quot;admin&amp;quot;&lt;br /&gt;
    And I fill in &amp;quot;password&amp;quot; with &amp;quot;admin&amp;quot;&lt;br /&gt;
    And I press &amp;quot;loginbtn&amp;quot;&lt;br /&gt;
    Then I should see &amp;quot;Moodle 101: Course Name&amp;quot;&lt;br /&gt;
* &#039;&#039;&#039;Steps&#039;&#039;&#039;: Human-readable sentences that describes an action. There are 3 types of steps, &amp;quot;Given&amp;quot; describing the initial context, &amp;quot;When&amp;quot; the event that provokes a change and &amp;quot;Then&amp;quot; where the outcomes should be asserted.&lt;br /&gt;
  I click on the &amp;quot;Add user&amp;quot; button&lt;br /&gt;
* &#039;&#039;&#039;Steps definitions&#039;&#039;&#039;: PHP methods referenced by steps when matching it&#039;s regular expression. The @Given, @When and @Then tags are descriptive and they are not taken into account when matching steps with steps definitions. The regular expressions placeholders are returned to the PHP method as arguments so methods can use them to tell the browser which button (for example) they want to click.&lt;br /&gt;
  /**&lt;br /&gt;
   * @When /^I click on the &amp;quot;(.*)&amp;quot; button$/&lt;br /&gt;
   */&lt;br /&gt;
  public function i_click_on_the_button($button) {&lt;br /&gt;
    // Simulates the user interaction (see Mink description below for more info)&lt;br /&gt;
    $this-&amp;gt;getSession()-&amp;gt;getPage()-&amp;gt;pressButton($button);&lt;br /&gt;
  }&lt;br /&gt;
  &lt;br /&gt;
* &#039;&#039;&#039;Behat&#039;&#039;&#039;: PHP framework and CLI application that wraps the whole process of features files loading + features files parsing + execution of actions in the browser + results output (http://behat.org/)&lt;br /&gt;
* &#039;&#039;&#039;Gherkin&#039;&#039;&#039;: Human-readable language used to define features that can be parsed and translated into PHP methods. For more info, it&#039;s the same language used by Cucumber, the BDD Ruby framework (https://github.com/cucumber/cucumber/wiki/Gherkin)&lt;br /&gt;
* &#039;&#039;&#039;Context&#039;&#039;&#039;: In Behat scope a context is a PHP class that groups steps definitions (as methods)&lt;br /&gt;
* &#039;&#039;&#039;Mink&#039;&#039;&#039;: Is the component which interacts with browsers, simulating a real user interaction. It allows us to write PHP code (or use the available PHP methods) to send requests to the different browsers APIs through a common interface or extend it to allow browser-specific actions. The supported browsers includes Selenium, Selenium2, Sahi... http://mink.behat.org/&lt;br /&gt;
* &#039;&#039;&#039;Selenium 2&#039;&#039;&#039;: Web browser automation tool, applications like Mink can communicate with it through a RESTful API (http://code.google.com/p/selenium/wiki/JsonWireProtocol) to execute actions simulating user interaction.&lt;br /&gt;
* &#039;&#039;&#039;Selector type&#039;&#039;&#039;: Related with &#039;&#039;&#039;locator&#039;&#039;&#039;, is a way to select a node inside the page DOM, more info in https://docs.moodle.org/dev/Acceptance_testing#Providing_values_to_steps&lt;br /&gt;
* &#039;&#039;&#039;Locator&#039;&#039;&#039;: Is what we are looking for inside the page DOM, it completely depends on the associated selector type, a few examples of it:&lt;br /&gt;
** Selector type = &amp;quot;link&amp;quot;, Locator = &amp;quot;Link text&amp;quot;&lt;br /&gt;
** Selector type = &amp;quot;field&amp;quot;, Locator = &amp;quot;Field legend text&amp;quot;&lt;br /&gt;
** Selector type = &amp;quot;css&amp;quot;, Locator = &amp;quot;.css-class #id&amp;quot;&lt;br /&gt;
** Selector type = &amp;quot;xpath&amp;quot;, Locator = &amp;quot;//input[@id=&#039;id-value&#039;]&amp;quot;&lt;br /&gt;
&lt;br /&gt;
All this components are written in PHP, open sourced and packaged in a single and extensible framework.&lt;br /&gt;
&lt;br /&gt;
=== Quick view of the whole process ===&lt;br /&gt;
&lt;br /&gt;
# Behat CLI execution&lt;br /&gt;
#* Behat application initialization and loading of arguments (features files to execute, output format...)&lt;br /&gt;
#* Reads the Behat config file (browser servers are specified here)&lt;br /&gt;
#* Extensions overrides management&lt;br /&gt;
#* Gherkin initialization&lt;br /&gt;
# Features files selection&lt;br /&gt;
#* According to the arguments Gherkin looks for .features files&lt;br /&gt;
#** It can use different features loaders (single file, a directory, the default directory...)&lt;br /&gt;
#** The framework can be extended to allow multiple folders loading&lt;br /&gt;
# Features parsing (Gherkin)&lt;br /&gt;
#* Loops through the loaded features files looking for scenarios&lt;br /&gt;
#* Gets the list of steps of each scenario&lt;br /&gt;
#* There are hooks at different levels (http://docs.behat.org/guides/3.hooks.html)&lt;br /&gt;
# Steps parsing (Gherkin)&lt;br /&gt;
#* Gherkin looks in the available steps definitions for a regular expression that matches the step text&lt;br /&gt;
# Step definition execution&lt;br /&gt;
#* The step definition code is executed&lt;br /&gt;
#* Steps definitions most of the time uses the Mink component to communicate with the browser API sending requests like &amp;quot;click on that button&amp;quot; or &amp;quot;go to XXX page&amp;quot;&lt;br /&gt;
# Scenario outcomes&lt;br /&gt;
#* The scenario counts as failed if an exception is thrown when executing a step definition (for example trying to click a non-existing button)&lt;br /&gt;
#* The scenario counts as passed if no exception is thrown during it&#039;s steps execution&lt;br /&gt;
# Finishing CLI execution&lt;br /&gt;
#* A summary with all the scenario results is displayed&lt;br /&gt;
#* It accepts different output formats (like JUnitXML) to it&#039;s execution in continuous integration systems (http://docs.behat.org/guides/6.cli.html#format-options)&lt;br /&gt;
&lt;br /&gt;
== Moodle integration ==&lt;br /&gt;
&lt;br /&gt;
It follows the approach chosen with PHPUnit:&lt;br /&gt;
* It comes disabled by default, Behat is not included within Moodle and it has to be installed separately with the composer installer&lt;br /&gt;
* Moodle components (subsystems and plugins) can have a tests/behat/ folder&lt;br /&gt;
* The scenarios are executed in a test environment, the production database and dataroot are not affected by the tests modifications&lt;br /&gt;
* The scenarios specifies their own fixtures and it&#039;s execution is isolated from other scenarios and features, resetting the test database and the test dataroot before each scenario&lt;br /&gt;
* Moodle lists the features files and steps definitions of it&#039;s components in a behat.yml file, similar to the phpunit.xml manifest&lt;br /&gt;
* A basic behat.yml.dist config file has been included&lt;br /&gt;
&lt;br /&gt;
=== Alternative environment ===&lt;br /&gt;
Acceptance testing implies interaction with the browser like real users does, so it requires the site to be accessible via URL. The Moodle integration creates a new moodle site installation in parallel to the production one to run the tests in a sandbox without affecting the production environment, switching the regular $CFG-&amp;gt;wwwroot, $CFG-&amp;gt;dataroot and $CFG-&amp;gt;prefix to alternatives, which should be only accessible from localhost or internal networks. Info about how to run the tests in https://docs.moodle.org/dev/Acceptance_testing#Running_tests. &lt;br /&gt;
&lt;br /&gt;
This default configuration is useful when developing in a local host, but to run the tests automatically with Jenkins, travis, other CI systems or with saucelabs we provide a few extra settings. More info in https://docs.moodle.org/dev/Acceptance_testing#Advanced_usage&lt;br /&gt;
&lt;br /&gt;
All the behat CLI utilities we provide within the Moodle codebase (admin/tool/behat/cli/*) are using $CFG-&amp;gt;behat_wwwroot, $CFG-&amp;gt;behat_prefix and $CFG-&amp;gt;behat_dataroot instead of $CFG-&amp;gt;wwwroot, $CFG-&amp;gt;prefix and $CFG-&amp;gt;dataroot, this scripts are self-contained, but as we are accessing through a browser, we also need to switch the whole Moodle instance to test mode. For this there are two requirements:&lt;br /&gt;
&lt;br /&gt;
* Test mode is enabled if&lt;br /&gt;
** &#039;&#039;&#039;php admin/tool/behat/cli/init.php&#039;&#039;&#039; or &#039;&#039;&#039;php admin/tool/behat/cli/util.php --enable&#039;&#039;&#039; has been executed&lt;br /&gt;
* Test mode is requested if&lt;br /&gt;
** The vendor/bin/behat command is running, we know it because we hook the Behat process before the tests begins to run and we require moodle config.php after it&lt;br /&gt;
** We set $CFG-&amp;gt;behat_wwwroot in config.php and we are accessing the moodle instance through it&lt;br /&gt;
&lt;br /&gt;
The unique $CFG-&amp;gt;behat_wwwroot prevents unintended execution of acceptance tests on production sites.&lt;br /&gt;
&lt;br /&gt;
=== Javascript ===&lt;br /&gt;
There are two types of tests depending on if their scenario needs a real browser capable of execute Javascript or if they can run in a headless browser.&lt;br /&gt;
* Tests with Javascript requires interaction with a browser through a user simulation tool like Selenium or ZombieJS to be executed; see http://mink.behat.org/#different-browsers-drivers for all available drivers&lt;br /&gt;
* Test that does not requires Javascript are faster to run but can not test rich applications like Moodle&lt;br /&gt;
&lt;br /&gt;
In most of the cases a Javascript test would be more appropriate because most of the users uses Javascript-capable browsers, non-Javascript tests can be useful to ensure that Moodle maintains its functionality without Javascript enabled and to ensure there are no big issues, regressions or exceptions in general.&lt;br /&gt;
&lt;br /&gt;
=== Admin tool &amp;quot;Acceptance testing&amp;quot; ===&lt;br /&gt;
&lt;br /&gt;
There is an admin tool to run and ease the creation of acceptance tests. &lt;br /&gt;
* Web interface: The web interface allows you to list and filter the available steps definitions, a non-technical user can use this interface to write new features (admin/tool/behat/index.php)&lt;br /&gt;
* CLI: Command to enable and disable the test environment and to update the behat.yml file with the system tests and steps definitions (admin/tool/behat/cli/util.php and admin/tool/behat/cli/init.php for a quick start)&lt;br /&gt;
&lt;br /&gt;
[[File:Acceptance_testing_UI_2.5.png]]&lt;br /&gt;
&lt;br /&gt;
=== Available steps to create tests ===&lt;br /&gt;
There are behat libraries with tons of steps definitions to run all sort of processes and interactions with the browser, some of them overlaps Moodle-specific libraries and tests writers can be confused not only by this also by the amount of steps and vague or too technical steps descriptions. Moodle provides a set of steps definitions written in a common format to make tests writers life easier. New steps definitions must follow this guidelines: https://docs.moodle.org/dev/Acceptance_testing#Adding_steps_definitions&lt;br /&gt;
&lt;br /&gt;
=== Behat extension ===&lt;br /&gt;
A new Behat extension (https://github.com/moodlehq/moodle-behat-extension) has been created to maintain Behat and its dependencies as they comes from upstream.&lt;br /&gt;
&lt;br /&gt;
The aim of this extension is:&lt;br /&gt;
* Load features from multiple folders (Moodle subsystems and plugins)&lt;br /&gt;
* Load steps definitions from multiple folders and add them as subcontexts (Moodle subsystems and plugins)&lt;br /&gt;
* Return the available steps definitions in a more human-readable format without regexps&lt;br /&gt;
* Look for exceptions, debugging() calls, PHP error messages and other backtraces in Moodle&#039;s output&lt;br /&gt;
* Extend the Selenium2 behat driver to allow extra Selenium capabilities&lt;br /&gt;
* Add a new formatter method based on progress (the moodle default one) to display info about the moodle site being tested&lt;br /&gt;
&lt;br /&gt;
All the other particularities of this integration can managed playing with different Behat config parameters.&lt;br /&gt;
&lt;br /&gt;
[[Category:Behat]]&lt;br /&gt;
&lt;br /&gt;
[[es:Behat]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Backup_2.0_for_developers&amp;diff=50380</id>
		<title>Backup 2.0 for developers</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Backup_2.0_for_developers&amp;diff=50380"/>
		<updated>2016-06-06T07:52:46Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;{{Template:Backup 2.0}}{{Moodle_2.0}}{{Work in progress}}&lt;br /&gt;
&lt;br /&gt;
== Introduction ==&lt;br /&gt;
&lt;br /&gt;
This page tries to explain, from a development perspective, &#039;&#039;&#039;how to implement&#039;&#039;&#039; the backup feature for various Moodle 2.x plugins, mainly, modules and blocks. &lt;br /&gt;
&lt;br /&gt;
Note that, at the time of writing this, the backup &amp;amp; restore subsystem itself is &#039;&#039;&#039;under development&#039;&#039;&#039;, so still there are some missing bits, specially about the way to handle &#039;&#039;&#039;subplugins&#039;&#039;&#039; (question types, data fields...) under the new backup infrastructure, so any module using such artifacts, like data, assignment, quiz, workshop, aren&#039;t  good candidates right now. This will be addressed (and this Docs updated) once we have determined how each subplugin is expected to work (from a DB / backup perspective).&lt;br /&gt;
&lt;br /&gt;
Everything in backup &#039;&#039;&#039;is about tasks and steps&#039;&#039;&#039; (see [[Backup 2.0 general architecture|Backup 2.0 general architecture]] for more information), all them conforming one backup plan. Each module instance and each block instance will be backup by one backup task instance that is, basically, one collection of backup steps. How steps are organized within the task will dictate to the backup system what to do and in which order.&lt;br /&gt;
&lt;br /&gt;
Another important point is that Moodle backup 2.0, supports &#039;&#039;&#039;multiple backup formats&#039;&#039;&#039; (&amp;quot;moodle2&amp;quot;, &amp;quot;imscc&amp;quot;...) each one having its own tasks/steps, completely unrelated between them. In any case, for now, we are focusing all the explanations below in the &amp;quot;moodle2&amp;quot; format, that is the one required in order to keep any module/block &#039;&#039;&#039;transportable between Moodle instances&#039;&#039;&#039; without any loss of data. Surely, for the rest of formats, we&#039;ll end with other documents describing them, since each one can have its own particularities.&lt;br /&gt;
&lt;br /&gt;
Talking about backup steps we must differentiate &#039;&#039;&#039;two type of steps&#039;&#039;&#039;:&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;Execution steps&#039;&#039;&#039;: That, simply, execute arbitrary PHP code. They are useful to prepare different structures, create directories, whatever have to be done not involving the generation of XML files. Normally you won&#039;t need them.&lt;br /&gt;
* &#039;&#039;&#039;Structure steps&#039;&#039;&#039;: That, using one PHP API (detailed below) define completely the XML structure to be exported and its contents. Hopefully, &amp;quot;normal&amp;quot; modules only will have to use one step of this type in order to have the backup functionality 100% implemented.&lt;br /&gt;
&lt;br /&gt;
Said that, in the next steps we are going through all the steps necessary to create the backup of one simple module and one block, in order to get all the possibilities covered.&lt;br /&gt;
&lt;br /&gt;
== How to backup one module ==&lt;br /&gt;
&lt;br /&gt;
For this section, we have selected one simple module (choice) that requires practically all the backup &amp;quot;machinery&amp;quot; to be used, so it will get explained as we progress in the development. The only point not covered here are the &amp;quot;subplugin&amp;quot; facilities, covered later in a separate section.&lt;br /&gt;
&lt;br /&gt;
=== Prerequisites ===&lt;br /&gt;
&lt;br /&gt;
In order to achieve the backup implementation for the module, some prerequisites should be fulfilled.  They are default recommendations that are especially helpful while getting used to the backup process.&lt;br /&gt;
&lt;br /&gt;
# &#039;&#039;&#039;Learn about the module&#039;&#039;&#039;. If you aren&#039;t the creator of the module, spend some time playing with the module, creating and using it, exploring each one of its functionalities. By doing this you will end with some &amp;quot;real&amp;quot; data in the module instances that will be really useful when testing / debugging how the module backup is being generated.&lt;br /&gt;
# &#039;&#039;&#039;Draw one schema of the module&#039;&#039;&#039; DB structures. While you are playing with the module, look continuously to the DB, how records are saved and what the relationships are between the module&#039;s tables. Since a backup is, basically, one &amp;quot;selective dump&amp;quot; of those tables, knowing the maximum about them is highly recommended. At the end, you must end with one tree structure will be the basis for the generated XML file.&lt;br /&gt;
# &#039;&#039;&#039;Annotate which tables contain user-related info&#039;&#039;&#039; and which ones don&#039;t. One of the core functionalities that must be present on each module is the ability to include user related information or skip it, as you will need that information later.&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;Tip&#039;&#039;&#039;: If the module already existed before Moodle 2.0, it can be a &#039;&#039;&#039;good idea&#039;&#039;&#039; to look at its 1.9 backuplib.php file, since the structure is already defined there and can help to understand the organization better and, at the same time, &#039;&#039;&#039;keeping the XML structure as similar as possible&#039;&#039;&#039;, that will, definitively, &#039;&#039;&#039;make things easier&#039;&#039;&#039; when converting 1.9 backup files to the new backup 2.0 format.&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;Note&#039;&#039;&#039;: It&#039;s important to highlight that the structure schema, should be as stable as possible moving forward, because any change in the structure makes restore much more complex to implement. There aren&#039;t problems with adding/deleting fields, nor adding new elements to the structure. &#039;&#039;&#039;The structure (tree) itself must persist as stable as possible&#039;&#039;&#039;, so be careful when deciding it, as it will have implications on future maintenance.&lt;br /&gt;
&lt;br /&gt;
Applying these pre-requisites to our candidate module (choice), here it&#039;s the corresponding schema. We&#039;ll use it along the whole process.&lt;br /&gt;
&lt;br /&gt;
=== Schema ===&lt;br /&gt;
&lt;br /&gt;
In the schema, you must try to put as much information as possible, so that will produce the coding process later to be quicker and easier while keeping the final results free from errors and missing bits. So, once more, don&#039;t start coding immediately, instead spend some time with the requisites above, understanding how the module works and designing the final structure that represents it better.&lt;br /&gt;
&lt;br /&gt;
==== The (correct) candidate ====&lt;br /&gt;
&lt;br /&gt;
[[Image:Backup20 choice alt.png‎|left|Alternative choice backup structure]]&lt;br /&gt;
&lt;br /&gt;
The tree on the left shows the ER/DB structure of the choice module, where one choice have one or more options and each option is answered by users one or more times (note: ignore cardinality accuracy in the previous phrase).&lt;br /&gt;
&lt;br /&gt;
And that&#039;s the best schema representing the structure of the module, with each element properly nested so, we won&#039;t have any problem with restore since the order required by restore (1, 2, 3) are naturally given. &lt;br /&gt;
&lt;br /&gt;
Looks easy, cool, but continue reading… you will get surprised! :-)&amp;lt;br style=&amp;quot;clear: both&amp;quot; /&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==== The (chosen) candidate ====&lt;br /&gt;
&lt;br /&gt;
Instead we are going to use the (complete this time) diagram below. See the rationale about that after the image.&lt;br /&gt;
&lt;br /&gt;
[[Image:Backup20 choice.png‎|center|Used choice backup structure]]&lt;br /&gt;
&lt;br /&gt;
The main reason to use this tree (instead of the &amp;quot;correct&amp;quot; one) is that this is the structure that has been used by Moodle 1.9 backup since ages ago for the choice module and, of course have done its work ok. As commented above we must &#039;&#039;&#039;try to reduce the number of structural changes&#039;&#039;&#039; in one module backup in order to keep the restore operations working along the time (the same is applicable for the conversion of 1.9 backup files to the new 2.0 format). Finally, this is a good example about how one module &#039;&#039;&#039;can have different XML representations&#039;&#039;&#039; and we need to try to get that best one (this is not the case) on each case. So, once more, &#039;&#039;&#039;spending some time analyzing&#039;&#039;&#039; the activity is worth it.&lt;br /&gt;
&lt;br /&gt;
Let&#039;s analyze the schema with some detail:&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;Detecting user information&#039;&#039;&#039;: We must be able to define the entities (tables) in the diagram that are used to store user information. One of the core features of the backup subsystem since its early days have been the ability to produce backup with and without user information. So we need that info. Hence, the &amp;quot;no user info&amp;quot; in the choice and choice_options elements (they are configuration, user-independent), while the choice_answers is marked as &amp;quot;user info&amp;quot; (contains user&#039;s answers to the choice).&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;Determining the correct order of backup&#039;&#039;&#039;: This, while simple, is critical too (especially from a restore perspective). Since the restore reads progressively the xml file and performs actions in that order, we &#039;&#039;&#039;must guarantee that the &amp;quot;read order&amp;quot; is the correct&#039;&#039;&#039; one, fulfilling any possible dependency. Back to our schema it&#039;s clear that we need to backup the &amp;quot;choice&amp;quot; element at first, and then the &amp;quot;choice_options&amp;quot; and &amp;quot;choice_answers&amp;quot; ones. Moreover, the &amp;quot;choice_options&amp;quot; must be backup before &amp;quot;choice_answers&amp;quot;, since the later needs to save the values of the former (the &amp;quot;optionid&amp;quot; information). Note that, as commented some paragraphs above, the &amp;quot;correct&amp;quot; alternative really gave us that order information easily. Doesn&#039;t matter, since we have been able to establish it also in the &amp;quot;chosen&amp;quot; schema.&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;Attributes and elements&#039;&#039;&#039;: Now it&#039;s time to decide which fields will be considered attributes in the resulting XML file and which ones will be child elements (tags). The rule is simple: &#039;&#039;&#039;All the &amp;quot;id&amp;quot; fields must (should) be defined as attributes&#039;&#039;&#039;. Note this is just one arbitrary rule without much rationale behind it since, from a restore perspective, everything (attributes and child tags) will be handled in the same way (object attributes). So, in our schema, all the &amp;quot;id&amp;quot; fields have been marked as &amp;quot;attr&amp;quot;.&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;Not needed elements&#039;&#039;&#039;: If we have designed the schema properly, we&#039;ll find that some fields aren&#039;t necessary, since such information is already included in some parent element. In our schema, the field &amp;quot;choiceid&amp;quot;, pointing to the &amp;quot;choice-&amp;gt;id&amp;quot;, both in the options and in the answer elements, have been marked as &amp;quot;not needed&amp;quot; since their parent &amp;quot;choice&amp;quot; already contains it. Something similar happens with the &amp;quot;course&amp;quot; field in the choice element. It doesn&#039;t need to be included in the backup file since something above it (course element, outside the module scope) already has it defined. Finally, there is one element marked as &amp;quot;needed&amp;quot; that shows us, once more, that the schema we are using is not the best. Since &amp;quot;choice_answers&amp;quot; isn&#039;t nested under &amp;quot;choice_options&amp;quot;, we must keep the &amp;quot;choice_answers-&amp;gt;optionid&amp;quot; field in the backup, or restore won&#039;t know to which option each answer belongs to. Instead, with the &amp;quot;correct&amp;quot; schema, where answers are nested under options, that field is not needed. Summarizing, &#039;&#039;&#039;any field except those already existing in parent elements must be included in backup&#039;&#039;&#039;.&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;Detecting file areas used by the module&#039;&#039;&#039;: Along the module we can be using various file areas in different elements and fields. We need to know exactly which file area is handled by which element and the (optional) itemid information used for that file area. In general, &#039;&#039;&#039;anything being one text field, or anything looking like one attachment&#039;&#039;&#039; has high chances to have one (hidden) file area associated. In our schema, we have one file area (choice_intro) corresponding to the introduction of the module and available to put any images or whatever in that field. Also, in general, all the &amp;quot;xxx_intro&amp;quot; file areas use to have no itemid, since the module&#039;s context is enough to define them without ambiguities. So, we mark the choice-&amp;gt;intro as &amp;quot;choice_intro&amp;quot; file area and &amp;quot;no itemid&amp;quot;). From our expertise playing with the module we know there are no more file areas associated with this module.&lt;br /&gt;
&lt;br /&gt;
* &amp;lt;span id=&amp;quot;annotate_is_important&amp;quot;&amp;gt;&#039;&#039;&#039;Annotating some important bits&#039;&#039;&#039;:&amp;lt;/span&amp;gt; Due to the modularity of the backup and in order to know exactly which information must be saved (because it&#039;s used) and which one can be skipped, &#039;&#039;&#039;it&#039;s important to annotate some important elements along the whole backup&#039;&#039;&#039; process. So, back to our schema, we have marked the &amp;quot;choice_answer-&amp;gt;userid&amp;quot; field as &amp;quot;annotation&amp;quot; (so backup will, automatically, add all the information for that user). Here it&#039;s the list of elements that we must not forget to annotate (or we could end with non-restorable backups). Note that we must, always, be annotating &amp;quot;id&amp;quot; values and not other types of data:&lt;br /&gt;
** &#039;&#039;&#039;user&#039;&#039;&#039;: Any field pointing to one user-&amp;gt;id present along the schema (as said above, our schema has one).&lt;br /&gt;
** &#039;&#039;&#039;grouping&#039;&#039;&#039;: Any field pointing to one grouping-&amp;gt;id&lt;br /&gt;
** &#039;&#039;&#039;group&#039;&#039;&#039;: Any field pointing to one group-&amp;gt;id&lt;br /&gt;
** &#039;&#039;&#039;role&#039;&#039;&#039;: Any field pointing to one role-&amp;gt;id&lt;br /&gt;
** &#039;&#039;&#039;scale&#039;&#039;&#039;: Any field pointing to one scale-&amp;gt;id&lt;br /&gt;
** &#039;&#039;&#039;outcome&#039;&#039;&#039;: Any field pointing to one outcome-&amp;gt;id&lt;br /&gt;
&lt;br /&gt;
And this is all the information we need to know, before starting to code. Surely, once used to backup and restore, you will be able to start coding sooner, but &#039;&#039;&#039;don&#039;t forget about the importance of choosing one good and stable structure&#039;&#039;&#039; before anything else. It&#039;s really the critical part of any module&#039;s backup.&lt;br /&gt;
&lt;br /&gt;
That said, let&#039;s see how to code all this information in order to get one cool backup for our beloved module.&lt;br /&gt;
&lt;br /&gt;
=== Coding ===&lt;br /&gt;
&lt;br /&gt;
Already here? Have you read, at least once, all the explanations and comments in the previous sections? Yes? Sure? I can imagine it&#039;s hard to read so much text, just imagine how hard is to write it! Go, go, go and read it!&lt;br /&gt;
&lt;br /&gt;
Jokes aside, in this section we are going to code the module&#039;s (choice, in our example) backup code. As you&#039;ll see soon, all the information gathered in previous steps is really important and will make the coding task easier and less prone to errors.&lt;br /&gt;
&lt;br /&gt;
==== Setting up the environment ====&lt;br /&gt;
&lt;br /&gt;
By default, any backup operation will end with one .zip file stored in some course / section / activity area. That means that, each time you execute one backup, you&#039;ll need to go across the web interface to that file area, download the generated .zip file, uncompress it, and then see how things have been generated. And you will be executing a bunch of backup files until you get everything working as expected, so the whole develop / test process isn&#039;t really &amp;quot;agile&amp;quot;. To improve things a bit, there is one $CFG setting that you should consider using &#039;&#039;&#039;in your development environment&#039;&#039;&#039;. Just put this in your config.php:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$CFG-&amp;gt;keeptempdirectoriesonbackup = true;&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
With this setting enabled, backup won&#039;t delete the temporary directory where everything is calculated, so you will be able to access to it directly, skipping all the ui / download / unzip steps above. Those temp directories are under $CFG-&amp;gt;dataroot/temp/backup. Note that, for each backup invocation, a new directory is created.&lt;br /&gt;
&lt;br /&gt;
Also, in order to be able to execute backups quickly (instead of navigating along the UI), you can, simply, put one script like this in your $CFG-&amp;gt;dirroot directory:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
&amp;lt;?php&lt;br /&gt;
&lt;br /&gt;
define(&#039;CLI_SCRIPT&#039;, 1);&lt;br /&gt;
require_once(&#039;config.php&#039;);&lt;br /&gt;
require_once($CFG-&amp;gt;dirroot . &#039;/backup/util/includes/backup_includes.php&#039;);&lt;br /&gt;
&lt;br /&gt;
$course_module_to_backup = XX; // Set this to one existing choice cmid in your dev site&lt;br /&gt;
$user_doing_the_backup   = YY; // Set this to the id of your admin accouun&lt;br /&gt;
&lt;br /&gt;
$bc = new backup_controller(backup::TYPE_1ACTIVITY, $course_module_to_backup, backup::FORMAT_MOODLE,&lt;br /&gt;
                            backup::INTERACTIVE_NO, backup::MODE_GENERAL, $user_doing_the_backup);&lt;br /&gt;
$bc-&amp;gt;execute_plan();&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
just set proper values for XX and YY above and execute it from the command line. If you get one error about one not found class (with the name of your module) everything is ok.&lt;br /&gt;
&lt;br /&gt;
==== Required stuff ====&lt;br /&gt;
&lt;br /&gt;
The first thing you need to make is to, explicitly, declare that your module (choice in our example) is going to support the MOODLE2 backup format, to do so, you need to go to mod/choice/lib.php and, in the choice_supports() function add one new feature by adding this line:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
case FEATURE_BACKUP_MOODLE2:          return true;&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
If you execute another backup (with the script provided above, you will continue getting one error, since we haven&#039;t still coded anything related to backup, that&#039;s ok.&lt;br /&gt;
&lt;br /&gt;
Next step is to create the directory where all the backup code for the choice module will be. Just create the directory(s) mod/choice/backup/moodle2&lt;br /&gt;
&lt;br /&gt;
At this point, we have all the required stuff ready and all the pending tasks will be done under that recently created directory.&lt;br /&gt;
&lt;br /&gt;
==== Settings, Steps and Tasks ====&lt;br /&gt;
&lt;br /&gt;
In the introduction of the tutorial, we commented about backup being structured into tasks, each one being one collection of steps (and potentially using some custom settings). Those are, exactly, the objects that we need to create to achieve the backup functionality in our module.&lt;br /&gt;
&lt;br /&gt;
First of all, lets&#039; create the settings file, where all the custom settings to be used by our module will be defined and implemented. It must be named &#039;&#039;&#039;mod/choice/backup/moodle2/backup_choice_settingslib.php&#039;&#039;&#039; and their contents are really meaningful:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
&amp;lt;?php&lt;br /&gt;
&lt;br /&gt;
// This file is part of Moodle - http://moodle.org/&lt;br /&gt;
//&lt;br /&gt;
// Moodle is free software: you can redistribute it and/or modify&lt;br /&gt;
// it under the terms of the GNU General Public License as published by&lt;br /&gt;
// the Free Software Foundation, either version 3 of the License, or&lt;br /&gt;
// (at your option) any later version.&lt;br /&gt;
//&lt;br /&gt;
// Moodle is distributed in the hope that it will be useful,&lt;br /&gt;
// but WITHOUT ANY WARRANTY; without even the implied warranty of&lt;br /&gt;
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the&lt;br /&gt;
// GNU General Public License for more details.&lt;br /&gt;
//&lt;br /&gt;
// You should have received a copy of the GNU General Public License&lt;br /&gt;
// along with Moodle.  If not, see &amp;lt;http://www.gnu.org/licenses/&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
/**&lt;br /&gt;
 * @package moodlecore&lt;br /&gt;
 * @subpackage backup-moodle2&lt;br /&gt;
 * @copyright 2010 onwards YOUR_NAME_GOES_HERE {@link YOUR_URL_GOES_HERE}&lt;br /&gt;
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later&lt;br /&gt;
 */&lt;br /&gt;
&lt;br /&gt;
 // This activity has not particular settings but the inherited from the generic&lt;br /&gt;
 // backup_activity_task so here there isn&#039;t any class definition, like the ones&lt;br /&gt;
 // existing in /backup/moodle2/backup_settingslib.php (activities section)&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Looks simple, isn&#039;t it? Nothing but a few comments. This is looking really easy. For now, we aren&#039;t going to introduce any custom setting for any module, only the &amp;quot;core activity settings&amp;quot; will be used. Once backup and Moodle 2.0 is stable we can start analyzing useful settings to customize how the module&#039;s backup is performed. For now, just leave it blank, please. In fact, if it&#039;s empty,&#039;&#039;&#039; you can safely not create it&#039;&#039;&#039; at all. It&#039;s here just for explanation purposes.&lt;br /&gt;
&lt;br /&gt;
Side note: To save some space, we only will be showing the © message/license in the code above. Just add it to each file created.&lt;br /&gt;
&lt;br /&gt;
Now we are going to create the steps file, where all the steps to be executed by our backup activity task will be defined and implemented. It must be named &#039;&#039;&#039;mod/choice/backup/moodle2/backup_choice_stepslib.php&#039;&#039;&#039; and their contents are these:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
&amp;lt;?php&lt;br /&gt;
&lt;br /&gt;
/**&lt;br /&gt;
 * Define all the backup steps that will be used by the backup_choice_activity_task&lt;br /&gt;
 */&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Yes, it&#039;s another empty file. No worries we&#039;ll fill it later.&lt;br /&gt;
&lt;br /&gt;
Finally we need to create the task file, where our just created settings and steps files will be included and used. It must be named &#039;&#039;&#039;mod/choice/backup/moodle2/backup_choice_activity_task.class.php&#039;&#039;&#039; and their contents are these:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
&amp;lt;?php&lt;br /&gt;
&lt;br /&gt;
require_once($CFG-&amp;gt;dirroot . &#039;/mod/choice/backup/moodle2/backup_choice_stepslib.php&#039;); // Because it exists (must)&lt;br /&gt;
require_once($CFG-&amp;gt;dirroot . &#039;/mod/choice/backup/moodle2/backup_choice_settingslib.php&#039;); // Because it exists (optional)&lt;br /&gt;
&lt;br /&gt;
/**&lt;br /&gt;
 * choice backup task that provides all the settings and steps to perform one&lt;br /&gt;
 * complete backup of the activity&lt;br /&gt;
 */&lt;br /&gt;
class backup_choice_activity_task extends backup_activity_task {&lt;br /&gt;
&lt;br /&gt;
    /**&lt;br /&gt;
     * Define (add) particular settings this activity can have&lt;br /&gt;
     */&lt;br /&gt;
    protected function define_my_settings() {&lt;br /&gt;
        // No particular settings for this activity&lt;br /&gt;
    }&lt;br /&gt;
&lt;br /&gt;
    /**&lt;br /&gt;
     * Define (add) particular steps this activity can have&lt;br /&gt;
     */&lt;br /&gt;
    protected function define_my_steps() {&lt;br /&gt;
        // Choice only has one structure step&lt;br /&gt;
    }&lt;br /&gt;
&lt;br /&gt;
    /**&lt;br /&gt;
     * Code the transformations to perform in the activity in&lt;br /&gt;
     * order to get transportable (encoded) links&lt;br /&gt;
     */&lt;br /&gt;
    static public function encode_content_links($content) {&lt;br /&gt;
        return $content;&lt;br /&gt;
    }&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This is the main file (class) of the choice backup and it will be used to define any setting (define_my_settings()  method) and any step (define_my_steps() method) to be executed in the backup process. It also contains one 3rd method (encode_content_links($content)) that will allow manually URLs pointing to the choice to be properly converted when the choice is moved to other site / course using the backup / restore functionality.&lt;br /&gt;
&lt;br /&gt;
As you see, for now, the three required methods are doing nothing. Just execute the backup again. Wow, no errors anymore. We have already fulfilled all the minimum coding needs in order to have the choice backup working. &lt;br /&gt;
&lt;br /&gt;
Now you should go to your $CFG-&amp;gt;dataroot/temp/backup/xxxx directory (the more recent) and spend some time looking what has been created under the activities/choice_XX directory. There is already a lot of stuff that backup has generated for you: comments, blocks, logs, grades, module info, roles... some of them empty and others already showing real information.&lt;br /&gt;
&lt;br /&gt;
In any case, now, we need to add one important file there, the &amp;quot;choice.xml&amp;quot; where the real information for your module will be present, following the specs given by the schema we decided some sections above.&lt;br /&gt;
&lt;br /&gt;
So, let&#039;s go, it&#039;s time to create our choice structure step. To do so, we edit the &#039;&#039;&#039;mod/choice/backup/moodle2/backup_choice_stepslib.php&#039;&#039;&#039; file and add this code after the existing comments:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
/**&lt;br /&gt;
 * Define the complete choice structure for backup, with file and id annotations&lt;br /&gt;
 */     &lt;br /&gt;
class backup_choice_activity_structure_step extends backup_activity_structure_step {&lt;br /&gt;
&lt;br /&gt;
    protected function define_structure() {&lt;br /&gt;
&lt;br /&gt;
        // To know if we are including userinfo&lt;br /&gt;
        $userinfo = $this-&amp;gt;get_setting_value(&#039;userinfo&#039;);&lt;br /&gt;
&lt;br /&gt;
        // Define each element separated&lt;br /&gt;
&lt;br /&gt;
        // Build the tree&lt;br /&gt;
&lt;br /&gt;
        // Define sources&lt;br /&gt;
&lt;br /&gt;
        // Define id annotations&lt;br /&gt;
&lt;br /&gt;
        // Define file annotations&lt;br /&gt;
&lt;br /&gt;
        // Return the root element (choice), wrapped into standard activity structure&lt;br /&gt;
&lt;br /&gt;
    }&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
So, we have defined one structure step that will be the responsible, using one PHP API to provide backup with all the information needed to generate the choice.xml file. Now, go back to the task file and add these contents in the define_my_steps() methods:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
        $this-&amp;gt;add_step(new backup_choice_activity_structure_step(&#039;choice_structure&#039;, &#039;choice.xml&#039;));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
That way, our choice task knows it must execute one new step, the one involving the generation of the choice.xml file. Let&#039;s execute one new backup and see results.You should be getting one new error with something like that &amp;quot;backup_structure_step_wrong_structure&amp;quot;. It means that everything is ok up to now, the task has tried to execute the structure step, but this is not properly defined.&lt;br /&gt;
&lt;br /&gt;
===== Defining each element =====&lt;br /&gt;
&lt;br /&gt;
So, next step is about to define the choice structure. Going back to our step, under the &#039;&#039;// Define each element separate&#039;&#039; comment we&#039;ll add this code:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
        $choice = new backup_nested_element(&#039;choice&#039;, array(&#039;id&#039;), array(&lt;br /&gt;
            &#039;name&#039;, &#039;intro&#039;, &#039;introformat&#039;, &#039;publish&#039;,&lt;br /&gt;
            &#039;showresults&#039;, &#039;display&#039;, &#039;allowupdate&#039;, &#039;allowunanswered&#039;,&lt;br /&gt;
            &#039;limitanswers&#039;, &#039;timeopen&#039;, &#039;timeclose&#039;, &#039;timemodified&#039;));&lt;br /&gt;
&lt;br /&gt;
        $options = new backup_nested_element(&#039;options&#039;);&lt;br /&gt;
&lt;br /&gt;
        $option = new backup_nested_element(&#039;option&#039;, array(&#039;id&#039;), array(&lt;br /&gt;
            &#039;text&#039;, &#039;maxanswers&#039;, &#039;timemodified&#039;));&lt;br /&gt;
&lt;br /&gt;
        $answers = new backup_nested_element(&#039;answers&#039;);&lt;br /&gt;
&lt;br /&gt;
        $answer = new backup_nested_element(&#039;answer&#039;, array(&#039;id&#039;), array(&lt;br /&gt;
            &#039;userid&#039;, &#039;optionid&#039;, &#039;timemodified&#039;));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
===== Return the root element =====&lt;br /&gt;
&lt;br /&gt;
And also, in order to get it working, let&#039;s define the return element, so, after the &#039;&#039;// Return the root element&#039;&#039; comment, add this code:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
        return $this-&amp;gt;prepare_activity_structure($choice);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Now we can execute the backup again and, as long as we have already defined the root element of the module, should have now one choice.xml file created (without proper contents but must be there).&lt;br /&gt;
&lt;br /&gt;
About the code above, all we have done is to define, separately each element that will be part of the choice.xml file. Special note about the $options and $answers elements. Since Moodle 1.9 we use to enclose real elements (the singular ones) inside one extra plural element, hence we create them here (as empty elements without attributes nor child tags). About the rest (the singular ones) we use 3 params in the instantiation:&lt;br /&gt;
* The name of the element&lt;br /&gt;
* One array of attributes of the element&lt;br /&gt;
* One array of child tags (fields) of the element.&lt;br /&gt;
And we include all the fields that previously we had defined in our schema &#039;&#039;&#039;but&#039;&#039;&#039; the ones marked as &#039;&#039;&#039;not needed&#039;&#039;&#039;.&lt;br /&gt;
&lt;br /&gt;
===== Building the tree =====&lt;br /&gt;
&lt;br /&gt;
Now it&#039;s time to declare the relations between all those elements, so, after the &#039;&#039;// Build the tree&#039;&#039; comment we&#039;ll add this code:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
        $choice-&amp;gt;add_child($options);&lt;br /&gt;
        $options-&amp;gt;add_child($option);&lt;br /&gt;
&lt;br /&gt;
        $choice-&amp;gt;add_child($answers);&lt;br /&gt;
        $answers-&amp;gt;add_child($answer);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Self explanatory, using $choice as root element, we define the whole tree using the add_child() method. And, of course, we respect &#039;&#039;&#039;the order&#039;&#039;&#039; that we had decided, so $options will be &#039;&#039;&#039;physically&#039;&#039;&#039; before $answers in the tree (and in the generated XML).&lt;br /&gt;
&lt;br /&gt;
===== Defining the sources =====&lt;br /&gt;
&lt;br /&gt;
After this, it&#039;s the moment to instruct our tree about how to fetch information from DB in order to generate the choice.xml file, so after the &#039;&#039;// Define sources&#039;&#039; comment, we&#039;ll add this code:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
        $choice-&amp;gt;set_source_table(&#039;choice&#039;, array(&#039;id&#039; =&amp;gt; backup::VAR_ACTIVITYID));&lt;br /&gt;
&lt;br /&gt;
        $option-&amp;gt;set_source_sql(&#039;&lt;br /&gt;
            SELECT *&lt;br /&gt;
              FROM {choice_options}&lt;br /&gt;
             WHERE choiceid = ?&#039;,&lt;br /&gt;
            array(backup::VAR_PARENTID));&lt;br /&gt;
&lt;br /&gt;
        // All the rest of elements only happen if we are including user info&lt;br /&gt;
        if ($userinfo) {&lt;br /&gt;
            $answer-&amp;gt;set_source_table(&#039;choice_answers&#039;, array(&#039;choiceid&#039; =&amp;gt; &#039;../../id&#039;));&lt;br /&gt;
        }&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
So we define the source for the $choice element as the information present in the &#039;choice&#039; table for the id that is being backup (backup::VAR_ACTIVITYID). Or we define the source for the $option element like one SQL (could have been one table too, just to show more possibilities of the API, using the parent (the choice one) as value for the query (backup::VAR_PARENTID).&lt;br /&gt;
&lt;br /&gt;
And finally, conditionally, if user information is going to be included, we define the source for the $answer (note we had already annotated in our schema that this element was dependent of that). &lt;br /&gt;
&lt;br /&gt;
And we define the source condition as having the &#039;choiceid&#039; field matching the value of the &#039;id&#039; field two levels above (../../id). If you follow the tree created in the previous code section, that&#039;s exactly the choice-&amp;gt;id (remember we have introduced one extra level (the plural one between the &#039;choice&#039; and the &#039;answer&#039; singular elements). Note this is 100% equivalent to use backup::VAR_PARENTID (as we have done in the $option source) just used to show possibilities of the API.&lt;br /&gt;
&lt;br /&gt;
Summarizing, with the API, we have these 3 method for defining sources:&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;set_source_table($tablename, array $conditions)&#039;&#039;&#039;: When the information is get straight from one table (vast majority of cases in backup)&lt;br /&gt;
* &#039;&#039;&#039;set_source_sql($sql, array $params)&#039;&#039;&#039;: When the information doesn&#039;t map one table directly and we need something more complex&lt;br /&gt;
* &#039;&#039;&#039;set_source_array($array)&#039;&#039;&#039;: When we have some fixed information to backup. Not really useful in nested information, but used by core here and there.&lt;br /&gt;
&lt;br /&gt;
Note that both the $conditions and $params above only accept one limited number of constants or values (not all available in all backups!), mainly:&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;backup::VAR_COURSEID&#039;&#039;&#039;: The id of the course this activity belongs to / the course id being backup&lt;br /&gt;
* &#039;&#039;&#039;backup::VAR_SECTIONID&#039;&#039;&#039;: The id of the section this activity belongs to / the section id being backup&lt;br /&gt;
* &#039;&#039;&#039;backup::VAR_ACTIVITYID&#039;&#039;&#039;: The id of the activity id being backup&lt;br /&gt;
* &#039;&#039;&#039;backup::VAR_MODID&#039;&#039;&#039;: The id of the course_module being backup&lt;br /&gt;
* &#039;&#039;&#039;backup::VAR_MODULENAME&#039;&#039;&#039;: The name of the module being backup&lt;br /&gt;
* &#039;&#039;&#039;backup::VAR_BLOCKID&#039;&#039;&#039;: The id of the block being backup&lt;br /&gt;
* &#039;&#039;&#039;backup::VAR_BLOCKNAME&#039;&#039;&#039;: The name of the block being backup&lt;br /&gt;
* &#039;&#039;&#039;backup::VAR_CONTEXTID&#039;&#039;&#039;: The context id of the activity / course being backup&lt;br /&gt;
* &#039;&#039;&#039;backup::VAR_PARENTID&#039;&#039;&#039;: The value of the first parent id found in the structure.&lt;br /&gt;
* &#039;&#039;&#039;../some/path/to/parent&#039;&#039;&#039;: To manually point to other value of any parent.&lt;br /&gt;
&lt;br /&gt;
Is important to note that, in 99% of the case we should be using, exclusively, some of the constants above, and backup, automatically will handle them properly. In case we have any other condition or param to be added like, for example, the number 23, or the string &#039;user&#039;, we cannot add them directly, but enclose them with the helper &#039;&#039;&#039;backup_helper::is_sqlparam(23)&#039;&#039;&#039; or &#039;&#039;&#039;backup_helper::is_sqlparam(&#039;user&#039;)&#039;&#039;&#039;. That way backup will know they are raw SQL params not needing any special handling, like the constants above.&lt;br /&gt;
&lt;br /&gt;
Well, now it&#039;s time to run backup again and take a look to our activities/choice_XX/choice.xml file. Now everything should be there, properly nested, the choice, the options and the answers. We are really near finishing now.&lt;br /&gt;
&lt;br /&gt;
===== Annotating IDs =====&lt;br /&gt;
&lt;br /&gt;
Now it&#039;s time to perform all the annotations that we had already detected in our analysis of the module. So, after the &#039;&#039;// Define id annotations&#039;&#039; comment we&#039;ll be adding:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
        $answer-&amp;gt;annotate_ids(&#039;user&#039;, &#039;userid&#039;);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
It simply means, annotate for each $answer element, the value of the &#039;userid&#039; field as one &#039;user&#039; to be backup. In other words we are instructing backup that there is one new user to include later, when generating the users information and, at the same time, we are determining that those users are needed for the choice XX, so, if on restore we decide to skip that choice and such user isn&#039;t necessary for any other module / subsystem, it won&#039;t be restored. All this &amp;quot;uses&amp;quot; information is handled by the &amp;quot;inforef.xml&amp;quot; files within each activity backup, just in case you&#039;re interested to take a look to them. Else, just consider them, &amp;quot;dark magic&amp;quot;.&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;Note&#039;&#039;&#039;: If you&#039;re not sure about which elements must be annotated, review [[Backup 2.0 for developers #annotate_is_important|&amp;quot;Annotating some important bits&amp;quot;]] above for details about &#039;&#039;&#039;must-be-done&#039;&#039;&#039; annotations.&lt;br /&gt;
&lt;br /&gt;
===== Annotating files =====&lt;br /&gt;
&lt;br /&gt;
And, finally, reviewing our elaborate and detailed schema, the last thing we need to take care of are the file areas used, so, after the &#039;&#039;// Define file annotations&#039;&#039; comment we&#039;ll add:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
        $choice-&amp;gt;annotate_files(&#039;mod_choice&#039;, &#039;intro&#039;, null); // This file area does not have an itemid&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
That means that, within the $choice element we have one file area in use, of course belonging to the &#039;mod_choice&#039; component (where all the choice module files belong to), named &#039;intro&#039; and not using itemid (null). Note that, since it is possible to have multiple file areas in the same element (table), you may end up having multiple calls to the annotate_files() method, one for each filearea to be added to backup. The third parameter, if it is needed, must be the name of one of the attributes or fields of the $choice element (usually, in the vast majority of cases, the &#039;id&#039; of the element), otherwise we&#039;ll use null.&lt;br /&gt;
&lt;br /&gt;
=== One encoded wor(l)d ===&lt;br /&gt;
&lt;br /&gt;
Already out from the step definition, that should be working ok now, with the choice.xml file being generated and all the annotations being processed and added to the inforef.xml file, there is one more point to fulfill before considering choice&#039;s backup 100% finished.&lt;br /&gt;
&lt;br /&gt;
And it&#039;s about how to provide the ability to transform some links to the choice module when the backup file is restored into another server / course. That is automatically handled by a two-step approach:&lt;br /&gt;
# On backup, we transform as many well-know URLs as possible to one encoded form.&lt;br /&gt;
# On restore, we transform those encoded URLS back to their original form, but pointing to their new targets.&lt;br /&gt;
&lt;br /&gt;
So, in backup, we must provide services for the point 1 above, and that is done by adding some &amp;quot;encoding&amp;quot; conversions to the &#039;&#039;&#039;encode_content_links()&#039;&#039;&#039; method in our &#039;&#039;&#039;backup_choice_activity_task&#039;&#039;&#039;. So, define it to look like this&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
    /**&lt;br /&gt;
     * Code the transformations to perform in the activity in&lt;br /&gt;
     * order to get transportable (encoded) links&lt;br /&gt;
     */&lt;br /&gt;
    static public function encode_content_links($content) {&lt;br /&gt;
        global $CFG;&lt;br /&gt;
&lt;br /&gt;
        $base = preg_quote($CFG-&amp;gt;wwwroot,&amp;quot;/&amp;quot;);&lt;br /&gt;
&lt;br /&gt;
        // Link to the list of choices&lt;br /&gt;
        $search=&amp;quot;/(&amp;quot;.$base.&amp;quot;\/mod\/choice\/index.php\?id\=)([0-9]+)/&amp;quot;;&lt;br /&gt;
        $content= preg_replace($search, &#039;$@CHOICEINDEX*$2@$&#039;, $content);&lt;br /&gt;
&lt;br /&gt;
        // Link to choice view by moduleid&lt;br /&gt;
        $search=&amp;quot;/(&amp;quot;.$base.&amp;quot;\/mod\/choice\/view.php\?id\=)([0-9]+)/&amp;quot;;&lt;br /&gt;
        $content= preg_replace($search, &#039;$@CHOICEVIEWBYID*$2@$&#039;, $content);&lt;br /&gt;
&lt;br /&gt;
        return $content;&lt;br /&gt;
    }&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Básically, it gets any URL (manually written) in any content of the backup being generated and transform some (well-known) URLs to one encoded alternative. In this case we are encoding:&lt;br /&gt;
* Any URL pointing to the list of choices in a course == is changed to ==&amp;gt; $@CHOICEINDEX*XX@$&lt;br /&gt;
* Any URL pointing to one exact choice == is changed to ==&amp;gt; $@CHOICEVIEWBYID*YY@$&lt;br /&gt;
&lt;br /&gt;
In restore, well have the opposite conversions happening, replacing the XX and YY above to their new equivalents, so those links will be transportable via backup/restore without any need to edit them manually later.&lt;br /&gt;
&lt;br /&gt;
Tip: Don&#039;t forget to look to the module&#039;s 1.9 backup code, as far as there you&#039;ll find which conversions must be considered to be added here.&lt;br /&gt;
&lt;br /&gt;
=== Final notes ===&lt;br /&gt;
&lt;br /&gt;
* Don&#039;t get stressed, it&#039;s really more difficult / longer to explain than to do it. 100% guaranteed, else we&#039;ll return your money. :-P&lt;br /&gt;
* If you&#039;ve become lost, or your code is not working properly, you always can [https://github.com/moodle/moodle/tree/master/mod/choice/backup/moodle2 see the complete choice working code in git]. Or, alternatively, look to other well known modules, like [https://github.com/moodle/moodle/blob/master/mod/forum/backup/moodle2/ forum] or also the [https://github.com/moodle/moodle/blob/master/backup/moodle2/backup_stepslib.php big core library of steps], where you will find all sort of uses of the API.&lt;br /&gt;
* If you are going to implement backup for module XXXX, just copy this document, replace any &amp;quot;choice&amp;quot; occurrence within it by XXXX and follow it from the beginning to the end. Should work.&lt;br /&gt;
* If the module already existed in Moodle 1.x, try to follow the same structure if possible, that will make things easier for restore / conversion.&lt;br /&gt;
* Right now there are some pending tasks related with different exceptions that will be thrown if you code something wrongly (bad nesting, incorrect field names, bad constant/sql param uses...) and how they are shown. Fix for that will be coming soon.&lt;br /&gt;
* Also, as stated at the beginning of this tutorial, we are still missing &amp;quot;subplugins&amp;quot; final support in modules, so try to avoid implementing backup on them for now. Once ready, there will be one new section in this document about them.&lt;br /&gt;
* Any question / improvement / comment, feel free to contact with Moodle HQ, better if using the Tracker or, alternatively, forums / email / direct contact with your very-best-developer-friend. Note this is version x.0 (dot zero) of the backup API, so sure there are possibilities to improve it along the time.&lt;br /&gt;
&lt;br /&gt;
== Other components that can be backed up ==&lt;br /&gt;
&lt;br /&gt;
Most plugins which can be added to a course can also include data in a course backup. Some examples:&lt;br /&gt;
&lt;br /&gt;
* Course formats&lt;br /&gt;
* Themes: [[ Backup 2.0 theme data| Backup 2.0 theme data]]&lt;br /&gt;
* Plagiarism plugins&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=lib/formslib.php_Form_Definition&amp;diff=49292</id>
		<title>lib/formslib.php Form Definition</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=lib/formslib.php_Form_Definition&amp;diff=49292"/>
		<updated>2016-01-26T19:54:35Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: /* radio */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;{{Formslib}}&lt;br /&gt;
== &#039;&#039;definition()&#039;&#039; ==&lt;br /&gt;
&lt;br /&gt;
The definition of the elements to be included in the form, their &#039;types&#039; (PARAM_*), helpbuttons included, etc. is all included in a function you must define in your class.&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;definition()&#039;&#039; is used to define the elements in the form and &#039;&#039;&#039;this definition will be used for validating data submitted as well as for printing the form.&#039;&#039;&#039; For select and checkbox type elements only data that could have been selected will be allowed. And only data that corresponds to a form element in the definition will be accepted as submitted data.&lt;br /&gt;
&lt;br /&gt;
The &#039;&#039;definition()&#039;&#039; should include all elements that are going to be used on form, some elements may be removed or tweaked later in &#039;&#039;definition_after_data()&#039;&#039;. Please do not create conditional elements in &#039;&#039;definition()&#039;&#039;, the definition() should not directly depend on the submitted data.&lt;br /&gt;
&lt;br /&gt;
Note that the definition function is called when the form class is instantiated. There is no option to (say) manipulate data in the class (that may affect the rendering of the form) between instantiating the form and calling any other methods. &lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
require_once(&amp;quot;$CFG-&amp;gt;libdir/formslib.php&amp;quot;);&lt;br /&gt;
&lt;br /&gt;
class simplehtml_form extends moodleform {&lt;br /&gt;
&lt;br /&gt;
    function definition() {&lt;br /&gt;
        global $CFG;&lt;br /&gt;
       &lt;br /&gt;
        $mform = $this-&amp;gt;_form; // Don&#039;t forget the underscore! &lt;br /&gt;
&lt;br /&gt;
        $mform-&amp;gt;addElement()... // Add elements to your form&lt;br /&gt;
            ...&lt;br /&gt;
    }                           // Close the function&lt;br /&gt;
}                               // Close the class&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
===Passing parameters to the Form===&lt;br /&gt;
&lt;br /&gt;
The constructor for &#039;&#039;moodleform&#039;&#039; allows a number of parameters including one (&#039;&#039;$customdata&#039;&#039;) to permit an array of arbitrary data to be passed to your form. &lt;br /&gt;
&lt;br /&gt;
For example, you can pass the data &amp;quot;$email&amp;quot; and &amp;quot;$username&amp;quot; to the Form&#039;s class for use inside (say) the definition.&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
...&lt;br /&gt;
 $mform_simple = new simplehtml_form( null, array(&#039;email&#039;=&amp;gt;$email, &#039;username&#039;=&amp;gt;$username ) );&lt;br /&gt;
...&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
(the first parameter is $action, &#039;&#039;null&#039;&#039; will case the form action to be determined automatically)&lt;br /&gt;
&lt;br /&gt;
Secondly, inside the form definition you can use those parameters to set the default values to some of the form&#039;s fields&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
...&lt;br /&gt;
 $mform-&amp;gt;addElement(&#039;text&#039;, &#039;email&#039;, get_string(&#039;email&#039;), &#039;maxlength=&amp;quot;100&amp;quot; size=&amp;quot;25&amp;quot; &#039;);&lt;br /&gt;
 $mform-&amp;gt;setType(&#039;email&#039;, PARAM_NOTAGS);&lt;br /&gt;
 $mform-&amp;gt;addRule(&#039;email&#039;, get_string(&#039;missingemail&#039;), &#039;required&#039;, null, &#039;server&#039;);&lt;br /&gt;
 // Set default value by using a passed parameter&lt;br /&gt;
 $mform-&amp;gt;setDefault(&#039;email&#039;,$this-&amp;gt;_customdata[&#039;email&#039;]);&lt;br /&gt;
...&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==Use Fieldsets to group Form Elements==&lt;br /&gt;
&lt;br /&gt;
You use code like this to open a fieldset with a &#039;&#039;legend&#039;&#039;. &amp;lt;br /&amp;gt;&lt;br /&gt;
(&#039;&#039;&#039;Note&#039;&#039;&#039;: Some themes turn off legends on admin setting pages by using CSS: &amp;lt;nowiki&amp;gt;#adminsettings legend {display:none;}&amp;lt;/nowiki&amp;gt;.)&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;header&#039;, &#039;nameforyourheaderelement&#039;, get_string(&#039;titleforlegened&#039;, &#039;modulename&#039;));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You can&#039;t yet nest these visible fieldsets unfortunately. But in fact groups of elements are wrapped in invisible fieldsets.&lt;br /&gt;
&lt;br /&gt;
{{Moodle 2.5}}&lt;br /&gt;
Since Moodle 2.5 fieldsets without any required fields are collapsed by default. To display these fieldsets on page load, use:&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
 $mform-&amp;gt;setExpanded(&#039;foo&#039;)&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You close a fieldset with moodle_form&#039;s closeHeaderBefore method. You tell closeHeaderBefore the element before you wish to end the fieldset. A fieldset is automatically closed if you open a new one. You need to use this code only if you want to close a fieldset and the subsequent form elements are not to be enclosed by a visible fieldset (they are still enclosed with an invisibe one with no legend) :&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;closeHeaderBefore(&#039;buttonar&#039;);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==addElement==&lt;br /&gt;
&lt;br /&gt;
Use the addElement method to add an element to a form. The first few arguments are always the same. The first param is the type of the element to add. The second is the elementname to use which is normally the html name of the element in the form. The third is often the text for the label for the element.&lt;br /&gt;
&lt;br /&gt;
Some examples are below :&lt;br /&gt;
=== button ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;button&#039;, &#039;intro&#039;, get_string(&amp;quot;buttonlabel&amp;quot;));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A button element. If you want a submit or cancel button see &#039;submit&#039; element.&lt;br /&gt;
&lt;br /&gt;
=== checkbox ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;checkbox&#039;, &#039;ratingtime&#039;, get_string(&#039;ratingtime&#039;, &#039;forum&#039;));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This is a simple checkbox. The third parameter for this element is the label to display on the left side of the form. You can also supply a string as a fourth parameter to specify a label that will appear on the right of the element. Checkboxes and radio buttons can be grouped and have individual labels on their right.&lt;br /&gt;
&lt;br /&gt;
You can have a 5th parameter $attributes, as on other elements.&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;BEWARE:&#039;&#039;&#039; Unchecked checkboxes return nothing at all (as if they didn&#039;t exist). This can surprise the unwary. You may wish to use advcheckbox instead, which does return a value when not checked. &#039;Advcheckbox&#039; eliminates this problem. &lt;br /&gt;
&lt;br /&gt;
==== advcheckbox ====&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;advcheckbox&#039;, &#039;ratingtime&#039;, get_string(&#039;ratingtime&#039;, &#039;forum&#039;), &#039;Label displayed after checkbox&#039;, array(&#039;group&#039; =&amp;gt; 1), array(0, 1));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Similar to the checkbox above, but with some important improvements:&lt;br /&gt;
&lt;br /&gt;
# The (optional) 5th parameter is a normal $attributes array, normally used to set HTML attributes for the &amp;lt;input&amp;gt; element. However, a special value of &#039;group&#039; can be given, which will add a class name to the element, and enable its grouping for a [[lib/formslib.php_add_checkbox_controller|checkbox controller]]&lt;br /&gt;
#The (optional) 6th parameter is an array of values that will be associated with the checked/unchecked state of the checkbox. With a normal checkbox you cannot choose that value, and in fact an unchecked checkbox will not even be sent with the form data.&lt;br /&gt;
#It returns a 0 value when unchecked. Compare with the ordinary checkbox which does not return anything at all.&lt;br /&gt;
&lt;br /&gt;
=== choosecoursefile ===&lt;br /&gt;
{{Moodle 1.9}}&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;choosecoursefile&#039;, &#039;mediafile&#039;, get_string(&#039;mediafile&#039;, &#039;lesson&#039;), array(&#039;courseid&#039;=&amp;gt;$COURSE-&amp;gt;id));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Choose a file from the course files area. The fourth option is a list of options for the element. &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;Note: This has been superceded by [[#filepicker|filepicker]] in Moodle 2.&#039;&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
array(&#039;courseid&#039; =&amp;gt;null,  //if it is null (default then use global $COURSE&lt;br /&gt;
      &#039;height&#039;   =&amp;gt;500,   // height of the popup window&lt;br /&gt;
      &#039;width&#039;    =&amp;gt;750,   // width of the popup window&lt;br /&gt;
      &#039;options&#039;  =&amp;gt;&#039;none&#039;); //options string for the pop up window &lt;br /&gt;
                          //eg. &#039;menubar=0,location=0,scrollbars,resizable&#039;&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You can also pass an optional 5th parameter of attributes, as for other elements. The most useful way of using that is something like &lt;br /&gt;
&amp;lt;code php&amp;gt;array(&#039;maxlength&#039; =&amp;gt; 255, &#039;size&#039; =&amp;gt; 48)&amp;lt;/code&amp;gt;&lt;br /&gt;
to control the maxlength / size of the text box (note size will default to 48 if not specified)&lt;br /&gt;
&lt;br /&gt;
Finally, as this element is a group containing two elements (button + value), you can add validation rules by using the &#039;&#039;&#039;addGroupRule()&#039;&#039;&#039; method in this (complex) way:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;$mform-&amp;gt;addGroupRule(&#039;elementname&#039;, array(&#039;value&#039; =&amp;gt; array(array(list, of, rule, params, but, fieldname))));&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Where: &#039;&#039;&#039;&amp;quot;elementname&amp;quot;&#039;&#039;&#039; is the name of the choosecoursefile group element, &#039;&#039;&#039;&amp;quot;value&amp;quot;&#039;&#039;&#039; is the name of the text field within the group and the &#039;&#039;&#039;&amp;quot;list, of, addrule, params, but, fieldname&amp;quot;&#039;&#039;&#039; is exactly that, the list of fields in the normal addRule() function but ommiting the first one, the fieldname.&lt;br /&gt;
&lt;br /&gt;
For example, the [http://cvs.moodle.org/moodle/mod/resource/type/file/resource.class.php?view=markup file/url resource type], uses one &amp;quot;choosecoursefile&amp;quot; element, and it controls the maximum length of the field (255) with this use of addGroupRule():&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;$mform-&amp;gt;addGroupRule(&#039;reference&#039;, array(&#039;value&#039; =&amp;gt; array(array(get_string(&#039;maximumchars&#039;, &#039;&#039;, 255), &#039;maxlength&#039;, 255, &#039;client&#039;))));&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== date_selector ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;date_selector&#039;, &#039;assesstimefinish&#039;, get_string(&#039;to&#039;));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This is a date selector. You can select a Day, Month and Year using a group of select boxes. The fourth param here is an array of options. The defaults for the options are :&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
array(&lt;br /&gt;
    &#039;startyear&#039; =&amp;gt; 1970, &lt;br /&gt;
    &#039;stopyear&#039;  =&amp;gt; 2020,&lt;br /&gt;
    &#039;timezone&#039;  =&amp;gt; 99,&lt;br /&gt;
    &#039;optional&#039;  =&amp;gt; false&lt;br /&gt;
);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.&lt;br /&gt;
&lt;br /&gt;
=== date_time_selector ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;date_time_selector&#039;, &#039;assesstimestart&#039;, get_string(&#039;from&#039;));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This is a group of select boxes to select a date (Day Month and Year) and time (Hour and Minute). When submitted, submitted data is processed and a timestamp is passed to $form-&amp;gt;get_data(); the fourth param here is an array of options. The defaults for the options are:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
array(&lt;br /&gt;
    &#039;startyear&#039; =&amp;gt; 1970, &lt;br /&gt;
    &#039;stopyear&#039;  =&amp;gt; 2020,&lt;br /&gt;
    &#039;timezone&#039;  =&amp;gt; 99,&lt;br /&gt;
    &#039;step&#039;      =&amp;gt; 5&lt;br /&gt;
);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.&lt;br /&gt;
&lt;br /&gt;
===duration===&lt;br /&gt;
{{Moodle 2.0}}&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
        $mform-&amp;gt;addElement(&#039;duration&#039;, &#039;timelimit&#039;, get_string(&#039;timelimit&#039;, &#039;quiz&#039;));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
This field type lets the user input an interval of time. It comprises a text field, where you can type a number, and a dropdown for selecting a unit (days, hours, minutes or seconds). When submitted the value is converted to a number of seconds.&lt;br /&gt;
&lt;br /&gt;
You can add a fourth parameter to give options. At the moment the only option supported is here is an array of options. The defaults for the options is:&lt;br /&gt;
&amp;lt;code php&amp;gt;array(&#039;optional&#039; =&amp;gt; true)&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You can also pass an optional 5th parameter of attributes, as for other elements. The most useful way of using that is something like &lt;br /&gt;
&amp;lt;code php&amp;gt;array(&#039;size&#039; =&amp;gt; 5)&amp;lt;/code&amp;gt;&lt;br /&gt;
to control the size of the text box.&lt;br /&gt;
&lt;br /&gt;
=== editor ===&lt;br /&gt;
&lt;br /&gt;
This replaces the old htmleditor field type. It allows the user to enter rich text content in a variety of formats.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;editor&#039;, &#039;fieldname&#039;, get_string(&#039;labeltext&#039;, &#039;langfile&#039;));&lt;br /&gt;
$mform-&amp;gt;setType(&#039;fieldname&#039;, PARAM_RAW);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
NOTE: It won&#039;t work properly without the setType() as shown.&lt;br /&gt;
&lt;br /&gt;
If you would like to let the user use the filepicker to upload images etc. that are used in the content, then see [[Using_the_File_API_in_Moodle_forms]].&lt;br /&gt;
&lt;br /&gt;
You can supply a fourth param to htmleditor of an array of options that are mostly related to file handling:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
array(&lt;br /&gt;
    &#039;subdirs&#039;=&amp;gt;0,&lt;br /&gt;
    &#039;maxbytes&#039;=&amp;gt;0,&lt;br /&gt;
    &#039;maxfiles&#039;=&amp;gt;0,&lt;br /&gt;
    &#039;changeformat&#039;=&amp;gt;0,&lt;br /&gt;
    &#039;context&#039;=&amp;gt;null,&lt;br /&gt;
    &#039;noclean&#039;=&amp;gt;0,&lt;br /&gt;
    &#039;trusttext&#039;=&amp;gt;0,&lt;br /&gt;
    &#039;enable_filemanagement&#039; =&amp;gt; true);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The option &#039;enable_filemanagement&#039; will display the file management button on true and remove it on false.&lt;br /&gt;
&lt;br /&gt;
To save the data if you don&#039;t care about files:&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$formdata = $mform-&amp;gt;get_data();&lt;br /&gt;
$text     = $formdata-&amp;gt;fieldname[&#039;text&#039;];&lt;br /&gt;
$format   = $formdata-&amp;gt;fieldname[&#039;format&#039;];&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Note: Because the text editor might be &amp;quot;Atto&amp;quot; (depending on user preferences) and Atto has an &amp;quot;autosave&amp;quot; feature - it requires that the combination of $PAGE-&amp;gt;url and this elementid are unique. If not, the autosaved text for a different form may be restored into this form.&lt;br /&gt;
&lt;br /&gt;
=== file ===&lt;br /&gt;
&lt;br /&gt;
File upload input box with browse button. In the form definition type&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;file&#039;, &#039;attachment&#039;, get_string(&#039;attachment&#039;, &#039;forum&#039;));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
after form submission and validation use&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
if ($data = $mform-&amp;gt;get_data()) {&lt;br /&gt;
      ...&lt;br /&gt;
    $mform-&amp;gt;save_files($destination_directory);&lt;br /&gt;
      ...&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
If there is no requirement to save the file, you can read the file contents directly into a string as follows...&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
    $mform-&amp;gt;get_file_content(&#039;attachment&#039;);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
If you need advanced settings such as required file, different max upload size or name of uploaded file&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$this-&amp;gt;set_upload_manager(new upload_manager(&#039;attachment&#039;, true, false, $COURSE, false, 0, true, true, false));&lt;br /&gt;
            $mform-&amp;gt;addElement(&#039;file&#039;, &#039;attachment&#039;, get_string(&#039;attachment&#039;, &#039;forum&#039;));&lt;br /&gt;
            $mform-&amp;gt;addRule(&#039;attachment&#039;, null, &#039;required&#039;);&lt;br /&gt;
&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
if ($data = $mform-&amp;gt;get_data()) {&lt;br /&gt;
      ...&lt;br /&gt;
    $mform-&amp;gt;save_files($destination_directory);&lt;br /&gt;
    $newfilename = $mform-&amp;gt;get_new_filename();&lt;br /&gt;
      ...&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
When porting old code it is also possible to use the upload manager directly for processing of uploaded files.&lt;br /&gt;
&lt;br /&gt;
Please note that if using set_upload_manager() it must be before addElement(&#039;file&#039;,..).&lt;br /&gt;
&lt;br /&gt;
{{Moodle 2.0}}&lt;br /&gt;
File uploading was rewritten in 2.0. Please see inline docs for now. This page will be updated when the new API stabilises.&lt;br /&gt;
&lt;br /&gt;
===filepicker===&lt;br /&gt;
{{Moodle 2.0}}&lt;br /&gt;
General replacement of &#039;&#039;file&#039;&#039; element.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;filepicker&#039;, &#039;userfile&#039;, get_string(&#039;file&#039;), null, array(&#039;maxbytes&#039; =&amp;gt; $maxbytes, &#039;accepted_types&#039; =&amp;gt; &#039;*&#039;));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
See also [[Using the File API in Moodle forms]]&lt;br /&gt;
&lt;br /&gt;
=== hidden ===&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;hidden&#039;, &#039;reply&#039;, &#039;yes&#039;);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A hidden element. Set the element name (in this case &#039;&#039;&#039;reply&#039;&#039;&#039;) to the stated value (in this case &#039;&#039;&#039;yes&#039;&#039;&#039;).&lt;br /&gt;
&lt;br /&gt;
=== html ===&lt;br /&gt;
You can add arbitrary HTML to your Moodle form:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;html&#039;, &#039;&amp;lt;div class=&amp;quot;qheader&amp;quot;&amp;gt;&#039;);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
See [http://moodle.org/mod/forum/discuss.php?d=126935 &amp;quot;Question: Can I put a moodleform inside a table td?&amp;quot;] for a concrete example.&lt;br /&gt;
&lt;br /&gt;
=== htmleditor &amp;amp; format ===&lt;br /&gt;
&lt;br /&gt;
These elements are now deprecated. Please use the [[#editor|editor]] field type instead.&lt;br /&gt;
&lt;br /&gt;
===modgrade===&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;modgrade&#039;, &#039;scale&#039;, get_string(&#039;grade&#039;), false);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
This is a custom element for selecting a grade for any activity module. The fourth argument is whether to include an option for no grade which has a value 0. This select box does include scales. The default is true, include no grade option.&lt;br /&gt;
&lt;br /&gt;
A helpbutton is automatically added.&lt;br /&gt;
&lt;br /&gt;
===modvisible===&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;modvisible&#039;, &#039;visible&#039;, get_string(&#039;visible&#039;));&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
This is a custom element for selecting a grade visibility in an activity mod update form.&lt;br /&gt;
&lt;br /&gt;
===password===&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;password&#039;, &#039;password&#039;, get_string(&#039;label&#039;), $attributes);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A password element. Fourth param is an array or string of attributes.&lt;br /&gt;
&lt;br /&gt;
===passwordunmask===&lt;br /&gt;
{{Moodle 1.9}}&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;passwordunmask&#039;, &#039;password&#039;, get_string(&#039;label&#039;), $attributes);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A password element with option to show the password in plaintext. Fourth param is an array or string of attributes.&lt;br /&gt;
&lt;br /&gt;
=== radio ===&lt;br /&gt;
{{Moodle 2.3}}&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$radioarray=array();&lt;br /&gt;
$radioarray[] = $mform-&amp;gt;createElement(&#039;radio&#039;, &#039;yesno&#039;, &#039;&#039;, get_string(&#039;yes&#039;), 1, $attributes);&lt;br /&gt;
$radioarray[] = $mform-&amp;gt;createElement(&#039;radio&#039;, &#039;yesno&#039;, &#039;&#039;, get_string(&#039;no&#039;), 0, $attributes);&lt;br /&gt;
$mform-&amp;gt;addGroup($radioarray, &#039;radioar&#039;, &#039;&#039;, array(&#039; &#039;), false);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Second param names the radio button and should be the same for each button in the group in order to toggle correctly. Third param would be the label for the form element but is generally ignored as this element will always be in a group which has it&#039;s own label. Fourth param is a string, a label to be displayed on the right of the element. The fifth is the value for this radio button. $attributes can be a string or an array of attributes.&lt;br /&gt;
&lt;br /&gt;
It is possible to add help to individual radio buttons but this requires a custom template to be defined for the group elements. See MDL-15571.&lt;br /&gt;
&lt;br /&gt;
Since 2.3 it cannot be statically called anymore, so we need to call createElement from $mform reference.&lt;br /&gt;
&lt;br /&gt;
==== setDefault ====&lt;br /&gt;
&lt;br /&gt;
To set the default for a radio button group as above use the following :&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;setDefault(&#039;yesno&#039;, 0);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This would make the default &#039;no&#039;.&lt;br /&gt;
&lt;br /&gt;
===select===&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;select&#039;, &#039;type&#039;, get_string(&#039;forumtype&#039;, &#039;forum&#039;), $FORUM_TYPES, $attributes);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The fourth param for this element is an array of options for the select box. The keys are the values for the option and the value of the array is the text for the option. The fifth param $attributes is optional, see text element for description of attributes param.&lt;br /&gt;
&lt;br /&gt;
It is also possible to create a select with certain options disabled, using [http://stackoverflow.com/questions/2138089/how-can-i-use-quickform-to-add-disabled-select-options/2150275#2150275 this technique].&lt;br /&gt;
&lt;br /&gt;
====multi-select====&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$select = $mform-&amp;gt;addElement(&#039;select&#039;, &#039;colors&#039;, get_string(&#039;colors&#039;), array(&#039;red&#039;, &#039;blue&#039;, &#039;green&#039;), $attributes);&lt;br /&gt;
$select-&amp;gt;setMultiple(true);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=====setSelected=====&lt;br /&gt;
&lt;br /&gt;
To set the default selected item in a select element, you can use the &#039;setSelected&#039; method. The &#039;setSelected&#039; can either get a value or an array of values.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$options = array(&lt;br /&gt;
    &#039;ff0000&#039; =&amp;gt; &#039;Red&#039;,&lt;br /&gt;
    &#039;00ff00&#039; =&amp;gt; &#039;Green&#039;,&lt;br /&gt;
    &#039;0000ff&#039; =&amp;gt; &#039;Blue&#039;&lt;br /&gt;
);&lt;br /&gt;
$select = $mform-&amp;gt;addElement(&#039;select&#039;, &#039;colors&#039;, get_string(&#039;colors&#039;), $options);&lt;br /&gt;
// This will select the colour blue.&lt;br /&gt;
$select-&amp;gt;setSelected(&#039;0000ff&#039;);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Or for multpi-selection:&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$skillsarray = array(&lt;br /&gt;
    &#039;val1&#039; =&amp;gt; &#039;Skill A&#039;,&lt;br /&gt;
    &#039;val2&#039; =&amp;gt; &#039;Skill B&#039;,&lt;br /&gt;
    &#039;val3&#039; =&amp;gt; &#039;Skill C&#039;&lt;br /&gt;
);&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;select&#039;, &#039;md_skills&#039;, get_string(&#039;skills&#039;, &#039;metadata&#039;), $skillsarray);&lt;br /&gt;
$mform-&amp;gt;getElement(&#039;md_skills&#039;)-&amp;gt;setMultiple(true);&lt;br /&gt;
// This will select the skills A and B.&lt;br /&gt;
$mform-&amp;gt;getElement(&#039;md_skills&#039;)-&amp;gt;setSelected(array(&#039;val1&#039;, &#039;val2&#039;));&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
However you probably don&#039;t want to do this. Instead you probably want to use setDefault, or set it using the form&#039;s setData method.&lt;br /&gt;
&lt;br /&gt;
===selectyesno===&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;selectyesno&#039;, &#039;maxbytes&#039;, get_string(&#039;maxattachmentsize&#039;, &#039;forum&#039;));&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
If you want a yes / no select box this one automatically translates itself and has value 1 for yes and 0 for no.&lt;br /&gt;
&lt;br /&gt;
===selectwithlink===&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$options = array();&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;selectwithlink&#039;, &#039;scaleid&#039;, get_string(&#039;scale&#039;), $options, null, &lt;br /&gt;
    array(&#039;link&#039; =&amp;gt; $CFG-&amp;gt;wwwroot.&#039;/grade/edit/scale/edit.php?courseid=&#039;.$COURSE-&amp;gt;id, &#039;label&#039; =&amp;gt; get_string(&#039;scalescustomcreate&#039;)));&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
select type element with options containing link&lt;br /&gt;
===static===&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;static&#039;, &#039;description&#039;, get_string(&#039;description&#039;, &#039;exercise&#039;),&lt;br /&gt;
    get_string(&#039;descriptionofexercise&#039;, &#039;exercise&#039;, $COURSE-&amp;gt;students));&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This is a static element. It should be used with care if it is used to display a static piece of text with a label. The third param is the label and the fourth is the static text itself.&lt;br /&gt;
&lt;br /&gt;
===submit, reset and cancel===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
//normally you use add_action_buttons instead of this code&lt;br /&gt;
$buttonarray=array();&lt;br /&gt;
$buttonarray[] = &amp;amp;$mform-&amp;gt;createElement(&#039;submit&#039;, &#039;submitbutton&#039;, get_string(&#039;savechanges&#039;));&lt;br /&gt;
$buttonarray[] = &amp;amp;$mform-&amp;gt;createElement(&#039;reset&#039;, &#039;resetbutton&#039;, get_string(&#039;revert&#039;));&lt;br /&gt;
$buttonarray[] = &amp;amp;$mform-&amp;gt;createElement(&#039;cancel&#039;);&lt;br /&gt;
$mform-&amp;gt;addGroup($buttonarray, &#039;buttonar&#039;, &#039;&#039;, array(&#039; &#039;), false);&lt;br /&gt;
$mform-&amp;gt;closeHeaderBefore(&#039;buttonar&#039;);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A &#039;Submit&#039; type element is a submit type form element which will submit the form. A &#039;Reset&#039; will not submit the form but will reset any changes the user has made to form contents. A &#039;Cancel&#039; element cancels form submission. You need to have a branch in your code before you check for get_data() to check if submission has been cancelled with is_cancelled(); See the example on the usage page.&lt;br /&gt;
&lt;br /&gt;
You should name your submit and reset buttons &#039;submitbutton&#039; and &#039;resetbutton&#039; or something similar (not &#039;submit&#039; and &#039;reset&#039;). This avoids problems in JavaScript of collisions between form element names and names of JavaScript methods of the form object.&lt;br /&gt;
&lt;br /&gt;
====add_action_buttons($cancel = true, $submitlabel=null);====&lt;br /&gt;
&lt;br /&gt;
You will normally use this helper function which is a method of moodleform to add all the &#039;action&#039; buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string(&#039;savechanges&#039;). Note the &#039;&#039;&#039;$this&#039;&#039;&#039; not &#039;&#039;&#039;$mform&#039;&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$this-&amp;gt;add_action_buttons();&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
===text===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;text&#039;, &#039;name&#039;, get_string(&#039;forumname&#039;, &#039;forum&#039;), $attributes);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
For a simple text element. Your fourth parameter here can be a string or array of attributes for the text element. The following are equivalent :&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$attributes=&#039;size=&amp;quot;20&amp;quot;&#039;;&lt;br /&gt;
$attributes=array(&#039;size&#039;=&amp;gt;&#039;20&#039;);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
 &lt;br /&gt;
Generally you are encouraged to use CSS instead of using attributes for styling.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
A format element can be used as a format select box. It will be non-selectable if you&#039;re using an html editor.&lt;br /&gt;
&lt;br /&gt;
The third param for this element is $useHtmlEditor and it defaults to null in which case an html editor is used if the browser and user profile support it.&lt;br /&gt;
&lt;br /&gt;
===textarea===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;textarea&#039;, &#039;introduction&#039;, get_string(&amp;quot;introtext&amp;quot;, &amp;quot;survey&amp;quot;), &#039;wrap=&amp;quot;virtual&amp;quot; rows=&amp;quot;20&amp;quot; cols=&amp;quot;50&amp;quot;&#039;);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A textarea element. If you want an htmleditor use htmleditor element. Fourth element here is a string or array of attributes.&lt;br /&gt;
&lt;br /&gt;
===recaptcha===&lt;br /&gt;
{{Moodle 1.9}}&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;recaptcha&#039;, &#039;recaptcha_field_name&#039;, $attributes);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Use this recaptcha element to reduce the spam risk in your forms. Third element here is a string or array of attributes. Take care to get an API key from http://recaptcha.net/api/getkey before using this element.&lt;br /&gt;
&lt;br /&gt;
To check whether recaptcha is enabled at site level use:&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
if (!empty($CFG-&amp;gt;recaptchapublickey) &amp;amp;&amp;amp; !empty($CFG-&amp;gt;recaptchaprivatekey)) {&lt;br /&gt;
    //recaptcha is enabled&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
===tags===&lt;br /&gt;
{{Moodle 2.0}}&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;tags&#039;, &#039;field_name&#039;, $lable, $options, $attributes);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Used for editing a list of tags, for example on a blog post.&lt;br /&gt;
&lt;br /&gt;
There is only one option available, &#039;display&#039;, which should be set to one of the contstants MoodleQuickForm_tags::ONLYOFFICIAL, NOOFFICIAL or DEFAULTUI. This controls whether the official tags are listed for easy selection, or a text area where arbitrary tags may be typed, or both. The default is both.&lt;br /&gt;
&lt;br /&gt;
The value should be set/returned as an array of tags.&lt;br /&gt;
&lt;br /&gt;
===grading===&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;grading&#039;, &#039;advancedgrading&#039;, get_string(&#039;grade&#039;).&#039;:&#039;, array(&#039;gradinginstance&#039; =&amp;gt; $gradinginstance));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Custom element for advanced grading plugins.&lt;br /&gt;
&lt;br /&gt;
When adding the &#039;grading&#039; element to the form, developer must pass an object of class gradingform_instance as $attributes[&#039;gradinginstance&#039;]. Otherwise an exception will be thrown.&lt;br /&gt;
&lt;br /&gt;
===questioncategory===&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;questioncategory&#039;, &#039;category&#039;, get_string(&#039;category&#039;, &#039;question&#039;),&lt;br /&gt;
    array(&#039;contexts&#039;=&amp;gt;$contexts, &#039;top&#039;=&amp;gt;true, &#039;currentcat&#039;=&amp;gt;$currentcat, &#039;nochildrenof&#039;=&amp;gt;$currentcat));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
Creates a drop down element to select a question category.&lt;br /&gt;
&lt;br /&gt;
Options are:&lt;br /&gt;
&#039;&#039;&#039;contexts&#039;&#039;&#039; - (required) context in which question appears&lt;br /&gt;
&#039;&#039;&#039;currentcat&#039;&#039;&#039; - (optional) course category&lt;br /&gt;
&#039;&#039;&#039;top&#039;&#039;&#039; - (optional) if true will put top categories on top&lt;br /&gt;
&#039;&#039;&#039;nochildrenof&#039;&#039;&#039; - (optional) Format categories into an indented list reflecting the tree structure&lt;br /&gt;
&lt;br /&gt;
==addGroup==&lt;br /&gt;
&lt;br /&gt;
A &#039;group&#039; in formslib is just a group of elements that will have a label and will be included on one line. &lt;br /&gt;
&lt;br /&gt;
For example typical code to include a submit and cancel button on the same line : &lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$buttonarray=array();&lt;br /&gt;
$buttonarray[] =&amp;amp; $mform-&amp;gt;createElement(&#039;submit&#039;, &#039;submitbutton&#039;, get_string(&#039;savechanges&#039;));&lt;br /&gt;
$buttonarray[] =&amp;amp; $mform-&amp;gt;createElement(&#039;submit&#039;, &#039;cancel&#039;, get_string(&#039;cancel&#039;));&lt;br /&gt;
$mform-&amp;gt;addGroup($buttonarray, &#039;buttonar&#039;, &#039;&#039;, array(&#039; &#039;), false);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You use the same arguments for createElement as you do for addElement. Any label for the element in the third argument is normally ignored (but not in the case of the submit buttons above where the third argument is not for a label but is the text for the button).&lt;br /&gt;
&lt;br /&gt;
Here&#039;s a bad example (don&#039;t do this for real, use the &#039;optional&#039; =&amp;gt; true option of the date element): putting a date_selector (which is itself a group of elements) and a checkbox on the same line, note that you can disable every element in the group using the group name &#039;availablefromgroup&#039; but it doesn&#039;t disable the controlling element the &#039;availablefromenabled&#039; checkbox:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$availablefromgroup=array();&lt;br /&gt;
$availablefromgroup[] =&amp;amp; $mform-&amp;gt;createElement(&#039;date_selector&#039;, &#039;availablefrom&#039;, &#039;&#039;);&lt;br /&gt;
$availablefromgroup[] =&amp;amp; $mform-&amp;gt;createElement(&#039;checkbox&#039;, &#039;availablefromenabled&#039;, &#039;&#039;, get_string(&#039;enable&#039;));&lt;br /&gt;
$mform-&amp;gt;addGroup($availablefromgroup, &#039;availablefromgroup&#039;, get_string(&#039;availablefromdate&#039;, &#039;data&#039;), &#039;&amp;amp;nbsp;&#039;, false);&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;availablefromgroup&#039;, &#039;availablefromenabled&#039;);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
* If you want to put a group inside another array so that you can repeat items, use createElement instead of addGroup:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$group = $mform-&amp;gt;createElement(&#039;group&#039;, &#039;groupname&#039;, get_string(&#039;label&#039;), $groupitems);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
* By default, groups modify the names of elements inside them by appending a number. This is often unhelpful, for example if you want to use disabledIf on the element. To prevent this behaviour, set the last parameter to false when creating a group.:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$group = $mform-&amp;gt;createElement(&#039;group&#039;, &#039;groupname&#039;, get_string(&#039;label&#039;), $groupitems, null, false);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==addRule==&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addRule(&#039;elementname&#039;, get_string(&#039;error&#039;), &#039;rule type&#039;, &#039;extraruledata&#039;, &#039;server&#039;(default), false, false);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The first param(element) is an element name and second(message) is the error message that will be displayed to the user.&lt;br /&gt;
The third parameter(type) is the type of rule. The fourth param(format) is used for extra data needed with some rules such as minlength and regex. The fifth parameter(validation) validates input data on server or client side, if validation is done on client side then it will be checked on the server side as well.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
 * @param    string     $element       Form element name&lt;br /&gt;
 * @param    string     $message       Message to display for invalid data&lt;br /&gt;
 * @param    string     $type          Rule type, use getRegisteredRules() to get types&lt;br /&gt;
 * @param    string     $format        (optional)Required for extra rule data&lt;br /&gt;
 * @param    string     $validation    (optional)Where to perform validation: &amp;quot;server&amp;quot;, &amp;quot;client&amp;quot;&lt;br /&gt;
 * @param    boolean    $reset         Client-side validation: reset the form element to its original value if there is an error?&lt;br /&gt;
 * @param    boolean    $force         Force the rule to be applied, even if the target form element does not exist&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;Common Rule Types&#039;&#039;&#039;&lt;br /&gt;
* required &lt;br /&gt;
* maxlength&lt;br /&gt;
* minlength&lt;br /&gt;
* rangelength&lt;br /&gt;
* email&lt;br /&gt;
* regex&lt;br /&gt;
* lettersonly&lt;br /&gt;
* alphanumeric&lt;br /&gt;
* numeric&lt;br /&gt;
* nopunctuation&lt;br /&gt;
* nonzero&lt;br /&gt;
* callback&lt;br /&gt;
* compare&lt;br /&gt;
&lt;br /&gt;
===Server side and Client side===&lt;br /&gt;
In case you use the &#039;&#039;Client side&#039;&#039; validation option, you can mainly check for an empty or not input field. unless you write some &#039;&#039;Client side&#039;&#039; code which will probably be JavaScript functions to verify the data inside the input fields before it is submitted to the server. It could save some time if those functions are short, simple and quick to compute.&lt;br /&gt;
In case you need a more complex validation checks which relay on Moodle&#039;s internal PHP libraries (or other/external PHP libraries) you better use the &#039;&#039;Server side&#039;&#039; validation checks. Where you can query the DB, write complex PHP validation functions and much much more, that are not available (easily) when using JavaScript on the client&#039;s side.&lt;br /&gt;
&lt;br /&gt;
==setHelpButton==&lt;br /&gt;
{{Moodle 1.9}}&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;setHelpButton(&#039;lessondefault&#039;, array(&#039;lessondefault&#039;, get_string(&#039;lessondefault&#039;, &#039;lesson&#039;), &#039;lesson&#039;));&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
First param is an elementname and the second param is an array of params that are passed to helpbutton in weblib.php. Params are :&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
 * @param string $page  The keyword that defines a help page&lt;br /&gt;
 * @param string $title The title of links, rollover tips, alt tags etc&lt;br /&gt;
 *           &#039;Help with&#039; (or the language equivalent) will be prefixed and &#039;...&#039; will be stripped.&lt;br /&gt;
 * @param string $module Which module is the page defined in&lt;br /&gt;
 * @param mixed $image Use a help image for the link?  (true/false/&amp;quot;both&amp;quot;)&lt;br /&gt;
 * @param boolean $linktext If true, display the title next to the help icon.&lt;br /&gt;
 * @param string $text If defined then this text is used in the page, and&lt;br /&gt;
 *           the $page variable is ignored.&lt;br /&gt;
 * @param boolean $return If true then the output is returned as a string, if false it is printed to the current page.&lt;br /&gt;
 * @param string $imagetext The full text for the helpbutton icon. If empty use default help.gif&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
Make sure you don&#039;t set boolean $return to false. &lt;br /&gt;
&lt;br /&gt;
You need to do use this method after addElement();&lt;br /&gt;
&lt;br /&gt;
==addHelpButton==&lt;br /&gt;
{{Moodle 2.0}}&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addHelpButton(&#039;api_key_field&#039;, &#039;api_key&#039;, &#039;block_extsearch&#039;);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In Moodle 2.0 the &amp;quot;setHelpButton&amp;quot; method has been deprecated in favor of the &amp;quot;addHelpButton&amp;quot; method, which has a simplified interface and uses $OUTPUT-&amp;gt;help_icon() on the back end. The following parameters are expected:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
/**&lt;br /&gt;
 * @param $elementname The name of the form element to add the help button for&lt;br /&gt;
 * @param $identifier The identifier for the help string and its title (see below)&lt;br /&gt;
 * @param $component The component name to look for the help string in&lt;br /&gt;
 */&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
Unlike in Moodle 1.9, it is no longer necessary to put your help pages in separate HTML files. Instead, the function looks for two strings:&lt;br /&gt;
&lt;br /&gt;
# get_string($identifier, $component) // The title of the help page&lt;br /&gt;
# get_string(&amp;quot;{$identifier}_help&amp;quot;, $component) // The content of the help page&lt;br /&gt;
&lt;br /&gt;
So you will need to have &#039;&#039;&#039;$identifier&#039;&#039;&#039; and &#039;&#039;&#039;{$identifier}_help&#039;&#039;&#039; defined in order for the help button to be created properly. For example the multiple choice question editing form has a button for shuffling the answers. &lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addHelpButton(&#039;shuffleanswers&#039;, &#039;shuffleanswers&#039;, &#039;qtype_multichoice&#039;);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
and so the language file includes the strings&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$string[&#039;shuffleanswers&#039;] = &#039;Shuffle the choices?&#039;; &lt;br /&gt;
$string[&#039;shuffleanswers_help&#039;] = &#039;If enabled,.....&#039;;&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
You can also add the language string like&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$string[&#039;shuffleanswers_link&#039;] = &#039;question/shuffleanswers&#039;;&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
to add a link to more help on Moodle docs. See [[String_API]] for more information about help icons.&lt;br /&gt;
&lt;br /&gt;
==setDefault==&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;select&#039;, &#039;grade&#039;, get_string(&#039;gradeforsubmission&#039;, &#039;exercise&#039;), $grades);&lt;br /&gt;
$mform-&amp;gt;setHelpButton(&#039;grade&#039;, array(&#039;grade&#039;, get_string(&#039;gradeforsubmission&#039;, &#039;exercise&#039;), &#039;exercise&#039;));&lt;br /&gt;
$mform-&amp;gt;setDefault(&#039;grade&#039;, 100);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Set the default of the form value with setDefault($elementname, $value); where elementname is the elementname whose default you want to set and $value is the default to set. We set the defaults for the form in definition(). This default is what is used if no data is loaded into the form with set_data(); eg. on display of the form for an &#039;add&#039; rather than &#039;update&#039; function.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;editor&#039;, &#039;desc&#039;, get_string(&#039;description&#039;));     &lt;br /&gt;
$mform-&amp;gt;setDefault(&#039;desc&#039;, array(&#039;text&#039;=&amp;gt;$defaulttext));&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Note that when setting the default for an editor element you must use an array to define the default &amp;quot;text&amp;quot; value as shown above.&lt;br /&gt;
&lt;br /&gt;
==disabledIf==&lt;br /&gt;
&lt;br /&gt;
For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.&lt;br /&gt;
&lt;br /&gt;
You can use $mform-&amp;gt;disabledIf($elementName, $dependentOn, $condition = &#039;notchecked&#039;, $value=&#039;1&#039;)&lt;br /&gt;
&lt;br /&gt;
* elementname can be a group. If you specify a group all elements in the group will be disabled (if dependentOn is in elementname group that is ignored and not disabled). These are the element names you&#039;ve used as the second argument in addElement or addGroup.&lt;br /&gt;
* dependentOn is the actual name of the element as it will appear in html. This can be different to the name used in addGroup particularly but also addElement where you&#039;re adding a complex element like a date_selector. Check the html of your page. You typically make the depedentOn a checkbox or select box.&lt;br /&gt;
* $condition will be &#039;notchecked&#039;, &#039;checked&#039;, &#039;noitemselected&#039;, &#039;eq&#039;, &#039;in&#039; or, if it is anything else, we test for &#039;neq&#039;.&lt;br /&gt;
** If $condition is &#039;eq&#039; or &#039;neq&#039; then we check the value of the dependentOn field and check for equality (==) or nonequality (!=) in js&lt;br /&gt;
** If $condition is &#039;checked&#039; or &#039;notchecked&#039; then we check to see if a checkbox is checked or not.&lt;br /&gt;
** If $condition is &#039;in&#039; then we check to see if a selected item is in the given list or not. (This was introduced in Moodle 2.7+)&lt;br /&gt;
** If $condition is &#039;noitemselected&#039; then we check to see whether nothing is selected in a dropdown list.&lt;br /&gt;
&lt;br /&gt;
Examples:&lt;br /&gt;
 // Disable my control unless a checkbox is checked.&lt;br /&gt;
 $mform-&amp;gt;disabledIf(&#039;mycontrol&#039;, &#039;somecheckbox&#039;);&lt;br /&gt;
 &lt;br /&gt;
 // Disable my control if a checkbox &#039;&#039;&#039;is&#039;&#039;&#039; checked.&lt;br /&gt;
 $mform-&amp;gt;disabledIf(&#039;mycontrol&#039;, &#039;somecheckbox&#039;, &#039;checked&#039;);&lt;br /&gt;
 &lt;br /&gt;
 // Disable my control when a dropdown has value 42.&lt;br /&gt;
 $mform-&amp;gt;disabledIf(&#039;mycontrol&#039;, &#039;someselect&#039;, &#039;eq&#039;, 42);&lt;br /&gt;
&lt;br /&gt;
 // Disable my control unless a dropdown has value 42.&lt;br /&gt;
 $mform-&amp;gt;disabledIf(&#039;mycontrol&#039;, &#039;someselect&#039;, &#039;neq&#039;, 42);&lt;br /&gt;
&lt;br /&gt;
The possible choices here are in the dependency manager in lib/form/form.js.&lt;br /&gt;
===A tricky case===&lt;br /&gt;
&lt;br /&gt;
You need to take care with disabledIf if you plan to use it with groups of checkboxes.&lt;br /&gt;
&lt;br /&gt;
Let&#039;s say you have a group of 5 checkboxes and you want to enable a depending item such as a drop down menu only when the first and the last checkboxes are selected.&lt;br /&gt;
&lt;br /&gt;
To fix ideas:&lt;br /&gt;
&lt;br /&gt;
If the selection in the checkboxes group is:&lt;br /&gt;
&lt;br /&gt;
 mycheck_01 == 1&lt;br /&gt;
 mycheck_02 == 0&lt;br /&gt;
 mycheck_03 == 0&lt;br /&gt;
 mycheck_04 == 0&lt;br /&gt;
 mycheck_05 == 1&lt;br /&gt;
&lt;br /&gt;
the depending item must be enabled while ANY OTHER COMBINATION must disable the drop down menu.&lt;br /&gt;
&lt;br /&gt;
The following code will, apparently, fail:&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_01&#039;, &#039;neq&#039;, &#039;1&#039;);&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_02&#039;, &#039;neq&#039;, &#039;0&#039;);&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_03&#039;, &#039;neq&#039;, &#039;0&#039;);&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_04&#039;, &#039;neq&#039;, &#039;0&#039;);&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_05&#039;, &#039;neq&#039;, &#039;1&#039;);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In fact, once you get the drop down menu enabled, you are free to unselect mycheck_01 whilst still having the depending item enabled.&lt;br /&gt;
This apparent bug occurs because a non-checked checkbox behaves like a non existing mform element. So the js code will not find the element &amp;quot;mycheck_01&amp;quot; and will not apply the corresponding rule.&lt;br /&gt;
&lt;br /&gt;
A working solution for this kind of issue seems to be:&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_01&#039;, &#039;notchecked&#039;);&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_02&#039;, &#039;checked&#039;);&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_03&#039;, &#039;checked&#039;);&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_04&#039;, &#039;checked&#039;);&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_05&#039;, &#039;notchecked&#039;);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
To see a failing example as the one described, try the attachments provided in MDL-38975. See also in MDL-38975 for the working solution in action with modifications suggested by Eloy.&lt;br /&gt;
&lt;br /&gt;
==setType==&lt;br /&gt;
&lt;br /&gt;
PARAM_* types are used to specify how a submitted variable should be cleaned. These should be used for get parameters such as id, course etc. which are used to load a page and also with setType(); method. Every form element should have a type specified except select, radio box and checkbox elements, these elements do a good job of cleaning themselves (only specified options are allowed as user input).&lt;br /&gt;
&lt;br /&gt;
===Most Commonly Used PARAM_* Types===&lt;br /&gt;
&lt;br /&gt;
These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.&lt;br /&gt;
&lt;br /&gt;
* PARAM_CLEAN is deprecated and you should try to use a more specific type.&lt;br /&gt;
* PARAM_TEXT should be used for cleaning data that is expected to contain multi-lang content. It will strip all html tags. But will still let tags for multilang support through.&lt;br /&gt;
* PARAM_NOTAGS should be used for cleaning data that is expected to be plain text. It will strip *all* html type tags. It will *not* let tags for multilang support through. This should be used for instance for email addresses where no multilang support is appropriate.&lt;br /&gt;
* PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the html editor. Data from the editor is later cleaned before display using format_text() function. PARAM_RAW can also be used for data that is validated by some other way or printed by p() or s().&lt;br /&gt;
* PARAM_INT should be used for integers. PARAM_FLOAT is also available for decimal numbers but is not recommended for user input since it does not work for languages that use , as a decimal separator.&lt;br /&gt;
* PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.&lt;br /&gt;
&lt;br /&gt;
==disable_form_change_checker==&lt;br /&gt;
&lt;br /&gt;
By default, any Moodle form will pop-up an &amp;quot;Are you sure?&amp;quot; alert if you make some changes and then try to leave the page without saving. Occasionally, that is undesirable, in which case you can call&lt;br /&gt;
&lt;br /&gt;
 $mform-&amp;gt;disable_form_change_checker()&lt;br /&gt;
&lt;br /&gt;
==References==&lt;br /&gt;
&lt;br /&gt;
* [http://www.midnighthax.com/quickform.php PEAR HTML QuickForm Getting Started Guide] by Keith Edmunds of Midnighthax.com&lt;br /&gt;
* [http://pear.php.net/manual/en/package.html.html-quickform.php PEAR::HTML_QuickForm manual]&lt;br /&gt;
&lt;br /&gt;
[[Category:Formslib]]&lt;br /&gt;
[[Category:Interfaces]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=lib/formslib.php_Form_Definition&amp;diff=49291</id>
		<title>lib/formslib.php Form Definition</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=lib/formslib.php_Form_Definition&amp;diff=49291"/>
		<updated>2016-01-26T19:50:11Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: /* definition() */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;{{Formslib}}&lt;br /&gt;
== &#039;&#039;definition()&#039;&#039; ==&lt;br /&gt;
&lt;br /&gt;
The definition of the elements to be included in the form, their &#039;types&#039; (PARAM_*), helpbuttons included, etc. is all included in a function you must define in your class.&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;definition()&#039;&#039; is used to define the elements in the form and &#039;&#039;&#039;this definition will be used for validating data submitted as well as for printing the form.&#039;&#039;&#039; For select and checkbox type elements only data that could have been selected will be allowed. And only data that corresponds to a form element in the definition will be accepted as submitted data.&lt;br /&gt;
&lt;br /&gt;
The &#039;&#039;definition()&#039;&#039; should include all elements that are going to be used on form, some elements may be removed or tweaked later in &#039;&#039;definition_after_data()&#039;&#039;. Please do not create conditional elements in &#039;&#039;definition()&#039;&#039;, the definition() should not directly depend on the submitted data.&lt;br /&gt;
&lt;br /&gt;
Note that the definition function is called when the form class is instantiated. There is no option to (say) manipulate data in the class (that may affect the rendering of the form) between instantiating the form and calling any other methods. &lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
require_once(&amp;quot;$CFG-&amp;gt;libdir/formslib.php&amp;quot;);&lt;br /&gt;
&lt;br /&gt;
class simplehtml_form extends moodleform {&lt;br /&gt;
&lt;br /&gt;
    function definition() {&lt;br /&gt;
        global $CFG;&lt;br /&gt;
       &lt;br /&gt;
        $mform = $this-&amp;gt;_form; // Don&#039;t forget the underscore! &lt;br /&gt;
&lt;br /&gt;
        $mform-&amp;gt;addElement()... // Add elements to your form&lt;br /&gt;
            ...&lt;br /&gt;
    }                           // Close the function&lt;br /&gt;
}                               // Close the class&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
===Passing parameters to the Form===&lt;br /&gt;
&lt;br /&gt;
The constructor for &#039;&#039;moodleform&#039;&#039; allows a number of parameters including one (&#039;&#039;$customdata&#039;&#039;) to permit an array of arbitrary data to be passed to your form. &lt;br /&gt;
&lt;br /&gt;
For example, you can pass the data &amp;quot;$email&amp;quot; and &amp;quot;$username&amp;quot; to the Form&#039;s class for use inside (say) the definition.&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
...&lt;br /&gt;
 $mform_simple = new simplehtml_form( null, array(&#039;email&#039;=&amp;gt;$email, &#039;username&#039;=&amp;gt;$username ) );&lt;br /&gt;
...&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
(the first parameter is $action, &#039;&#039;null&#039;&#039; will case the form action to be determined automatically)&lt;br /&gt;
&lt;br /&gt;
Secondly, inside the form definition you can use those parameters to set the default values to some of the form&#039;s fields&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
...&lt;br /&gt;
 $mform-&amp;gt;addElement(&#039;text&#039;, &#039;email&#039;, get_string(&#039;email&#039;), &#039;maxlength=&amp;quot;100&amp;quot; size=&amp;quot;25&amp;quot; &#039;);&lt;br /&gt;
 $mform-&amp;gt;setType(&#039;email&#039;, PARAM_NOTAGS);&lt;br /&gt;
 $mform-&amp;gt;addRule(&#039;email&#039;, get_string(&#039;missingemail&#039;), &#039;required&#039;, null, &#039;server&#039;);&lt;br /&gt;
 // Set default value by using a passed parameter&lt;br /&gt;
 $mform-&amp;gt;setDefault(&#039;email&#039;,$this-&amp;gt;_customdata[&#039;email&#039;]);&lt;br /&gt;
...&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==Use Fieldsets to group Form Elements==&lt;br /&gt;
&lt;br /&gt;
You use code like this to open a fieldset with a &#039;&#039;legend&#039;&#039;. &amp;lt;br /&amp;gt;&lt;br /&gt;
(&#039;&#039;&#039;Note&#039;&#039;&#039;: Some themes turn off legends on admin setting pages by using CSS: &amp;lt;nowiki&amp;gt;#adminsettings legend {display:none;}&amp;lt;/nowiki&amp;gt;.)&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;header&#039;, &#039;nameforyourheaderelement&#039;, get_string(&#039;titleforlegened&#039;, &#039;modulename&#039;));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You can&#039;t yet nest these visible fieldsets unfortunately. But in fact groups of elements are wrapped in invisible fieldsets.&lt;br /&gt;
&lt;br /&gt;
{{Moodle 2.5}}&lt;br /&gt;
Since Moodle 2.5 fieldsets without any required fields are collapsed by default. To display these fieldsets on page load, use:&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
 $mform-&amp;gt;setExpanded(&#039;foo&#039;)&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You close a fieldset with moodle_form&#039;s closeHeaderBefore method. You tell closeHeaderBefore the element before you wish to end the fieldset. A fieldset is automatically closed if you open a new one. You need to use this code only if you want to close a fieldset and the subsequent form elements are not to be enclosed by a visible fieldset (they are still enclosed with an invisibe one with no legend) :&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;closeHeaderBefore(&#039;buttonar&#039;);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==addElement==&lt;br /&gt;
&lt;br /&gt;
Use the addElement method to add an element to a form. The first few arguments are always the same. The first param is the type of the element to add. The second is the elementname to use which is normally the html name of the element in the form. The third is often the text for the label for the element.&lt;br /&gt;
&lt;br /&gt;
Some examples are below :&lt;br /&gt;
=== button ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;button&#039;, &#039;intro&#039;, get_string(&amp;quot;buttonlabel&amp;quot;));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A button element. If you want a submit or cancel button see &#039;submit&#039; element.&lt;br /&gt;
&lt;br /&gt;
=== checkbox ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;checkbox&#039;, &#039;ratingtime&#039;, get_string(&#039;ratingtime&#039;, &#039;forum&#039;));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This is a simple checkbox. The third parameter for this element is the label to display on the left side of the form. You can also supply a string as a fourth parameter to specify a label that will appear on the right of the element. Checkboxes and radio buttons can be grouped and have individual labels on their right.&lt;br /&gt;
&lt;br /&gt;
You can have a 5th parameter $attributes, as on other elements.&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;BEWARE:&#039;&#039;&#039; Unchecked checkboxes return nothing at all (as if they didn&#039;t exist). This can surprise the unwary. You may wish to use advcheckbox instead, which does return a value when not checked. &#039;Advcheckbox&#039; eliminates this problem. &lt;br /&gt;
&lt;br /&gt;
==== advcheckbox ====&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;advcheckbox&#039;, &#039;ratingtime&#039;, get_string(&#039;ratingtime&#039;, &#039;forum&#039;), &#039;Label displayed after checkbox&#039;, array(&#039;group&#039; =&amp;gt; 1), array(0, 1));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Similar to the checkbox above, but with some important improvements:&lt;br /&gt;
&lt;br /&gt;
# The (optional) 5th parameter is a normal $attributes array, normally used to set HTML attributes for the &amp;lt;input&amp;gt; element. However, a special value of &#039;group&#039; can be given, which will add a class name to the element, and enable its grouping for a [[lib/formslib.php_add_checkbox_controller|checkbox controller]]&lt;br /&gt;
#The (optional) 6th parameter is an array of values that will be associated with the checked/unchecked state of the checkbox. With a normal checkbox you cannot choose that value, and in fact an unchecked checkbox will not even be sent with the form data.&lt;br /&gt;
#It returns a 0 value when unchecked. Compare with the ordinary checkbox which does not return anything at all.&lt;br /&gt;
&lt;br /&gt;
=== choosecoursefile ===&lt;br /&gt;
{{Moodle 1.9}}&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;choosecoursefile&#039;, &#039;mediafile&#039;, get_string(&#039;mediafile&#039;, &#039;lesson&#039;), array(&#039;courseid&#039;=&amp;gt;$COURSE-&amp;gt;id));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Choose a file from the course files area. The fourth option is a list of options for the element. &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;Note: This has been superceded by [[#filepicker|filepicker]] in Moodle 2.&#039;&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
array(&#039;courseid&#039; =&amp;gt;null,  //if it is null (default then use global $COURSE&lt;br /&gt;
      &#039;height&#039;   =&amp;gt;500,   // height of the popup window&lt;br /&gt;
      &#039;width&#039;    =&amp;gt;750,   // width of the popup window&lt;br /&gt;
      &#039;options&#039;  =&amp;gt;&#039;none&#039;); //options string for the pop up window &lt;br /&gt;
                          //eg. &#039;menubar=0,location=0,scrollbars,resizable&#039;&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You can also pass an optional 5th parameter of attributes, as for other elements. The most useful way of using that is something like &lt;br /&gt;
&amp;lt;code php&amp;gt;array(&#039;maxlength&#039; =&amp;gt; 255, &#039;size&#039; =&amp;gt; 48)&amp;lt;/code&amp;gt;&lt;br /&gt;
to control the maxlength / size of the text box (note size will default to 48 if not specified)&lt;br /&gt;
&lt;br /&gt;
Finally, as this element is a group containing two elements (button + value), you can add validation rules by using the &#039;&#039;&#039;addGroupRule()&#039;&#039;&#039; method in this (complex) way:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;$mform-&amp;gt;addGroupRule(&#039;elementname&#039;, array(&#039;value&#039; =&amp;gt; array(array(list, of, rule, params, but, fieldname))));&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Where: &#039;&#039;&#039;&amp;quot;elementname&amp;quot;&#039;&#039;&#039; is the name of the choosecoursefile group element, &#039;&#039;&#039;&amp;quot;value&amp;quot;&#039;&#039;&#039; is the name of the text field within the group and the &#039;&#039;&#039;&amp;quot;list, of, addrule, params, but, fieldname&amp;quot;&#039;&#039;&#039; is exactly that, the list of fields in the normal addRule() function but ommiting the first one, the fieldname.&lt;br /&gt;
&lt;br /&gt;
For example, the [http://cvs.moodle.org/moodle/mod/resource/type/file/resource.class.php?view=markup file/url resource type], uses one &amp;quot;choosecoursefile&amp;quot; element, and it controls the maximum length of the field (255) with this use of addGroupRule():&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;$mform-&amp;gt;addGroupRule(&#039;reference&#039;, array(&#039;value&#039; =&amp;gt; array(array(get_string(&#039;maximumchars&#039;, &#039;&#039;, 255), &#039;maxlength&#039;, 255, &#039;client&#039;))));&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== date_selector ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;date_selector&#039;, &#039;assesstimefinish&#039;, get_string(&#039;to&#039;));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This is a date selector. You can select a Day, Month and Year using a group of select boxes. The fourth param here is an array of options. The defaults for the options are :&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
array(&lt;br /&gt;
    &#039;startyear&#039; =&amp;gt; 1970, &lt;br /&gt;
    &#039;stopyear&#039;  =&amp;gt; 2020,&lt;br /&gt;
    &#039;timezone&#039;  =&amp;gt; 99,&lt;br /&gt;
    &#039;optional&#039;  =&amp;gt; false&lt;br /&gt;
);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.&lt;br /&gt;
&lt;br /&gt;
=== date_time_selector ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;date_time_selector&#039;, &#039;assesstimestart&#039;, get_string(&#039;from&#039;));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This is a group of select boxes to select a date (Day Month and Year) and time (Hour and Minute). When submitted, submitted data is processed and a timestamp is passed to $form-&amp;gt;get_data(); the fourth param here is an array of options. The defaults for the options are:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
array(&lt;br /&gt;
    &#039;startyear&#039; =&amp;gt; 1970, &lt;br /&gt;
    &#039;stopyear&#039;  =&amp;gt; 2020,&lt;br /&gt;
    &#039;timezone&#039;  =&amp;gt; 99,&lt;br /&gt;
    &#039;step&#039;      =&amp;gt; 5&lt;br /&gt;
);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.&lt;br /&gt;
&lt;br /&gt;
===duration===&lt;br /&gt;
{{Moodle 2.0}}&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
        $mform-&amp;gt;addElement(&#039;duration&#039;, &#039;timelimit&#039;, get_string(&#039;timelimit&#039;, &#039;quiz&#039;));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
This field type lets the user input an interval of time. It comprises a text field, where you can type a number, and a dropdown for selecting a unit (days, hours, minutes or seconds). When submitted the value is converted to a number of seconds.&lt;br /&gt;
&lt;br /&gt;
You can add a fourth parameter to give options. At the moment the only option supported is here is an array of options. The defaults for the options is:&lt;br /&gt;
&amp;lt;code php&amp;gt;array(&#039;optional&#039; =&amp;gt; true)&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You can also pass an optional 5th parameter of attributes, as for other elements. The most useful way of using that is something like &lt;br /&gt;
&amp;lt;code php&amp;gt;array(&#039;size&#039; =&amp;gt; 5)&amp;lt;/code&amp;gt;&lt;br /&gt;
to control the size of the text box.&lt;br /&gt;
&lt;br /&gt;
=== editor ===&lt;br /&gt;
&lt;br /&gt;
This replaces the old htmleditor field type. It allows the user to enter rich text content in a variety of formats.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;editor&#039;, &#039;fieldname&#039;, get_string(&#039;labeltext&#039;, &#039;langfile&#039;));&lt;br /&gt;
$mform-&amp;gt;setType(&#039;fieldname&#039;, PARAM_RAW);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
NOTE: It won&#039;t work properly without the setType() as shown.&lt;br /&gt;
&lt;br /&gt;
If you would like to let the user use the filepicker to upload images etc. that are used in the content, then see [[Using_the_File_API_in_Moodle_forms]].&lt;br /&gt;
&lt;br /&gt;
You can supply a fourth param to htmleditor of an array of options that are mostly related to file handling:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
array(&lt;br /&gt;
    &#039;subdirs&#039;=&amp;gt;0,&lt;br /&gt;
    &#039;maxbytes&#039;=&amp;gt;0,&lt;br /&gt;
    &#039;maxfiles&#039;=&amp;gt;0,&lt;br /&gt;
    &#039;changeformat&#039;=&amp;gt;0,&lt;br /&gt;
    &#039;context&#039;=&amp;gt;null,&lt;br /&gt;
    &#039;noclean&#039;=&amp;gt;0,&lt;br /&gt;
    &#039;trusttext&#039;=&amp;gt;0,&lt;br /&gt;
    &#039;enable_filemanagement&#039; =&amp;gt; true);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The option &#039;enable_filemanagement&#039; will display the file management button on true and remove it on false.&lt;br /&gt;
&lt;br /&gt;
To save the data if you don&#039;t care about files:&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$formdata = $mform-&amp;gt;get_data();&lt;br /&gt;
$text     = $formdata-&amp;gt;fieldname[&#039;text&#039;];&lt;br /&gt;
$format   = $formdata-&amp;gt;fieldname[&#039;format&#039;];&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Note: Because the text editor might be &amp;quot;Atto&amp;quot; (depending on user preferences) and Atto has an &amp;quot;autosave&amp;quot; feature - it requires that the combination of $PAGE-&amp;gt;url and this elementid are unique. If not, the autosaved text for a different form may be restored into this form.&lt;br /&gt;
&lt;br /&gt;
=== file ===&lt;br /&gt;
&lt;br /&gt;
File upload input box with browse button. In the form definition type&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;file&#039;, &#039;attachment&#039;, get_string(&#039;attachment&#039;, &#039;forum&#039;));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
after form submission and validation use&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
if ($data = $mform-&amp;gt;get_data()) {&lt;br /&gt;
      ...&lt;br /&gt;
    $mform-&amp;gt;save_files($destination_directory);&lt;br /&gt;
      ...&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
If there is no requirement to save the file, you can read the file contents directly into a string as follows...&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
    $mform-&amp;gt;get_file_content(&#039;attachment&#039;);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
If you need advanced settings such as required file, different max upload size or name of uploaded file&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$this-&amp;gt;set_upload_manager(new upload_manager(&#039;attachment&#039;, true, false, $COURSE, false, 0, true, true, false));&lt;br /&gt;
            $mform-&amp;gt;addElement(&#039;file&#039;, &#039;attachment&#039;, get_string(&#039;attachment&#039;, &#039;forum&#039;));&lt;br /&gt;
            $mform-&amp;gt;addRule(&#039;attachment&#039;, null, &#039;required&#039;);&lt;br /&gt;
&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
if ($data = $mform-&amp;gt;get_data()) {&lt;br /&gt;
      ...&lt;br /&gt;
    $mform-&amp;gt;save_files($destination_directory);&lt;br /&gt;
    $newfilename = $mform-&amp;gt;get_new_filename();&lt;br /&gt;
      ...&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
When porting old code it is also possible to use the upload manager directly for processing of uploaded files.&lt;br /&gt;
&lt;br /&gt;
Please note that if using set_upload_manager() it must be before addElement(&#039;file&#039;,..).&lt;br /&gt;
&lt;br /&gt;
{{Moodle 2.0}}&lt;br /&gt;
File uploading was rewritten in 2.0. Please see inline docs for now. This page will be updated when the new API stabilises.&lt;br /&gt;
&lt;br /&gt;
===filepicker===&lt;br /&gt;
{{Moodle 2.0}}&lt;br /&gt;
General replacement of &#039;&#039;file&#039;&#039; element.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;filepicker&#039;, &#039;userfile&#039;, get_string(&#039;file&#039;), null, array(&#039;maxbytes&#039; =&amp;gt; $maxbytes, &#039;accepted_types&#039; =&amp;gt; &#039;*&#039;));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
See also [[Using the File API in Moodle forms]]&lt;br /&gt;
&lt;br /&gt;
=== hidden ===&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;hidden&#039;, &#039;reply&#039;, &#039;yes&#039;);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A hidden element. Set the element name (in this case &#039;&#039;&#039;reply&#039;&#039;&#039;) to the stated value (in this case &#039;&#039;&#039;yes&#039;&#039;&#039;).&lt;br /&gt;
&lt;br /&gt;
=== html ===&lt;br /&gt;
You can add arbitrary HTML to your Moodle form:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;html&#039;, &#039;&amp;lt;div class=&amp;quot;qheader&amp;quot;&amp;gt;&#039;);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
See [http://moodle.org/mod/forum/discuss.php?d=126935 &amp;quot;Question: Can I put a moodleform inside a table td?&amp;quot;] for a concrete example.&lt;br /&gt;
&lt;br /&gt;
=== htmleditor &amp;amp; format ===&lt;br /&gt;
&lt;br /&gt;
These elements are now deprecated. Please use the [[#editor|editor]] field type instead.&lt;br /&gt;
&lt;br /&gt;
===modgrade===&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;modgrade&#039;, &#039;scale&#039;, get_string(&#039;grade&#039;), false);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
This is a custom element for selecting a grade for any activity module. The fourth argument is whether to include an option for no grade which has a value 0. This select box does include scales. The default is true, include no grade option.&lt;br /&gt;
&lt;br /&gt;
A helpbutton is automatically added.&lt;br /&gt;
&lt;br /&gt;
===modvisible===&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;modvisible&#039;, &#039;visible&#039;, get_string(&#039;visible&#039;));&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
This is a custom element for selecting a grade visibility in an activity mod update form.&lt;br /&gt;
&lt;br /&gt;
===password===&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;password&#039;, &#039;password&#039;, get_string(&#039;label&#039;), $attributes);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A password element. Fourth param is an array or string of attributes.&lt;br /&gt;
&lt;br /&gt;
===passwordunmask===&lt;br /&gt;
{{Moodle 1.9}}&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;passwordunmask&#039;, &#039;password&#039;, get_string(&#039;label&#039;), $attributes);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A password element with option to show the password in plaintext. Fourth param is an array or string of attributes.&lt;br /&gt;
&lt;br /&gt;
=== radio ===&lt;br /&gt;
{{Moodle 2.3}}&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$radioarray=array();&lt;br /&gt;
$radioarray[] =&amp;amp; $mform-&amp;gt;createElement(&#039;radio&#039;, &#039;yesno&#039;, &#039;&#039;, get_string(&#039;yes&#039;), 1, $attributes);&lt;br /&gt;
$radioarray[] =&amp;amp; $mform-&amp;gt;createElement(&#039;radio&#039;, &#039;yesno&#039;, &#039;&#039;, get_string(&#039;no&#039;), 0, $attributes);&lt;br /&gt;
$mform-&amp;gt;addGroup($radioarray, &#039;radioar&#039;, &#039;&#039;, array(&#039; &#039;), false);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Second param names the radio button and should be the same for each button in the group in order to toggle correctly. Third param would be the label for the form element but is generally ignored as this element will always be in a group which has it&#039;s own label. Fourth param is a string, a label to be displayed on the right of the element. The fifth is the value for this radio button. $attributes can be a string or an array of attributes.&lt;br /&gt;
&lt;br /&gt;
It is possible to add help to individual radio buttons but this requires a custom template to be defined for the group elements. See MDL-15571.&lt;br /&gt;
&lt;br /&gt;
Since 2.3 it cannot be statically called anymore, so we need to call createElement from $mform reference.&lt;br /&gt;
&lt;br /&gt;
==== setDefault ====&lt;br /&gt;
&lt;br /&gt;
To set the default for a radio button group as above use the following :&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;setDefault(&#039;yesno&#039;, 0);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This would make the default &#039;no&#039;.&lt;br /&gt;
&lt;br /&gt;
===select===&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;select&#039;, &#039;type&#039;, get_string(&#039;forumtype&#039;, &#039;forum&#039;), $FORUM_TYPES, $attributes);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The fourth param for this element is an array of options for the select box. The keys are the values for the option and the value of the array is the text for the option. The fifth param $attributes is optional, see text element for description of attributes param.&lt;br /&gt;
&lt;br /&gt;
It is also possible to create a select with certain options disabled, using [http://stackoverflow.com/questions/2138089/how-can-i-use-quickform-to-add-disabled-select-options/2150275#2150275 this technique].&lt;br /&gt;
&lt;br /&gt;
====multi-select====&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$select = $mform-&amp;gt;addElement(&#039;select&#039;, &#039;colors&#039;, get_string(&#039;colors&#039;), array(&#039;red&#039;, &#039;blue&#039;, &#039;green&#039;), $attributes);&lt;br /&gt;
$select-&amp;gt;setMultiple(true);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=====setSelected=====&lt;br /&gt;
&lt;br /&gt;
To set the default selected item in a select element, you can use the &#039;setSelected&#039; method. The &#039;setSelected&#039; can either get a value or an array of values.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$options = array(&lt;br /&gt;
    &#039;ff0000&#039; =&amp;gt; &#039;Red&#039;,&lt;br /&gt;
    &#039;00ff00&#039; =&amp;gt; &#039;Green&#039;,&lt;br /&gt;
    &#039;0000ff&#039; =&amp;gt; &#039;Blue&#039;&lt;br /&gt;
);&lt;br /&gt;
$select = $mform-&amp;gt;addElement(&#039;select&#039;, &#039;colors&#039;, get_string(&#039;colors&#039;), $options);&lt;br /&gt;
// This will select the colour blue.&lt;br /&gt;
$select-&amp;gt;setSelected(&#039;0000ff&#039;);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Or for multpi-selection:&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$skillsarray = array(&lt;br /&gt;
    &#039;val1&#039; =&amp;gt; &#039;Skill A&#039;,&lt;br /&gt;
    &#039;val2&#039; =&amp;gt; &#039;Skill B&#039;,&lt;br /&gt;
    &#039;val3&#039; =&amp;gt; &#039;Skill C&#039;&lt;br /&gt;
);&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;select&#039;, &#039;md_skills&#039;, get_string(&#039;skills&#039;, &#039;metadata&#039;), $skillsarray);&lt;br /&gt;
$mform-&amp;gt;getElement(&#039;md_skills&#039;)-&amp;gt;setMultiple(true);&lt;br /&gt;
// This will select the skills A and B.&lt;br /&gt;
$mform-&amp;gt;getElement(&#039;md_skills&#039;)-&amp;gt;setSelected(array(&#039;val1&#039;, &#039;val2&#039;));&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
However you probably don&#039;t want to do this. Instead you probably want to use setDefault, or set it using the form&#039;s setData method.&lt;br /&gt;
&lt;br /&gt;
===selectyesno===&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;selectyesno&#039;, &#039;maxbytes&#039;, get_string(&#039;maxattachmentsize&#039;, &#039;forum&#039;));&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
If you want a yes / no select box this one automatically translates itself and has value 1 for yes and 0 for no.&lt;br /&gt;
&lt;br /&gt;
===selectwithlink===&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$options = array();&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;selectwithlink&#039;, &#039;scaleid&#039;, get_string(&#039;scale&#039;), $options, null, &lt;br /&gt;
    array(&#039;link&#039; =&amp;gt; $CFG-&amp;gt;wwwroot.&#039;/grade/edit/scale/edit.php?courseid=&#039;.$COURSE-&amp;gt;id, &#039;label&#039; =&amp;gt; get_string(&#039;scalescustomcreate&#039;)));&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
select type element with options containing link&lt;br /&gt;
===static===&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;static&#039;, &#039;description&#039;, get_string(&#039;description&#039;, &#039;exercise&#039;),&lt;br /&gt;
    get_string(&#039;descriptionofexercise&#039;, &#039;exercise&#039;, $COURSE-&amp;gt;students));&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This is a static element. It should be used with care if it is used to display a static piece of text with a label. The third param is the label and the fourth is the static text itself.&lt;br /&gt;
&lt;br /&gt;
===submit, reset and cancel===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
//normally you use add_action_buttons instead of this code&lt;br /&gt;
$buttonarray=array();&lt;br /&gt;
$buttonarray[] = &amp;amp;$mform-&amp;gt;createElement(&#039;submit&#039;, &#039;submitbutton&#039;, get_string(&#039;savechanges&#039;));&lt;br /&gt;
$buttonarray[] = &amp;amp;$mform-&amp;gt;createElement(&#039;reset&#039;, &#039;resetbutton&#039;, get_string(&#039;revert&#039;));&lt;br /&gt;
$buttonarray[] = &amp;amp;$mform-&amp;gt;createElement(&#039;cancel&#039;);&lt;br /&gt;
$mform-&amp;gt;addGroup($buttonarray, &#039;buttonar&#039;, &#039;&#039;, array(&#039; &#039;), false);&lt;br /&gt;
$mform-&amp;gt;closeHeaderBefore(&#039;buttonar&#039;);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A &#039;Submit&#039; type element is a submit type form element which will submit the form. A &#039;Reset&#039; will not submit the form but will reset any changes the user has made to form contents. A &#039;Cancel&#039; element cancels form submission. You need to have a branch in your code before you check for get_data() to check if submission has been cancelled with is_cancelled(); See the example on the usage page.&lt;br /&gt;
&lt;br /&gt;
You should name your submit and reset buttons &#039;submitbutton&#039; and &#039;resetbutton&#039; or something similar (not &#039;submit&#039; and &#039;reset&#039;). This avoids problems in JavaScript of collisions between form element names and names of JavaScript methods of the form object.&lt;br /&gt;
&lt;br /&gt;
====add_action_buttons($cancel = true, $submitlabel=null);====&lt;br /&gt;
&lt;br /&gt;
You will normally use this helper function which is a method of moodleform to add all the &#039;action&#039; buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string(&#039;savechanges&#039;). Note the &#039;&#039;&#039;$this&#039;&#039;&#039; not &#039;&#039;&#039;$mform&#039;&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$this-&amp;gt;add_action_buttons();&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
===text===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;text&#039;, &#039;name&#039;, get_string(&#039;forumname&#039;, &#039;forum&#039;), $attributes);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
For a simple text element. Your fourth parameter here can be a string or array of attributes for the text element. The following are equivalent :&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$attributes=&#039;size=&amp;quot;20&amp;quot;&#039;;&lt;br /&gt;
$attributes=array(&#039;size&#039;=&amp;gt;&#039;20&#039;);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
 &lt;br /&gt;
Generally you are encouraged to use CSS instead of using attributes for styling.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
A format element can be used as a format select box. It will be non-selectable if you&#039;re using an html editor.&lt;br /&gt;
&lt;br /&gt;
The third param for this element is $useHtmlEditor and it defaults to null in which case an html editor is used if the browser and user profile support it.&lt;br /&gt;
&lt;br /&gt;
===textarea===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;textarea&#039;, &#039;introduction&#039;, get_string(&amp;quot;introtext&amp;quot;, &amp;quot;survey&amp;quot;), &#039;wrap=&amp;quot;virtual&amp;quot; rows=&amp;quot;20&amp;quot; cols=&amp;quot;50&amp;quot;&#039;);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A textarea element. If you want an htmleditor use htmleditor element. Fourth element here is a string or array of attributes.&lt;br /&gt;
&lt;br /&gt;
===recaptcha===&lt;br /&gt;
{{Moodle 1.9}}&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;recaptcha&#039;, &#039;recaptcha_field_name&#039;, $attributes);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Use this recaptcha element to reduce the spam risk in your forms. Third element here is a string or array of attributes. Take care to get an API key from http://recaptcha.net/api/getkey before using this element.&lt;br /&gt;
&lt;br /&gt;
To check whether recaptcha is enabled at site level use:&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
if (!empty($CFG-&amp;gt;recaptchapublickey) &amp;amp;&amp;amp; !empty($CFG-&amp;gt;recaptchaprivatekey)) {&lt;br /&gt;
    //recaptcha is enabled&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
===tags===&lt;br /&gt;
{{Moodle 2.0}}&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;tags&#039;, &#039;field_name&#039;, $lable, $options, $attributes);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Used for editing a list of tags, for example on a blog post.&lt;br /&gt;
&lt;br /&gt;
There is only one option available, &#039;display&#039;, which should be set to one of the contstants MoodleQuickForm_tags::ONLYOFFICIAL, NOOFFICIAL or DEFAULTUI. This controls whether the official tags are listed for easy selection, or a text area where arbitrary tags may be typed, or both. The default is both.&lt;br /&gt;
&lt;br /&gt;
The value should be set/returned as an array of tags.&lt;br /&gt;
&lt;br /&gt;
===grading===&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;grading&#039;, &#039;advancedgrading&#039;, get_string(&#039;grade&#039;).&#039;:&#039;, array(&#039;gradinginstance&#039; =&amp;gt; $gradinginstance));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Custom element for advanced grading plugins.&lt;br /&gt;
&lt;br /&gt;
When adding the &#039;grading&#039; element to the form, developer must pass an object of class gradingform_instance as $attributes[&#039;gradinginstance&#039;]. Otherwise an exception will be thrown.&lt;br /&gt;
&lt;br /&gt;
===questioncategory===&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;questioncategory&#039;, &#039;category&#039;, get_string(&#039;category&#039;, &#039;question&#039;),&lt;br /&gt;
    array(&#039;contexts&#039;=&amp;gt;$contexts, &#039;top&#039;=&amp;gt;true, &#039;currentcat&#039;=&amp;gt;$currentcat, &#039;nochildrenof&#039;=&amp;gt;$currentcat));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
Creates a drop down element to select a question category.&lt;br /&gt;
&lt;br /&gt;
Options are:&lt;br /&gt;
&#039;&#039;&#039;contexts&#039;&#039;&#039; - (required) context in which question appears&lt;br /&gt;
&#039;&#039;&#039;currentcat&#039;&#039;&#039; - (optional) course category&lt;br /&gt;
&#039;&#039;&#039;top&#039;&#039;&#039; - (optional) if true will put top categories on top&lt;br /&gt;
&#039;&#039;&#039;nochildrenof&#039;&#039;&#039; - (optional) Format categories into an indented list reflecting the tree structure&lt;br /&gt;
&lt;br /&gt;
==addGroup==&lt;br /&gt;
&lt;br /&gt;
A &#039;group&#039; in formslib is just a group of elements that will have a label and will be included on one line. &lt;br /&gt;
&lt;br /&gt;
For example typical code to include a submit and cancel button on the same line : &lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$buttonarray=array();&lt;br /&gt;
$buttonarray[] =&amp;amp; $mform-&amp;gt;createElement(&#039;submit&#039;, &#039;submitbutton&#039;, get_string(&#039;savechanges&#039;));&lt;br /&gt;
$buttonarray[] =&amp;amp; $mform-&amp;gt;createElement(&#039;submit&#039;, &#039;cancel&#039;, get_string(&#039;cancel&#039;));&lt;br /&gt;
$mform-&amp;gt;addGroup($buttonarray, &#039;buttonar&#039;, &#039;&#039;, array(&#039; &#039;), false);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
You use the same arguments for createElement as you do for addElement. Any label for the element in the third argument is normally ignored (but not in the case of the submit buttons above where the third argument is not for a label but is the text for the button).&lt;br /&gt;
&lt;br /&gt;
Here&#039;s a bad example (don&#039;t do this for real, use the &#039;optional&#039; =&amp;gt; true option of the date element): putting a date_selector (which is itself a group of elements) and a checkbox on the same line, note that you can disable every element in the group using the group name &#039;availablefromgroup&#039; but it doesn&#039;t disable the controlling element the &#039;availablefromenabled&#039; checkbox:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$availablefromgroup=array();&lt;br /&gt;
$availablefromgroup[] =&amp;amp; $mform-&amp;gt;createElement(&#039;date_selector&#039;, &#039;availablefrom&#039;, &#039;&#039;);&lt;br /&gt;
$availablefromgroup[] =&amp;amp; $mform-&amp;gt;createElement(&#039;checkbox&#039;, &#039;availablefromenabled&#039;, &#039;&#039;, get_string(&#039;enable&#039;));&lt;br /&gt;
$mform-&amp;gt;addGroup($availablefromgroup, &#039;availablefromgroup&#039;, get_string(&#039;availablefromdate&#039;, &#039;data&#039;), &#039;&amp;amp;nbsp;&#039;, false);&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;availablefromgroup&#039;, &#039;availablefromenabled&#039;);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
* If you want to put a group inside another array so that you can repeat items, use createElement instead of addGroup:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$group = $mform-&amp;gt;createElement(&#039;group&#039;, &#039;groupname&#039;, get_string(&#039;label&#039;), $groupitems);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
* By default, groups modify the names of elements inside them by appending a number. This is often unhelpful, for example if you want to use disabledIf on the element. To prevent this behaviour, set the last parameter to false when creating a group.:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$group = $mform-&amp;gt;createElement(&#039;group&#039;, &#039;groupname&#039;, get_string(&#039;label&#039;), $groupitems, null, false);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==addRule==&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addRule(&#039;elementname&#039;, get_string(&#039;error&#039;), &#039;rule type&#039;, &#039;extraruledata&#039;, &#039;server&#039;(default), false, false);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The first param(element) is an element name and second(message) is the error message that will be displayed to the user.&lt;br /&gt;
The third parameter(type) is the type of rule. The fourth param(format) is used for extra data needed with some rules such as minlength and regex. The fifth parameter(validation) validates input data on server or client side, if validation is done on client side then it will be checked on the server side as well.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
 * @param    string     $element       Form element name&lt;br /&gt;
 * @param    string     $message       Message to display for invalid data&lt;br /&gt;
 * @param    string     $type          Rule type, use getRegisteredRules() to get types&lt;br /&gt;
 * @param    string     $format        (optional)Required for extra rule data&lt;br /&gt;
 * @param    string     $validation    (optional)Where to perform validation: &amp;quot;server&amp;quot;, &amp;quot;client&amp;quot;&lt;br /&gt;
 * @param    boolean    $reset         Client-side validation: reset the form element to its original value if there is an error?&lt;br /&gt;
 * @param    boolean    $force         Force the rule to be applied, even if the target form element does not exist&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;Common Rule Types&#039;&#039;&#039;&lt;br /&gt;
* required &lt;br /&gt;
* maxlength&lt;br /&gt;
* minlength&lt;br /&gt;
* rangelength&lt;br /&gt;
* email&lt;br /&gt;
* regex&lt;br /&gt;
* lettersonly&lt;br /&gt;
* alphanumeric&lt;br /&gt;
* numeric&lt;br /&gt;
* nopunctuation&lt;br /&gt;
* nonzero&lt;br /&gt;
* callback&lt;br /&gt;
* compare&lt;br /&gt;
&lt;br /&gt;
===Server side and Client side===&lt;br /&gt;
In case you use the &#039;&#039;Client side&#039;&#039; validation option, you can mainly check for an empty or not input field. unless you write some &#039;&#039;Client side&#039;&#039; code which will probably be JavaScript functions to verify the data inside the input fields before it is submitted to the server. It could save some time if those functions are short, simple and quick to compute.&lt;br /&gt;
In case you need a more complex validation checks which relay on Moodle&#039;s internal PHP libraries (or other/external PHP libraries) you better use the &#039;&#039;Server side&#039;&#039; validation checks. Where you can query the DB, write complex PHP validation functions and much much more, that are not available (easily) when using JavaScript on the client&#039;s side.&lt;br /&gt;
&lt;br /&gt;
==setHelpButton==&lt;br /&gt;
{{Moodle 1.9}}&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;setHelpButton(&#039;lessondefault&#039;, array(&#039;lessondefault&#039;, get_string(&#039;lessondefault&#039;, &#039;lesson&#039;), &#039;lesson&#039;));&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
First param is an elementname and the second param is an array of params that are passed to helpbutton in weblib.php. Params are :&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
 * @param string $page  The keyword that defines a help page&lt;br /&gt;
 * @param string $title The title of links, rollover tips, alt tags etc&lt;br /&gt;
 *           &#039;Help with&#039; (or the language equivalent) will be prefixed and &#039;...&#039; will be stripped.&lt;br /&gt;
 * @param string $module Which module is the page defined in&lt;br /&gt;
 * @param mixed $image Use a help image for the link?  (true/false/&amp;quot;both&amp;quot;)&lt;br /&gt;
 * @param boolean $linktext If true, display the title next to the help icon.&lt;br /&gt;
 * @param string $text If defined then this text is used in the page, and&lt;br /&gt;
 *           the $page variable is ignored.&lt;br /&gt;
 * @param boolean $return If true then the output is returned as a string, if false it is printed to the current page.&lt;br /&gt;
 * @param string $imagetext The full text for the helpbutton icon. If empty use default help.gif&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
Make sure you don&#039;t set boolean $return to false. &lt;br /&gt;
&lt;br /&gt;
You need to do use this method after addElement();&lt;br /&gt;
&lt;br /&gt;
==addHelpButton==&lt;br /&gt;
{{Moodle 2.0}}&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addHelpButton(&#039;api_key_field&#039;, &#039;api_key&#039;, &#039;block_extsearch&#039;);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In Moodle 2.0 the &amp;quot;setHelpButton&amp;quot; method has been deprecated in favor of the &amp;quot;addHelpButton&amp;quot; method, which has a simplified interface and uses $OUTPUT-&amp;gt;help_icon() on the back end. The following parameters are expected:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
/**&lt;br /&gt;
 * @param $elementname The name of the form element to add the help button for&lt;br /&gt;
 * @param $identifier The identifier for the help string and its title (see below)&lt;br /&gt;
 * @param $component The component name to look for the help string in&lt;br /&gt;
 */&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
Unlike in Moodle 1.9, it is no longer necessary to put your help pages in separate HTML files. Instead, the function looks for two strings:&lt;br /&gt;
&lt;br /&gt;
# get_string($identifier, $component) // The title of the help page&lt;br /&gt;
# get_string(&amp;quot;{$identifier}_help&amp;quot;, $component) // The content of the help page&lt;br /&gt;
&lt;br /&gt;
So you will need to have &#039;&#039;&#039;$identifier&#039;&#039;&#039; and &#039;&#039;&#039;{$identifier}_help&#039;&#039;&#039; defined in order for the help button to be created properly. For example the multiple choice question editing form has a button for shuffling the answers. &lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addHelpButton(&#039;shuffleanswers&#039;, &#039;shuffleanswers&#039;, &#039;qtype_multichoice&#039;);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
and so the language file includes the strings&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$string[&#039;shuffleanswers&#039;] = &#039;Shuffle the choices?&#039;; &lt;br /&gt;
$string[&#039;shuffleanswers_help&#039;] = &#039;If enabled,.....&#039;;&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
You can also add the language string like&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$string[&#039;shuffleanswers_link&#039;] = &#039;question/shuffleanswers&#039;;&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
to add a link to more help on Moodle docs. See [[String_API]] for more information about help icons.&lt;br /&gt;
&lt;br /&gt;
==setDefault==&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;select&#039;, &#039;grade&#039;, get_string(&#039;gradeforsubmission&#039;, &#039;exercise&#039;), $grades);&lt;br /&gt;
$mform-&amp;gt;setHelpButton(&#039;grade&#039;, array(&#039;grade&#039;, get_string(&#039;gradeforsubmission&#039;, &#039;exercise&#039;), &#039;exercise&#039;));&lt;br /&gt;
$mform-&amp;gt;setDefault(&#039;grade&#039;, 100);&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Set the default of the form value with setDefault($elementname, $value); where elementname is the elementname whose default you want to set and $value is the default to set. We set the defaults for the form in definition(). This default is what is used if no data is loaded into the form with set_data(); eg. on display of the form for an &#039;add&#039; rather than &#039;update&#039; function.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
$mform-&amp;gt;addElement(&#039;editor&#039;, &#039;desc&#039;, get_string(&#039;description&#039;));     &lt;br /&gt;
$mform-&amp;gt;setDefault(&#039;desc&#039;, array(&#039;text&#039;=&amp;gt;$defaulttext));&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Note that when setting the default for an editor element you must use an array to define the default &amp;quot;text&amp;quot; value as shown above.&lt;br /&gt;
&lt;br /&gt;
==disabledIf==&lt;br /&gt;
&lt;br /&gt;
For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.&lt;br /&gt;
&lt;br /&gt;
You can use $mform-&amp;gt;disabledIf($elementName, $dependentOn, $condition = &#039;notchecked&#039;, $value=&#039;1&#039;)&lt;br /&gt;
&lt;br /&gt;
* elementname can be a group. If you specify a group all elements in the group will be disabled (if dependentOn is in elementname group that is ignored and not disabled). These are the element names you&#039;ve used as the second argument in addElement or addGroup.&lt;br /&gt;
* dependentOn is the actual name of the element as it will appear in html. This can be different to the name used in addGroup particularly but also addElement where you&#039;re adding a complex element like a date_selector. Check the html of your page. You typically make the depedentOn a checkbox or select box.&lt;br /&gt;
* $condition will be &#039;notchecked&#039;, &#039;checked&#039;, &#039;noitemselected&#039;, &#039;eq&#039;, &#039;in&#039; or, if it is anything else, we test for &#039;neq&#039;.&lt;br /&gt;
** If $condition is &#039;eq&#039; or &#039;neq&#039; then we check the value of the dependentOn field and check for equality (==) or nonequality (!=) in js&lt;br /&gt;
** If $condition is &#039;checked&#039; or &#039;notchecked&#039; then we check to see if a checkbox is checked or not.&lt;br /&gt;
** If $condition is &#039;in&#039; then we check to see if a selected item is in the given list or not. (This was introduced in Moodle 2.7+)&lt;br /&gt;
** If $condition is &#039;noitemselected&#039; then we check to see whether nothing is selected in a dropdown list.&lt;br /&gt;
&lt;br /&gt;
Examples:&lt;br /&gt;
 // Disable my control unless a checkbox is checked.&lt;br /&gt;
 $mform-&amp;gt;disabledIf(&#039;mycontrol&#039;, &#039;somecheckbox&#039;);&lt;br /&gt;
 &lt;br /&gt;
 // Disable my control if a checkbox &#039;&#039;&#039;is&#039;&#039;&#039; checked.&lt;br /&gt;
 $mform-&amp;gt;disabledIf(&#039;mycontrol&#039;, &#039;somecheckbox&#039;, &#039;checked&#039;);&lt;br /&gt;
 &lt;br /&gt;
 // Disable my control when a dropdown has value 42.&lt;br /&gt;
 $mform-&amp;gt;disabledIf(&#039;mycontrol&#039;, &#039;someselect&#039;, &#039;eq&#039;, 42);&lt;br /&gt;
&lt;br /&gt;
 // Disable my control unless a dropdown has value 42.&lt;br /&gt;
 $mform-&amp;gt;disabledIf(&#039;mycontrol&#039;, &#039;someselect&#039;, &#039;neq&#039;, 42);&lt;br /&gt;
&lt;br /&gt;
The possible choices here are in the dependency manager in lib/form/form.js.&lt;br /&gt;
===A tricky case===&lt;br /&gt;
&lt;br /&gt;
You need to take care with disabledIf if you plan to use it with groups of checkboxes.&lt;br /&gt;
&lt;br /&gt;
Let&#039;s say you have a group of 5 checkboxes and you want to enable a depending item such as a drop down menu only when the first and the last checkboxes are selected.&lt;br /&gt;
&lt;br /&gt;
To fix ideas:&lt;br /&gt;
&lt;br /&gt;
If the selection in the checkboxes group is:&lt;br /&gt;
&lt;br /&gt;
 mycheck_01 == 1&lt;br /&gt;
 mycheck_02 == 0&lt;br /&gt;
 mycheck_03 == 0&lt;br /&gt;
 mycheck_04 == 0&lt;br /&gt;
 mycheck_05 == 1&lt;br /&gt;
&lt;br /&gt;
the depending item must be enabled while ANY OTHER COMBINATION must disable the drop down menu.&lt;br /&gt;
&lt;br /&gt;
The following code will, apparently, fail:&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_01&#039;, &#039;neq&#039;, &#039;1&#039;);&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_02&#039;, &#039;neq&#039;, &#039;0&#039;);&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_03&#039;, &#039;neq&#039;, &#039;0&#039;);&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_04&#039;, &#039;neq&#039;, &#039;0&#039;);&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_05&#039;, &#039;neq&#039;, &#039;1&#039;);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In fact, once you get the drop down menu enabled, you are free to unselect mycheck_01 whilst still having the depending item enabled.&lt;br /&gt;
This apparent bug occurs because a non-checked checkbox behaves like a non existing mform element. So the js code will not find the element &amp;quot;mycheck_01&amp;quot; and will not apply the corresponding rule.&lt;br /&gt;
&lt;br /&gt;
A working solution for this kind of issue seems to be:&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_01&#039;, &#039;notchecked&#039;);&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_02&#039;, &#039;checked&#039;);&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_03&#039;, &#039;checked&#039;);&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_04&#039;, &#039;checked&#039;);&lt;br /&gt;
$mform-&amp;gt;disabledIf(&#039;dropdownmenu&#039;, &#039;mycheck_05&#039;, &#039;notchecked&#039;);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
To see a failing example as the one described, try the attachments provided in MDL-38975. See also in MDL-38975 for the working solution in action with modifications suggested by Eloy.&lt;br /&gt;
&lt;br /&gt;
==setType==&lt;br /&gt;
&lt;br /&gt;
PARAM_* types are used to specify how a submitted variable should be cleaned. These should be used for get parameters such as id, course etc. which are used to load a page and also with setType(); method. Every form element should have a type specified except select, radio box and checkbox elements, these elements do a good job of cleaning themselves (only specified options are allowed as user input).&lt;br /&gt;
&lt;br /&gt;
===Most Commonly Used PARAM_* Types===&lt;br /&gt;
&lt;br /&gt;
These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.&lt;br /&gt;
&lt;br /&gt;
* PARAM_CLEAN is deprecated and you should try to use a more specific type.&lt;br /&gt;
* PARAM_TEXT should be used for cleaning data that is expected to contain multi-lang content. It will strip all html tags. But will still let tags for multilang support through.&lt;br /&gt;
* PARAM_NOTAGS should be used for cleaning data that is expected to be plain text. It will strip *all* html type tags. It will *not* let tags for multilang support through. This should be used for instance for email addresses where no multilang support is appropriate.&lt;br /&gt;
* PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the html editor. Data from the editor is later cleaned before display using format_text() function. PARAM_RAW can also be used for data that is validated by some other way or printed by p() or s().&lt;br /&gt;
* PARAM_INT should be used for integers. PARAM_FLOAT is also available for decimal numbers but is not recommended for user input since it does not work for languages that use , as a decimal separator.&lt;br /&gt;
* PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.&lt;br /&gt;
&lt;br /&gt;
==disable_form_change_checker==&lt;br /&gt;
&lt;br /&gt;
By default, any Moodle form will pop-up an &amp;quot;Are you sure?&amp;quot; alert if you make some changes and then try to leave the page without saving. Occasionally, that is undesirable, in which case you can call&lt;br /&gt;
&lt;br /&gt;
 $mform-&amp;gt;disable_form_change_checker()&lt;br /&gt;
&lt;br /&gt;
==References==&lt;br /&gt;
&lt;br /&gt;
* [http://www.midnighthax.com/quickform.php PEAR HTML QuickForm Getting Started Guide] by Keith Edmunds of Midnighthax.com&lt;br /&gt;
* [http://pear.php.net/manual/en/package.html.html-quickform.php PEAR::HTML_QuickForm manual]&lt;br /&gt;
&lt;br /&gt;
[[Category:Formslib]]&lt;br /&gt;
[[Category:Interfaces]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
	<entry>
		<id>https://docs.moodle.org/dev/index.php?title=Adding_a_web_service_to_a_plugin&amp;diff=49239</id>
		<title>Adding a web service to a plugin</title>
		<link rel="alternate" type="text/html" href="https://docs.moodle.org/dev/index.php?title=Adding_a_web_service_to_a_plugin&amp;diff=49239"/>
		<updated>2016-01-19T15:41:28Z</updated>

		<summary type="html">&lt;p&gt;Tmuras: /* Making web service accessible through Apache Thrift */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;{{Moodle_2.0}}&lt;br /&gt;
&lt;br /&gt;
= Quick start =&lt;br /&gt;
== Example ==&lt;br /&gt;
Have a look to the [https://github.com/moodlehq/moodle-local_wstemplate web service plugin template]. This plugin contains a web service hello_world function. To make testing easy for you, the plugin is distributed with a test client in the folder /client.&lt;br /&gt;
== File structure ==&lt;br /&gt;
The file structure is explained in these two documents:&lt;br /&gt;
* [[Web_services_API|Web services API]]&lt;br /&gt;
* [[External_functions_API|External function API]]&lt;br /&gt;
&lt;br /&gt;
= Tutorial =&lt;br /&gt;
We will create a web service into a local plugin. This service will contain one &#039;&#039;local_myplugin_create_groups($groups)&#039;&#039; web service function. This web service function will create a group into a Moodle course.&lt;br /&gt;
&lt;br /&gt;
== Write the specification documentation ==&lt;br /&gt;
Before starting coding, let&#039;s identify our needs writing some short specification documents.&lt;br /&gt;
&lt;br /&gt;
=== functional specification===&lt;br /&gt;
&#039;&#039;local_myplugin_create_groups($groups)&#039;&#039; will take a list of groups as parameters and it will return the same groups with their newly created id. If ever one group creation fails, the function will throw an exception, and no creation will happen.&lt;br /&gt;
&lt;br /&gt;
=== technical specification ===&lt;br /&gt;
* &#039;&#039;&#039;the core function the external function will call&#039;&#039;&#039;:  &#039;&#039;groups_create_group()&#039;&#039; from [http://cvs.moodle.org/moodle/group/ /group/lib.php].&lt;br /&gt;
* &#039;&#039;&#039;the parameter types&#039;&#039;&#039;: a list of object. This object are groups, with id/name/courseid.&lt;br /&gt;
* &#039;&#039;&#039;the returned value types&#039;&#039;&#039;:  a list of objects (groups) with their id.&lt;br /&gt;
* &#039;&#039;&#039;the user capabilities to check&#039;&#039;&#039;: &#039;&#039;moodle/course:managegroups&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
== Write a simple test client ==&lt;br /&gt;
The first thing you should code is a web service test client. You will often discover use cases that you didn&#039;t think about. We are not showing any test client code here, see [[Creating_a_web_service_client|How to create a web service client]].&lt;br /&gt;
&lt;br /&gt;
== Declare the service ==&lt;br /&gt;
This step is optional. You can pre-build a service including any web service functions, so the Moodle administrator doesn&#039;t need to do it. Add into /local/myplugin/db/services.php:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
  $services = array(&lt;br /&gt;
      &#039;mypluginservice&#039; =&amp;gt; array(                                                //the name of the web service&lt;br /&gt;
          &#039;functions&#039; =&amp;gt; array (&#039;local_myplugin_create_groups&#039;), //web service functions of this service&lt;br /&gt;
          &#039;requiredcapability&#039; =&amp;gt; &#039;&#039;,                //if set, the web service user need this capability to access &lt;br /&gt;
                                                                              //any function of this service. For example: &#039;some/capability:specified&#039;                 &lt;br /&gt;
          &#039;restrictedusers&#039; =&amp;gt;0,                                             //if enabled, the Moodle administrator must link some user to this service&lt;br /&gt;
                                                                              //into the administration&lt;br /&gt;
          &#039;enabled&#039;=&amp;gt;1,                                                       //if enabled, the service can be reachable on a default installation&lt;br /&gt;
       )&lt;br /&gt;
  );&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Note: it is not possible for an administrator to add/remove any function from a pre-built service.&lt;br /&gt;
&lt;br /&gt;
== Declare the web service function ==&lt;br /&gt;
Following the [[Web_services_API|Web service API]], you must declare the web service function in the &#039;&#039;local/myplugin/db/services.php&#039;&#039; file. &lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
$functions = array(&lt;br /&gt;
    &#039;local_myplugin_create_groups&#039; =&amp;gt; array(         //web service function name&lt;br /&gt;
        &#039;classname&#039;   =&amp;gt; &#039;local_myplugin_external&#039;,  //class containing the external function&lt;br /&gt;
        &#039;methodname&#039;  =&amp;gt; &#039;create_groups&#039;,          //external function name&lt;br /&gt;
        &#039;classpath&#039;   =&amp;gt; &#039;local/myplugin/externallib.php&#039;,  //file containing the class/external function&lt;br /&gt;
        &#039;description&#039; =&amp;gt; &#039;Creates new groups.&#039;,    //human readable description of the web service function&lt;br /&gt;
        &#039;type&#039;        =&amp;gt; &#039;write&#039;,                  //database rights of the web service function (read, write)&lt;br /&gt;
    ),&lt;br /&gt;
);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Web service functions should match the [https://docs.moodle.org/dev/Web_services_Roadmap#Naming_convention naming convention].&lt;br /&gt;
&lt;br /&gt;
== Write the external function descriptions ==&lt;br /&gt;
Every web service function is mapped to an external function. External function are described in the [[External_functions_API|External functions API]].&lt;br /&gt;
Each external function is written with two other functions describing the parameters and the return values. These description functions are used by web service servers to:&lt;br /&gt;
* validate the web service function parameters&lt;br /&gt;
* validate the web service function returned values&lt;br /&gt;
* build WSDL files or other protocol documents &lt;br /&gt;
&lt;br /&gt;
These two description functions are located in the same file and the same class mentioned in local/myplugin/db/services.php.&lt;br /&gt;
&lt;br /&gt;
Thus for the web service function &#039;&#039;&#039;local_myplugin_create_groups()&#039;&#039;&#039;, we need write a class named &#039;&#039;&#039;local_myplugin_external&#039;&#039;&#039; in the file &#039;&#039;&#039;local/myplugin/externallib.php&#039;&#039;&#039;. The class will contain:&lt;br /&gt;
* create_groups(...)&lt;br /&gt;
* create_groups_parameters()&lt;br /&gt;
* create_groups_return()&lt;br /&gt;
&lt;br /&gt;
=== create_groups_parameters() ===&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
require_once(&amp;quot;$CFG-&amp;gt;libdir/externallib.php&amp;quot;);&lt;br /&gt;
&lt;br /&gt;
class local_myplugin_external extends external_api {&lt;br /&gt;
&lt;br /&gt;
    /**&lt;br /&gt;
     * Returns description of method parameters&lt;br /&gt;
     * @return external_function_parameters&lt;br /&gt;
     */&lt;br /&gt;
    public static function create_groups_parameters() {&lt;br /&gt;
        return new external_function_parameters(&lt;br /&gt;
            array(&lt;br /&gt;
                &#039;groups&#039; =&amp;gt; new external_multiple_structure(&lt;br /&gt;
                    new external_single_structure(&lt;br /&gt;
                        array(&lt;br /&gt;
                            &#039;courseid&#039; =&amp;gt; new external_value(PARAM_INT, &#039;id of course&#039;),&lt;br /&gt;
                            &#039;name&#039; =&amp;gt; new external_value(PARAM_TEXT, &#039;multilang compatible name, course unique&#039;),&lt;br /&gt;
                            &#039;description&#039; =&amp;gt; new external_value(PARAM_RAW, &#039;group description text&#039;),&lt;br /&gt;
                            &#039;enrolmentkey&#039; =&amp;gt; new external_value(PARAM_RAW, &#039;group enrol secret phrase&#039;),&lt;br /&gt;
                        )&lt;br /&gt;
                    )&lt;br /&gt;
                )&lt;br /&gt;
            )&lt;br /&gt;
        );&lt;br /&gt;
    }&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A web service function without parameters will have a parameter description function like that:&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
/**&lt;br /&gt;
     * Returns description of method parameters&lt;br /&gt;
     * @return external_function_parameters&lt;br /&gt;
     */&lt;br /&gt;
    public static function functionname_parameters() {&lt;br /&gt;
        return new external_function_parameters(&lt;br /&gt;
            array(&lt;br /&gt;
               //if I had any parameters, they would be described here. But I don&#039;t have any, so this array is empty.&lt;br /&gt;
            )&lt;br /&gt;
        );&lt;br /&gt;
    }&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
A parameter can be described as: &lt;br /&gt;
* a list               =&amp;gt; external_multiple_structure&lt;br /&gt;
* an object         =&amp;gt; external_single_structure&lt;br /&gt;
* a primary type =&amp;gt; external_value&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Our create_groups() function expects one parameter named &#039;&#039;groups&#039;&#039;, so we will first write:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
    /**&lt;br /&gt;
     * Returns description of method parameters&lt;br /&gt;
     * @return external_function_parameters&lt;br /&gt;
     */&lt;br /&gt;
    public static function create_groups_parameters() {&lt;br /&gt;
        return new external_function_parameters(&lt;br /&gt;
            array(&lt;br /&gt;
                &#039;groups&#039; =&amp;gt; ...&lt;br /&gt;
                &lt;br /&gt;
            )&lt;br /&gt;
        );&lt;br /&gt;
    }&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This &#039;&#039;groups&#039;&#039; parameter is a list of group. So we will write :&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;  &lt;br /&gt;
                &#039;groups&#039; =&amp;gt; new external_multiple_structure(&lt;br /&gt;
                    ...&lt;br /&gt;
                )          &lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
An external_multiple_structure object (list) can be constructed with: &lt;br /&gt;
* &#039;&#039;external_multiple_structure&#039;&#039; (list)&lt;br /&gt;
* &#039;&#039;external_single_structure&#039;&#039; (object)&lt;br /&gt;
* &#039;&#039;external_value&#039;&#039; (primary type). &lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
For our function it will be a &#039;&#039;external_single_structure&#039;&#039;: &lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;             &lt;br /&gt;
                    new external_single_structure(&lt;br /&gt;
                        array(&lt;br /&gt;
                            &#039;courseid&#039; =&amp;gt; ...,&lt;br /&gt;
                            &#039;name&#039; =&amp;gt; ...,&lt;br /&gt;
                            &#039;description&#039; =&amp;gt; ...,&lt;br /&gt;
                            &#039;enrolmentkey&#039; =&amp;gt; ...,&lt;br /&gt;
                        )&lt;br /&gt;
                    )           &lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Thus we obtain :&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;  &lt;br /&gt;
                &#039;groups&#039; =&amp;gt; new external_multiple_structure(&lt;br /&gt;
                    new external_single_structure(&lt;br /&gt;
                        array(&lt;br /&gt;
                            &#039;courseid&#039; =&amp;gt; ...,&lt;br /&gt;
                            &#039;name&#039; =&amp;gt; ...,&lt;br /&gt;
                            &#039;description&#039; =&amp;gt; ...,&lt;br /&gt;
                            &#039;enrolmentkey&#039; =&amp;gt; ...,&lt;br /&gt;
                        )&lt;br /&gt;
                    )&lt;br /&gt;
                )          &lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Each group values is a &#039;&#039;external_value&#039;&#039; (primary type):&lt;br /&gt;
* &#039;&#039;courseid&#039;&#039; is an integer&lt;br /&gt;
* &#039;&#039;name&#039;&#039; is a string (text only, not tag)&lt;br /&gt;
* &#039;&#039;description&#039;&#039; is a string (can be anything)&lt;br /&gt;
* &#039;&#039;enrolmentkey&#039;&#039; is also a string (can be anything) &lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
We add them to the description :&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;  &lt;br /&gt;
                &#039;groups&#039; =&amp;gt; new external_multiple_structure(&lt;br /&gt;
                    new external_single_structure(&lt;br /&gt;
                        array(&lt;br /&gt;
                            &#039;courseid&#039; =&amp;gt; new external_value(PARAM_INT, &#039;id of course&#039;), //the second argument is a human readable description text. This text is displayed in the automatically generated documentation.&lt;br /&gt;
                            &#039;name&#039; =&amp;gt; new external_value(PARAM_TEXT, &#039;multilang compatible name, course unique&#039;),&lt;br /&gt;
                            &#039;description&#039; =&amp;gt; new external_value(PARAM_RAW, &#039;group description text&#039;),&lt;br /&gt;
                            &#039;enrolmentkey&#039; =&amp;gt; new external_value(PARAM_RAW, &#039;group enrol secret phrase&#039;),&lt;br /&gt;
                        )&lt;br /&gt;
                    )&lt;br /&gt;
                )          &lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== create_groups_return() ===&lt;br /&gt;
&lt;br /&gt;
It&#039;s similar to create_groups_parameters(), but instead of describing the parameters, it describes the return values.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
public static function create_groups_returns() {&lt;br /&gt;
        return new external_multiple_structure(&lt;br /&gt;
            new external_single_structure(&lt;br /&gt;
                array(&lt;br /&gt;
                    &#039;id&#039; =&amp;gt; new external_value(PARAM_INT, &#039;group record id&#039;),&lt;br /&gt;
                    &#039;courseid&#039; =&amp;gt; new external_value(PARAM_INT, &#039;id of course&#039;),&lt;br /&gt;
                    &#039;name&#039; =&amp;gt; new external_value(PARAM_TEXT, &#039;multilang compatible name, course unique&#039;),&lt;br /&gt;
                    &#039;description&#039; =&amp;gt; new external_value(PARAM_RAW, &#039;group description text&#039;),&lt;br /&gt;
                    &#039;enrolmentkey&#039; =&amp;gt; new external_value(PARAM_RAW, &#039;group enrol secret phrase&#039;),&lt;br /&gt;
                )&lt;br /&gt;
            )&lt;br /&gt;
        );&lt;br /&gt;
    }&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Required, Optional or Default value ===&lt;br /&gt;
A value can be VALUE_REQUIRED, VALUE_OPTIONAL, or VALUE_DEFAULT. If not mentioned, a value is VALUE_REQUIRED by default.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;                 &lt;br /&gt;
                            &#039;yearofstudy&#039; =&amp;gt; new external_value(PARAM_INT, &#039;year of study&#039;,VALUE_DEFAULT, 1979),                        &lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
* VALUE_REQUIRED - if the value is not supplied =&amp;gt; the server throws an error message&lt;br /&gt;
* VALUE_OPTIONAL - if the value is not supplied =&amp;gt; the value is ignored. Note that VALUE_OPTIONAL can&#039;t be used in parameters, it must be used only in array/objects key definition. If you need Optional parameters you should use VALUE_DEFAULT instead.&lt;br /&gt;
* VALUE_DEFAULT   - if the value is not supplied =&amp;gt; the default value is used&lt;br /&gt;
&lt;br /&gt;
== Implement the external function ==&lt;br /&gt;
We declared our web service function and we defined the external function parameters and return values. We will now implement the external function:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
    /**&lt;br /&gt;
     * Create groups&lt;br /&gt;
     * @param array $groups array of group description arrays (with keys groupname and courseid)&lt;br /&gt;
     * @return array of newly created groups&lt;br /&gt;
     */&lt;br /&gt;
    public static function create_groups($groups) { //Don&#039;t forget to set it as static&lt;br /&gt;
        global $CFG, $DB;&lt;br /&gt;
        require_once(&amp;quot;$CFG-&amp;gt;dirroot/group/lib.php&amp;quot;);&lt;br /&gt;
&lt;br /&gt;
        $params = self::validate_parameters(self::create_groups_parameters(), array(&#039;groups&#039;=&amp;gt;$groups));&lt;br /&gt;
&lt;br /&gt;
        $transaction = $DB-&amp;gt;start_delegated_transaction(); //If an exception is thrown in the below code, all DB queries in this code will be rollback.&lt;br /&gt;
&lt;br /&gt;
        $groups = array();&lt;br /&gt;
&lt;br /&gt;
        foreach ($params[&#039;groups&#039;] as $group) {&lt;br /&gt;
            $group = (object)$group;&lt;br /&gt;
&lt;br /&gt;
            if (trim($group-&amp;gt;name) == &#039;&#039;) {&lt;br /&gt;
                throw new invalid_parameter_exception(&#039;Invalid group name&#039;);&lt;br /&gt;
            }&lt;br /&gt;
            if ($DB-&amp;gt;get_record(&#039;groups&#039;, array(&#039;courseid&#039;=&amp;gt;$group-&amp;gt;courseid, &#039;name&#039;=&amp;gt;$group-&amp;gt;name))) {&lt;br /&gt;
                throw new invalid_parameter_exception(&#039;Group with the same name already exists in the course&#039;);&lt;br /&gt;
            }&lt;br /&gt;
&lt;br /&gt;
            // now security checks&lt;br /&gt;
            $context = get_context_instance(CONTEXT_COURSE, $group-&amp;gt;courseid);&lt;br /&gt;
            self::validate_context($context);&lt;br /&gt;
            require_capability(&#039;moodle/course:managegroups&#039;, $context);&lt;br /&gt;
&lt;br /&gt;
            // finally create the group&lt;br /&gt;
            $group-&amp;gt;id = groups_create_group($group, false);&lt;br /&gt;
            $groups[] = (array)$group;&lt;br /&gt;
        }&lt;br /&gt;
&lt;br /&gt;
        $transaction-&amp;gt;allow_commit();&lt;br /&gt;
&lt;br /&gt;
        return $groups;&lt;br /&gt;
    }&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Parameter validation ===&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
 $params = self::validate_parameters(self::create_groups_parameters(), array(&#039;groups&#039;=&amp;gt;$groups));&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
This &#039;&#039;validate_parameters&#039;&#039; function validates the external function parameters against the description. It will return an exception if some required parameters are missing, if parameters are not well-formed, and check the parameters validity. It is essential that you do this call to avoid potential hack. &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;Important:&#039;&#039;&#039; the parameters of the external function and their declaration in the description &#039;&#039;&#039;must be the same order&#039;&#039;&#039;. In this example we have only one parameter named $groups, so we don&#039;t need to worry about the order.&lt;br /&gt;
&lt;br /&gt;
=== Context and Capability checks ===&lt;br /&gt;
&lt;br /&gt;
In a long term, in Moodle 2.0, all context/capability checks will disappear from the core functions and will be located into the external functions. Don&#039;t forget them.&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
/// now security checks&lt;br /&gt;
$context = get_context_instance(CONTEXT_COURSE, $group-&amp;gt;courseid);&lt;br /&gt;
self::validate_context($context);&lt;br /&gt;
require_capability(&#039;moodle/course:managegroups&#039;, $context);&lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Exceptions===&lt;br /&gt;
You can throw exceptions. There are automatically handle by Moodle web service servers.&lt;br /&gt;
&amp;lt;code php&amp;gt;&lt;br /&gt;
//Note: it is good practice to add detailled information in $debuginfo, &lt;br /&gt;
//         and only send back a generic exception message when Moodle DEBUG mode &amp;lt; NORMAL.&lt;br /&gt;
//         It&#039;s what we do here throwing the invalid_parameter_exception($debug) exception&lt;br /&gt;
throw new invalid_parameter_exception(&#039;Group with the same name already exists in the course&#039;); &lt;br /&gt;
&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Correct return values ===&lt;br /&gt;
The return values will be validated by the Moodle web service servers: &lt;br /&gt;
* return values contain some values not described =&amp;gt; these values will be skipped.&lt;br /&gt;
* return values miss some required values (VALUE_REQUIRED) =&amp;gt; the server will return an error.&lt;br /&gt;
* return values types don&#039;t match the description (int != PARAM_ALPHA) =&amp;gt; the server will return an error&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;Note:&#039;&#039;&#039; cast all your returned objects into arrays.&lt;br /&gt;
&lt;br /&gt;
== Making web service accessible through Apache Thrift ==&lt;br /&gt;
This step is optional. If you wish to generate SDK for different programming languages and platforms using [http://thrift.apache.org Apache Thrift framework] then [https://bitbucket.org/hhteam/moodle_thrift_tools/wiki/Home Moodle Thrift tools] can help you. &lt;br /&gt;
&lt;br /&gt;
Two steps should be performed: &lt;br /&gt;
&lt;br /&gt;
* Generate .thrift files for Moodle API using thriftgenerator script.&lt;br /&gt;
* Generate thrift handlers for PHP and copy the php files generated to your plugin source tree.&lt;br /&gt;
&lt;br /&gt;
It is also recommended to include thrift files into the distribution of your plugin in order to simplify creation of client bindings for the users of your API.&lt;br /&gt;
&lt;br /&gt;
That&#039;s it. Now the web API of your plugin is accessible through Apache Thrift Framework.&lt;br /&gt;
&lt;br /&gt;
== Bump the plugin version ==&lt;br /&gt;
Edit your local/myplugin/version.php and increase the plugin version. This should trigger a Moodle upgrade and the new web service should be available in the administration (&#039;&#039;Administration &amp;gt; Plugins &amp;gt; Web Services &amp;gt; Manage services&#039;&#039;)&lt;br /&gt;
&lt;br /&gt;
=See also=&lt;br /&gt;
* [[Web_services|Web services developer documentation]]&lt;br /&gt;
* [[:en:Web_services|Web services user documentation]]&lt;br /&gt;
* [[Creating_a_web_service_client|Implement a web service client]]&lt;br /&gt;
&lt;br /&gt;
Specification:&lt;br /&gt;
* [[External services security]]&lt;br /&gt;
* [[External services description]]&lt;br /&gt;
&lt;br /&gt;
[[Category:Web Services]]&lt;br /&gt;
[[Category:Plugins]]&lt;/div&gt;</summary>
		<author><name>Tmuras</name></author>
	</entry>
</feed>