MoodleDocs - User contributions [en]

Javascript Modules

2016-03-06T08:28:33Z

RussellEngland: /* Running grunt */

{{Moodle 2.9}}

= Javascript Modules =

== What is a Javascript module and why do I care? ==

A Javascript module is nothing more than a collection of Javascript code that can be used (reliably) from other pieces of Javascript.

== Why should I package my code as a module? ==

By packaging your code as a module you break your code up into smaller reusable pieces. This is good because:

a) Each smaller piece is simpler to understand / debug

b) Each smaller piece is simpler to test

c) You can re-use common code instead of duplicating it

= How do I write a Javascript module in Moodle? =

Since version 2.9, Moodle supports Javascript modules written using the Asynchronous Module Definition ([https://github.com/amdjs/amdjs-api/wiki/AMD AMD]) API. This is a standard API for creating Javascript modules and you will find many useful third party libraries that are already using this format.

To edit or create an AMD module in Moodle you need to do a couple of things.

== Install grunt ==

The AMD modules in Moodle must be processed by some build tools before they will be visible to your web browser. We use "[http://gruntjs.com/ grunt]" as a build tool to wrap our different processes. Grunt is a build tool written in Javascript that runs in the "[http://nodejs.org/ nodejs]" environment.

This means you first have to '''install nodejs''' - and its package manager [https://www.npmjs.com/ npm]. The details of how to install those packages will vary by operating system, but on Linux it's probably similar to "sudo apt-get install nodejs npm". There are downloadable packages for other operating systems here: http://nodejs.org/download/.

Once this is done, you can '''run the command''':

npm install
npm install -g grunt-cli

from the top of the Moodle directory to install all of the required tools. (You may need extra permissions to use the -g option.)

== Running grunt ==

See [[Grunt#Running_grunt]] for more details of specific grunt commands which can be used.

If you get the error message

/usr/bin/env: node: No such file or directory

Then see the thread https://github.com/nodejs/node-v0.x-archive/issues/3911

On Ubuntu 14.04 this fixed it for me:

sudo ln -fs /usr/bin/nodejs /usr/local/bin/node

== "Hello World" I am a Javascript Module ==
Lets now create a simple Javascript module so we can see how to lay things out.

Each Javascript module is contained in a single source file in the <componentdir>/amd/src folder. The final name of the module is taken from the file name and the component name. E.g. block_overview/amd/src/helloworld.js would be a module named "block_overview/helloworld". the name of the module is important when you want to call it from somewhere else in the code.

After running grunt - the minified Javascript files are stored in the <componentdir>/amd/build folder. The javascript files are renamed to show that they are minified (helloworld.js becomes helloworld.min.js).

Don't forget to add the built files (the ones in amd/build) to your git commits, or in production no-one will see your changes.

Lets create a simple module now:

blocks/overview/amd/src/helloworld.js
<code javascript>
// Standard license block omitted.
/*
* @package block_overview
* @copyright 2015 Someone cool
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

/**
* @module block_overview/helloworld
*/
define(['jquery'], function($) {

/**
* Give me blue.
* @access private
* @return {string}
*/
var makeItBlue = function() {
// We can use our jquery dependency here.
return $('.blue').show();
};

/**
* @constructor
* @alias module:block_overview/helloworld
*/
var greeting = function() {
/** @access private */
var privateThoughts = 'I like the colour blue';

/** @access public */
this.publicThoughts = 'I like the colour orange';

};

/**
* A formal greeting.
* @access public
* @return {string}
*/
greeting.prototype.formal = function() {
return 'How do you do?';
};

/**
* An informal greeting.
* @access public
* @return {string}
*/
greeting.prototype.informal = function() {
return 'Wassup!';
};
return greeting;
});
</code>

The most interesting line above is:
<code>
define(['jquery'], function($) {
</code>

All AMD modules must call "define()" as the first and only global scoped piece of code. This ensures the javascript code contains no global variables and will not conflict with any other loaded module. The name of the module does not need to be specified because it is determined from the filename and component (but it can be listed in a comment for JSDoc as shown here).

The first argument to "define" is the list of dependencies for the module. This argument must be passed as an array, even if there is only one. In this example "jquery" is a dependency. "jquery" is shipped as a core module is available to all AMD modules.

The second argument to "define" is the function that defines the module. This function will receive as arguments, each of the requested dependencies in the same order they were requested. In this example we receive JQuery as an argument and we name the variable "$" (it's a JQuery thing). We can then access JQuery normally through the $ variable which is in scope for any code in our module.

The rest of the code in this example is a standard way to define a Javascript module with public/private variables and methods. There are many ways to do this, this is only one.

It is important that we are returning 'greeting'. If there is no return then your module will be declared as undefined.

== Loading modules dynamically ==
What do you do if you don't know in advance which modules will be required? Stuffing all possible required modules in the define call is one solution, but it's ugly and it only works for code that is in an AMD module (what about inline code in the page?). AMD lets you load a dependency any time you like.
<code javascript>

// Load a new dependency.
require(['mod_wiki/timer'], function(timer) {
// timer is available to do my bidding.
});
</code>

== Including an external javascript/jquery library ==
If you want to include a javascript / jquery library downloaded from the internet you can do so as follows:

If the library is in AMD format and has a define:
e.g. i want to include the jquery final countdown timer on my page ( hilios.github.io/jQuery.countdown/ )
* download the module in both normal and minified versions
* place the modules in your moodle install e.g. your custom theme dir, or plugin dir
* /theme/mytheme/amd/src/jquery.countdown.js

you can now include the module and initialise it (there are multiple ways to do this)
php:
<code php>
// 1. Create your own amd module and initialise it:
$this->page->requires->js_call_amd('theme_mytheme/countdowntimer', 'initialise', $params);
</code>
javascript:
<code javascript>
//1. put this code in theme/mytheme/amd/src/countdowntimer.js
define(['jquery', 'theme_mytheme/jquery.countdown'], function($) {
return {
initialise: function ($params) {
$('#clock').countdown('2020/10/10', function(event) {
$(this).html(event.strftime('%D days %H:%M:%S'));
});
}
};
});
</code>

2. put the javascript into a mustache template
<code javascript>
// /theme/mytheme/templates/countdowntimer.mustache
<span id="clock"></span>
{{#js}}
require(['jquery', 'theme_mytheme/jquery.countdown'], function($) {
$('#clock').countdown('2020/10/10', function(event) {
$(this).html(event.strftime('%D days %H:%M:%S'));
});
});
{{/js}}
</code>

3. call the javascript directly from php -- although who would want to put javascript into php? ergh..
<code php>
$PAGE->requires->js_amd_inline('
require(['theme_mytheme/jquery.countdown'], function(min) {
$('#clock').countdown('2020/10/10', function(event) {
$(this).html(event.strftime('%D days %H:%M:%S'));
});
});
');
</code>

== Embedding AMD code in a page ==
So you have created lots of cool Javascript modules. Great. How do we actually call them? Any javascript code that calls an AMD module must execute AFTER the requirejs module loader has finished loading. We have provided a function "js_call_amd" that will call a single function from an AMD module with parameters.

<code php>
$PAGE->requires->js_call_amd($modulename, $functionname, $params);
</code>

that will "do the right thing" with your block of AMD code and execute it at the end of the page, after our AMD module loader has loaded.
Notes:
* the $modulename is the 'componentname/modulename' discussed above
* the $functionname is the name of a public function exposed by the amd module.
* the $params is an array of params passed as arguments to the function. These should be simple types that can be handled by json_encode (no recursive arrays, or complex classes please).
* if the size of the params array is too large (> 1Kb), this will produce a developer warning. Do not attempt to pass large amounts of data through this function, it will pollute the page size. A preferred approach is to pass css selectors for DOM elements that contain data-attributes for any required data, or fetch data via ajax in the background.

AMD / JS code can also be embedded on a page via mustache templates
see here: https://docs.moodle.org/dev/Templates#What_if_a_template_contains_javascript.3F

== But I have a mega JS file I don't want loaded on every page? ==
Loading all JS files at once and stuffing them in the browser cache is the right choice for MOST js files, there are probably some exceptions. For these files, you can rename the javascript file to end with the suffix "-lazy.js" which indicates that the module will not be loaded by default, it will be requested the first time it is used. There is no difference in usage for lazy loaded modules, the require() call looks exactly the same, it's just that the module name will also have the "-lazy" suffix.

[[Category:AJAX]]
[[Category:Javascript]]

Data manipulation API

2013-09-09T14:14:58Z

RussellEngland: /* SQL compatibility functions */

{{Moodle_2.0}}This page describes the functions available to access data in the Moodle database. You should '''exclusively''' use these functions in order to retrieve or modify database content because these functions provide a high level of abstraction and guarantee that your database manipulation will work against different RDBMSes.

Where possible, tricks and examples will be documented here in order to make developers' lives a bit easier. Of course, feel free to clarify, complete and add more information to this documentation. It will be welcome, absolutely!

== Main info ==

'''Important note:''' All the functions shown on this page are for use in '''Moodle 2.0 upwards''', where we changed the [[DB layer 2.0|DB layer]] to support some new features. If you need information for previous Moodle version, take a look to the [[DML functions - pre 2.0|DML functions - pre 2.0]] page. For a detailed reference of changes, see the [[DB layer 2.0 migration docs|migration docs]].

* All the function calls on this page are public methods of the $DB global object, so you'll need to "import" it within your functions (not needed in global scripts) with one simple:
<code php>global $DB;</code>
* The $DB global object is an instance of the moodle_database class, which is defined in [http://git.moodle.org/gw?p=moodle.git;a=blob;f=lib/dml/moodle_database.php;h=2a6676c84e7c77b0534f18a13ba584f58a8ed024;hb=refs/heads/master moodle_database.php]
* All the $table parameters in the functions are meant to be the table name ''without'' prefixes.
<code php>$user = $DB->get_record('user', array('id'=>'1'));</code>
* When using the xxx_sql() functions, table names must be enclosed between curly braces.
<code php>$user = $DB->get_record_sql('SELECT * FROM {user} WHERE id = ?', array(1));</code>
* All the $conditions parameters in the functions are arrays of fieldname=>fieldvalue elements.
<code php>$user = $DB->get_record('user', array('firstname'=>'Martin', 'lastname'=>'Dougiamas'));</code>
* All the $params parameters in the functions are arrays of values used to fill placeholders in SQL statements. Both the question mark and named placeholders can be used. Note that named params '''must be unique''' even if the value passed is the same.
<code php>
/// Question mark placeholders:
$DB->get_record_sql('SELECT * FROM {user} WHERE firstname = ? AND lastname = ?',
array('Martin', 'Dougiamas'));

/// Named placeholders:
$DB->get_record_sql('SELECT * FROM {user} WHERE firstname = :firstname AND lastname = :lastname',
array('firstname'=>'Martin', 'lastname'=>'Dougiamas'));
</code>

== The functions ==

===Getting a single record===

<code php>
o $DB->get_record($table, array $conditions, $fields='*', $strictness=IGNORE_MISSING)
/// Get a single database record as an object where all the given conditions met.
/// @param int $strictness IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found;
/// IGNORE_MULTIPLE means return first, ignore multiple records found(not recommended);
/// MUST_EXIST means throw exception if no record or multiple records found
o $DB->get_record_select($table, $select, array $params=null, $fields='*', $strictness=IGNORE_MISSING)
/// Get a single database record as an object which match a particular WHERE clause.
o $DB->get_record_sql($sql, array $params=null, $strictness=IGNORE_MISSING)
/// Get a single database record as an object using a SQL statement.
</code>

===Getting an hashed array of records===
Each of the following methods return an array of objects. The array is indexed by the first column of the fields returned by the query. Thus to assure consistent data, it appears to be best practice to ensure that your query include an "id column" as the first field. (When developing custom tables, be sure to make id your first column for this reason!)
<code php>
o $DB->get_records($table, array $conditions=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0)
/// Get a number of records as an array of objects where all the given conditions met.
o $DB->get_records_select($table, $select, array $params=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0)
/// Get a number of records as an array of objects which match a particular WHERE clause.
o $DB->get_records_sql($sql, array $params=null, $limitfrom=0, $limitnum=0)
/// Get a number of records as an array of objects using a SQL statement.
o $DB->get_records_list($table, $field, array $values, $sort='', $fields='*', $limitfrom='', $limitnum='')
/// Get a number of records as an array of objects where one field match one list of values.
</code>

===Getting data as key/value pairs in an associative array===
<code php>
o $DB->get_records_menu($table, array $conditions=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0)
/// Get the first two columns from a number of records as an associative array where all the given conditions met.
o $DB->get_records_select_menu($table, $select, array $params=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0)
/// Get the first two columns from a number of records as an associative array which match a particular WHERE clause.
o $DB->get_records_sql_menu($sql, array $params=null, $limitfrom=0, $limitnum=0)
/// Get the first two columns from a number of records as an associative array using a SQL statement.
</code>

===Seeing how many records match a given criterion===
<code php>
o $DB->count_records($table, array $conditions=null)
/// Count the records in a table where all the given conditions met.
o $DB->count_records_select($table, $select, array $params=null, $countitem="COUNT('x')")
/// Count the records in a table which match a particular WHERE clause.
o $DB->count_records_sql($sql, array $params=null)
/// Get the result of an SQL SELECT COUNT(...) query.
</code>

===Seeing if one record exists===
<code php>
o $DB->record_exists($table, array $conditions=null)
/// Test whether a record exists in a table where all the given conditions met.
o $DB->record_exists_select($table, $select, array $params=null)
/// Test whether any records exists in a table which match a particular WHERE clause.
o $DB->record_exists_sql($sql, array $params=null)
/// Test whether a SQL SELECT statement returns any records.
</code>

====Examples====
=====moodle_database::get_records()=====
Get a number of records as an array of objects where all the given conditions met.
<code php>
///Get all records where foo = bar
$result = $DB->get_records($table,array('foo'=>'bar'));

///Get all records where foo = bar and jon = doe
$result = $DB->get_records($table,array('foo' => 'bar' , 'jon' => 'doe'));

///Get all records where foo = bar, but only return the fields foo,bar,jon,doe
$result = $DB->get_records($table,array('foo'=>'bar'),null,'foo,bar,jon,doe');
///The previous example would cause data issues unless the 'foo' field happens to have unique values.
</code>

=====moodle_database::get_records_select()=====
Get a number of records as an array of objects which match a particular WHERE clause. Note that the array keys will be the id of the object so you must not rely on the first item having a key of 0.
<code php>
///Get all records where jon = 'doe' and bob is not = 'tom'
///The 'select' parameter is (if not empty) is dropped directly into the WHERE clause without alteration.
$table = 'foo';
$select = "jon = 'doe' AND bob <> 'tom'"; //is put into the where clause
$result = $DB->get_records_select($table,$select);
</code>

=====moodle_database::get_records_sql()=====
Get a number of records as an array of objects using a SQL statement. Defined as an abstract function in moodle_database, this method is implemented per database type.
<code php>
///Get all records from 'table' where foo = bar
$result = $DB->get_records_sql('SELECT * FROM {table} WHERE foo = ?', array('bar'));

///Get all records from 'table' where foo = 'bar' and bob = 'tom'
///This is somewhat similar to how Drupal makes its queries
$result = $DB->get_records_sql('SELECT * FROM {table} WHERE foo = ? AND bob = ?', array( 'bar' , 'tom' ));
</code>

=====moodle_database::get_records_list()=====
Get a number of records as an array of objects where one field match one list of values.
<code php>
///Get all records where the values('bar', 'elephant', 'moodle') are found in the field 'foo'
$result = $DB->get_records_list($table, 'foo', array( 'bar', 'elephant', 'moodle'));

///Get all records where the values('bar', 'elephant', 'moodle') are found in the field 'foo'
///Only returning the fields 'id', 'test' and 'taco'
$result = $DB->get_records_list($table, 'foo', array( 'bar', 'elephant', 'moodle'), null, 'id,test,taco');
</code>

=====moodle_database::get_records_menu()=====
Get the first two columns from a number of records as an associative array where all the given conditions met.
You can choose the two fields or leave the parameter blank and the method will return the first two columns of the table.
Returns an associative array.
<code php>
///Get all records from table 'foo' where column 'foo' is equal to the value 'bar'
$table = 'foo'; ///name of table
$conditions = array('foo'=>'bar'); ///the name of the field (key) and the desired value

$result = $DB->get_records_menu($table,$conditions));

///Get all records from table 'foo' where column 'foo' is equal to the value 'bar'
///Returning the values from the columns 'id' and 'tacos'
$table = 'foo'; ///name of table
$conditions = array('foo'=>'bar'); ///the name of the field (key) and the desired value
$sort = 'id'; //field or fields you want to sort the result by
$fields = 'id, tacos'; ///list of fields to return

$result = $DB->get_records_menu($table,$conditions,$sort,$fields)); //If you do not specify $fields, the first two columns of the table will be returned

</code>
The result of this last example will look something like:
<code php>
/// The value of the id field is 909 and the value of the 'tacos' column is 6
array(1) { [909]=6 }
</code>

=====moodle_database::get_records_select_menu()=====
Get the first two columns from a number of records as an associative array which match a particular WHERE clause.
<code php>
///Get all records where jon = 'doe' and bob is not = 'tom'
///The 'select' parameter is (if not empty) is dropped directly into the WHERE clause without alteration.
$table = 'foo';
$select = 'jon = "doe" AND bob != "tom" '; //is put into the where clause
$result = $DB->get_records_select_menu($table,$select);

$table = 'foo';
$select = 'jon = "doe" AND bob != "tom" '; //is put into the where clause
$params = null;
$fields = 'id, tacos';//return these fields
$sort = 'id'; //field or fields you want to sort the result by
$result = $DB->get_records_select_menu($table,$select,$params,$sort,$fields);
</code>

The result of this last example will look something like:
<code php>
/// The value of the id field is 909 and the value of the 'tacos' column is 6
array(1) { [909]=6 }
</code>

=====moodle_database::get_records_sql_menu()=====
Get the first two columns from a number of records as an associative array using a SQL statement.
<code php>
///Get all records from table foo where bar = 6
$sql = 'SELECT * FROM foo WHERE bar = ?';
$params = array(6);

$result = $DB->get_records_sql_menu($sql,$params);

///Get all records from table foo where bar = 6
$sql = 'SELECT id,tacos FROM foo WHERE bar = ?';
$params = array(6);

$result = $DB->get_records_sql_menu($sql,$params);

</code>

The result of this last example will look something like:
<code php>
/// The value of the id field is 909 and the value of the 'tacos' column is 6
array(1) { [909]=6 }
</code>

===Getting a particular field value from one record===
<code php>
o $DB->get_field($table, $return, array $conditions, $strictness=IGNORE_MISSING)
/// Get a single field value from a table record where all the given conditions met.
/// @param int $strictness
/// IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found;
/// IGNORE_MULTIPLE means return first, ignore multiple records found(not recommended);
/// MUST_EXIST means throw exception if no record or multiple records found
o $DB->get_field_select($table, $return, $select, array $params=null, $strictness=IGNORE_MISSING)
/// Get a single field value from a table record which match a particular WHERE clause.
o $DB->get_field_sql($sql, array $params=null, $strictness=IGNORE_MISSING)
/// Get a single field value (first field) using a SQL statement.
</code>

===Getting a particular field value from various records===

<code php>
o $DB->get_fieldset_select($table, $return, $select, array $params=null)
/// Selects records and return values of chosen field as an array which match a particular WHERE clause.
o $DB->get_fieldset_sql($sql, array $params=null)
/// Selects records and return values (first field) as an array using a SQL statement.
</code>

===Setting a particular field in the database===
<code php>
o $DB->set_field($table, $newfield, $newvalue, array $conditions=null)
/// Set a single field in every table record where all the given conditions met.
o $DB->set_field_select($table, $newfield, $newvalue, $select, array $params=null)
/// Set a single field in every table record which match a particular WHERE clause.
</code>

===Deleting Records===
<code php>
o $DB->delete_records($table, array $conditions=null)
/// Delete the records from a table where all the given conditions met.
o $DB->delete_records_select($table, $select, array $params=null)
/// Delete one or more records from a table which match a particular WHERE clause.
</code>

===Inserting Records===
The method to insert records is called aptly enough, insert_record(). The method accepts 4 parameters, but the fourth, "bulk", in most implementations is unused.
<code php>
o $DB->insert_record($table, $dataobject, $returnid=true, $bulk=false)
/// Insert a record into a table and return the "id" field if required.
</code>
====Example(s)====
<code php>
$record = new stdClass();
$record->name = 'overview';
$record->displayorder = '10000';
$DB->insert_record('quiz_report', $record, false);
</code>

<code php>
$record = new stdClass();
$record->name = 'overview';
$record->displayorder = '10000';
$lastinsertid = $DB->insert_record('quiz_report', $record);
</code>

===Updating Records===
<code php>
o $DB->update_record($table, $dataobject, $bulk=false)
/// Update a record in a table.
///
/// $dataobject is an object containing needed data
/// Relies on $dataobject having a variable "id" to
/// specify the record to update
///
/// @param string $table The database table to be checked against.
/// @param object $dataobject An object with contents equal to fieldname=>fieldvalue.
/// Must have an entry for 'id' to map to the table specified.
/// @param bool $bulk true means repeated updates expected
/// @return bool true
/// @throws dml_exception if an error occurs.
</code>

===Using Recordsets===

Where the number of records to be retrieved from DB is high, the '''get_records_xxx()''' functions above are far from optimal, because they load all the records in memory at the same time. Under those circumstances, it is highly recommended to use these '''get_recordset_xxx()''' functions instead, which use one nice mechanism to iterate over all the target records and save a lot of memory.

Only one thing is '''absolutely important''': Don't forget to close the recordsets after using them! (This will free up a lot of resources in the RDBMS).

Here is the general way to iterate over records using the '''get_recordset_xxx()''' functions:

<code php>
$rs = $DB->get_recordset(....) {
foreach ($rs as $record) {
// Do whatever you want with this record
}
$rs->close(); // Don't forget to close the recordset!
</code>

And this is the list of available functions (100% paired with the get_records_xxx() above):
<code php>
o $DB->get_recordset($table, array $conditions=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0)
/// Get a number of records as a moodle_recordset where all the given conditions met.
o $DB->get_recordset_select($table, $select, array $params=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0)
/// Get a number of records as a moodle_recordset which match a particular WHERE clause.
o $DB->get_recordset_sql($sql, array $params=null, $limitfrom=0, $limitnum=0);
/// Get a number of records as a moodle_recordset using a SQL statement.

o $DB->get_recordset_list($table, $field='', $values='', $sort='', $fields='*', $limitfrom='', $limitnum='')
/// Get a number of records as a moodle_recordset where one field matches one list of values.
</code>

Unlike get_record functions, you cannot use <tt>$rs == true</tt> or <tt>!empty($rs)</tt> to determine if any records were found.
Recordsets implement the standard PHP Iterator interface (http://uk.php.net/manual/en/class.iterator.php)

So,
<code php>
if ($rs->valid()) {
// The recordset contains records.
}
</code>

===Delegated transactions===

* Please note some databases do not support transactions (such as the MyISAM MySQL database engine), however all server administrators are strongly encouraged to migrate to databases that support transactions (such as the InnoDB MySQL database engine).
* Previous versions supported only one level of transaction. Since Moodle 2.0, the DML layer emulates delegated transactions that allow nesting of transactions.
* Transactions should not be used much in Moodle core; they are intended for various plugins such as web services, enrol and auth plugins.
* Some subsystems (such as messaging) do not support transactions because is it is not possible to rollback in external systems.

A transaction is started by:
<code php>
$transaction = $DB->start_delegated_transaction();
</code>

and finished by:
<code php>
$transaction->allow_commit();
</code>

Usually a transaction is rolled back when an exception is thrown. <code>$transaction->rollback($ex);</code> must be used very carefully because it might break compatibility with databases that do not support transactions. Transactions cannot be used as part of expected code flow; they can be used only as an emergency protection of data consistency.

See more details in [[DB layer 2.0 delegated transactions]] or MDL-20625.

====Example(s)====

<code php>
global $DB;
try {
$transaction = $DB->start_delegated_transaction();
// Insert a record
$DB->insert('foo', $object);
$DB->insert('bar', $otherobject);

// Assuming the both inserts work, we get to the following line.
$transaction->allow_commit();
} catch(Exception $e) {
$transaction->rollback($e);
}
</code>

===SQL compatibility functions===

In order have real cross-db compatibility, there are some helper functions used to build SQL fragments based on the DB Moodle is running. Using them we'll avoid conditional queries here and there and have those "incompatibilities" fixed once and for ever.
<code php>
o $DB->sql_bitand($int1, $int2)
/// Returns the SQL text to be used in order to perform one bitwise AND
/// operation between 2 integers.
o $DB->sql_bitnot($int1)
/// Returns the SQL text to be used in order to perform one bitwise NOT
/// operation with 1 integer.
o $DB->sql_bitor($int1, $int2)
/// Returns the SQL text to be used in order to perform one bitwise OR
/// operation between 2 integers.
o $DB->sql_bitxor($int1, $int2)
/// Returns the SQL text to be used in order to perform one bitwise XOR
/// operation between 2 integers.

o $DB->sql_null_from_clause()
/// Returns the FROM clause required by some DBs in all SELECT statements.

o $DB->sql_ceil($fieldname)
/// Returns the correct CEIL expression applied to fieldname.
o $DB->sql_like($fieldname, $param, $casesensitive = true, $accentsensitive = true, $notlike = false, $escapechar = ' \\ ')
/// Returns the proper SQL to do LIKE. For example:
$DB->get_records_sql('SELECT ... WHERE '.$DB->sql_like('idnumber', ':idnum').' ... ', array( 'idnum' => 'foo'));
/// Note: Use $DB->sql_like_escape(...) when its user input from a form.

o $DB->sql_length($fieldname)
/// Returns the SQL text to be used to calculate the length in characters of one expression.
o $DB->sql_modulo($int1, $int2)
/// Returns the SQL text to be used in order to calculate module - remainder after division
o $DB->sql_position($needle, $haystack)
/// Returns the SQL for returning searching one string for the location of another.
/// Note: If using placeholders BOTH in $needle and $haystack, they MUST be named placeholders.
o $DB->sql_substr($expr, $start, $length=false)
/// Returns the proper substr() SQL text used to extract substrings from DB.
/// Note: This fuction has changed in Moodle 2.0 and now at least 2 params are mandatory.
/// Note: Now it returns the whole SQL text to be used instead of only the function name.

o $DB->sql_cast_char2int($fieldname, $text=false)
/// Returns the SQL to be used in order to CAST one CHAR column to INTEGER.
o $DB->sql_cast_char2real($fieldname, $text=false)
/// Returns the SQL to be used in order to CAST one CHAR column to REAL number.

o $DB->sql_compare_text($fieldname, $numchars=32)
/// Returns the SQL text to be used to compare one TEXT (clob) column.
/// with one VARCHAR column.
o $DB->sql_order_by_text($fieldname, $numchars=32)
/// Returns the SQL text to be used to order by one TEXT (clob) column.

o $DB->sql_concat()
/// Returns the proper SQL to do CONCAT between the elements passed.
o $DB->sql_concat_join($separator="' '", $elements=array())
/// Returns the proper SQL to do CONCAT between the elements passed using one separator.
o $DB->sql_fullname($first='firstname', $last='lastname')
/// Returns the proper SQL to concatenate $firstname and $lastname.

o $DB->sql_isempty($tablename, $fieldname, $nullablefield, $textfield)
/// Returns the proper SQL to know if one field is empty.
o $DB->sql_isnotempty($tablename, $fieldname, $nullablefield, $textfield)
/// Returns the proper SQL to know if one field is not empty.
o $DB->sql_empty()
/// Returns the empty string char used by every supported DB.
</code>

===Debug fuctions===

If you execute
<code php>
$DB->set_debug(true)
</code>
then $DB will outout the SQL of every query executed, along with timing information. This can be useful when debugging your code. Obviously, all such calls should be removed before code is submitted for integration.

==See also==

* [[SQL coding style]]
* [[Core APIs]]
* [[DML exceptions|DML exceptions]]: New DML code is throwing exceptions instead of returning false if anything goes wrong
* [[DML drivers|DML drivers]]: Database drivers for new DML layer
* [[DML functions - pre 2.0|DML functions - pre 2.0]]: '''(deprecated!)''' For information valid before Moodle 2.0.
* [[DDL functions|DDL functions]]: Where all the functions used to handle DB objects ([[wikipedia:Data_Definition_Language|DDL]]) are defined.
* [[DB layer 2.0 examples|DB layer 2.0 examples]]: To see some code examples using various DML functions.
* [[DB layer 2.0 migration docs|DB layer 2.0 migration docs]]: Information about how to modify your code to work with the new Moodle 2.0 DB layer.
* [[DTL functions|DTL functions]]: Exporting, importing and moving of data stored in SQL databases

[[Category:DB]]
[[Category:XMLDB]]
[[Category:API]]

Data manipulation API

2013-09-09T14:13:59Z

RussellEngland: /* SQL compatibility functions */

{{Moodle_2.0}}This page describes the functions available to access data in the Moodle database. You should '''exclusively''' use these functions in order to retrieve or modify database content because these functions provide a high level of abstraction and guarantee that your database manipulation will work against different RDBMSes.

Where possible, tricks and examples will be documented here in order to make developers' lives a bit easier. Of course, feel free to clarify, complete and add more information to this documentation. It will be welcome, absolutely!

== Main info ==

'''Important note:''' All the functions shown on this page are for use in '''Moodle 2.0 upwards''', where we changed the [[DB layer 2.0|DB layer]] to support some new features. If you need information for previous Moodle version, take a look to the [[DML functions - pre 2.0|DML functions - pre 2.0]] page. For a detailed reference of changes, see the [[DB layer 2.0 migration docs|migration docs]].

* All the function calls on this page are public methods of the $DB global object, so you'll need to "import" it within your functions (not needed in global scripts) with one simple:
<code php>global $DB;</code>
* The $DB global object is an instance of the moodle_database class, which is defined in [http://git.moodle.org/gw?p=moodle.git;a=blob;f=lib/dml/moodle_database.php;h=2a6676c84e7c77b0534f18a13ba584f58a8ed024;hb=refs/heads/master moodle_database.php]
* All the $table parameters in the functions are meant to be the table name ''without'' prefixes.
<code php>$user = $DB->get_record('user', array('id'=>'1'));</code>
* When using the xxx_sql() functions, table names must be enclosed between curly braces.
<code php>$user = $DB->get_record_sql('SELECT * FROM {user} WHERE id = ?', array(1));</code>
* All the $conditions parameters in the functions are arrays of fieldname=>fieldvalue elements.
<code php>$user = $DB->get_record('user', array('firstname'=>'Martin', 'lastname'=>'Dougiamas'));</code>
* All the $params parameters in the functions are arrays of values used to fill placeholders in SQL statements. Both the question mark and named placeholders can be used. Note that named params '''must be unique''' even if the value passed is the same.
<code php>
/// Question mark placeholders:
$DB->get_record_sql('SELECT * FROM {user} WHERE firstname = ? AND lastname = ?',
array('Martin', 'Dougiamas'));

/// Named placeholders:
$DB->get_record_sql('SELECT * FROM {user} WHERE firstname = :firstname AND lastname = :lastname',
array('firstname'=>'Martin', 'lastname'=>'Dougiamas'));
</code>

== The functions ==

===Getting a single record===

<code php>
o $DB->get_record($table, array $conditions, $fields='*', $strictness=IGNORE_MISSING)
/// Get a single database record as an object where all the given conditions met.
/// @param int $strictness IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found;
/// IGNORE_MULTIPLE means return first, ignore multiple records found(not recommended);
/// MUST_EXIST means throw exception if no record or multiple records found
o $DB->get_record_select($table, $select, array $params=null, $fields='*', $strictness=IGNORE_MISSING)
/// Get a single database record as an object which match a particular WHERE clause.
o $DB->get_record_sql($sql, array $params=null, $strictness=IGNORE_MISSING)
/// Get a single database record as an object using a SQL statement.
</code>

===Getting an hashed array of records===
Each of the following methods return an array of objects. The array is indexed by the first column of the fields returned by the query. Thus to assure consistent data, it appears to be best practice to ensure that your query include an "id column" as the first field. (When developing custom tables, be sure to make id your first column for this reason!)
<code php>
o $DB->get_records($table, array $conditions=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0)
/// Get a number of records as an array of objects where all the given conditions met.
o $DB->get_records_select($table, $select, array $params=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0)
/// Get a number of records as an array of objects which match a particular WHERE clause.
o $DB->get_records_sql($sql, array $params=null, $limitfrom=0, $limitnum=0)
/// Get a number of records as an array of objects using a SQL statement.
o $DB->get_records_list($table, $field, array $values, $sort='', $fields='*', $limitfrom='', $limitnum='')
/// Get a number of records as an array of objects where one field match one list of values.
</code>

===Getting data as key/value pairs in an associative array===
<code php>
o $DB->get_records_menu($table, array $conditions=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0)
/// Get the first two columns from a number of records as an associative array where all the given conditions met.
o $DB->get_records_select_menu($table, $select, array $params=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0)
/// Get the first two columns from a number of records as an associative array which match a particular WHERE clause.
o $DB->get_records_sql_menu($sql, array $params=null, $limitfrom=0, $limitnum=0)
/// Get the first two columns from a number of records as an associative array using a SQL statement.
</code>

===Seeing how many records match a given criterion===
<code php>
o $DB->count_records($table, array $conditions=null)
/// Count the records in a table where all the given conditions met.
o $DB->count_records_select($table, $select, array $params=null, $countitem="COUNT('x')")
/// Count the records in a table which match a particular WHERE clause.
o $DB->count_records_sql($sql, array $params=null)
/// Get the result of an SQL SELECT COUNT(...) query.
</code>

===Seeing if one record exists===
<code php>
o $DB->record_exists($table, array $conditions=null)
/// Test whether a record exists in a table where all the given conditions met.
o $DB->record_exists_select($table, $select, array $params=null)
/// Test whether any records exists in a table which match a particular WHERE clause.
o $DB->record_exists_sql($sql, array $params=null)
/// Test whether a SQL SELECT statement returns any records.
</code>

====Examples====
=====moodle_database::get_records()=====
Get a number of records as an array of objects where all the given conditions met.
<code php>
///Get all records where foo = bar
$result = $DB->get_records($table,array('foo'=>'bar'));

///Get all records where foo = bar and jon = doe
$result = $DB->get_records($table,array('foo' => 'bar' , 'jon' => 'doe'));

///Get all records where foo = bar, but only return the fields foo,bar,jon,doe
$result = $DB->get_records($table,array('foo'=>'bar'),null,'foo,bar,jon,doe');
///The previous example would cause data issues unless the 'foo' field happens to have unique values.
</code>

=====moodle_database::get_records_select()=====
Get a number of records as an array of objects which match a particular WHERE clause. Note that the array keys will be the id of the object so you must not rely on the first item having a key of 0.
<code php>
///Get all records where jon = 'doe' and bob is not = 'tom'
///The 'select' parameter is (if not empty) is dropped directly into the WHERE clause without alteration.
$table = 'foo';
$select = "jon = 'doe' AND bob <> 'tom'"; //is put into the where clause
$result = $DB->get_records_select($table,$select);
</code>

=====moodle_database::get_records_sql()=====
Get a number of records as an array of objects using a SQL statement. Defined as an abstract function in moodle_database, this method is implemented per database type.
<code php>
///Get all records from 'table' where foo = bar
$result = $DB->get_records_sql('SELECT * FROM {table} WHERE foo = ?', array('bar'));

///Get all records from 'table' where foo = 'bar' and bob = 'tom'
///This is somewhat similar to how Drupal makes its queries
$result = $DB->get_records_sql('SELECT * FROM {table} WHERE foo = ? AND bob = ?', array( 'bar' , 'tom' ));
</code>

=====moodle_database::get_records_list()=====
Get a number of records as an array of objects where one field match one list of values.
<code php>
///Get all records where the values('bar', 'elephant', 'moodle') are found in the field 'foo'
$result = $DB->get_records_list($table, 'foo', array( 'bar', 'elephant', 'moodle'));

///Get all records where the values('bar', 'elephant', 'moodle') are found in the field 'foo'
///Only returning the fields 'id', 'test' and 'taco'
$result = $DB->get_records_list($table, 'foo', array( 'bar', 'elephant', 'moodle'), null, 'id,test,taco');
</code>

=====moodle_database::get_records_menu()=====
Get the first two columns from a number of records as an associative array where all the given conditions met.
You can choose the two fields or leave the parameter blank and the method will return the first two columns of the table.
Returns an associative array.
<code php>
///Get all records from table 'foo' where column 'foo' is equal to the value 'bar'
$table = 'foo'; ///name of table
$conditions = array('foo'=>'bar'); ///the name of the field (key) and the desired value

$result = $DB->get_records_menu($table,$conditions));

///Get all records from table 'foo' where column 'foo' is equal to the value 'bar'
///Returning the values from the columns 'id' and 'tacos'
$table = 'foo'; ///name of table
$conditions = array('foo'=>'bar'); ///the name of the field (key) and the desired value
$sort = 'id'; //field or fields you want to sort the result by
$fields = 'id, tacos'; ///list of fields to return

$result = $DB->get_records_menu($table,$conditions,$sort,$fields)); //If you do not specify $fields, the first two columns of the table will be returned

</code>
The result of this last example will look something like:
<code php>
/// The value of the id field is 909 and the value of the 'tacos' column is 6
array(1) { [909]=6 }
</code>

=====moodle_database::get_records_select_menu()=====
Get the first two columns from a number of records as an associative array which match a particular WHERE clause.
<code php>
///Get all records where jon = 'doe' and bob is not = 'tom'
///The 'select' parameter is (if not empty) is dropped directly into the WHERE clause without alteration.
$table = 'foo';
$select = 'jon = "doe" AND bob != "tom" '; //is put into the where clause
$result = $DB->get_records_select_menu($table,$select);

$table = 'foo';
$select = 'jon = "doe" AND bob != "tom" '; //is put into the where clause
$params = null;
$fields = 'id, tacos';//return these fields
$sort = 'id'; //field or fields you want to sort the result by
$result = $DB->get_records_select_menu($table,$select,$params,$sort,$fields);
</code>

The result of this last example will look something like:
<code php>
/// The value of the id field is 909 and the value of the 'tacos' column is 6
array(1) { [909]=6 }
</code>

=====moodle_database::get_records_sql_menu()=====
Get the first two columns from a number of records as an associative array using a SQL statement.
<code php>
///Get all records from table foo where bar = 6
$sql = 'SELECT * FROM foo WHERE bar = ?';
$params = array(6);

$result = $DB->get_records_sql_menu($sql,$params);

///Get all records from table foo where bar = 6
$sql = 'SELECT id,tacos FROM foo WHERE bar = ?';
$params = array(6);

$result = $DB->get_records_sql_menu($sql,$params);

</code>

The result of this last example will look something like:
<code php>
/// The value of the id field is 909 and the value of the 'tacos' column is 6
array(1) { [909]=6 }
</code>

===Getting a particular field value from one record===
<code php>
o $DB->get_field($table, $return, array $conditions, $strictness=IGNORE_MISSING)
/// Get a single field value from a table record where all the given conditions met.
/// @param int $strictness
/// IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found;
/// IGNORE_MULTIPLE means return first, ignore multiple records found(not recommended);
/// MUST_EXIST means throw exception if no record or multiple records found
o $DB->get_field_select($table, $return, $select, array $params=null, $strictness=IGNORE_MISSING)
/// Get a single field value from a table record which match a particular WHERE clause.
o $DB->get_field_sql($sql, array $params=null, $strictness=IGNORE_MISSING)
/// Get a single field value (first field) using a SQL statement.
</code>

===Getting a particular field value from various records===

<code php>
o $DB->get_fieldset_select($table, $return, $select, array $params=null)
/// Selects records and return values of chosen field as an array which match a particular WHERE clause.
o $DB->get_fieldset_sql($sql, array $params=null)
/// Selects records and return values (first field) as an array using a SQL statement.
</code>

===Setting a particular field in the database===
<code php>
o $DB->set_field($table, $newfield, $newvalue, array $conditions=null)
/// Set a single field in every table record where all the given conditions met.
o $DB->set_field_select($table, $newfield, $newvalue, $select, array $params=null)
/// Set a single field in every table record which match a particular WHERE clause.
</code>

===Deleting Records===
<code php>
o $DB->delete_records($table, array $conditions=null)
/// Delete the records from a table where all the given conditions met.
o $DB->delete_records_select($table, $select, array $params=null)
/// Delete one or more records from a table which match a particular WHERE clause.
</code>

===Inserting Records===
The method to insert records is called aptly enough, insert_record(). The method accepts 4 parameters, but the fourth, "bulk", in most implementations is unused.
<code php>
o $DB->insert_record($table, $dataobject, $returnid=true, $bulk=false)
/// Insert a record into a table and return the "id" field if required.
</code>
====Example(s)====
<code php>
$record = new stdClass();
$record->name = 'overview';
$record->displayorder = '10000';
$DB->insert_record('quiz_report', $record, false);
</code>

<code php>
$record = new stdClass();
$record->name = 'overview';
$record->displayorder = '10000';
$lastinsertid = $DB->insert_record('quiz_report', $record);
</code>

===Updating Records===
<code php>
o $DB->update_record($table, $dataobject, $bulk=false)
/// Update a record in a table.
///
/// $dataobject is an object containing needed data
/// Relies on $dataobject having a variable "id" to
/// specify the record to update
///
/// @param string $table The database table to be checked against.
/// @param object $dataobject An object with contents equal to fieldname=>fieldvalue.
/// Must have an entry for 'id' to map to the table specified.
/// @param bool $bulk true means repeated updates expected
/// @return bool true
/// @throws dml_exception if an error occurs.
</code>

===Using Recordsets===

Where the number of records to be retrieved from DB is high, the '''get_records_xxx()''' functions above are far from optimal, because they load all the records in memory at the same time. Under those circumstances, it is highly recommended to use these '''get_recordset_xxx()''' functions instead, which use one nice mechanism to iterate over all the target records and save a lot of memory.

Only one thing is '''absolutely important''': Don't forget to close the recordsets after using them! (This will free up a lot of resources in the RDBMS).

Here is the general way to iterate over records using the '''get_recordset_xxx()''' functions:

<code php>
$rs = $DB->get_recordset(....) {
foreach ($rs as $record) {
// Do whatever you want with this record
}
$rs->close(); // Don't forget to close the recordset!
</code>

And this is the list of available functions (100% paired with the get_records_xxx() above):
<code php>
o $DB->get_recordset($table, array $conditions=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0)
/// Get a number of records as a moodle_recordset where all the given conditions met.
o $DB->get_recordset_select($table, $select, array $params=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0)
/// Get a number of records as a moodle_recordset which match a particular WHERE clause.
o $DB->get_recordset_sql($sql, array $params=null, $limitfrom=0, $limitnum=0);
/// Get a number of records as a moodle_recordset using a SQL statement.

o $DB->get_recordset_list($table, $field='', $values='', $sort='', $fields='*', $limitfrom='', $limitnum='')
/// Get a number of records as a moodle_recordset where one field matches one list of values.
</code>

Unlike get_record functions, you cannot use <tt>$rs == true</tt> or <tt>!empty($rs)</tt> to determine if any records were found.
Recordsets implement the standard PHP Iterator interface (http://uk.php.net/manual/en/class.iterator.php)

So,
<code php>
if ($rs->valid()) {
// The recordset contains records.
}
</code>

===Delegated transactions===

* Please note some databases do not support transactions (such as the MyISAM MySQL database engine), however all server administrators are strongly encouraged to migrate to databases that support transactions (such as the InnoDB MySQL database engine).
* Previous versions supported only one level of transaction. Since Moodle 2.0, the DML layer emulates delegated transactions that allow nesting of transactions.
* Transactions should not be used much in Moodle core; they are intended for various plugins such as web services, enrol and auth plugins.
* Some subsystems (such as messaging) do not support transactions because is it is not possible to rollback in external systems.

A transaction is started by:
<code php>
$transaction = $DB->start_delegated_transaction();
</code>

and finished by:
<code php>
$transaction->allow_commit();
</code>

Usually a transaction is rolled back when an exception is thrown. <code>$transaction->rollback($ex);</code> must be used very carefully because it might break compatibility with databases that do not support transactions. Transactions cannot be used as part of expected code flow; they can be used only as an emergency protection of data consistency.

See more details in [[DB layer 2.0 delegated transactions]] or MDL-20625.

====Example(s)====

<code php>
global $DB;
try {
$transaction = $DB->start_delegated_transaction();
// Insert a record
$DB->insert('foo', $object);
$DB->insert('bar', $otherobject);

// Assuming the both inserts work, we get to the following line.
$transaction->allow_commit();
} catch(Exception $e) {
$transaction->rollback($e);
}
</code>

===SQL compatibility functions===

In order have real cross-db compatibility, there are some helper functions used to build SQL fragments based on the DB Moodle is running. Using them we'll avoid conditional queries here and there and have those "incompatibilities" fixed once and for ever.
<code php>
o $DB->sql_bitand($int1, $int2)
/// Returns the SQL text to be used in order to perform one bitwise AND
/// operation between 2 integers.
o $DB->sql_bitnot($int1)
/// Returns the SQL text to be used in order to perform one bitwise NOT
/// operation with 1 integer.
o $DB->sql_bitor($int1, $int2)
/// Returns the SQL text to be used in order to perform one bitwise OR
/// operation between 2 integers.
o $DB->sql_bitxor($int1, $int2)
/// Returns the SQL text to be used in order to perform one bitwise XOR
/// operation between 2 integers.

o $DB->sql_null_from_clause()
/// Returns the FROM clause required by some DBs in all SELECT statements.

o $DB->sql_ceil($fieldname)
/// Returns the correct CEIL expression applied to fieldname.
o $DB->sql_like($fieldname, $param, $casesensitive = true, $accentsensitive = true, $notlike = false, $escapechar = ' \\ ')
/// Returns the proper SQL to do LIKE. For example:
$DB->get_records_sql('SELECT ... WHERE '.$DB->sql_like('idnumber', ':idnum').' ... ', array( 'idnum' => 'foo'));
/// Use $DB->sql_like_escape(...) when its user input from a form.

o $DB->sql_length($fieldname)
/// Returns the SQL text to be used to calculate the length in characters of one expression.
o $DB->sql_modulo($int1, $int2)
/// Returns the SQL text to be used in order to calculate module - remainder after division
o $DB->sql_position($needle, $haystack)
/// Returns the SQL for returning searching one string for the location of another.
/// Note: If using placeholders BOTH in $needle and $haystack, they MUST be named placeholders.
o $DB->sql_substr($expr, $start, $length=false)
/// Returns the proper substr() SQL text used to extract substrings from DB.
/// Note: This fuction has changed in Moodle 2.0 and now at least 2 params are mandatory.
/// Note: Now it returns the whole SQL text to be used instead of only the function name.

o $DB->sql_cast_char2int($fieldname, $text=false)
/// Returns the SQL to be used in order to CAST one CHAR column to INTEGER.
o $DB->sql_cast_char2real($fieldname, $text=false)
/// Returns the SQL to be used in order to CAST one CHAR column to REAL number.

o $DB->sql_compare_text($fieldname, $numchars=32)
/// Returns the SQL text to be used to compare one TEXT (clob) column.
/// with one VARCHAR column.
o $DB->sql_order_by_text($fieldname, $numchars=32)
/// Returns the SQL text to be used to order by one TEXT (clob) column.

o $DB->sql_concat()
/// Returns the proper SQL to do CONCAT between the elements passed.
o $DB->sql_concat_join($separator="' '", $elements=array())
/// Returns the proper SQL to do CONCAT between the elements passed using one separator.
o $DB->sql_fullname($first='firstname', $last='lastname')
/// Returns the proper SQL to concatenate $firstname and $lastname.

o $DB->sql_isempty($tablename, $fieldname, $nullablefield, $textfield)
/// Returns the proper SQL to know if one field is empty.
o $DB->sql_isnotempty($tablename, $fieldname, $nullablefield, $textfield)
/// Returns the proper SQL to know if one field is not empty.
o $DB->sql_empty()
/// Returns the empty string char used by every supported DB.
</code>

===Debug fuctions===

If you execute
<code php>
$DB->set_debug(true)
</code>
then $DB will outout the SQL of every query executed, along with timing information. This can be useful when debugging your code. Obviously, all such calls should be removed before code is submitted for integration.

==See also==

* [[SQL coding style]]
* [[Core APIs]]
* [[DML exceptions|DML exceptions]]: New DML code is throwing exceptions instead of returning false if anything goes wrong
* [[DML drivers|DML drivers]]: Database drivers for new DML layer
* [[DML functions - pre 2.0|DML functions - pre 2.0]]: '''(deprecated!)''' For information valid before Moodle 2.0.
* [[DDL functions|DDL functions]]: Where all the functions used to handle DB objects ([[wikipedia:Data_Definition_Language|DDL]]) are defined.
* [[DB layer 2.0 examples|DB layer 2.0 examples]]: To see some code examples using various DML functions.
* [[DB layer 2.0 migration docs|DB layer 2.0 migration docs]]: Information about how to modify your code to work with the new Moodle 2.0 DB layer.
* [[DTL functions|DTL functions]]: Exporting, importing and moving of data stored in SQL databases

[[Category:DB]]
[[Category:XMLDB]]
[[Category:API]]

Setting up Netbeans

2013-08-27T08:34:47Z

RussellEngland: /* Needs updating */

[http://www.netbeans.org/features/php/index.html NetBeans] has got a good PHP support. You find a host of information on the website (tutorials, developer blog, screen casts, etc.).

== Features ==
* CVS integration: see all changes, lines deletion, diff in real time, show annotations, diff history...
* Ctrl+Click: Go to declaration
* Export/Import Diff Patch
* Easy navigation
* List of functions
* Code completion
* Instant rename
* HTML, CSS, JavaScript support
* MySQL manager
* Quick Search
* Very few bugs

== Installation ==

* Download the latest stable version from http://netbeans.org. Get the bundle that contains only PHP support.
* Install and run it.

== Set up for Moodle development ==

* Checkout your Moodle project with a '''CVS client''' - see [[:en:CVS for Administrators]] or [[CVS for developers|CVS for Developers]].

* Open File > New Project > PHP > PHP Application > Next
: You're going to set the project now. ''Name'', ''Location'' and ''Folder'' are used by NetBeans and are not related to the source code. So you can choose whatever you like, except your source folder. ''Sources'' has to be your checked out Moodle branch/head folder. The rest is clear enough. Don't forget to choose UTF-8 for ''Default Encoding''.

: Example:

Project Name: Moodle 1.9 Stable
Project Location: C:\Users\jerome\Documents\NetBeansProjects
Project Folder: C:\Users\jerome\Documents\NetBeansProjects\Moodle 1.9 Stable
Project Sources: C:\Users\jerome\Projects\branch19_STABLE\moodle
Project URL: http://localhost/moodle19/
Index File: index.php
Create: unchecked
Default Encoding: UTF-8
Set as Main Project: unchecked

* Click on Finish.

* Start coding!

== CVS with NetBeans ==

NetBeans comes with '''integrated CVS support''' which might be the easiest way to check out Moodle.

=== Anonymous checkout ===

# In NetBeans, select Window->Versioning->CVS->Checkout
# Select Team->CVS->Checkout
# Enter into CVS Root: '':pserver:anonymous@us.cvs.moodle.org:/cvsroot/moodle''
: (Non-US-residents might use one of the other [https://docs.moodle.org/en/CVS_for_Administrators#CVS_Servers Moodle CVS servers] nearer to them.)
# Click ''Next''
# Browse or enter into ''Module:'' moodle
# Browse or enter into ''Branch:'' MOODLE_19_STABLE
# Browse or enter into ''Local Folder:'' C:\xampp\htdocs
# Click ''Finish'' (and wait a few minutes for Moodle to be checked out)
# When you get the dialog box "Do you want to create an IDE project from the checked-out sources?", Click "Create Project..."
# Select PHP Application with Existing Sources, and click Next
# Browse or enter into ''Sources Folder'' C:\xampp\htdocs\moodle
# Enter into ''Project Name:'' moodle
# Keep the other defaults and click next
# ''Run As:'' should have selected ''Local Web Site (running on local web server)''
# Enter into Project URL http://localhost/moodle/
# Browse or enter into ''Index File:'' index.php
# Click ''Finish''

=== Checkout for developers with write access ===

As far as I can tell, there is no way to get NetBeans to work with CVS keys on Mac/Linux via the system SSH binary, so you will need to use the internal SSH and your password (which you can choose to save).

If you wish to use NetBeans CVS and have CVS write access, the procedure is as follows:

====Checkout of main Moodle codebase====

# Follow the above instructions except for point 3
# At part 3, substitute '':ext:yourusername'' for the part before the @ and remove the country code from after it, leaving it like this ''''':ext:yourusername'''@cvs.moodle.org:/cvsroot/moodle''
# Follow the rest of the instructions as above

If you wish to work with a plugin, you will need to check this out separately and add it to the Moodle code project you have just made. This because for some reason, the 'Do you want to create a project' option fails to show any of the files once you open it if you try to check out the plugin on its own (NetBeans 6.7.1 on a Mac).

====Checkout of contrib code====

# Follow the above steps up to point 3, and again substitute '':ext:yourusername'' and click 'next'. Note that you should not try to specify the full contrib repository path yet.
# Click 'Browse...' next to the 'Module' dialogue
# Find the plugin you wish to work with in CONTRIB
# Click 'OK'
# Proceed as before up to point 6, then press 'Close' when asked if you want to create a new project.
# Now navigate to the folder you earlier specified in the 'local folder' dialogue and you will find a folder marked 'contrib'.
# navigate to the plugin folder, copy that folder, and then navigate to your main Moodle project folder and paste it where it belongs.

Note that the last three points may cause you some grief when attempting to commit changes. CVS doesn't seem to like having subfolders with different origins. A workaround that operates well for me is to check out the contrib code manually into a folder using the command line as specified in the CVS for developers instructions, then import that code as a new project with existing sources. This allows easy commits and updates, whilst keeping it separate. You can then make a symlink from you main Moodle project to your contrib directory, restart NetBeans (the CVS info and symlink stuff is only refreshed on restart) and then right click the linked directory and choose 'Ignore', then do the same and choose 'Exclude from commit'. You can now use the code as if it were part of Moodle, still getting all the code completion stuff, and also do clean updates and commits from the secondary project. [[User:Matt Gibson|Matt Gibson]] 19:53, 6 June 2010 (UTC)

===Adding a branch to your plugin===
Your plugin will likely start with just a HEAD tag and at some point, you will want to branch it so that you can have versions for different Moodles. To add a MOODLE_20_STABLE branch, for example, do the following.

# Checkout as above, but use the MOODLE_20_STABLE branch instead of MOODLE_19_STABLE
# You will end up with an empty folder, which you copy into place as above.
# Find the folder in NetBeans, then right click and choose CVS->Merge changes from branch...
# Choose to merge from whatever branch has all the current code, using the help link if not sure what to do.

There is a small chance that the Merge link will not be there, in which case, you will have to copy the files into the directory by hand outside netbeans and then check them in. If you do this, make sure you don't copy over the 'CVS' folders that will have been made when you checked out the MOODLE_19_STABLE code.

=== A few warnings ===

Some of these warnings could also apply to other IDEs:

* If you want to delete a file from your computer but not from CVS, delete it from Windows Explorer/Nautilus/Finder. Otherwise your next commit could delete the file from CVS. <br/>In case you have already deleted a wrong file from NetBeans: with Windows Explorer/Nautilus/Finder, delete all the folder content of this deleted file (including the CVS folder) and update the folder.
* If you rename files and that other people are working on them, NetBeans could end up to mess up your CVS folder (even though that is quite rare). Then NetBeans CVS will refuse to update your code displaying a no explicit error as '''Update Failed'''. In this case, delete the content of the damaged folder with Windows Explorer/Nautilus/Finder. Then update this folder.
* If you create a patch or a new PHP file with NetBeans on Microsoft Windows, please check that it's a Unix format file. You may want to use another software to create Unix format patch/php files.

== Git with NetBeans ==

=== NBGit | Git Support for NetBeans ===

"NBGit is a module for the NetBeans IDE that adds support for working with the Git version control system. It uses the JGit library created as part of EGit to interact with Git repositories. Because the module is Java code all the way, it should work better cross-platform modulo platform specific differences, such as file system behavior. It is based on the NetBeans Mercurial module."
(http://nbgit.org)

<p class="note orange">
Unfortunately, the key word in that quote is '''should'''. In reality, because JGit is a rewrite from scratch of the tried-and-tested git core C code, it is still buggy, incomplete and unreliable. Therefore, the NetBeans and Eclipse git plugins are still only beta quality, and pretty sucky. Well, they mostly work for browsing the contents of the repository, but there is a small chance that if you use them for update operations, they will corrupt your repository. Hence, I am still doing git from the command-line.--[[User:Tim Hunt|Tim Hunt]] 11:11, 19 January 2010 (UTC)
</p>

=== Wiki page needs updating ===

Git is now integrated into Netbeans 7
https://netbeans.org/kb/70/ide/git.html

== Optimization ==

=== Sun JDK ===
1. You may want to run NetBeans with the Sun JDK. NetBeans seems to work a bit better with the [http://java.sun.com/javase/downloads/index.jsp Sun JDK]. You'll have to edit NetBeans config file. Open netbeans/etc/netbeans.conf. Then uncomment and edit:

netbeans_jdkhome="your_JDK_path"

2. To change the NetBeans look and feel run netbeans in the command line with this parameter:
"netbeans" --laf javax.swing.plaf.metal.MetalLookAndFeel

3. If NetBeans starts to slow down, give it more memory
"netbeans" -J-Xmx600m
See FAQ for more [http://wiki.netbeans.org/FaqSettingHeapSize details on memory optimisation].

=== ScanOnDemand ===
To prevent NetBeans from scanning the whole code with every start up you can use the following plug-in: http://wiki.netbeans.org/ScanOnDemand

== Coding faster ==

=== Coding standards ===

* There is NB config file available with the [https://github.com/enovation/moodle-utils/tree/master/netbeans-config Moodle coding settings]

=== Keyboard shortcuts ===
(Note: Some shortcuts might not work for PHP development.)
* [http://www.phpmag.ru/2009/01/23/extremely-usefull-netbeans-shortcuts/ Extremely Useful NetBeans Shortcuts]
* [http://netbeanside61.blogspot.com/2008/04/top-10-netbeans-ide-keyboard-shortcuts.html Top 10 NetBeans IDE Keyboard Shortcuts I use the most]
* [http://wiki.netbeans.org/KeymapProfileFor60 NetBeans IDE 6.x Keyboard Shortcuts Specification]

=== PHPUnit support ===
See [http://blogs.sun.com/netbeansphp/entry/recent_improvements_in_phpunit_support "Recent improvements in PHPUnit-support"] on how to use PHPUnit with NetBeans.

===JIRA support===
You can install the optional JIRA module in order to be able to interact with the Moodle Tracker from within NetBeans. This has the advantage of avoiding constantly switching back and forth from the browser and works quite well. Go to ''Tools->plugins->available plugins'' and search for JIRA. Once installed, right click 'issue trackers' in the 'services' pane to make a new tracker instance, then enter your details.

== See also: ==
Moodle forums
* [http://moodle.org/mod/forum/discuss.php?d=112972 NetBeans 6.5 for moodle/PHP/debugging is a better experience v.s Eclipse]

Online resources
* [http://www.netbeans.org/kb/trails/php.html NetBeans PHP Learning Trail]
* [http://wiki.netbeans.org/PHP NetBeans PHP Wiki]
* Sun's [http://blogs.sun.com/netbeansphp/ NetBeans PHP Team Blog]

Book
* [http://www.packtpub.com/netbeans-platform-6-8-developers-guide/book NetBeans Platform 6.8 Developer's Guide] by Jürgen Petri (March 2010), focus on Java and Swing

[[Category:Developer tools|NetBeans]]

Setting up Netbeans

2013-08-27T08:33:43Z

RussellEngland: /* NBGit | Git Support for NetBeans */

[http://www.netbeans.org/features/php/index.html NetBeans] has got a good PHP support. You find a host of information on the website (tutorials, developer blog, screen casts, etc.).

== Features ==
* CVS integration: see all changes, lines deletion, diff in real time, show annotations, diff history...
* Ctrl+Click: Go to declaration
* Export/Import Diff Patch
* Easy navigation
* List of functions
* Code completion
* Instant rename
* HTML, CSS, JavaScript support
* MySQL manager
* Quick Search
* Very few bugs

== Installation ==

* Download the latest stable version from http://netbeans.org. Get the bundle that contains only PHP support.
* Install and run it.

== Set up for Moodle development ==

* Checkout your Moodle project with a '''CVS client''' - see [[:en:CVS for Administrators]] or [[CVS for developers|CVS for Developers]].

* Open File > New Project > PHP > PHP Application > Next
: You're going to set the project now. ''Name'', ''Location'' and ''Folder'' are used by NetBeans and are not related to the source code. So you can choose whatever you like, except your source folder. ''Sources'' has to be your checked out Moodle branch/head folder. The rest is clear enough. Don't forget to choose UTF-8 for ''Default Encoding''.

: Example:

Project Name: Moodle 1.9 Stable
Project Location: C:\Users\jerome\Documents\NetBeansProjects
Project Folder: C:\Users\jerome\Documents\NetBeansProjects\Moodle 1.9 Stable
Project Sources: C:\Users\jerome\Projects\branch19_STABLE\moodle
Project URL: http://localhost/moodle19/
Index File: index.php
Create: unchecked
Default Encoding: UTF-8
Set as Main Project: unchecked

* Click on Finish.

* Start coding!

== CVS with NetBeans ==

NetBeans comes with '''integrated CVS support''' which might be the easiest way to check out Moodle.

=== Anonymous checkout ===

# In NetBeans, select Window->Versioning->CVS->Checkout
# Select Team->CVS->Checkout
# Enter into CVS Root: '':pserver:anonymous@us.cvs.moodle.org:/cvsroot/moodle''
: (Non-US-residents might use one of the other [https://docs.moodle.org/en/CVS_for_Administrators#CVS_Servers Moodle CVS servers] nearer to them.)
# Click ''Next''
# Browse or enter into ''Module:'' moodle
# Browse or enter into ''Branch:'' MOODLE_19_STABLE
# Browse or enter into ''Local Folder:'' C:\xampp\htdocs
# Click ''Finish'' (and wait a few minutes for Moodle to be checked out)
# When you get the dialog box "Do you want to create an IDE project from the checked-out sources?", Click "Create Project..."
# Select PHP Application with Existing Sources, and click Next
# Browse or enter into ''Sources Folder'' C:\xampp\htdocs\moodle
# Enter into ''Project Name:'' moodle
# Keep the other defaults and click next
# ''Run As:'' should have selected ''Local Web Site (running on local web server)''
# Enter into Project URL http://localhost/moodle/
# Browse or enter into ''Index File:'' index.php
# Click ''Finish''

=== Checkout for developers with write access ===

As far as I can tell, there is no way to get NetBeans to work with CVS keys on Mac/Linux via the system SSH binary, so you will need to use the internal SSH and your password (which you can choose to save).

If you wish to use NetBeans CVS and have CVS write access, the procedure is as follows:

====Checkout of main Moodle codebase====

# Follow the above instructions except for point 3
# At part 3, substitute '':ext:yourusername'' for the part before the @ and remove the country code from after it, leaving it like this ''''':ext:yourusername'''@cvs.moodle.org:/cvsroot/moodle''
# Follow the rest of the instructions as above

If you wish to work with a plugin, you will need to check this out separately and add it to the Moodle code project you have just made. This because for some reason, the 'Do you want to create a project' option fails to show any of the files once you open it if you try to check out the plugin on its own (NetBeans 6.7.1 on a Mac).

====Checkout of contrib code====

# Follow the above steps up to point 3, and again substitute '':ext:yourusername'' and click 'next'. Note that you should not try to specify the full contrib repository path yet.
# Click 'Browse...' next to the 'Module' dialogue
# Find the plugin you wish to work with in CONTRIB
# Click 'OK'
# Proceed as before up to point 6, then press 'Close' when asked if you want to create a new project.
# Now navigate to the folder you earlier specified in the 'local folder' dialogue and you will find a folder marked 'contrib'.
# navigate to the plugin folder, copy that folder, and then navigate to your main Moodle project folder and paste it where it belongs.

Note that the last three points may cause you some grief when attempting to commit changes. CVS doesn't seem to like having subfolders with different origins. A workaround that operates well for me is to check out the contrib code manually into a folder using the command line as specified in the CVS for developers instructions, then import that code as a new project with existing sources. This allows easy commits and updates, whilst keeping it separate. You can then make a symlink from you main Moodle project to your contrib directory, restart NetBeans (the CVS info and symlink stuff is only refreshed on restart) and then right click the linked directory and choose 'Ignore', then do the same and choose 'Exclude from commit'. You can now use the code as if it were part of Moodle, still getting all the code completion stuff, and also do clean updates and commits from the secondary project. [[User:Matt Gibson|Matt Gibson]] 19:53, 6 June 2010 (UTC)

===Adding a branch to your plugin===
Your plugin will likely start with just a HEAD tag and at some point, you will want to branch it so that you can have versions for different Moodles. To add a MOODLE_20_STABLE branch, for example, do the following.

# Checkout as above, but use the MOODLE_20_STABLE branch instead of MOODLE_19_STABLE
# You will end up with an empty folder, which you copy into place as above.
# Find the folder in NetBeans, then right click and choose CVS->Merge changes from branch...
# Choose to merge from whatever branch has all the current code, using the help link if not sure what to do.

There is a small chance that the Merge link will not be there, in which case, you will have to copy the files into the directory by hand outside netbeans and then check them in. If you do this, make sure you don't copy over the 'CVS' folders that will have been made when you checked out the MOODLE_19_STABLE code.

=== A few warnings ===

Some of these warnings could also apply to other IDEs:

* If you want to delete a file from your computer but not from CVS, delete it from Windows Explorer/Nautilus/Finder. Otherwise your next commit could delete the file from CVS. <br/>In case you have already deleted a wrong file from NetBeans: with Windows Explorer/Nautilus/Finder, delete all the folder content of this deleted file (including the CVS folder) and update the folder.
* If you rename files and that other people are working on them, NetBeans could end up to mess up your CVS folder (even though that is quite rare). Then NetBeans CVS will refuse to update your code displaying a no explicit error as '''Update Failed'''. In this case, delete the content of the damaged folder with Windows Explorer/Nautilus/Finder. Then update this folder.
* If you create a patch or a new PHP file with NetBeans on Microsoft Windows, please check that it's a Unix format file. You may want to use another software to create Unix format patch/php files.

== Git with NetBeans ==

=== NBGit | Git Support for NetBeans ===

"NBGit is a module for the NetBeans IDE that adds support for working with the Git version control system. It uses the JGit library created as part of EGit to interact with Git repositories. Because the module is Java code all the way, it should work better cross-platform modulo platform specific differences, such as file system behavior. It is based on the NetBeans Mercurial module."
(http://nbgit.org)

<p class="note orange">
Unfortunately, the key word in that quote is '''should'''. In reality, because JGit is a rewrite from scratch of the tried-and-tested git core C code, it is still buggy, incomplete and unreliable. Therefore, the NetBeans and Eclipse git plugins are still only beta quality, and pretty sucky. Well, they mostly work for browsing the contents of the repository, but there is a small chance that if you use them for update operations, they will corrupt your repository. Hence, I am still doing git from the command-line.--[[User:Tim Hunt|Tim Hunt]] 11:11, 19 January 2010 (UTC)
</p>

==== Needs updating ====

Git is now integrated into Netbeans 7
https://netbeans.org/kb/70/ide/git.html

== Optimization ==

=== Sun JDK ===
1. You may want to run NetBeans with the Sun JDK. NetBeans seems to work a bit better with the [http://java.sun.com/javase/downloads/index.jsp Sun JDK]. You'll have to edit NetBeans config file. Open netbeans/etc/netbeans.conf. Then uncomment and edit:

netbeans_jdkhome="your_JDK_path"

2. To change the NetBeans look and feel run netbeans in the command line with this parameter:
"netbeans" --laf javax.swing.plaf.metal.MetalLookAndFeel

3. If NetBeans starts to slow down, give it more memory
"netbeans" -J-Xmx600m
See FAQ for more [http://wiki.netbeans.org/FaqSettingHeapSize details on memory optimisation].

=== ScanOnDemand ===
To prevent NetBeans from scanning the whole code with every start up you can use the following plug-in: http://wiki.netbeans.org/ScanOnDemand

== Coding faster ==

=== Coding standards ===

* There is NB config file available with the [https://github.com/enovation/moodle-utils/tree/master/netbeans-config Moodle coding settings]

=== Keyboard shortcuts ===
(Note: Some shortcuts might not work for PHP development.)
* [http://www.phpmag.ru/2009/01/23/extremely-usefull-netbeans-shortcuts/ Extremely Useful NetBeans Shortcuts]
* [http://netbeanside61.blogspot.com/2008/04/top-10-netbeans-ide-keyboard-shortcuts.html Top 10 NetBeans IDE Keyboard Shortcuts I use the most]
* [http://wiki.netbeans.org/KeymapProfileFor60 NetBeans IDE 6.x Keyboard Shortcuts Specification]

=== PHPUnit support ===
See [http://blogs.sun.com/netbeansphp/entry/recent_improvements_in_phpunit_support "Recent improvements in PHPUnit-support"] on how to use PHPUnit with NetBeans.

===JIRA support===
You can install the optional JIRA module in order to be able to interact with the Moodle Tracker from within NetBeans. This has the advantage of avoiding constantly switching back and forth from the browser and works quite well. Go to ''Tools->plugins->available plugins'' and search for JIRA. Once installed, right click 'issue trackers' in the 'services' pane to make a new tracker instance, then enter your details.

== See also: ==
Moodle forums
* [http://moodle.org/mod/forum/discuss.php?d=112972 NetBeans 6.5 for moodle/PHP/debugging is a better experience v.s Eclipse]

Online resources
* [http://www.netbeans.org/kb/trails/php.html NetBeans PHP Learning Trail]
* [http://wiki.netbeans.org/PHP NetBeans PHP Wiki]
* Sun's [http://blogs.sun.com/netbeansphp/ NetBeans PHP Team Blog]

Book
* [http://www.packtpub.com/netbeans-platform-6-8-developers-guide/book NetBeans Platform 6.8 Developer's Guide] by Jürgen Petri (March 2010), focus on Java and Swing

[[Category:Developer tools|NetBeans]]

PHPUnit

2013-08-06T09:34:11Z

RussellEngland: link to phpunit manual

{{Moodle 2.3}}

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

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

=Installation of PHPUnit via Composer=

The installation procedure depends on your operating system.
* Check that /your/moodle/dirroot/composer.json exists and the contents are similar to
{
"require-dev": {
"phpunit/phpunit": "3.7.*",
"phpunit/dbUnit": "1.2.*"
}
}
* Install Composer dependency manager

cd /your/moodle/dirroot
curl -s https://getcomposer.org/installer | php

* Execute Composer installer

cd /your/moodle/dirroot
php composer.phar install --dev

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

php composer.phar install --dev --prefer-source

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

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

=Initialisation of test environment=

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

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

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

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

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

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

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

=Test execution=

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

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

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

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

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

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

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

The fastest way to run a single test is:

vendor/bin/phpunit my_test_class_name my/tests/filename.php

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

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

If you add annotations like

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

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

phpunit --group qtype_stack

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

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

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

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

Also, for commodity, you can use this command:

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

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

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

or, also

cd directory/with/phpunit.xml
phpunit

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

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

=PHPUnit support in IDEs=

* [http://www.phpsrc.org/projects/pti-phpunit/wiki/ Eclipse PHP Tool Integration]
* [http://blog.jetbrains.com/webide/2009/12/phpunit-support/ PHPStorm IDE]
* [http://netbeans.org/kb/docs/php/phpunit.html Netbeans]

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

[[Category:Unit testing]]

PHPUnit

2013-08-06T09:30:02Z

RussellEngland: Added contents of composer.json

{{Moodle 2.3}}

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

=Installation of PHPUnit via Composer=

The installation procedure depends on your operating system.
* Check that /your/moodle/dirroot/composer.json exists and the contents are similar to
{
"require-dev": {
"phpunit/phpunit": "3.7.*",
"phpunit/dbUnit": "1.2.*"
}
}
* Install Composer dependency manager

cd /your/moodle/dirroot
curl -s https://getcomposer.org/installer | php

* Execute Composer installer

cd /your/moodle/dirroot
php composer.phar install --dev

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

php composer.phar install --dev --prefer-source

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

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

=Initialisation of test environment=

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

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

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

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

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

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

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

=Test execution=

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

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

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

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

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

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

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

The fastest way to run a single test is:

vendor/bin/phpunit my_test_class_name my/tests/filename.php

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

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

If you add annotations like

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

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

phpunit --group qtype_stack

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

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

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

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

Also, for commodity, you can use this command:

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

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

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

or, also

cd directory/with/phpunit.xml
phpunit

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

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

=PHPUnit support in IDEs=

* [http://www.phpsrc.org/projects/pti-phpunit/wiki/ Eclipse PHP Tool Integration]
* [http://blog.jetbrains.com/webide/2009/12/phpunit-support/ PHPStorm IDE]
* [http://netbeans.org/kb/docs/php/phpunit.html Netbeans]

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

[[Category:Unit testing]]

CodeSniffer

2013-02-07T01:04:53Z

RussellEngland: /* Linux set up */

{{Moodle 2.0}}

==Overview==

===Scope===
This document describes the CodeSniffing/Code checker tools their purpose and usage.

===Function===
The function of the CodeSniffer tool is to analyse PHP5 (only) code, apply a set of rules that match the [[Coding_style | Moodle Coding Style]], and output a report showing which parts of the code do not conform to this style.

==Usage==

===Using codechecker===

codechecker is a local plugin that creates a web based interface for checking the syntax of a given file. It can be found at
https://github.com/moodlehq/moodle-local_codechecker

Once installed a new codechecker option will appear in site administration\development page.

This page allows for the code in a specified directory to be checked, e.g. if you wanted to check the code for the shortanswer question type you would enter
/question/type/shortanswer

You would then be presented with a list of the count of files processed and any warnings or errors.

===Installing codechecker===

To install using git, type this command in the root of your Moodle install
git clone git://github.com/moodlehq/moodle-local_codechecker.git local/codechecker

Then edit .gitignore in your development folder eg:
gedit /var/www/moodle/.gitignore

And add /local/codechecker/ - including the slash at the end

Alternatively, download the zip from

https://github.com/moodlehq/moodle-local_codechecker/zipball/master

unzip it into the local folder, and then rename the new folder to codechecker.

===Codechecker output===

The output is similar to the following

Files found: 21

question\type\calculated\backup\moodle1\lib.php - 1 error(s) and 10 warning(s)
then a list of all files checked with a count of errors and warnings..followed by a summary
Total: 31 error(s) and 262 warning(s)

Then a list describing the exact issue in each file

<nowiki>question\type\calculated\backup\moodle1\lib.php

2: The opening <?php tag must be followed by exactly one newline.
········//·convert·and·write·the·answers·first
50: Inline comments must start with a capital letter, digit or 3-dots sequence
etc etc

</nowiki>You can then edit the files to attempt to remove each issue.

===IDE plugin alternatives===

Using the web based interface means switching between the browser and the editing environment. You may find it easier to use a plugin that allows you to check your code against the standards as you go along.

For Eclipse users
http://www.phpsrc.org/

For Netbeans users

Make sure you have the PEAR php Codesniffer code installed, you can find instructions at
http://pear.php.net/package/PHP_CodeSniffer/download/All

Then install the netbeans plugin which can be found at

https://github.com/beberlei/netbeans-php-enhancements/downloads

Once installed you can check it within Netbeans by going to
Tools/Options/PHP and click on the codesniffer tab.

====Windows set up====

There is an option for the codesniffer script. On my windows xampp install this needs to point to

C:\xampp\php\phpcs.bat

Underneath this should be a list of some of the coding standards available, but by default this will probably not include Moodle. To install the moodle standards copy the moodle folder from local\codechecker into your standards directory which for me was under

php\PEAR\PHP\CodeSniffer\Standards

[[Image:codesniffer.jpg]]

Now when you restart your Netbeans you should see a new moodle coding standard. Right clicking on a file name should present you with a new option of "Show Code Standard Violations".

====Linux set up====

After installing codesniffer and codechecker, copy the moodle standards folder from (assuming you have the code in /local/codechecker)

/var/www/moodle/local/codechecker/moodle

to

/usr/share/php/PHP/CodeSniffer/Standards/moodle

I changed the moodle standard in Netbeans - as described for Windows set up - but it didn't work for me.

There is an option to set the default standard in a configuration file :

phpcs --config-set default_standard moodle

But this gave me an error - its a known bug that should be fixed in the next release of codesniffer http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=470294

To work around it, simply create the required folder then re-run the default setting

cd /usr/share/php/data
sudo mkdir PHP_CodeSniffer
phpcs --config-set default_standard moodle

Then re-started Netbeans and it works! I also noticed that I can now switch between coding standards.

===Simple example===
The script is located in lib/pear/PHP and is called runsniffer. To check the syntax of a given file (e.g. index.php), run:

<code>
lib/pear/PHP/runsniffer index.php
</code>

You will get a report that looks like this:

<code>
--------------------------------------------------------------------------------
FOUND 139 ERROR(S) AND 24 WARNING(S) AFFECTING 130 LINE(S)
--------------------------------------------------------------------------------
1 | WARNING | $Id$ tag is no longer required, please remove.
28 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | A cast statement must be followed by a single space
55 | ERROR | line indented incorrectly; expected 0 spaces, found 4
....
</code>

The first column shows the line at which the ERROR or WARNING was found. The CodeSniffer uses a set of rules which are still being defined, so that what is currently defined as ERROR or WARNING is likely to change in the near future.

You should fix all ERRORs, but may safely ignore the WARNINGs. Fixing warnings will help your code be even more readable and consistent with other code that follow this standard.

===Advanced Usage===
====Ignoring warnings====
You can run the CodeSniffer with the -n flag to ignore warnings:

<code>
lib/pear/PHP/runsniffer -n index.php
</code>

Resulting output:
<code>
--------------------------------------------------------------------------------
FOUND 139 ERROR(S) AFFECTING 125 LINE(S)
--------------------------------------------------------------------------------
28 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | line indented incorrectly; expected 0 spaces, found 4
...
</code>

====Recursive analysis====
If you give the name of a folder instead of a file, it will search, analyse and report on all PHP files found in this folder and all its subfolders. This will produce a full report for each PHP file. Since this is likely to be too much information, you may want to print only a summary report, by using the following syntax (search the files/ folder as an example):

<code>
lib/pear/PHP/runsniffer --report=summary files
</code>

Report:
<code>
PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE ERRORS WARNINGS
--------------------------------------------------------------------------------
/web/htdocs/moodle_blog2/files/index.php 11 58
/web/htdocs/moodle_blog2/files/draftfiles.php 6 22
--------------------------------------------------------------------------------
A TOTAL OF 17 ERROR(S) AND 80 WARNING(S) WERE FOUND IN 2 FILE(S)
--------------------------------------------------------------------------------
</code>

You can also use the -n flag to ignore warnings.

====Several files in one folder====
If you want to search all files under a folder, but not recurse through the subfolders, you can use the -l flag (local files only):

<code>
lib/pear/PHP/runsniffer --report=summary -l grade

PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE ERRORS WARNINGS
--------------------------------------------------------------------------------
/web/htdocs/moodle_blog2/grade/index.php 0 2
/web/htdocs/moodle_blog2/grade/lib.php 6 210
/web/htdocs/moodle_blog2/grade/querylib.php 5 39
--------------------------------------------------------------------------------
A TOTAL OF 11 ERROR(S) AND 251 WARNING(S) WERE FOUND IN 3 FILE(S)
--------------------------------------------------------------------------------
</code>

You can pass as many files and folders to the script as you want, the analysis and flags will apply to all of them.

===Special rules===
When recursing through folders, the CodeSniffer script looks for a file called thirdpartylibs.xml. Currently there is only one, found under lib/. It lists directories and files which are meant to stay 'as-is' in Moodle, in order to ensure minimum hassle when upgrading these libraries. You can use this file as a template to create your own list of exceptions.

===Other report formats===
CodeSniffer can export its reports in the following formats:
#full: default, shown first above
#summary: also shown above
#xml: Simple XML format
#csv: Comma-separated list
#checkstyle: XML format intended for use with CruiseControl

==See also==

#[[Coding]]
#[[Coding style]]

CodeSniffer

2013-02-07T01:04:11Z

RussellEngland: /* IDE plugin alternatives */

{{Moodle 2.0}}

==Overview==

===Scope===
This document describes the CodeSniffing/Code checker tools their purpose and usage.

===Function===
The function of the CodeSniffer tool is to analyse PHP5 (only) code, apply a set of rules that match the [[Coding_style | Moodle Coding Style]], and output a report showing which parts of the code do not conform to this style.

==Usage==

===Using codechecker===

codechecker is a local plugin that creates a web based interface for checking the syntax of a given file. It can be found at
https://github.com/moodlehq/moodle-local_codechecker

Once installed a new codechecker option will appear in site administration\development page.

This page allows for the code in a specified directory to be checked, e.g. if you wanted to check the code for the shortanswer question type you would enter
/question/type/shortanswer

You would then be presented with a list of the count of files processed and any warnings or errors.

===Installing codechecker===

To install using git, type this command in the root of your Moodle install
git clone git://github.com/moodlehq/moodle-local_codechecker.git local/codechecker

Then edit .gitignore in your development folder eg:
gedit /var/www/moodle/.gitignore

And add /local/codechecker/ - including the slash at the end

Alternatively, download the zip from

https://github.com/moodlehq/moodle-local_codechecker/zipball/master

unzip it into the local folder, and then rename the new folder to codechecker.

===Codechecker output===

The output is similar to the following

Files found: 21

question\type\calculated\backup\moodle1\lib.php - 1 error(s) and 10 warning(s)
then a list of all files checked with a count of errors and warnings..followed by a summary
Total: 31 error(s) and 262 warning(s)

Then a list describing the exact issue in each file

<nowiki>question\type\calculated\backup\moodle1\lib.php

2: The opening <?php tag must be followed by exactly one newline.
········//·convert·and·write·the·answers·first
50: Inline comments must start with a capital letter, digit or 3-dots sequence
etc etc

</nowiki>You can then edit the files to attempt to remove each issue.

===IDE plugin alternatives===

Using the web based interface means switching between the browser and the editing environment. You may find it easier to use a plugin that allows you to check your code against the standards as you go along.

For Eclipse users
http://www.phpsrc.org/

For Netbeans users

Make sure you have the PEAR php Codesniffer code installed, you can find instructions at
http://pear.php.net/package/PHP_CodeSniffer/download/All

Then install the netbeans plugin which can be found at

https://github.com/beberlei/netbeans-php-enhancements/downloads

Once installed you can check it within Netbeans by going to
Tools/Options/PHP and click on the codesniffer tab.

====Windows set up====

There is an option for the codesniffer script. On my windows xampp install this needs to point to

C:\xampp\php\phpcs.bat

Underneath this should be a list of some of the coding standards available, but by default this will probably not include Moodle. To install the moodle standards copy the moodle folder from local\codechecker into your standards directory which for me was under

php\PEAR\PHP\CodeSniffer\Standards

[[Image:codesniffer.jpg]]

Now when you restart your Netbeans you should see a new moodle coding standard. Right clicking on a file name should present you with a new option of "Show Code Standard Violations".

====Linux set up====

After installing codesniffer and codechecker, copy the moodle standards folder from (assuming you have the code in /local/codechecker)

/var/www/moodle/local/codechecker/moodle

to

/usr/share/php/PHP/CodeSniffer/Standards/moodle

I changed the moodle standard in Netbeans - as described above - but it didn't work for me.

There is an option to set the default standard in a configuration file :

phpcs --config-set default_standard moodle

But this gave me an error - its a known bug that should be fixed in the next release of codesniffer http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=470294

To work around it, simply create the required folder then re-run the default setting

cd /usr/share/php/data
sudo mkdir PHP_CodeSniffer
phpcs --config-set default_standard moodle

Then re-started Netbeans and it works! I also noticed that I can now switch between coding standards.

===Simple example===
The script is located in lib/pear/PHP and is called runsniffer. To check the syntax of a given file (e.g. index.php), run:

<code>
lib/pear/PHP/runsniffer index.php
</code>

You will get a report that looks like this:

<code>
--------------------------------------------------------------------------------
FOUND 139 ERROR(S) AND 24 WARNING(S) AFFECTING 130 LINE(S)
--------------------------------------------------------------------------------
1 | WARNING | $Id$ tag is no longer required, please remove.
28 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | A cast statement must be followed by a single space
55 | ERROR | line indented incorrectly; expected 0 spaces, found 4
....
</code>

The first column shows the line at which the ERROR or WARNING was found. The CodeSniffer uses a set of rules which are still being defined, so that what is currently defined as ERROR or WARNING is likely to change in the near future.

You should fix all ERRORs, but may safely ignore the WARNINGs. Fixing warnings will help your code be even more readable and consistent with other code that follow this standard.

===Advanced Usage===
====Ignoring warnings====
You can run the CodeSniffer with the -n flag to ignore warnings:

<code>
lib/pear/PHP/runsniffer -n index.php
</code>

Resulting output:
<code>
--------------------------------------------------------------------------------
FOUND 139 ERROR(S) AFFECTING 125 LINE(S)
--------------------------------------------------------------------------------
28 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | line indented incorrectly; expected 0 spaces, found 4
...
</code>

====Recursive analysis====
If you give the name of a folder instead of a file, it will search, analyse and report on all PHP files found in this folder and all its subfolders. This will produce a full report for each PHP file. Since this is likely to be too much information, you may want to print only a summary report, by using the following syntax (search the files/ folder as an example):

<code>
lib/pear/PHP/runsniffer --report=summary files
</code>

Report:
<code>
PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE ERRORS WARNINGS
--------------------------------------------------------------------------------
/web/htdocs/moodle_blog2/files/index.php 11 58
/web/htdocs/moodle_blog2/files/draftfiles.php 6 22
--------------------------------------------------------------------------------
A TOTAL OF 17 ERROR(S) AND 80 WARNING(S) WERE FOUND IN 2 FILE(S)
--------------------------------------------------------------------------------
</code>

You can also use the -n flag to ignore warnings.

====Several files in one folder====
If you want to search all files under a folder, but not recurse through the subfolders, you can use the -l flag (local files only):

<code>
lib/pear/PHP/runsniffer --report=summary -l grade

PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE ERRORS WARNINGS
--------------------------------------------------------------------------------
/web/htdocs/moodle_blog2/grade/index.php 0 2
/web/htdocs/moodle_blog2/grade/lib.php 6 210
/web/htdocs/moodle_blog2/grade/querylib.php 5 39
--------------------------------------------------------------------------------
A TOTAL OF 11 ERROR(S) AND 251 WARNING(S) WERE FOUND IN 3 FILE(S)
--------------------------------------------------------------------------------
</code>

You can pass as many files and folders to the script as you want, the analysis and flags will apply to all of them.

===Special rules===
When recursing through folders, the CodeSniffer script looks for a file called thirdpartylibs.xml. Currently there is only one, found under lib/. It lists directories and files which are meant to stay 'as-is' in Moodle, in order to ensure minimum hassle when upgrading these libraries. You can use this file as a template to create your own list of exceptions.

===Other report formats===
CodeSniffer can export its reports in the following formats:
#full: default, shown first above
#summary: also shown above
#xml: Simple XML format
#csv: Comma-separated list
#checkstyle: XML format intended for use with CruiseControl

==See also==

#[[Coding]]
#[[Coding style]]

Talk:Trusttext cleaning bypass

2012-12-12T04:42:05Z

RussellEngland:

I drafted up this little ditty before abandoning it. It doesn't require extra fields - other than the userid field which is in most tables.

Use by calling the function before an insert/update or before displaying the data.

The main advantage is that the trust is checked before being displayed. So if a users trust is revoked after they have entered some malicious script, then the script won't be displayed.

eg:

<code php>
$data = new stdClass();
$data->id = 0;
$data->userid = 2;
$data->description = '<script>alert(1);</script>';

...

$data = my_trusttext_prepare($data, array('description'), $data->userid);

$id = $DB->insert_record('mytable', $data);

/**
* Returns clean text fields if the user is not trusted
*
* Removes XSS nasties
*
* @param object $data Record object - either pre-insert/update or after retrieval
* @param array $fields Array of fields to clean
* @param integer|object $updatinguserid A user id or object, this is the last editor of the record NOT the current user
* @param object $context - Context to use, defaults to system context
* @return object $data Cleaned data fields where appropriate
*/
function my_trusttext_prepare($data, $fields, $updatinguserid, $context = null) {
if (is_null($context)) {
// Default to system context
$context = get_context_instance(CONTEXT_SYSTEM);
}

if (!is_object($data) || !is_array($fields)) {
// Params are invalid
print_error('error:trusttextparam', 'my_errors');
}

if (!has_capability('moodle/site:trustcontent', $context, $updatinguserid)) {
// User might be a cheeky monkey, so clean the text
foreach ($fields as $field) {
if (!isset($data->$field)) {
// Oops, field doesn't exist
print_error('error:trusttextfieldunknown', 'my_errors', null, $field);
} else {
$data->$field = clean_text($data->$field);
}
}
}

return $data;
}
</code>

Talk:Trusttext cleaning bypass

2012-12-12T04:40:30Z

RussellEngland:

I drafted up this little ditty before abandoning it. It doesn't require extra fields - other than the userid field which is in most tables.

Use by calling the function before an insert/update or before displaying the data.

The main advantage is that the trust is checked before being displayed. So if a users trust is revoked after they have entered some malicious script, then the script won't be displayed.

eg:

<code php>
$data = new stdClass();
$data->id = 0;
$data->userid = 2;
$data->description = '<script>alaert(1);</script>';

...

$data = my_trusttext_prepare($data, array('description'), $data->userid);

$id = $DB->insert_record('mytable', $data);

/**
* Returns clean text fields if the user is not trusted
*
* Removes XSS nasties
*
* @param object $data Record object - either pre-insert/update or after retrieval
* @param array $fields Array of fields to clean
* @param integer|object $updatinguserid A user id or object, this is the last editor of the record NOT the current user
* @param object $context - Context to use, defaults to system context
* @return object $data Cleaned data fields where appropriate
*/
function my_trusttext_prepare($data, $fields, $updatinguserid, $context = null) {
if (is_null($context)) {
// Default to system context
$context = get_context_instance(CONTEXT_SYSTEM);
}

if (!is_object($data) || !is_array($fields)) {
// Params are invalid
print_error('error:trusttextparam', 'totara_core');
}

if (!has_capability('moodle/site:trustcontent', $context, $updatinguserid)) {
// User might be a cheeky monkey, so clean the text
foreach ($fields as $field) {
if (!isset($data->$field)) {
// Oops, field doesn't exist
print_error('error:trusttextfieldunknown', 'totara_core', null, $field);
} else {
$data->$field = clean_text($data->$field);
}
}
}

return $data;
}
</code>

Talk:Trusttext cleaning bypass

2012-12-12T04:38:18Z

RussellEngland: Possible simple solution for trusttext?

I drafted up this little ditty before abandoning it. It doesn't require extra fields - other than the userid field which is in most tables.

Use by calling the function before an insert/update or before displaying the data.

The main advantage is that the trust is checked before being displayed. So if a users trust is revoked after they have entered some malicious script, then the script won't be displayed.

eg:

$data = new stdClass();
$data->id = 0;
$data->userid = 2;
$data->description = '<script>alaert(1);</script>';

...

$data = my_trusttext_prepare($data, array('description'), $data->userid);

$id = $DB->insert_record('mytable', $data);

/**
* Returns clean text fields if the user is not trusted
*
* Removes XSS nasties
*
* @param object $data Record object - either pre-insert/update or after retrieval
* @param array $fields Array of fields to clean
* @param integer|object $updatinguserid A user id or object, this is the last editor of the record NOT the current user
* @param object $context - Context to use, defaults to system context
* @return object $data Cleaned data fields where appropriate
*/
function my_trusttext_prepare($data, $fields, $updatinguserid, $context = null) {
if (is_null($context)) {
// Default to system context
$context = get_context_instance(CONTEXT_SYSTEM);
}

if (!is_object($data) || !is_array($fields)) {
// Params are invalid
print_error('error:trusttextparam', 'totara_core');
}

if (!has_capability('moodle/site:trustcontent', $context, $updatinguserid)) {
// User might be a cheeky monkey, so clean the text
foreach ($fields as $field) {
if (!isset($data->$field)) {
// Oops, field doesn't exist
print_error('error:trusttextfieldunknown', 'totara_core', null, $field);
} else {
$data->$field = clean_text($data->$field);
}
}
}

return $data;
}

CodeSniffer

2012-12-10T01:53:01Z

RussellEngland: /* Linux set up */

{{Moodle 2.0}}

==Overview==

===Scope===
This document describes the CodeSniffing/Code checker tools their purpose and usage.

===Function===
The function of the CodeSniffer tool is to analyse PHP5 (only) code, apply a set of rules that match the [[Coding_style | Moodle Coding Style]], and output a report showing which parts of the code do not conform to this style.

==Usage==

===Using codechecker===

codechecker is a local plugin that creates a web based interface for checking the syntax of a given file. It can be found at
https://github.com/moodlehq/moodle-local_codechecker

Once installed a new codechecker option will appear in site administration\development page.

This page allows for the code in a specified directory to be checked, e.g. if you wanted to check the code for the shortanswer question type you would enter
/question/type/shortanswer

You would then be presented with a list of the count of files processed and any warnings or errors.

===Installing codechecker===

To install using git, type this command in the root of your Moodle install
git clone git://github.com/moodlehq/moodle-local_codechecker.git local/codechecker

Then edit .gitignore in your development folder eg:
gedit /var/www/moodle/.gitignore

And add /local/codechecker/ - including the slash at the end

Alternatively, download the zip from

https://github.com/moodlehq/moodle-local_codechecker/zipball/master

unzip it into the local folder, and then rename the new folder to codechecker.

===Codechecker output===

The output is similar to the following

Files found: 21

question\type\calculated\backup\moodle1\lib.php - 1 error(s) and 10 warning(s)
then a list of all files checked with a count of errors and warnings..followed by a summary
Total: 31 error(s) and 262 warning(s)

Then a list describing the exact issue in each file

<nowiki>question\type\calculated\backup\moodle1\lib.php

2: The opening <?php tag must be followed by exactly one newline.
········//·convert·and·write·the·answers·first
50: Inline comments must start with a capital letter, digit or 3-dots sequence
etc etc

</nowiki>You can then edit the files to attempt to remove each issue.

===IDE plugin alternatives===

Using the web based interface means switching between the browser and the editing environment. You may find it easier to use a plugin that allows you to check your code against the standards as you go along.

For Eclipse users
http://www.phpsrc.org/

For Netbeans users

Make sure you have the PEAR php Codesniffer code installed, you can find instructions at
http://pear.php.net/package/PHP_CodeSniffer/download/All

Then install the netbeans plugin which can be found at

https://github.com/beberlei/netbeans-php-enhancements/downloads

Once installed you can check it within Netbeans by going to
Tools/Options/PHP and click on the codesniffer tab.

There is an option for the codesniffer script. On my windows xampp install this needs to point to

C:\xampp\php\phpcs.bat

Underneath this should be a list of some of the coding standards available, but by default this will probably not include Moodle. To install the moodle standards copy the moodle folder from local\codechecker into your standards directory which for me was under

php\PEAR\PHP\CodeSniffer\Standards

[[Image:codesniffer.jpg]]

Now when you restart your Netbeans you should see a new moodle coding standard. Right clicking on a file name should present you with a new option of "Show Code Standard Violations".

====Linux set up====

After installing codesniffer and codechecker, copy the moodle standards folder from (assuming you have the code in /local/codechecker)

/var/www/moodle/local/codechecker/moodle

to

/usr/share/php/PHP/CodeSniffer/Standards/moodle

I changed the moodle standard in Netbeans - as described above - but it didn't work for me.

There is an option to set the default standard in a configuration file :

phpcs --config-set default_standard moodle

But this gave me an error - its a known bug that should be fixed in the next release of codesniffer http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=470294

To work around it, simply create the required folder then re-run the default setting

cd /usr/share/php/data
sudo mkdir PHP_CodeSniffer
phpcs --config-set default_standard moodle

Then re-started Netbeans and it works! I also noticed that I can now switch between coding standards.

===Simple example===
The script is located in lib/pear/PHP and is called runsniffer. To check the syntax of a given file (e.g. index.php), run:

<code>
lib/pear/PHP/runsniffer index.php
</code>

You will get a report that looks like this:

<code>
--------------------------------------------------------------------------------
FOUND 139 ERROR(S) AND 24 WARNING(S) AFFECTING 130 LINE(S)
--------------------------------------------------------------------------------
1 | WARNING | $Id$ tag is no longer required, please remove.
28 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | A cast statement must be followed by a single space
55 | ERROR | line indented incorrectly; expected 0 spaces, found 4
....
</code>

The first column shows the line at which the ERROR or WARNING was found. The CodeSniffer uses a set of rules which are still being defined, so that what is currently defined as ERROR or WARNING is likely to change in the near future.

You should fix all ERRORs, but may safely ignore the WARNINGs. Fixing warnings will help your code be even more readable and consistent with other code that follow this standard.

===Advanced Usage===
====Ignoring warnings====
You can run the CodeSniffer with the -n flag to ignore warnings:

<code>
lib/pear/PHP/runsniffer -n index.php
</code>

Resulting output:
<code>
--------------------------------------------------------------------------------
FOUND 139 ERROR(S) AFFECTING 125 LINE(S)
--------------------------------------------------------------------------------
28 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | line indented incorrectly; expected 0 spaces, found 4
...
</code>

====Recursive analysis====
If you give the name of a folder instead of a file, it will search, analyse and report on all PHP files found in this folder and all its subfolders. This will produce a full report for each PHP file. Since this is likely to be too much information, you may want to print only a summary report, by using the following syntax (search the files/ folder as an example):

<code>
lib/pear/PHP/runsniffer --report=summary files
</code>

Report:
<code>
PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE ERRORS WARNINGS
--------------------------------------------------------------------------------
/web/htdocs/moodle_blog2/files/index.php 11 58
/web/htdocs/moodle_blog2/files/draftfiles.php 6 22
--------------------------------------------------------------------------------
A TOTAL OF 17 ERROR(S) AND 80 WARNING(S) WERE FOUND IN 2 FILE(S)
--------------------------------------------------------------------------------
</code>

You can also use the -n flag to ignore warnings.

====Several files in one folder====
If you want to search all files under a folder, but not recurse through the subfolders, you can use the -l flag (local files only):

<code>
lib/pear/PHP/runsniffer --report=summary -l grade

PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE ERRORS WARNINGS
--------------------------------------------------------------------------------
/web/htdocs/moodle_blog2/grade/index.php 0 2
/web/htdocs/moodle_blog2/grade/lib.php 6 210
/web/htdocs/moodle_blog2/grade/querylib.php 5 39
--------------------------------------------------------------------------------
A TOTAL OF 11 ERROR(S) AND 251 WARNING(S) WERE FOUND IN 3 FILE(S)
--------------------------------------------------------------------------------
</code>

You can pass as many files and folders to the script as you want, the analysis and flags will apply to all of them.

===Special rules===
When recursing through folders, the CodeSniffer script looks for a file called thirdpartylibs.xml. Currently there is only one, found under lib/. It lists directories and files which are meant to stay 'as-is' in Moodle, in order to ensure minimum hassle when upgrading these libraries. You can use this file as a template to create your own list of exceptions.

===Other report formats===
CodeSniffer can export its reports in the following formats:
#full: default, shown first above
#summary: also shown above
#xml: Simple XML format
#csv: Comma-separated list
#checkstyle: XML format intended for use with CruiseControl

==See also==

#[[Coding]]
#[[Coding style]]

CodeSniffer

2012-12-10T01:52:03Z

RussellEngland: /* IDE plugin alternatives */

{{Moodle 2.0}}

==Overview==

===Scope===
This document describes the CodeSniffing/Code checker tools their purpose and usage.

===Function===
The function of the CodeSniffer tool is to analyse PHP5 (only) code, apply a set of rules that match the [[Coding_style | Moodle Coding Style]], and output a report showing which parts of the code do not conform to this style.

==Usage==

===Using codechecker===

codechecker is a local plugin that creates a web based interface for checking the syntax of a given file. It can be found at
https://github.com/moodlehq/moodle-local_codechecker

Once installed a new codechecker option will appear in site administration\development page.

This page allows for the code in a specified directory to be checked, e.g. if you wanted to check the code for the shortanswer question type you would enter
/question/type/shortanswer

You would then be presented with a list of the count of files processed and any warnings or errors.

===Installing codechecker===

To install using git, type this command in the root of your Moodle install
git clone git://github.com/moodlehq/moodle-local_codechecker.git local/codechecker

Then edit .gitignore in your development folder eg:
gedit /var/www/moodle/.gitignore

And add /local/codechecker/ - including the slash at the end

Alternatively, download the zip from

https://github.com/moodlehq/moodle-local_codechecker/zipball/master

unzip it into the local folder, and then rename the new folder to codechecker.

===Codechecker output===

The output is similar to the following

Files found: 21

question\type\calculated\backup\moodle1\lib.php - 1 error(s) and 10 warning(s)
then a list of all files checked with a count of errors and warnings..followed by a summary
Total: 31 error(s) and 262 warning(s)

Then a list describing the exact issue in each file

<nowiki>question\type\calculated\backup\moodle1\lib.php

2: The opening <?php tag must be followed by exactly one newline.
········//·convert·and·write·the·answers·first
50: Inline comments must start with a capital letter, digit or 3-dots sequence
etc etc

</nowiki>You can then edit the files to attempt to remove each issue.

===IDE plugin alternatives===

Using the web based interface means switching between the browser and the editing environment. You may find it easier to use a plugin that allows you to check your code against the standards as you go along.

For Eclipse users
http://www.phpsrc.org/

For Netbeans users

Make sure you have the PEAR php Codesniffer code installed, you can find instructions at
http://pear.php.net/package/PHP_CodeSniffer/download/All

Then install the netbeans plugin which can be found at

https://github.com/beberlei/netbeans-php-enhancements/downloads

Once installed you can check it within Netbeans by going to
Tools/Options/PHP and click on the codesniffer tab.

There is an option for the codesniffer script. On my windows xampp install this needs to point to

C:\xampp\php\phpcs.bat

Underneath this should be a list of some of the coding standards available, but by default this will probably not include Moodle. To install the moodle standards copy the moodle folder from local\codechecker into your standards directory which for me was under

php\PEAR\PHP\CodeSniffer\Standards

[[Image:codesniffer.jpg]]

Now when you restart your Netbeans you should see a new moodle coding standard. Right clicking on a file name should present you with a new option of "Show Code Standard Violations".

====Linux set up====

After installing codesniffer and codechecker, copy the moodle standards folder from (assuming you have the code in /local/codechecker)

/var/www/moodle/local/codechecker/moodle

to

/usr/share/php/PHP/CodeSniffer/Standards/moodle

I changed the moodle standard in Netbeans - as described above - but it didn't work for me.

There is an option to set the default standard in a configuration file :

phpcs --config-set default_standard moodle

But this gave me an error - its a known bug that should be fixed in the next release of codesniffer http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=470294

To work around it, simply create the required folder then re-run the default setting

cd /usr/share/php/data/PHP_CodeSniffer
sudo mkdir PHP_CodeSniffer
phpcs --config-set default_standard moodle

Then re-started Netbeans and it works! I also noticed that I can now switch between coding standards.

===Simple example===
The script is located in lib/pear/PHP and is called runsniffer. To check the syntax of a given file (e.g. index.php), run:

<code>
lib/pear/PHP/runsniffer index.php
</code>

You will get a report that looks like this:

<code>
--------------------------------------------------------------------------------
FOUND 139 ERROR(S) AND 24 WARNING(S) AFFECTING 130 LINE(S)
--------------------------------------------------------------------------------
1 | WARNING | $Id$ tag is no longer required, please remove.
28 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | A cast statement must be followed by a single space
55 | ERROR | line indented incorrectly; expected 0 spaces, found 4
....
</code>

The first column shows the line at which the ERROR or WARNING was found. The CodeSniffer uses a set of rules which are still being defined, so that what is currently defined as ERROR or WARNING is likely to change in the near future.

You should fix all ERRORs, but may safely ignore the WARNINGs. Fixing warnings will help your code be even more readable and consistent with other code that follow this standard.

===Advanced Usage===
====Ignoring warnings====
You can run the CodeSniffer with the -n flag to ignore warnings:

<code>
lib/pear/PHP/runsniffer -n index.php
</code>

Resulting output:
<code>
--------------------------------------------------------------------------------
FOUND 139 ERROR(S) AFFECTING 125 LINE(S)
--------------------------------------------------------------------------------
28 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | line indented incorrectly; expected 0 spaces, found 4
...
</code>

====Recursive analysis====
If you give the name of a folder instead of a file, it will search, analyse and report on all PHP files found in this folder and all its subfolders. This will produce a full report for each PHP file. Since this is likely to be too much information, you may want to print only a summary report, by using the following syntax (search the files/ folder as an example):

<code>
lib/pear/PHP/runsniffer --report=summary files
</code>

Report:
<code>
PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE ERRORS WARNINGS
--------------------------------------------------------------------------------
/web/htdocs/moodle_blog2/files/index.php 11 58
/web/htdocs/moodle_blog2/files/draftfiles.php 6 22
--------------------------------------------------------------------------------
A TOTAL OF 17 ERROR(S) AND 80 WARNING(S) WERE FOUND IN 2 FILE(S)
--------------------------------------------------------------------------------
</code>

You can also use the -n flag to ignore warnings.

====Several files in one folder====
If you want to search all files under a folder, but not recurse through the subfolders, you can use the -l flag (local files only):

<code>
lib/pear/PHP/runsniffer --report=summary -l grade

PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE ERRORS WARNINGS
--------------------------------------------------------------------------------
/web/htdocs/moodle_blog2/grade/index.php 0 2
/web/htdocs/moodle_blog2/grade/lib.php 6 210
/web/htdocs/moodle_blog2/grade/querylib.php 5 39
--------------------------------------------------------------------------------
A TOTAL OF 11 ERROR(S) AND 251 WARNING(S) WERE FOUND IN 3 FILE(S)
--------------------------------------------------------------------------------
</code>

You can pass as many files and folders to the script as you want, the analysis and flags will apply to all of them.

===Special rules===
When recursing through folders, the CodeSniffer script looks for a file called thirdpartylibs.xml. Currently there is only one, found under lib/. It lists directories and files which are meant to stay 'as-is' in Moodle, in order to ensure minimum hassle when upgrading these libraries. You can use this file as a template to create your own list of exceptions.

===Other report formats===
CodeSniffer can export its reports in the following formats:
#full: default, shown first above
#summary: also shown above
#xml: Simple XML format
#csv: Comma-separated list
#checkstyle: XML format intended for use with CruiseControl

==See also==

#[[Coding]]
#[[Coding style]]

CodeSniffer

2012-12-10T01:50:11Z

RussellEngland: /* IDE plugin alternatives */ troubleshooting the linux install

{{Moodle 2.0}}

==Overview==

===Scope===
This document describes the CodeSniffing/Code checker tools their purpose and usage.

===Function===
The function of the CodeSniffer tool is to analyse PHP5 (only) code, apply a set of rules that match the [[Coding_style | Moodle Coding Style]], and output a report showing which parts of the code do not conform to this style.

==Usage==

===Using codechecker===

codechecker is a local plugin that creates a web based interface for checking the syntax of a given file. It can be found at
https://github.com/moodlehq/moodle-local_codechecker

Once installed a new codechecker option will appear in site administration\development page.

This page allows for the code in a specified directory to be checked, e.g. if you wanted to check the code for the shortanswer question type you would enter
/question/type/shortanswer

You would then be presented with a list of the count of files processed and any warnings or errors.

===Installing codechecker===

To install using git, type this command in the root of your Moodle install
git clone git://github.com/moodlehq/moodle-local_codechecker.git local/codechecker

Then edit .gitignore in your development folder eg:
gedit /var/www/moodle/.gitignore

And add /local/codechecker/ - including the slash at the end

Alternatively, download the zip from

https://github.com/moodlehq/moodle-local_codechecker/zipball/master

unzip it into the local folder, and then rename the new folder to codechecker.

===Codechecker output===

The output is similar to the following

Files found: 21

question\type\calculated\backup\moodle1\lib.php - 1 error(s) and 10 warning(s)
then a list of all files checked with a count of errors and warnings..followed by a summary
Total: 31 error(s) and 262 warning(s)

Then a list describing the exact issue in each file

<nowiki>question\type\calculated\backup\moodle1\lib.php

2: The opening <?php tag must be followed by exactly one newline.
········//·convert·and·write·the·answers·first
50: Inline comments must start with a capital letter, digit or 3-dots sequence
etc etc

</nowiki>You can then edit the files to attempt to remove each issue.

===IDE plugin alternatives===

Using the web based interface means switching between the browser and the editing environment. You may find it easier to use a plugin that allows you to check your code against the standards as you go along.

For Eclipse users
http://www.phpsrc.org/

For Netbeans users

Make sure you have the PEAR php Codesniffer code installed, you can find instructions at
http://pear.php.net/package/PHP_CodeSniffer/download/All

Then install the netbeans plugin which can be found at

https://github.com/beberlei/netbeans-php-enhancements/downloads

Once installed you can check it within Netbeans by going to
Tools/Options/PHP and click on the codesniffer tab.

There is an option for the codesniffer script. On my windows xampp install this needs to point to

C:\xampp\php\phpcs.bat

Underneath this should be a list of some of the coding standards available, but by default this will probably not include Moodle. To install the moodle standards copy the moodle folder from local\codechecker into your standards directory which for me was under

php\PEAR\PHP\CodeSniffer\Standards

====Linux set up====

After installing codesniffer and codechecker, copy the moodle standards folder from (assuming you have the code in /local/codechecker)

/var/www/moodle/local/codechecker/moodle

to

/usr/share/php/PHP/CodeSniffer/Standards/moodle

I changed the moodle standard in Netbeans - as described below - but it didn't work for me.

There is an option to set the default standard in a configuration file :

phpcs --config-set default_standard moodle

But this gave me an error - its a known bug that should be fixed in the next release of codesniffer http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=470294

To work around it, simply create the required folder then re-run the default setting

cd /usr/share/php/data/PHP_CodeSniffer
sudo mkdir PHP_CodeSniffer
phpcs --config-set default_standard moodle

Then start up Netbeans and it works!

[[Image:codesniffer.jpg]]

Now when you restart your Netbeans you should see a new moodle coding standard. Right clicking on a file name should present you with a new option of "Show Code Standard Violations".

===Simple example===
The script is located in lib/pear/PHP and is called runsniffer. To check the syntax of a given file (e.g. index.php), run:

<code>
lib/pear/PHP/runsniffer index.php
</code>

You will get a report that looks like this:

<code>
--------------------------------------------------------------------------------
FOUND 139 ERROR(S) AND 24 WARNING(S) AFFECTING 130 LINE(S)
--------------------------------------------------------------------------------
1 | WARNING | $Id$ tag is no longer required, please remove.
28 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | A cast statement must be followed by a single space
55 | ERROR | line indented incorrectly; expected 0 spaces, found 4
....
</code>

The first column shows the line at which the ERROR or WARNING was found. The CodeSniffer uses a set of rules which are still being defined, so that what is currently defined as ERROR or WARNING is likely to change in the near future.

You should fix all ERRORs, but may safely ignore the WARNINGs. Fixing warnings will help your code be even more readable and consistent with other code that follow this standard.

===Advanced Usage===
====Ignoring warnings====
You can run the CodeSniffer with the -n flag to ignore warnings:

<code>
lib/pear/PHP/runsniffer -n index.php
</code>

Resulting output:
<code>
--------------------------------------------------------------------------------
FOUND 139 ERROR(S) AFFECTING 125 LINE(S)
--------------------------------------------------------------------------------
28 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | line indented incorrectly; expected 0 spaces, found 4
...
</code>

====Recursive analysis====
If you give the name of a folder instead of a file, it will search, analyse and report on all PHP files found in this folder and all its subfolders. This will produce a full report for each PHP file. Since this is likely to be too much information, you may want to print only a summary report, by using the following syntax (search the files/ folder as an example):

<code>
lib/pear/PHP/runsniffer --report=summary files
</code>

Report:
<code>
PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE ERRORS WARNINGS
--------------------------------------------------------------------------------
/web/htdocs/moodle_blog2/files/index.php 11 58
/web/htdocs/moodle_blog2/files/draftfiles.php 6 22
--------------------------------------------------------------------------------
A TOTAL OF 17 ERROR(S) AND 80 WARNING(S) WERE FOUND IN 2 FILE(S)
--------------------------------------------------------------------------------
</code>

You can also use the -n flag to ignore warnings.

====Several files in one folder====
If you want to search all files under a folder, but not recurse through the subfolders, you can use the -l flag (local files only):

<code>
lib/pear/PHP/runsniffer --report=summary -l grade

PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE ERRORS WARNINGS
--------------------------------------------------------------------------------
/web/htdocs/moodle_blog2/grade/index.php 0 2
/web/htdocs/moodle_blog2/grade/lib.php 6 210
/web/htdocs/moodle_blog2/grade/querylib.php 5 39
--------------------------------------------------------------------------------
A TOTAL OF 11 ERROR(S) AND 251 WARNING(S) WERE FOUND IN 3 FILE(S)
--------------------------------------------------------------------------------
</code>

You can pass as many files and folders to the script as you want, the analysis and flags will apply to all of them.

===Special rules===
When recursing through folders, the CodeSniffer script looks for a file called thirdpartylibs.xml. Currently there is only one, found under lib/. It lists directories and files which are meant to stay 'as-is' in Moodle, in order to ensure minimum hassle when upgrading these libraries. You can use this file as a template to create your own list of exceptions.

===Other report formats===
CodeSniffer can export its reports in the following formats:
#full: default, shown first above
#summary: also shown above
#xml: Simple XML format
#csv: Comma-separated list
#checkstyle: XML format intended for use with CruiseControl

==See also==

#[[Coding]]
#[[Coding style]]

CodeSniffer

2012-12-09T22:09:00Z

RussellEngland: added location of linux folder

{{Moodle 2.0}}

==Overview==

===Scope===
This document describes the CodeSniffing/Code checker tools their purpose and usage.

===Function===
The function of the CodeSniffer tool is to analyse PHP5 (only) code, apply a set of rules that match the [[Coding_style | Moodle Coding Style]], and output a report showing which parts of the code do not conform to this style.

==Usage==

===Using codechecker===

codechecker is a local plugin that creates a web based interface for checking the syntax of a given file. It can be found at
https://github.com/moodlehq/moodle-local_codechecker

Once installed a new codechecker option will appear in site administration\development page.

This page allows for the code in a specified directory to be checked, e.g. if you wanted to check the code for the shortanswer question type you would enter
/question/type/shortanswer

You would then be presented with a list of the count of files processed and any warnings or errors.

===Installing codechecker===

To install using git, type this command in the root of your Moodle install
git clone git://github.com/moodlehq/moodle-local_codechecker.git local/codechecker

Then edit .gitignore in your development folder eg:
gedit /var/www/moodle/.gitignore

And add /local/codechecker/ - including the slash at the end

Alternatively, download the zip from

https://github.com/moodlehq/moodle-local_codechecker/zipball/master

unzip it into the local folder, and then rename the new folder to codechecker.

===Codechecker output===

The output is similar to the following

Files found: 21

question\type\calculated\backup\moodle1\lib.php - 1 error(s) and 10 warning(s)
then a list of all files checked with a count of errors and warnings..followed by a summary
Total: 31 error(s) and 262 warning(s)

Then a list describing the exact issue in each file

<nowiki>question\type\calculated\backup\moodle1\lib.php

2: The opening <?php tag must be followed by exactly one newline.
········//·convert·and·write·the·answers·first
50: Inline comments must start with a capital letter, digit or 3-dots sequence
etc etc

</nowiki>You can then edit the files to attempt to remove each issue.

===IDE plugin alternatives===

Using the web based interface means switching between the browser and the editing environment. You may find it easier to use a plugin that allows you to check your code against the standards as you go along.

For Eclipse users
http://www.phpsrc.org/

For Netbeans users

Make sure you have the PEAR php Codesniffer code installed, you can find instructions at
http://pear.php.net/package/PHP_CodeSniffer/download/All

Then install the netbeans plugin which can be found at

https://github.com/beberlei/netbeans-php-enhancements/downloads

Once installed you can check it within Netbeans by going to
Tools/Options/PHP and click on the codesniffer tab.

There is an option for the codesniffer script. On my windows xampp install this needs to point to

C:\xampp\php\phpcs.bat

Underneath this should be a list of some of the coding standards available, but by default this will probably not include Moodle. To install the moodle standards copy the moodle folder from local\codechecker into your standards directory which for me was under

php\PEAR\PHP\CodeSniffer\Standards

Linux folder is

/usr/share/php/PHP/CodeSniffer/Standards

[[Image:codesniffer.jpg]]

Now when you restart your Netbeans you should see a new moodle coding standard. Right clicking on a file name should present you with a new option of "Show Code Standard Violations".

===Simple example===
The script is located in lib/pear/PHP and is called runsniffer. To check the syntax of a given file (e.g. index.php), run:

<code>
lib/pear/PHP/runsniffer index.php
</code>

You will get a report that looks like this:

<code>
--------------------------------------------------------------------------------
FOUND 139 ERROR(S) AND 24 WARNING(S) AFFECTING 130 LINE(S)
--------------------------------------------------------------------------------
1 | WARNING | $Id$ tag is no longer required, please remove.
28 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | A cast statement must be followed by a single space
55 | ERROR | line indented incorrectly; expected 0 spaces, found 4
....
</code>

The first column shows the line at which the ERROR or WARNING was found. The CodeSniffer uses a set of rules which are still being defined, so that what is currently defined as ERROR or WARNING is likely to change in the near future.

You should fix all ERRORs, but may safely ignore the WARNINGs. Fixing warnings will help your code be even more readable and consistent with other code that follow this standard.

===Advanced Usage===
====Ignoring warnings====
You can run the CodeSniffer with the -n flag to ignore warnings:

<code>
lib/pear/PHP/runsniffer -n index.php
</code>

Resulting output:
<code>
--------------------------------------------------------------------------------
FOUND 139 ERROR(S) AFFECTING 125 LINE(S)
--------------------------------------------------------------------------------
28 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | line indented incorrectly; expected 0 spaces, found 4
...
</code>

====Recursive analysis====
If you give the name of a folder instead of a file, it will search, analyse and report on all PHP files found in this folder and all its subfolders. This will produce a full report for each PHP file. Since this is likely to be too much information, you may want to print only a summary report, by using the following syntax (search the files/ folder as an example):

<code>
lib/pear/PHP/runsniffer --report=summary files
</code>

Report:
<code>
PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE ERRORS WARNINGS
--------------------------------------------------------------------------------
/web/htdocs/moodle_blog2/files/index.php 11 58
/web/htdocs/moodle_blog2/files/draftfiles.php 6 22
--------------------------------------------------------------------------------
A TOTAL OF 17 ERROR(S) AND 80 WARNING(S) WERE FOUND IN 2 FILE(S)
--------------------------------------------------------------------------------
</code>

You can also use the -n flag to ignore warnings.

====Several files in one folder====
If you want to search all files under a folder, but not recurse through the subfolders, you can use the -l flag (local files only):

<code>
lib/pear/PHP/runsniffer --report=summary -l grade

PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE ERRORS WARNINGS
--------------------------------------------------------------------------------
/web/htdocs/moodle_blog2/grade/index.php 0 2
/web/htdocs/moodle_blog2/grade/lib.php 6 210
/web/htdocs/moodle_blog2/grade/querylib.php 5 39
--------------------------------------------------------------------------------
A TOTAL OF 11 ERROR(S) AND 251 WARNING(S) WERE FOUND IN 3 FILE(S)
--------------------------------------------------------------------------------
</code>

You can pass as many files and folders to the script as you want, the analysis and flags will apply to all of them.

===Special rules===
When recursing through folders, the CodeSniffer script looks for a file called thirdpartylibs.xml. Currently there is only one, found under lib/. It lists directories and files which are meant to stay 'as-is' in Moodle, in order to ensure minimum hassle when upgrading these libraries. You can use this file as a template to create your own list of exceptions.

===Other report formats===
CodeSniffer can export its reports in the following formats:
#full: default, shown first above
#summary: also shown above
#xml: Simple XML format
#csv: Comma-separated list
#checkstyle: XML format intended for use with CruiseControl

==See also==

#[[Coding]]
#[[Coding style]]

CodeSniffer

2012-12-09T21:57:22Z

RussellEngland: /* Installing codechecker */

{{Moodle 2.0}}

==Overview==

===Scope===
This document describes the CodeSniffing/Code checker tools their purpose and usage.

===Function===
The function of the CodeSniffer tool is to analyse PHP5 (only) code, apply a set of rules that match the [[Coding_style | Moodle Coding Style]], and output a report showing which parts of the code do not conform to this style.

==Usage==

===Using codechecker===

codechecker is a local plugin that creates a web based interface for checking the syntax of a given file. It can be found at
https://github.com/moodlehq/moodle-local_codechecker

Once installed a new codechecker option will appear in site administration\development page.

This page allows for the code in a specified directory to be checked, e.g. if you wanted to check the code for the shortanswer question type you would enter
/question/type/shortanswer

You would then be presented with a list of the count of files processed and any warnings or errors.

===Installing codechecker===

To install using git, type this command in the root of your Moodle install
git clone git://github.com/moodlehq/moodle-local_codechecker.git local/codechecker

Then edit .gitignore in your development folder eg:
gedit /var/www/moodle/.gitignore

And add /local/codechecker/ - including the slash at the end

Alternatively, download the zip from

https://github.com/moodlehq/moodle-local_codechecker/zipball/master

unzip it into the local folder, and then rename the new folder to codechecker.

===Codechecker output===

The output is similar to the following

Files found: 21

question\type\calculated\backup\moodle1\lib.php - 1 error(s) and 10 warning(s)
then a list of all files checked with a count of errors and warnings..followed by a summary
Total: 31 error(s) and 262 warning(s)

Then a list describing the exact issue in each file

<nowiki>question\type\calculated\backup\moodle1\lib.php

2: The opening <?php tag must be followed by exactly one newline.
········//·convert·and·write·the·answers·first
50: Inline comments must start with a capital letter, digit or 3-dots sequence
etc etc

</nowiki>You can then edit the files to attempt to remove each issue.

===IDE plugin alternatives===

Using the web based interface means switching between the browser and the editing environment. You may find it easier to use a plugin that allows you to check your code against the standards as you go along.

For Eclipse users
http://www.phpsrc.org/

For Netbeans users

Make sure you have the PEAR php Codesniffer code installed, you can find instructions at
http://pear.php.net/package/PHP_CodeSniffer/download/All

Then install the netbeans plugin which can be found at

https://github.com/beberlei/netbeans-php-enhancements/downloads

Once installed you can check it within Netbeans by going to
Tools/Options/PHP and click on the codesniffer tab.

There is an option for the codesniffer script. On my windows xampp install this needs to point to

C:\xampp\php\phpcs.bat

Underneath this should be a list of some of the coding standards available, but by default this will probably not include Moodle. To install the moodle standards copy the moodle folder from local\codechecker into your standards directory which for me was under

php\PEAR\PHP\CodeSniffer\Standards

[[Image:codesniffer.jpg]]

Now when you restart your Netbeans you should see a new moodle coding standard. Right clicking on a file name should present you with a new option of "Show Code Standard Violations".

===Simple example===
The script is located in lib/pear/PHP and is called runsniffer. To check the syntax of a given file (e.g. index.php), run:

<code>
lib/pear/PHP/runsniffer index.php
</code>

You will get a report that looks like this:

<code>
--------------------------------------------------------------------------------
FOUND 139 ERROR(S) AND 24 WARNING(S) AFFECTING 130 LINE(S)
--------------------------------------------------------------------------------
1 | WARNING | $Id$ tag is no longer required, please remove.
28 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | A cast statement must be followed by a single space
55 | ERROR | line indented incorrectly; expected 0 spaces, found 4
....
</code>

The first column shows the line at which the ERROR or WARNING was found. The CodeSniffer uses a set of rules which are still being defined, so that what is currently defined as ERROR or WARNING is likely to change in the near future.

You should fix all ERRORs, but may safely ignore the WARNINGs. Fixing warnings will help your code be even more readable and consistent with other code that follow this standard.

===Advanced Usage===
====Ignoring warnings====
You can run the CodeSniffer with the -n flag to ignore warnings:

<code>
lib/pear/PHP/runsniffer -n index.php
</code>

Resulting output:
<code>
--------------------------------------------------------------------------------
FOUND 139 ERROR(S) AFFECTING 125 LINE(S)
--------------------------------------------------------------------------------
28 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | line indented incorrectly; expected 0 spaces, found 4
...
</code>

====Recursive analysis====
If you give the name of a folder instead of a file, it will search, analyse and report on all PHP files found in this folder and all its subfolders. This will produce a full report for each PHP file. Since this is likely to be too much information, you may want to print only a summary report, by using the following syntax (search the files/ folder as an example):

<code>
lib/pear/PHP/runsniffer --report=summary files
</code>

Report:
<code>
PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE ERRORS WARNINGS
--------------------------------------------------------------------------------
/web/htdocs/moodle_blog2/files/index.php 11 58
/web/htdocs/moodle_blog2/files/draftfiles.php 6 22
--------------------------------------------------------------------------------
A TOTAL OF 17 ERROR(S) AND 80 WARNING(S) WERE FOUND IN 2 FILE(S)
--------------------------------------------------------------------------------
</code>

You can also use the -n flag to ignore warnings.

====Several files in one folder====
If you want to search all files under a folder, but not recurse through the subfolders, you can use the -l flag (local files only):

<code>
lib/pear/PHP/runsniffer --report=summary -l grade

PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE ERRORS WARNINGS
--------------------------------------------------------------------------------
/web/htdocs/moodle_blog2/grade/index.php 0 2
/web/htdocs/moodle_blog2/grade/lib.php 6 210
/web/htdocs/moodle_blog2/grade/querylib.php 5 39
--------------------------------------------------------------------------------
A TOTAL OF 11 ERROR(S) AND 251 WARNING(S) WERE FOUND IN 3 FILE(S)
--------------------------------------------------------------------------------
</code>

You can pass as many files and folders to the script as you want, the analysis and flags will apply to all of them.

===Special rules===
When recursing through folders, the CodeSniffer script looks for a file called thirdpartylibs.xml. Currently there is only one, found under lib/. It lists directories and files which are meant to stay 'as-is' in Moodle, in order to ensure minimum hassle when upgrading these libraries. You can use this file as a template to create your own list of exceptions.

===Other report formats===
CodeSniffer can export its reports in the following formats:
#full: default, shown first above
#summary: also shown above
#xml: Simple XML format
#csv: Comma-separated list
#checkstyle: XML format intended for use with CruiseControl

==See also==

#[[Coding]]
#[[Coding style]]

CodeSniffer

2012-12-09T21:56:56Z

RussellEngland: added the install instructions from https://github.com/moodlehq/moodle-local_codechecker#readme

{{Moodle 2.0}}

==Overview==

===Scope===
This document describes the CodeSniffing/Code checker tools their purpose and usage.

===Function===
The function of the CodeSniffer tool is to analyse PHP5 (only) code, apply a set of rules that match the [[Coding_style | Moodle Coding Style]], and output a report showing which parts of the code do not conform to this style.

==Usage==

===Using codechecker===

codechecker is a local plugin that creates a web based interface for checking the syntax of a given file. It can be found at
https://github.com/moodlehq/moodle-local_codechecker

Once installed a new codechecker option will appear in site administration\development page.

This page allows for the code in a specified directory to be checked, e.g. if you wanted to check the code for the shortanswer question type you would enter
/question/type/shortanswer

You would then be presented with a list of the count of files processed and any warnings or errors.

===Installing codechecker===

To install using git, type this command in the root of your Moodle install
git clone git://github.com/moodlehq/moodle-local_codechecker.git local/codechecker

Then edit .gitignore in your development folder eg: gedit /var/www/moodle/.gitignore

And add /local/codechecker/ - including the slash at the end

Alternatively, download the zip from

https://github.com/moodlehq/moodle-local_codechecker/zipball/master

unzip it into the local folder, and then rename the new folder to codechecker.

===Codechecker output===

The output is similar to the following

Files found: 21

question\type\calculated\backup\moodle1\lib.php - 1 error(s) and 10 warning(s)
then a list of all files checked with a count of errors and warnings..followed by a summary
Total: 31 error(s) and 262 warning(s)

Then a list describing the exact issue in each file

<nowiki>question\type\calculated\backup\moodle1\lib.php

2: The opening <?php tag must be followed by exactly one newline.
········//·convert·and·write·the·answers·first
50: Inline comments must start with a capital letter, digit or 3-dots sequence
etc etc

</nowiki>You can then edit the files to attempt to remove each issue.

===IDE plugin alternatives===

Using the web based interface means switching between the browser and the editing environment. You may find it easier to use a plugin that allows you to check your code against the standards as you go along.

For Eclipse users
http://www.phpsrc.org/

For Netbeans users

Make sure you have the PEAR php Codesniffer code installed, you can find instructions at
http://pear.php.net/package/PHP_CodeSniffer/download/All

Then install the netbeans plugin which can be found at

https://github.com/beberlei/netbeans-php-enhancements/downloads

Once installed you can check it within Netbeans by going to
Tools/Options/PHP and click on the codesniffer tab.

There is an option for the codesniffer script. On my windows xampp install this needs to point to

C:\xampp\php\phpcs.bat

Underneath this should be a list of some of the coding standards available, but by default this will probably not include Moodle. To install the moodle standards copy the moodle folder from local\codechecker into your standards directory which for me was under

php\PEAR\PHP\CodeSniffer\Standards

[[Image:codesniffer.jpg]]

Now when you restart your Netbeans you should see a new moodle coding standard. Right clicking on a file name should present you with a new option of "Show Code Standard Violations".

===Simple example===
The script is located in lib/pear/PHP and is called runsniffer. To check the syntax of a given file (e.g. index.php), run:

<code>
lib/pear/PHP/runsniffer index.php
</code>

You will get a report that looks like this:

<code>
--------------------------------------------------------------------------------
FOUND 139 ERROR(S) AND 24 WARNING(S) AFFECTING 130 LINE(S)
--------------------------------------------------------------------------------
1 | WARNING | $Id$ tag is no longer required, please remove.
28 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | A cast statement must be followed by a single space
55 | ERROR | line indented incorrectly; expected 0 spaces, found 4
....
</code>

The first column shows the line at which the ERROR or WARNING was found. The CodeSniffer uses a set of rules which are still being defined, so that what is currently defined as ERROR or WARNING is likely to change in the near future.

You should fix all ERRORs, but may safely ignore the WARNINGs. Fixing warnings will help your code be even more readable and consistent with other code that follow this standard.

===Advanced Usage===
====Ignoring warnings====
You can run the CodeSniffer with the -n flag to ignore warnings:

<code>
lib/pear/PHP/runsniffer -n index.php
</code>

Resulting output:
<code>
--------------------------------------------------------------------------------
FOUND 139 ERROR(S) AFFECTING 125 LINE(S)
--------------------------------------------------------------------------------
28 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | line indented incorrectly; expected 0 spaces, found 4
...
</code>

====Recursive analysis====
If you give the name of a folder instead of a file, it will search, analyse and report on all PHP files found in this folder and all its subfolders. This will produce a full report for each PHP file. Since this is likely to be too much information, you may want to print only a summary report, by using the following syntax (search the files/ folder as an example):

<code>
lib/pear/PHP/runsniffer --report=summary files
</code>

Report:
<code>
PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE ERRORS WARNINGS
--------------------------------------------------------------------------------
/web/htdocs/moodle_blog2/files/index.php 11 58
/web/htdocs/moodle_blog2/files/draftfiles.php 6 22
--------------------------------------------------------------------------------
A TOTAL OF 17 ERROR(S) AND 80 WARNING(S) WERE FOUND IN 2 FILE(S)
--------------------------------------------------------------------------------
</code>

You can also use the -n flag to ignore warnings.

====Several files in one folder====
If you want to search all files under a folder, but not recurse through the subfolders, you can use the -l flag (local files only):

<code>
lib/pear/PHP/runsniffer --report=summary -l grade

PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE ERRORS WARNINGS
--------------------------------------------------------------------------------
/web/htdocs/moodle_blog2/grade/index.php 0 2
/web/htdocs/moodle_blog2/grade/lib.php 6 210
/web/htdocs/moodle_blog2/grade/querylib.php 5 39
--------------------------------------------------------------------------------
A TOTAL OF 11 ERROR(S) AND 251 WARNING(S) WERE FOUND IN 3 FILE(S)
--------------------------------------------------------------------------------
</code>

You can pass as many files and folders to the script as you want, the analysis and flags will apply to all of them.

===Special rules===
When recursing through folders, the CodeSniffer script looks for a file called thirdpartylibs.xml. Currently there is only one, found under lib/. It lists directories and files which are meant to stay 'as-is' in Moodle, in order to ensure minimum hassle when upgrading these libraries. You can use this file as a template to create your own list of exceptions.

===Other report formats===
CodeSniffer can export its reports in the following formats:
#full: default, shown first above
#summary: also shown above
#xml: Simple XML format
#csv: Comma-separated list
#checkstyle: XML format intended for use with CruiseControl

==See also==

#[[Coding]]
#[[Coding style]]