unset($data->idnumber);
}
+ // Any empty value for course->hiddensections will lead to 0 (default, show collapsed).
+ // It has been reported that some old 1.9 courses may have it null leading to DB error. MDL-31532
+ if (empty($data->hiddensections)) {
+ $data->hiddensections = 0;
+ }
+
// Only restrict modules if original course was and target site too for new courses
$data->restrictmodules = $data->restrictmodules && !empty($CFG->restrictmodulesfor) && $CFG->restrictmodulesfor == 'all';
<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * Blog RSS Management
+ *
+ * @package core_blog
+ * @category rss
+ * @copyright 2010 Andrew Davis
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
require_once($CFG->dirroot.'/lib/rsslib.php');
require_once($CFG->dirroot .'/blog/lib.php');
+/**
+ * Build the URL for the RSS feed
+ *
+ * @param int $contextid The context under which the URL should be created
+ * @param int $userid The id of the user requesting the RSS Feed
+ * @param string $filtertype The source of the RSS feed (site/course/group/user)
+ * @param int $filterselect The id of the item defined by $filtertype
+ * @param int $tagid The id of the row in the tag table that identifies the RSS Feed
+ * @return string
+ */
function blog_rss_get_url($contextid, $userid, $filtertype, $filterselect=0, $tagid=0) {
$componentname = 'blog';
return rss_get_url($contextid, $userid, $componentname, $additionalargs);
}
-// This function returns the icon (from theme) with the link to rss/file.php
-// needs some hacking to rss/file.php
+/**
+ * Print the link for the RSS feed with the correct RSS icon (Theme based)
+ *
+ * @param stdClass $context The context under which the URL should be created
+ * @param string $filtertype The source of the RSS feed (site/course/group/user)
+ * @param int $filterselect The id of the item defined by $filtertype
+ * @param int $tagid The id of the row in the tag table that identifies the RSS Feed
+ * @param string $tooltiptext The tooltip to be displayed with the link
+ */
function blog_rss_print_link($context, $filtertype, $filterselect=0, $tagid=0, $tooltiptext='') {
global $CFG, $USER, $OUTPUT;
print '<div class="mdl-right"><a href="'. $url .'"><img src="'. $rsspix .'" title="'. strip_tags($tooltiptext) .'" alt="'.get_string('rss').'" /></a></div>';
}
+/**
+ * Build the URL for the RSS feed amd add it as a header
+ *
+ * @param stdClass $context The context under which the URL should be created
+ * @param string $title Name for the link to be added to the page header
+ * @param string $filtertype The source of the RSS feed (site/course/group/user)
+ * @param int $filterselect The id of the item defined by $filtertype
+ * @param int $tagid The id of the row in the tag table that identifies the RSS Feed
+ */
function blog_rss_add_http_header($context, $title, $filtertype, $filterselect=0, $tagid=0) {
global $PAGE, $USER, $CFG;
/**
* Utility function to extract parameters needed to generate RSS URLs from the blog filters
- * @param <type> $filters
- * @return array array containing the id of the user/course/group, the relevant context and the filter type (site/user/course/group)
+ *
+ * @param array $filters filters for the blog
+ * @return array array containing the id of the user/course/group, the relevant context and the filter type: site/user/course/group
*/
function blog_rss_get_params($filters) {
$thingid = $rsscontext = $filtertype = null;
return array($thingid, $rsscontext, $filtertype);
}
-
-// Generate any blog RSS feed via one function (called by ../rss/file.php)
+/**
+ * Generate any blog RSS feed via one function
+ *
+ * @param stdClass $context The context of the blog for which the feed it being generated
+ * @param array $args An array of arguements needed to build the feed (contextid, token, componentname, type, id, tagid)
+ */
function blog_rss_get_feed($context, $args) {
global $CFG, $SITE, $DB;
}
}
-
+/**
+ * Retrieve the location and file name of a cached RSS feed
+ *
+ * @param string $type The source of the RSS feed (site/course/group/user)
+ * @param int $id The id of the item defined by $type
+ * @param int $tagid The id of the row in the tag table that identifies the RSS Feed
+ * @return string
+ */
function blog_rss_file_name($type, $id, $tagid=0) {
global $CFG;
}
}
-//This function saves to file the rss feed specified in the parameters
+/**
+ * This function saves to file the rss feed specified in the parameters
+ *
+ * @param string $type The source of the RSS feed (site/course/group/user)
+ * @param int $id The id of the item defined by $type
+ * @param int $tagid The id of the row in the tag table that identifies the RSS Feed
+ * @param string $contents The contents of the RSS Feed file
+ * @return bool whether the save was successful or not
+ */
function blog_rss_save_file($type, $id, $tagid=0, $contents='') {
global $CFG;
$string['pluginname'] = 'LDAP enrolments';
$string['pluginname_desc'] = '<p>You can use an LDAP server to control your enrolments. It is assumed your LDAP tree contains groups that map to the courses, and that each of those groups/courses will have membership entries to map to students.</p><p>It is assumed that courses are defined as groups in LDAP, with each group having multiple membership fields (<em>member</em> or <em>memberUid</em>) that contain a uniqueidentification of the user.</p><p>To use LDAP enrolment, your users <strong>must</strong> to have a valid idnumber field. The LDAP groups must have that idnumber in the member fields for a user to be enrolled in the course. This will usually work well if you are already using LDAP Authentication.</p><p>Enrolments will be updated when the user logs in. You can also run a script to keep enrolments in synch. Look in <em>enrol/ldap/cli/sync.php</em>.</p><p>This plugin can also be set to automatically create new courses when new groups appear in LDAP.</p>';
$string['pluginnotenabled'] = 'Plugin not enabled!';
-$string['role_mapping'] = '<p>For each rol that you want to assign from LDAP, you need to specify the list of contexts where the role courses\'s groups are located. Separate different contexts with \';\'.</p><p>You also need to specify the attribute your LDAP server uses to hold the members of a group. Usually \'member\' or \'memberUid\'</p>';
+$string['role_mapping'] = '<p>For each rol
e that you want to assign from LDAP, you need to specify the list of contexts where the role courses\'s groups are located. Separate different contexts with \';\'.</p><p>You also need to specify the attribute your LDAP server uses to hold the members of a group. Usually \'member\' or \'memberUid\'</p>';
$string['role_mapping_key'] = 'Map roles from LDAP ';
$string['roles'] = 'Role mapping';
$string['server_settings'] = 'LDAP server settings';
.gradingform_rubric_editform .status.ready {background-color:#e7f1c3;border-color:#AAEEAA;}
.gradingform_rubric_editform .status.draft {background-color:#f3f2aa;border-color:#EEEE22;}
+.gradingform_rubric {overflow:auto;padding-bottom:1.5em;max-width:720px;position:relative;}
+
.gradingform_rubric.editor .criterion .controls,
.gradingform_rubric .criterion .description,
.gradingform_rubric .criterion .levels,
$string['strftimedate'] = '%d %B %Y';
$string['strftimedatefullshort'] = '%d/%m/%y';
$string['strftimedateshort'] = '%d %B';
-$string['strftimedatetime'] = '%d %B %Y, %l:%M %p';
+$string['strftimedatetime'] = '%d %B %Y, %I:%M %p';
$string['strftimedatetimeshort'] = '%d/%m/%y, %H:%M';
$string['strftimedaydate'] = '%A, %d %B %Y';
-$string['strftimedaydatetime'] = '%A, %d %B %Y, %l:%M %p';
+$string['strftimedaydatetime'] = '%A, %d %B %Y, %I:%M %p';
$string['strftimedayshort'] = '%A, %d %B';
$string['strftimedaytime'] = '%a, %H:%M';
$string['strftimemonthyear'] = '%B %Y';
$string['strftimerecent'] = '%d %b, %H:%M';
-$string['strftimerecentfull'] = '%a, %d %b %Y, %l:%M %p';
-$string['strftimetime'] = '%l:%M %p';
+$string['strftimerecentfull'] = '%a, %d %b %Y, %I:%M %p';
+$string['strftimetime'] = '%I:%M %p';
$string['thisdirection'] = 'ltr';
$string['thisdirectionvertical'] = 'btt';
$string['thislanguage'] = 'English';
<FIELD NAME="subject" TYPE="char" LENGTH="128" NOTNULL="true" SEQUENCE="false" PREVIOUS="coursemoduleid" NEXT="summary"/>
<FIELD NAME="summary" TYPE="text" LENGTH="big" NOTNULL="false" SEQUENCE="false" PREVIOUS="subject" NEXT="content"/>
<FIELD NAME="content" TYPE="text" LENGTH="big" NOTNULL="false" SEQUENCE="false" PREVIOUS="summary" NEXT="uniquehash"/>
- <FIELD NAME="uniquehash" TYPE="char" LENGTH="128" NOTNULL="true" SEQUENCE="false" PREVIOUS="content" NEXT="rating"/>
+ <FIELD NAME="uniquehash" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" PREVIOUS="content" NEXT="rating"/>
<FIELD NAME="rating" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="uniquehash" NEXT="format"/>
<FIELD NAME="format" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="rating" NEXT="summaryformat"/>
<FIELD NAME="summaryformat" TYPE="int" LENGTH="2" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="format" NEXT="attachment"/>
upgrade_main_savepoint(true, 2012020200.06);
}
+ if ($oldversion < 2012021700.01) {
+ // Changing precision of field uniquehash on table post to 255
+ $table = new xmldb_table('post');
+ $field = new xmldb_field('uniquehash', XMLDB_TYPE_CHAR, '255', null, XMLDB_NOTNULL, null, null, 'content');
+
+ // Launch change of precision for field uniquehash
+ $dbman->change_field_precision($table, $field);
+
+ // Main savepoint reached
+ upgrade_main_savepoint(true, 2012021700.01);
+ }
+
+ if ($oldversion < 2012021700.02) {
+ // Somewhere before 1.9 summary and content column in post table were not null. In 1.9+
+ // not null became false.
+ $columns = $DB->get_columns('post');
+
+ // Fix discrepancies in summary field after upgrade from 1.9
+ if (array_key_exists('summary', $columns) && $columns['summary']->not_null != false) {
+ $table = new xmldb_table('post');
+ $summaryfield = new xmldb_field('summary', XMLDB_TYPE_TEXT, 'big', null, null, null, null, 'subject');
+
+ if ($dbman->field_exists($table, $summaryfield)) {
+ $dbman->change_field_notnull($table, $summaryfield);
+ }
+
+ }
+
+ // Fix discrepancies in content field after upgrade from 1.9
+ if (array_key_exists('content', $columns) && $columns['content']->not_null != false) {
+ $table = new xmldb_table('post');
+ $contentfield = new xmldb_field('content', XMLDB_TYPE_TEXT, 'big', null, null, null, null, 'summary');
+
+ if ($dbman->field_exists($table, $contentfield)) {
+ $dbman->change_field_notnull($table, $contentfield);
+ }
+
+ }
+
+ upgrade_main_savepoint(true, 2012021700.02);
+ }
+
return true;
}
* Database column information.
*
* @package core
+ * @category dml
* @subpackage dml
* @copyright 2008 Petr Skoda (http://skodak.org)
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
defined('MOODLE_INTERNAL') || die();
/**
- * Detail database field information.
- * Based on ADOFieldObject.
+ * Detailed database field information.
+ *
+ * It is based on the adodb library's ADOFieldObject object.
+ * 'column' does mean 'the field' here.
+ *
+ * @package core
+ * @category dml
+ * @copyright 2008 Petr Skoda (http://skodak.org)
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class database_column_info {
/**
- * Name of column - lowercase
+ * Name of column - lowercase.
+ * @var string
*/
public $name;
/**
- * Driver dependent native data type
- * Not standardised - used to find meta_type
+ * Driver dependent native data type.
+ * Not standardised, its used to find meta_type.
+ * @var string
*/
public $type;
* float - digits left from floating point
* boolean - 1
* enums - null
+ * @var int
*/
public $max_length;
* Scale
* float - decimal points
* other - null
+ * @var int
*/
public $scale;
*
* For performance reasons this field is optional!
* You can use DDL sql_generator::getCheckConstraintsFromDB() if needed.
+ * @var string
*/
public $enums;
/**
* True if not null, false otherwise
+ * @var bool
*/
public $not_null;
/**
* True if column is primary key.
* (usually 'id').
+ * @var bool
*/
public $primary_key;
/**
* True if filed autoincrementing
* (usually 'id' only)
+ * @var bool
*/
public $auto_increment;
/**
* True if binary
+ * @var bool
*/
public $binary;
/**
* True if integer unsigned, false if signed.
* Null for other types
+ * @var integer
*/
public $unsigned;
/**
- * True if default value defined
+ * True if the default value is defined.
+ * @var bool
*/
public $has_default;
/**
- * Default value if defined
+ * The default value (if defined).
+ * @var string
*/
public $default_value;
/**
- * True if field values unique, false if not
+ * True if field values are unique, false if not.
+ * @var bool
*/
public $unique;
/**
- * Standardised one character column type, uppercase
+ * Standardised one character column type, uppercased and enumerated as follows:
* R - counter (integer primary key)
* I - integers
* N - numbers (floats)
* L - boolean (1 bit)
* T - timestamp - unsupported
* D - date - unsupported
+ * @var string
*/
public $meta_type;
/**
* Constructor
- * @param $data mixed object or array with properties
+ * @param mixed $data object or array with properties
*/
public function __construct($data) {
foreach ($data as $key=>$value) {
/**
* Abstract database driver class.
*
- * @package core
+ * @package core
+ * @category dml
* @subpackage dml
- * @copyright 2008 Petr Skoda (http://skodak.org)
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @copyright 2008 Petr Skoda (http://skodak.org)
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
defined('MOODLE_INTERNAL') || die();
/// GLOBAL CONSTANTS /////////////////////////////////////////////////////////
-/** Bitmask, indicates :name type parameters are supported by db backend. */
+/** SQL_PARAMS_NAMED - Bitmask, indicates :name type parameters are supported by db backend. */
define('SQL_PARAMS_NAMED', 1);
-/** Bitmask, indicates ? type parameters are supported by db backend. */
+/** SQL_PARAMS_QM - Bitmask, indicates ? type parameters are supported by db backend. */
define('SQL_PARAMS_QM', 2);
-/** Bitmask, indicates $1, $2, ... type parameters are supported by db backend. */
+/** SQL_PARAMS_DOLLAR - Bitmask, indicates $1, $2, ... type parameters are supported by db backend. */
define('SQL_PARAMS_DOLLAR', 4);
-
-/** Normal select query, reading only */
+/** SQL_QUERY_SELECT - Normal select query, reading only. */
define('SQL_QUERY_SELECT', 1);
-/** Insert select query, writing */
+/** SQL_QUERY_INSERT - Insert select query, writing. */
define('SQL_QUERY_INSERT', 2);
-/** Update select query, writing */
+/** SQL_QUERY_UPDATE - Update select query, writing. */
define('SQL_QUERY_UPDATE', 3);
-/** Query changing db structure, writing */
+/** SQL_QUERY_STRUCTURE - Query changing db structure, writing. */
define('SQL_QUERY_STRUCTURE', 4);
-/** Auxiliary query done by driver, setting connection config, getting table info, etc. */
+/** SQL_QUERY_AUX - Auxiliary query done by driver, setting connection config, getting table info, etc. */
define('SQL_QUERY_AUX', 5);
/**
* Abstract class representing moodle database interface.
+ * @link http://docs.moodle.org/dev/DML_functions
+ *
+ * @package core
+ * @category dml
+ * @copyright 2008 Petr Skoda (http://skodak.org)
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
abstract class moodle_database {
- /** @var database_manager db manager which allows db structure modifications */
+ /** @var database_manager db manager which allows db structure modifications. */
protected $database_manager;
- /** @var moodle_temptables temptables manager to provide cross-db support for temp tables */
+ /** @var moodle_temptables temptables manager to provide cross-db support for temp tables. */
protected $temptables;
- /** @var array cache of column info */
+ /** @var array Cache of column info. */
protected $columns = array(); // I wish we had a shared memory cache for this :-(
- /** @var array cache of table info */
+ /** @var array Cache of table info. */
protected $tables = null;
// db connection options
- /** @var string db host name */
+ /** @var string db host name. */
protected $dbhost;
- /** @var string db host user */
+ /** @var string db host user. */
protected $dbuser;
- /** @var string db host password */
+ /** @var string db host password. */
protected $dbpass;
- /** @var string db name */
+ /** @var string db name. */
protected $dbname;
- /** @var string table prefix */
+ /** @var string Prefix added to table names. */
protected $prefix;
- /** @var array Database or driver specific options, such as sockets or TCPIP db connections */
+ /** @var array Database or driver specific options, such as sockets or TCPIP db connections. */
protected $dboptions;
- /** @var bool true means non-moodle external database used.*/
+ /** @var bool True means non-moodle external database used.*/
protected $external;
/** @var int The database reads (performance counter).*/
/** @var int The database writes (performance counter).*/
protected $writes = 0;
- /** @var int Debug level */
+ /** @var int Debug level. */
protected $debug = 0;
- /** @var string last query sql */
+ /** @var string Last used query sql. */
protected $last_sql;
- /** @var array last query parameters */
+ /** @var array Last query parameters. */
protected $last_params;
- /** @var int last query type */
+ /** @var int Last query type. */
protected $last_type;
- /** @var string last extra info */
+ /** @var string Last extra info. */
protected $last_extrainfo;
- /** @var float last time in seconds with millisecond precision */
+ /** @var float Last time in seconds with millisecond precision. */
protected $last_time;
- /** @var bool flag indicating logging of query in progress, prevents infinite loops */
+ /** @var bool Flag indicating logging of query in progress. This helps prevent infinite loops. */
private $loggingquery = false;
- /** @var bool true if db used for db sessions */
+ /** @var bool True if the db is used for db sessions. */
protected $used_for_db_sessions = false;
- /** @var array open transactions */
+ /** @var array Array containing open transactions. */
private $transactions = array();
- /** @var bool force rollback of all current transactions */
+ /** @var bool Flag used to force rollback of all current transactions. */
private $force_rollback = false;
- /** @var int internal temporary variable */
+ /**
+ * @var int internal temporary variable used to fix params. Its used by {@link _fix_sql_params_dollar_callback()}.
+ */
private $fix_sql_params_i;
- /** @var int internal temporary variable used by {@link get_in_or_equal()}. */
- private $inorequaluniqueindex = 1; // guarantees unique parameters in each request
+ /**
+ * @var int internal temporary variable used to guarantee unique parameters in each request. Its used by {@link get_in_or_equal()}.
+ */
+ private $inorequaluniqueindex = 1;
/**
- * Constructor - instantiates the database, specifying if it's external (connect to other systems) or no (Moodle DB)
- * note this has effect to decide if prefix checks must be performed or no
- * @param bool true means external database used
+ * Constructor - Instantiates the database, specifying if it's external (connect to other systems) or not (Moodle DB).
+ * Note that this affects the decision of whether prefix checks must be performed or not.
+ * @param bool $external True means that an external database is used.
*/
public function __construct($external=false) {
$this->external = $external;
}
/**
- * Detects if all needed PHP stuff installed.
+ * Detects if all needed PHP stuff are installed for DB connectivity.
* Note: can be used before connect()
- * @return mixed true if ok, string if something
+ * @return mixed True if requirements are met, otherwise a string if something isn't installed.
*/
public abstract function driver_installed();
/**
* Returns database table prefix
* Note: can be used before connect()
- * @return string database table prefix
+ * @return string The prefix used in the database.
*/
public function get_prefix() {
return $this->prefix;
/**
* Loads and returns a database instance with the specified type and library.
- * @param string $type database type of the driver (mysqli, pgsql, mssql, sqldrv, oci, etc.)
- * @param string $library database library of the driver (native, pdo, etc.)
- * @param boolean $external true if this is an external database
- * @return moodle_database driver object or null if error
+ *
+ * The loaded class is within lib/dml directory and of the form: $type.'_'.$library.'_moodle_database'
+ *
+ * @param string $type Database driver's type. (eg: mysqli, pgsql, mssql, sqldrv, oci, etc.)
+ * @param string $library Database driver's library (native, pdo, etc.)
+ * @param bool $external True if this is an external database.
+ * @return moodle_database driver object or null if error, for example of driver object see {@link mysqli_native_moodle_database}
*/
public static function get_driver_instance($type, $library, $external = false) {
global $CFG;
}
/**
- * Returns database family type - describes SQL dialect
+ * Returns the database family type. (This sort of describes the SQL 'dialect')
* Note: can be used before connect()
- * @return string db family name (mysql, postgres, mssql, oracle, etc.)
+ * @return string The db family name (mysql, postgres, mssql, oracle, etc.)
*/
public abstract function get_dbfamily();
/**
- * Returns more specific database driver type
+ * Returns a more specific database driver type
* Note: can be used before connect()
- * @return string db type mysqli, pgsql, oci, mssql, sqlsrv
+ * @return string The db type mysqli, pgsql, oci, mssql, sqlsrv
*/
protected abstract function get_dbtype();
/**
- * Returns general database library name
+ * Returns the general database library name
* Note: can be used before connect()
- * @return string db type pdo, native
+ * @return string The db library type - pdo, native etc.
*/
protected abstract function get_dblibrary();
/**
- * Returns localised database type name
+ * Returns the localised database type name
* Note: can be used before connect()
* @return string
*/
public abstract function get_name();
/**
- * Returns localised database configuration help.
+ * Returns the localised database configuration help.
* Note: can be used before connect()
* @return string
*/
public abstract function get_configuration_help();
/**
- * Returns localised database description
+ * Returns the localised database description
* Note: can be used before connect()
* @return string
*/
public abstract function get_configuration_hints();
/**
- * Returns db related part of config.php
- * @return object
+ * Returns the db related part of config.php
+ * @return stdClass
*/
public function export_dbconfig() {
$cfg = new stdClass();
}
/**
- * Connect to db
+ * Connects to the database.
* Must be called before other methods.
- * @param string $dbhost
- * @param string $dbuser
- * @param string $dbpass
- * @param string $dbname
+ * @param string $dbhost The database host.
+ * @param string $dbuser The database user to connect as.
+ * @param string $dbpass The password to use when connecting to the database.
+ * @param string $dbname The name of the database being connected to.
* @param mixed $prefix string means moodle db prefix, false used for external databases where prefix not used
* @param array $dboptions driver specific options
* @return bool true
/**
* Store various database settings
- * @param string $dbhost
- * @param string $dbuser
- * @param string $dbpass
- * @param string $dbname
+ * @param string $dbhost The database host.
+ * @param string $dbuser The database user to connect as.
+ * @param string $dbpass The password to use when connecting to the database.
+ * @param string $dbname The name of the database being connected to.
* @param mixed $prefix string means moodle db prefix, false used for external databases where prefix not used
* @param array $dboptions driver specific options
* @return void
/**
* Attempt to create the database
- * @param string $dbhost
- * @param string $dbuser
- * @param string $dbpass
- * @param string $dbname
+ * @param string $dbhost The database host.
+ * @param string $dbuser The database user to connect as.
+ * @param string $dbpass The password to use when connecting to the database.
+ * @param string $dbname The name of the database being connected to.
+ * @param array $dboptions An array of optional database options (eg: dbport)
*
- * @return bool success
+ * @return bool success True for successful connection. False otherwise.
*/
public function create_database($dbhost, $dbuser, $dbpass, $dbname, array $dboptions=null) {
return false;
}
/**
- * Close database connection and release all resources
+ * Closes the database connection and releases all resources
* and memory (especially circular memory references).
* Do NOT use connect() again, create a new instance if needed.
* @return void
}
/**
- * Called before each db query.
- * @param string $sql
- * @param array array of parameters
- * @param int $type type of query
- * @param mixed $extrainfo driver specific extra information
+ * This should be called before each db query.
+ * @param string $sql The query string.
+ * @param array $params An array of parameters.
+ * @param int $type The type of query. ( SQL_QUERY_SELECT | SQL_QUERY_AUX | SQL_QUERY_INSERT | SQL_QUERY_UPDATE | SQL_QUERY_STRUCTURE )
+ * @param mixed $extrainfo This is here for any driver specific extra information.
* @return void
*/
protected function query_start($sql, array $params=null, $type, $extrainfo=null) {
}
/**
- * Called immediately after each db query.
- * @param mixed db specific result
+ * This should be called immediately after each db query. It does a clean up of resources.
+ * It also throws exceptions if the sql that ran produced errors.
+ * @param mixed $result The db specific result obtained from running a query.
+ * @throws dml_read_exception | dml_write_exception | ddl_change_structure_exception
* @return void
*/
protected function query_end($result) {
}
/**
- * Log last database query if requested
+ * This logs the last query based on 'logall', 'logslow' and 'logerrors' options configured via $CFG->dboptions .
* @param mixed string error or false if not error
* @return void
*/
/**
* Returns database server info array
- * @return array
+ * @return array Array containing 'description' and 'version' atleast.
*/
public abstract function get_server_info();
/**
* Returns supported query parameter types
- * @return int bitmask
+ * @return int bitmask of accepted SQL_PARAMS_*
*/
protected abstract function allowed_param_types();
/**
- * Returns last error reported by database engine.
- * @return string error message
+ * Returns the last error reported by the database engine.
+ * @return string The error message.
*/
public abstract function get_last_error();
/**
- * Print sql debug info
- * @param string $sql query which caused problems
- * @param array $params optional query parameters
- * @param mixed $obj optional library specific object
+ * Prints sql debug info
+ * @param string $sql The query which is being debugged.
+ * @param array $params The query parameters. (optional)
+ * @param mixed $obj The library specific object. (optional)
* @return void
*/
protected function print_debug($sql, array $params=null, $obj=null) {
}
/**
- * Returns SQL WHERE conditions.
- * @param string $table - the table name that these conditions will be validated against.
- * @param array conditions - must not contain numeric indexes
- * @return array sql part and params
+ * Returns the SQL WHERE conditions.
+ * @param string $table The table name that these conditions will be validated against.
+ * @param array $conditions The conditions to build the where clause. (must not contain numeric indexes)
+ * @throws dml_exception
+ * @return array An array list containing sql 'where' part and 'params'.
*/
protected function where_clause($table, array $conditions=null) {
// We accept nulls in conditions
}
/**
- * Returns SQL WHERE conditions for the ..._list methods.
+ * Returns SQL WHERE conditions for the ..._list group of methods.
*
* @param string $field the name of a field.
* @param array $values the values field might take.
- * @return array sql part and params
+ * @return array An array containing sql 'where' part and 'params'
*/
protected function where_clause_list($field, array $values) {
$params = array();
}
/**
- * Constructs IN() or = sql fragment
- * @param mixed $items single or array of values
- * @param int $type bound param type SQL_PARAMS_QM or SQL_PARAMS_NAMED
- * @param string $prefix named parameter placeholder prefix (unique counter value is appended to each parameter name)
- * @param bool $equal true means equal, false not equal
- * @param mixed $onemptyitems defines the behavior when the array of items is empty. Defaults to false,
+ * Constructs 'IN()' or '=' sql fragment
+ * @param mixed $items A single value or array of values for the expression.
+ * @param int $type Parameter bounding type : SQL_PARAMS_QM or SQL_PARAMS_NAMED.
+ * @param string $prefix Named parameter placeholder prefix (a unique counter value is appended to each parameter name).
+ * @param bool $equal True means we want to equate to the constructed expression, false means we don't want to equate to it.
+ * @param mixed $onemptyitems This defines the behavior when the array of items provided is empty. Defaults to false,
* meaning throw exceptions. Other values will become part of the returned SQL fragment.
- * @return array - $sql and $params
+ * @throws coding_exception | dml_exception
+ * @return array A list containing the constructed sql fragment and an array of parameters.
*/
public function get_in_or_equal($items, $type=SQL_PARAMS_QM, $prefix='param', $equal=true, $onemptyitems=false) {
}
/**
- * Converts short table name {tablename} to real table name
- * @param string sql
- * @return string sql
+ * Converts short table name {tablename} to the real prefixed table name in given sql.
+ * @param string $sql The sql to be operated on.
+ * @return string The sql with tablenames being prefixed with $CFG->prefix
*/
protected function fix_table_names($sql) {
return preg_replace('/\{([a-z][a-z0-9_]*)\}/', $this->prefix.'$1', $sql);
}
- /** Internal function */
+ /**
+ * Internal private utitlity function used to fix parameters.
+ * Used with {@link preg_replace_callback()}
+ * @param array $match Refer to preg_replace_callback usage for description.
+ */
private function _fix_sql_params_dollar_callback($match) {
$this->fix_sql_params_i++;
return "\$".$this->fix_sql_params_i;
/**
* Normalizes sql query parameters and verifies parameters.
- * @param string $sql query or part of it
- * @param array $params query parameters
+ * @param string $sql The query or part of it.
+ * @param array $params The query parameters.
* @return array (sql, params, type of params)
*/
public function fix_sql_params($sql, array $params=null) {
}
/**
- * Return tables in database WITHOUT current prefix
+ * Return tables in database WITHOUT current prefix.
+ * @param bool $usecache if true, returns list of cached tables.
* @return array of table names in lowercase and without prefix
*/
public abstract function get_tables($usecache=true);
/**
- * Return table indexes - everything lowercased
- * @return array of arrays
+ * Return table indexes - everything lowercased.
+ * @param string $table The table we want to get indexes from.
+ * @return array An associative array of indexes containing 'unique' flag and 'columns' being indexed
*/
public abstract function get_indexes($table);
/**
* Returns detailed information about columns in table. This information is cached internally.
- * @param string $table name
- * @param bool $usecache
+ * @param string $table The table's name.
+ * @param bool $usecache Flag to use internal cacheing. The default is true.
* @return array of database_column_info objects indexed with column names
*/
public abstract function get_columns($table, $usecache=true);
/**
- * Normalise values based in RDBMS dependencies (booleans, LOBs...)
+ * Normalise values based on varying RDBMS's dependencies (booleans, LOBs...)
*
* @param database_column_info $column column metadata corresponding with the value we are going to normalise
* @param mixed $value value we are going to normalise
protected abstract function normalise_value($column, $value);
/**
- * Reset internal column details cache
- * @param string $table - empty means all, or one if name of table given
+ * Resets the internal column details cache
* @return void
*/
public function reset_caches() {
}
/**
- * Returns sql generator used for db manipulation.
+ * Returns the sql generator used for db manipulation.
* Used mostly in upgrade.php scripts.
- * @return database_manager instance
+ * @return database_manager The instance used to perform ddl operations.
+ * @see lib/ddl/database_manager.php
*/
public function get_manager() {
global $CFG;
}
/**
- * Attempt to change db encoding toUTF-8 if possible
- * @return bool success
+ * Attempts to change db encoding to UTF-8 encoding if possible.
+ * @return bool True is successful.
*/
public function change_db_encoding() {
return false;
}
/**
- * Is db in unicode mode?
+ * Checks to see if the database is in unicode mode?
* @return bool
*/
public function setup_is_unicodedb() {
}
/**
- * Enable/disable very detailed debugging
+ * Enable/disable very detailed debugging.
* @param bool $state
* @return void
*/
}
/**
- * Do NOT use in code, to be used by database_manager only!
+ * Do NOT use in code, this is for use by database_manager only!
* @param string $sql query
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public abstract function change_database_structure($sql);
/**
- * Execute general sql query. Should be used only when no other method suitable.
+ * Executes a general sql query. Should be used only when no other method suitable.
* Do NOT use this to make changes in db structure, use database_manager::execute_sql() instead!
* @param string $sql query
* @param array $params query parameters
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public abstract function execute($sql, array $params=null);
* @param array $conditions optional array $fieldname=>requestedvalue with AND in between
* @param string $sort an order to sort the results in (optional, a valid SQL ORDER BY parameter).
* @param string $fields a comma separated list of fields to return (optional, by default all fields are returned).
- * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
+ * @param int $limitfrom return a subset of records, starting at this point (optional).
* @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
- * @return moodle_recordset instance
- * @throws dml_exception if error
+ * @return moodle_recordset A moodle_recordset instance
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_recordset($table, array $conditions=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0) {
list($select, $params) = $this->where_clause($table, $conditions);
* Only records where $field takes one of the values $values are returned.
* $values must be an array of values.
*
- * Other arguments and the return type as for @see function get_recordset.
+ * Other arguments and the return type are like {@link function get_recordset}.
*
* @param string $table the table to query.
* @param string $field a field to check (optional).
* @param array $values array of values the field must have
* @param string $sort an order to sort the results in (optional, a valid SQL ORDER BY parameter).
* @param string $fields a comma separated list of fields to return (optional, by default all fields are returned).
- * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
+ * @param int $limitfrom return a subset of records, starting at this point (optional).
* @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
- * @return moodle_recordset instance
- * @throws dml_exception if error
+ * @return moodle_recordset A moodle_recordset instance.
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_recordset_list($table, $field, array $values, $sort='', $fields='*', $limitfrom=0, $limitnum=0) {
list($select, $params) = $this->where_clause_list($field, $values);
* If given, $select is used as the SELECT parameter in the SQL query,
* otherwise all records from the table are returned.
*
- * Other arguments and the return type as for @see function get_recordset.
+ * Other arguments and the return type are like {@link function get_recordset}.
*
* @param string $table the table to query.
* @param string $select A fragment of SQL to be used in a where clause in the SQL call.
* @param array $params array of sql parameters
* @param string $sort an order to sort the results in (optional, a valid SQL ORDER BY parameter).
* @param string $fields a comma separated list of fields to return (optional, by default all fields are returned).
- * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
+ * @param int $limitfrom return a subset of records, starting at this point (optional).
* @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
- * @return moodle_recordset instance
- * @throws dml_exception if error
+ * @return moodle_recordset A moodle_recordset instance.
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_recordset_select($table, $select, array $params=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0) {
$sql = "SELECT $fields FROM {".$table."}";
* code where it's possible there might be large datasets being returned. For known
* small datasets use get_records_sql - it leads to simpler code.
*
- * The return type is as for @see function get_recordset.
+ * The return type is like {@link function get_recordset}.
*
* @param string $sql the SQL select query to execute.
* @param array $params array of sql parameters
- * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
+ * @param int $limitfrom return a subset of records, starting at this point (optional).
* @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
- * @return moodle_recordset instance
- * @throws dml_exception if error
+ * @return moodle_recordset A moodle_recordset instance.
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public abstract function get_recordset_sql($sql, array $params=null, $limitfrom=0, $limitnum=0);
* @param string $fields a comma separated list of fields to return (optional, by default
* all fields are returned). The first field will be used as key for the
* array so must be a unique field such as 'id'.
- * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
- * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
- * @return array of objects indexed by first column
- * @throws dml_exception if error
+ * @param int $limitfrom return a subset of records, starting at this point (optional).
+ * @param int $limitnum return a subset comprising this many records in total (optional, required if $limitfrom is set).
+ * @return array An array of Objects indexed by first column.
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_records($table, array $conditions=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0) {
list($select, $params) = $this->where_clause($table, $conditions);
/**
* Get a number of records as an array of objects where one field match one list of values.
*
- * Return value as for @see function get_records.
+ * Return value is like {@link function get_records}.
*
* @param string $table The database table to be checked against.
* @param string $field The field to search
- * @param string $values array of values
+ * @param array $values An array of values
* @param string $sort Sort order (as valid SQL sort parameter)
* @param string $fields A comma separated list of fields to be returned from the chosen table. If specified,
* the first field should be a unique one such as 'id' since it will be used as a key in the associative
* array.
- * @return array of objects indexed by first column
- * @throws dml_exception if error
+ * @return array An array of objects indexed by first column
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_records_list($table, $field, array $values, $sort='', $fields='*', $limitfrom=0, $limitnum=0) {
list($select, $params) = $this->where_clause_list($field, $values);
/**
* Get a number of records as an array of objects which match a particular WHERE clause.
*
- * Return value as for @see function get_records.
+ * Return value is like {@link function get_records}.
*
- * @param string $table the table to query.
+ * @param string $table The table to query.
* @param string $select A fragment of SQL to be used in a where clause in the SQL call.
- * @param array $params array of sql parameters
- * @param string $sort an order to sort the results in (optional, a valid SQL ORDER BY parameter).
- * @param string $fields a comma separated list of fields to return
+ * @param array $params An array of sql parameters
+ * @param string $sort An order to sort the results in (optional, a valid SQL ORDER BY parameter).
+ * @param string $fields A comma separated list of fields to return
* (optional, by default all fields are returned). The first field will be used as key for the
* array so must be a unique field such as 'id'.
- * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
- * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
+ * @param int $limitfrom return a subset of records, starting at this point (optional).
+ * @param int $limitnum return a subset comprising this many records in total (optional, required if $limitfrom is set).
* @return array of objects indexed by first column
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_records_select($table, $select, array $params=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0) {
if ($select) {
/**
* Get a number of records as an array of objects using a SQL statement.
*
- * Return value as for @see function get_records.
+ * Return value is like {@link function get_records}.
*
* @param string $sql the SQL select query to execute. The first column of this SELECT statement
* must be a unique value (usually the 'id' field), as it will be used as the key of the
* returned array.
* @param array $params array of sql parameters
- * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
- * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
+ * @param int $limitfrom return a subset of records, starting at this point (optional).
+ * @param int $limitnum return a subset comprising this many records in total (optional, required if $limitfrom is set).
* @return array of objects indexed by first column
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public abstract function get_records_sql($sql, array $params=null, $limitfrom=0, $limitnum=0);
/**
* Get the first two columns from a number of records as an associative array where all the given conditions met.
*
- * Arguments as for @see function get_recordset.
+ * Arguments are like {@link function get_recordset}.
*
* If no errors occur the return value
* is an associative whose keys come from the first field of each record,
* @param array $conditions optional array $fieldname=>requestedvalue with AND in between
* @param string $sort an order to sort the results in (optional, a valid SQL ORDER BY parameter).
* @param string $fields a comma separated list of fields to return - the number of fields should be 2!
- * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
+ * @param int $limitfrom return a subset of records, starting at this point (optional).
* @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
* @return array an associative array
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_records_menu($table, array $conditions=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0) {
$menu = array();
/**
* Get the first two columns from a number of records as an associative array which match a particular WHERE clause.
*
- * Arguments as for @see function get_recordset_select.
- * Return value as for @see function get_records_menu.
+ * Arguments are like {@link function get_recordset_select}.
+ * Return value is like {@link function get_records_menu}.
*
* @param string $table The database table to be checked against.
* @param string $select A fragment of SQL to be used in a where clause in the SQL call.
* @param array $params array of sql parameters
* @param string $sort Sort order (optional) - a valid SQL order parameter
* @param string $fields A comma separated list of fields to be returned from the chosen table - the number of fields should be 2!
- * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
+ * @param int $limitfrom return a subset of records, starting at this point (optional).
* @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
* @return array an associative array
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_records_select_menu($table, $select, array $params=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0) {
$menu = array();
/**
* Get the first two columns from a number of records as an associative array using a SQL statement.
*
- * Arguments as for @see function get_recordset_sql.
- * Return value as for @see function get_records_menu.
+ * Arguments are like {@link function get_recordset_sql}.
+ * Return value is like {@link function get_records_menu}.
*
* @param string $sql The SQL string you wish to be executed.
* @param array $params array of sql parameters
- * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
+ * @param int $limitfrom return a subset of records, starting at this point (optional).
* @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
* @return array an associative array
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_records_sql_menu($sql, array $params=null, $limitfrom=0, $limitnum=0) {
$menu = array();
* @param string $fields A comma separated list of fields to be returned from the chosen table.
* @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
+ * MUST_EXIST means we will throw an exception if no record or multiple records found.
+ *
+ * @todo MDL-30407 MUST_EXIST option should not throw a dml_exception, it should throw a different exception as it's a requested check.
* @return mixed a fieldset object containing the first matching record, false or exception if error not found depending on mode
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_record($table, array $conditions, $fields='*', $strictness=IGNORE_MISSING) {
list($select, $params) = $this->where_clause($table, $conditions);
* IGNORE_MULTIPLE means return first, ignore multiple records found(not recommended);
* MUST_EXIST means throw exception if no record or multiple records found
* @return mixed a fieldset object containing the first matching record, false or exception if error not found depending on mode
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_record_select($table, $select, array $params=null, $fields='*', $strictness=IGNORE_MISSING) {
if ($select) {
* IGNORE_MULTIPLE means return first, ignore multiple records found(not recommended);
* MUST_EXIST means throw exception if no record or multiple records found
* @return mixed a fieldset object containing the first matching record, false or exception if error not found depending on mode
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_record_sql($sql, array $params=null, $strictness=IGNORE_MISSING) {
$strictness = (int)$strictness; // we support true/false for BC reasons too
* IGNORE_MULTIPLE means return first, ignore multiple records found(not recommended);
* MUST_EXIST means throw exception if no record or multiple records found
* @return mixed the specified value false if not found
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_field($table, $return, array $conditions, $strictness=IGNORE_MISSING) {
list($select, $params) = $this->where_clause($table, $conditions);
* IGNORE_MULTIPLE means return first, ignore multiple records found(not recommended);
* MUST_EXIST means throw exception if no record or multiple records found
* @return mixed the specified value false if not found
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_field_select($table, $return, $select, array $params=null, $strictness=IGNORE_MISSING) {
if ($select) {
* IGNORE_MULTIPLE means return first, ignore multiple records found(not recommended);
* MUST_EXIST means throw exception if no record or multiple records found
* @return mixed the specified value false if not found
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_field_sql($sql, array $params=null, $strictness=IGNORE_MISSING) {
if (!$record = $this->get_record_sql($sql, $params, $strictness)) {
* @param string $select A fragment of SQL to be used in a where clause in the SQL call.
* @param array $params array of sql parameters
* @return array of values
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_fieldset_select($table, $return, $select, array $params=null) {
if ($select) {
* @param string $sql The SQL query
* @param array $params array of sql parameters
* @return array of values
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public abstract function get_fieldset_sql($sql, array $params=null);
* Insert new record into database, as fast as possible, no safety checks, lobs not supported.
* @param string $table name
* @param mixed $params data record as object or array
- * @param bool $returnit return it of inserted record
+ * @param bool $returnid Returns id of inserted record.
* @param bool $bulk true means repeated inserts expected
* @param bool $customsequence true if 'id' included in $params, disables $returnid
* @return bool|int true or new id
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public abstract function insert_record_raw($table, $params, $returnid=true, $bulk=false, $customsequence=false);
* @param object $data A data object with values for one or more fields in the record
* @param bool $returnid Should the id of the newly created record entry be returned? If this option is not requested then true/false is returned.
* @return bool|int true or new id
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public abstract function insert_record($table, $dataobject, $returnid=true, $bulk=false);
* @param string $table name of database table to be inserted into
* @param object $dataobject A data object with values for one or more fields in the record
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public abstract function import_record($table, $dataobject);
* Update record in database, as fast as possible, no safety checks, lobs not supported.
* @param string $table name
* @param mixed $params data record as object or array
- * @param bool true means repeated updates expected
+ * @param bool $bulk True means repeated updates expected.
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public abstract function update_record_raw($table, $params, $bulk=false);
*
* @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 true means repeated updates expected
+ * @param bool $bulk True means repeated updates expected.
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public abstract function update_record($table, $dataobject, $bulk=false);
* @param string $newvalue the value to set the field to.
* @param array $conditions optional array $fieldname=>requestedvalue with AND in between
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function set_field($table, $newfield, $newvalue, array $conditions=null) {
list($select, $params) = $this->where_clause($table, $conditions);
* @param string $select A fragment of SQL to be used in a where clause in the SQL call.
* @param array $params array of sql parameters
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public abstract function set_field_select($table, $newfield, $newvalue, $select, array $params=null);
* @param string $table The table to query.
* @param array $conditions optional array $fieldname=>requestedvalue with AND in between
* @return int The count of records returned from the specified criteria.
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function count_records($table, array $conditions=null) {
list($select, $params) = $this->where_clause($table, $conditions);
* @param array $params array of sql parameters
* @param string $countitem The count string to be used in the SQL call. Default is COUNT('x').
* @return int The count of records returned from the specified criteria.
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function count_records_select($table, $select, array $params=null, $countitem="COUNT('x')") {
if ($select) {
* @param string $sql The SQL string you wish to be executed.
* @param array $params array of sql parameters
* @return int the count
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function count_records_sql($sql, array $params=null) {
if ($count = $this->get_field_sql($sql, $params)) {
* @param string $table The table to check.
* @param array $conditions optional array $fieldname=>requestedvalue with AND in between
* @return bool true if a matching record exists, else false.
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function record_exists($table, array $conditions) {
list($select, $params) = $this->where_clause($table, $conditions);
* @param string $select A fragment of SQL to be used in a WHERE clause in the SQL call.
* @param array $params array of sql parameters
* @return bool true if a matching record exists, else false.
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function record_exists_select($table, $select, array $params=null) {
if ($select) {
* @param string $sql The SQL statement to execute.
* @param array $params array of sql parameters
* @return bool true if the SQL executes without errors and returns at least one record.
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function record_exists_sql($sql, array $params=null) {
$mrs = $this->get_recordset_sql($sql, $params, 0, 1);
* @param string $table the table to delete from.
* @param array $conditions optional array $fieldname=>requestedvalue with AND in between
* @return bool true.
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function delete_records($table, array $conditions=null) {
// truncate is drop/create (DDL), not transactional safe,
* @param string $field The field to search
* @param array $values array of values
* @return bool true.
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function delete_records_list($table, $field, array $values) {
list($select, $params) = $this->where_clause_list($field, $values);
* @param string $select A fragment of SQL to be used in a where clause in the SQL call (used to define the selection criteria).
* @param array $params array of sql parameters
* @return bool true.
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public abstract function delete_records_select($table, $select, array $params=null);
* NOTE: The SQL result is a number and can not be used directly in
* SQL condition, please compare it to some number to get a bool!!
*
- * @param int $int1 first integer in the operation
- * @param int $int2 second integer in the operation
- * @return string the piece of SQL code to be used in your statement
+ * @param int $int1 First integer in the operation.
+ * @param int $int2 Second integer in the operation.
+ * @return string The piece of SQL code to be used in your statement.
*/
public function sql_bitand($int1, $int2) {
return '((' . $int1 . ') & (' . $int2 . '))';
* Returns the SQL text to be used in order to perform one bitwise NOT operation
* with 1 integer.
*
- * @param int $int1 integer in the operation
- * @return string the piece of SQL code to be used in your statement.
+ * @param int $int1 The operand integer in the operation.
+ * @return string The piece of SQL code to be used in your statement.
*/
public function sql_bitnot($int1) {
return '(~(' . $int1 . '))';
* NOTE: The SQL result is a number and can not be used directly in
* SQL condition, please compare it to some number to get a bool!!
*
- * @param int $int1 first integer in the operation
- * @param int $int2 second integer in the operation
- * @return string the piece of SQL code to be used in your statement.
+ * @param int $int1 The first operand integer in the operation.
+ * @param int $int2 The second operand integer in the operation.
+ * @return string The piece of SQL code to be used in your statement.
*/
public function sql_bitor($int1, $int2) {
return '((' . $int1 . ') | (' . $int2 . '))';
* NOTE: The SQL result is a number and can not be used directly in
* SQL condition, please compare it to some number to get a bool!!
*
- * @param int $int1 first integer in the operation
- * @param int $int2 second integer in the operation
- * @return string the piece of SQL code to be used in your statement.
+ * @param int $int1 The first operand integer in the operation.
+ * @param int $int2 The second operand integer in the operation.
+ * @return string The piece of SQL code to be used in your statement.
*/
public function sql_bitxor($int1, $int2) {
return '((' . $int1 . ') ^ (' . $int2 . '))';
* Returns the SQL text to be used in order to perform module '%'
* operation - remainder after division
*
- * @param int $int1 first integer in the operation
- * @param int $int2 second integer in the operation
- * @return string the piece of SQL code to be used in your statement.
+ * @param int $int1 The first operand integer in the operation.
+ * @param int $int2 The second operand integer in the operation.
+ * @return string The piece of SQL code to be used in your statement.
*/
public function sql_modulo($int1, $int2) {
return '((' . $int1 . ') % (' . $int2 . '))';
}
/**
- * Returns the correct CEIL expression applied to fieldname.
+ * Returns the cross db correct CEIL (ceiling) expression applied to fieldname.
+ * note: Most DBs use CEIL(), hence it's the default here.
*
- * @param string $fieldname the field (or expression) we are going to ceil
- * @return string the piece of SQL code to be used in your ceiling statement
- * Most DB use CEIL(), hence it's the default.
+ * @param string $fieldname The field (or expression) we are going to ceil.
+ * @return string The piece of SQL code to be used in your ceiling statement.
*/
public function sql_ceil($fieldname) {
return ' CEIL(' . $fieldname . ')';
* Be aware that the CHAR column you're trying to cast contains really
* int values or the RDBMS will throw an error!
*
- * @param string $fieldname the name of the field to be casted
- * @param bool $text to specify if the original column is one TEXT (CLOB) column (true). Defaults to false.
- * @return string the piece of SQL code to be used in your statement.
+ * @param string $fieldname The name of the field to be casted.
+ * @param bool $text Specifies if the original column is one TEXT (CLOB) column (true). Defaults to false.
+ * @return string The piece of SQL code to be used in your statement.
*/
public function sql_cast_char2int($fieldname, $text=false) {
return ' ' . $fieldname . ' ';
* Be aware that the CHAR column you're trying to cast contains really
* numbers or the RDBMS will throw an error!
*
- * @param string $fieldname the name of the field to be casted
- * @param bool $text to specify if the original column is one TEXT (CLOB) column (true). Defaults to false.
- * @return string the piece of SQL code to be used in your statement.
+ * @param string $fieldname The name of the field to be casted.
+ * @param bool $text Specifies if the original column is one TEXT (CLOB) column (true). Defaults to false.
+ * @return string The piece of SQL code to be used in your statement.
*/
public function sql_cast_char2real($fieldname, $text=false) {
return ' ' . $fieldname . ' ';
* (Only MySQL needs this. MySQL things that 1 * -1 = 18446744073709551615
* if the 1 comes from an unsigned column).
*
- * @param string $fieldname the name of the field to be cast
- * @return string the piece of SQL code to be used in your statement.
+ * @param string $fieldname The name of the field to be cast
+ * @return string The piece of SQL code to be used in your statement.
*/
public function sql_cast_2signed($fieldname) {
return ' ' . $fieldname . ' ';
* one varchar column, because some RDBMS doesn't support such direct
* comparisons.
*
- * @param string $fieldname the name of the TEXT field we need to order by
- * @param int $numchars of chars to use for the ordering (defaults to 32)
- * @return string the piece of SQL code to be used in your statement.
+ * @param string $fieldname The name of the TEXT field we need to order by
+ * @param int $numchars Number of chars to use for the ordering (defaults to 32).
+ * @return string The piece of SQL code to be used in your statement.
*/
public function sql_compare_text($fieldname, $numchars=32) {
return $this->sql_order_by_text($fieldname, $numchars);
/**
* Returns 'LIKE' part of a query.
*
- * @param string $fieldname usually name of the table column
- * @param string $param usually bound query parameter (?, :named)
- * @param bool $casesensitive use case sensitive search
- * @param bool $accensensitive use accent sensitive search (not all databases support accent insensitive)
- * @param bool $notlike true means "NOT LIKE"
- * @param string $escapechar escape char for '%' and '_'
- * @return string SQL code fragment
+ * @param string $fieldname Usually the name of the table column.
+ * @param string $param Usually the bound query parameter (?, :named).
+ * @param bool $casesensitive Use case sensitive search when set to true (default).
+ * @param bool $accentsensitive Use accent sensitive search when set to true (default). (not all databases support accent insensitive)
+ * @param bool $notlike True means "NOT LIKE".
+ * @param string $escapechar The escape char for '%' and '_'.
+ * @return string The SQL code fragment.
*/
public function sql_like($fieldname, $param, $casesensitive = true, $accentsensitive = true, $notlike = false, $escapechar = '\\') {
if (strpos($param, '%') !== false) {
}
/**
- * Escape sql LIKE special characters.
- * @param string $text
- * @param string $escapechar
- * @return string
+ * Escape sql LIKE special characters like '_' or '%'.
+ * @param string $text The string containing characters needing escaping.
+ * @param string $escapechar The desired escape character, defaults to '\\'.
+ * @return string The escaped sql LIKE string.
*/
public function sql_like_escape($text, $escapechar = '\\') {
$text = str_replace('_', $escapechar.'_', $text);
* the case insensitive search using regexp_like() or NLS_COMP=LINGUISTIC :-(
* See http://docs.moodle.org/en/XMLDB_Problems#Case-insensitive_searches
*
- * @deprecated
- * @return string
+ * @deprecated since Moodle 2.0 MDL-23925 - please do not use this function any more.
+ * @todo MDL-31280 to remove deprecated functions prior to 2.3 release.
+ * @return string Do not use this function!
+ * @see sql_like()
*/
public function sql_ilike() {
debugging('sql_ilike() is deprecated, please use sql_like() instead');
}
/**
- * Returns the proper SQL to do CONCAT between the elements passed
- * Can take many parameters
+ * Returns the proper SQL to do CONCAT between the elements(fieldnames) passed.
*
* This function accepts variable number of string parameters.
+ * All strings/fieldnames will used in the SQL concatenate statement generated.
*
- * @return string
+ * @return string The SQL to concatenate strings passed in.
+ * @uses func_get_args() and thus parameters are unlimited OPTIONAL number of additional field names.
*/
public abstract function sql_concat();
* Returns the proper SQL to do CONCAT between the elements passed
* with a given separator
*
- * @param string $separator
- * @param array $elements
- * @return string
+ * @param string $separator The separator desired for the SQL concatenating $elements.
+ * @param array $elements The array of strings to be concatenated.
+ * @return string The SQL to concatenate the strings.
*/
public abstract function sql_concat_join($separator="' '", $elements=array());
/**
* Returns the proper SQL (for the dbms in use) to concatenate $firstname and $lastname
- * TODO: Does this really need to be here? Eloy 20070727.
- * TODO: we definitely do not! (skodak)
*
- * @param string $first User's first name
- * @param string $last User's last name
- * @return string
+ * @todo MDL-31233 This may not be needed here.
+ *
+ * @param string $first User's first name (default:'firstname').
+ * @param string $last User's last name (default:'lastname').
+ * @return string The SQL to concatenate strings.
*/
function sql_fullname($first='firstname', $last='lastname') {
return $this->sql_concat($first, "' '", $last);
* Note that the use or queries being ordered by TEXT columns must be minimised,
* because it's really slooooooow.
*
- * @param string $fieldname the name of the TEXT field we need to order by
- * @param string $numchars of chars to use for the ordering (defaults to 32)
- * @return string the piece of SQL code to be used in your statement.
+ * @param string $fieldname The name of the TEXT field we need to order by.
+ * @param string $numchars The number of chars to use for the ordering (defaults to 32).
+ * @return string The piece of SQL code to be used in your statement.
*/
public function sql_order_by_text($fieldname, $numchars=32) {
return $fieldname;
/**
* Returns the SQL text to be used to calculate the length in characters of one expression.
- * @param string $fieldname or expression to calculate its length in characters.
+ * @param string $fieldname The fieldname/expression to calculate its length in characters.
* @return string the piece of SQL code to be used in the statement.
*/
public function sql_length($fieldname) {
* Returns the proper substr() SQL text used to extract substrings from DB
* NOTE: this was originally returning only function name
*
- * @param string $expr some string field, no aggregates
- * @param mixed $start integer or expression evaluating to int (1 based value; first char has index 1)
- * @param mixed $length optional integer or expression evaluating to int
- * @return string sql fragment
+ * @param string $expr Some string field, no aggregates.
+ * @param mixed $start Integer or expression evaluating to integer (1 based value; first char has index 1)
+ * @param mixed $length Optional integer or expression evaluating to integer.
+ * @return string The sql substring extraction fragment.
*/
public function sql_substr($expr, $start, $length=false) {
if (count(func_get_args()) < 2) {
/**
* Returns the SQL for returning searching one string for the location of another.
+ *
* Note, there is no guarantee which order $needle, $haystack will be in
- * the resulting SQL, so when using this method, and both arguments contain
+ * the resulting SQL so when using this method, and both arguments contain
* placeholders, you should use named placeholders.
+ *
* @param string $needle the SQL expression that will be searched for.
* @param string $haystack the SQL expression that will be searched in.
- * @return string the required SQL
+ * @return string The required searching SQL part.
*/
public function sql_position($needle, $haystack) {
// Implementation using standard SQL.
* Returns the empty string char used by every supported DB. To be used when
* we are searching for that values in our queries. Only Oracle uses this
* for now (will be out, once we migrate to proper NULLs if that days arrives)
- * @return string
+ * @return string An empty string.
*/
function sql_empty() {
return '';
*
* (see parameters description below)
*
- * @param string $tablename name of the table (without prefix). Not used for now but can be
+ * @param string $tablename Name of the table (without prefix). Not used for now but can be
* necessary in the future if we want to use some introspection using
* meta information against the DB. /// TODO ///
- * @param string $fieldname name of the field we are going to check
- * @param boolean $nullablefield to specify if the field us nullable (true) or no (false) in the DB
- * @param boolean $textfield to specify if it is a text (also called clob) field (true) or a varchar one (false)
+ * @param string $fieldname Name of the field we are going to check
+ * @param bool $nullablefield For specifying if the field is nullable (true) or no (false) in the DB.
+ * @param bool $textfield For specifying if it is a text (also called clob) field (true) or a varchar one (false)
* @return string the sql code to be added to check for empty values
*/
public function sql_isempty($tablename, $fieldname, $nullablefield, $textfield) {
*
* (see parameters description below)
*
- * @param string $tablename name of the table (without prefix). Not used for now but can be
+ * @param string $tablename Name of the table (without prefix). This is not used for now but can be
* necessary in the future if we want to use some introspection using
- * meta information against the DB. /// TODO ///
- * @param string $fieldname name of the field we are going to check
- * @param boolean $nullablefield to specify if the field us nullable (true) or no (false) in the DB
- * @param boolean $textfield to specify if it is a text (also called clob) field (true) or a varchar one (false)
- * @return string the sql code to be added to check for non empty values
+ * meta information against the DB.
+ * @param string $fieldname The name of the field we are going to check.
+ * @param bool $nullablefield Specifies if the field is nullable (true) or not (false) in the DB.
+ * @param bool $textfield Specifies if it is a text (also called clob) field (true) or a varchar one (false).
+ * @return string The sql code to be added to check for non empty values.
*/
public function sql_isnotempty($tablename, $fieldname, $nullablefield, $textfield) {
return ' ( NOT ' . $this->sql_isempty($tablename, $fieldname, $nullablefield, $textfield) . ') ';
}
/**
- * Does this driver suppoer regex syntax when searching
- * @return bool
+ * Returns true if this database driver supports regex syntax when searching.
+ * @return bool True if supported.
*/
public function sql_regex_supported() {
return false;
}
/**
- * Return regex positive or negative match sql
+ * Returns the driver specific syntax (SQL part) for matching regex positively or negatively (inverted matching).
+ * Eg: 'REGEXP':'NOT REGEXP' or '~*' : '!~*'
* @param bool $positivematch
* @return string or empty if not supported
*/
/// transactions
/**
- * Are transactions supported?
+ * Checks and returns true if transactions are supported.
+ *
* It is not responsible to run productions servers
* on databases without transaction support ;-)
*
}
/**
- * Returns true if transaction in progress
+ * Returns true if a transaction is in progress.
* @return bool
*/
public function is_transaction_started() {
}
/**
- * Throws exception if transaction in progress.
+ * This is a test that throws an exception if transaction in progress.
* This test does not force rollback of active transactions.
* @return void
*/
* The real database transaction is committed only if
* all delegated transactions committed.
* @return void
+ * @throws dml_transaction_exception Creates and throws transaction related exceptions.
*/
public function commit_delegated_transaction(moodle_transaction $transaction) {
if ($transaction->is_disposed()) {
* because all open delegated transactions are rolled back
* automatically if exceptions not caught.
*
- * @param moodle_transaction $transaction
- * @param Exception $e exception that caused the problem
- * @return void - does not return, exception is rethrown
+ * @param moodle_transaction $transaction An instance of a moodle_transaction.
+ * @param Exception $e The related exception to this transaction rollback.
+ * @return void This does not return, instead the exception passed in will be rethrown.
*/
public function rollback_delegated_transaction(moodle_transaction $transaction, Exception $e) {
if ($transaction->is_disposed()) {
/**
* Force rollback of all delegated transaction.
- * Does not trow any exceptions and does not log anything.
+ * Does not throw any exceptions and does not log anything.
*
* This method should be used only from default exception handlers and other
* core code.
}
/**
- * Obtain session lock
- * @param int $rowid id of the row with session record
- * @param int $timeout max allowed time to wait for the lock in seconds
- * @return bool success
+ * Obtains the session lock.
+ * @param int $rowid The id of the row with session record.
+ * @param int $timeout The maximum allowed time to wait for the lock in seconds.
+ * @return void
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_session_lock($rowid, $timeout) {
$this->used_for_db_sessions = true;
}
/**
- * Release session lock
- * @param int $rowid id of the row with session record
- * @return bool success
+ * Releases the session lock.
+ * @param int $rowid The id of the row with session record.
+ * @return void
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function release_session_lock($rowid) {
}
/// performance and logging
/**
- * Returns number of reads done by this database
- * @return int
+ * Returns the number of reads done by this database.
+ * @return int Number of reads.
*/
public function perf_get_reads() {
return $this->reads;
}
/**
- * Returns number of writes done by this database
- * @return int
+ * Returns the number of writes done by this database.
+ * @return int Number of writes.
*/
public function perf_get_writes() {
return $this->writes;
}
/**
- * Returns number of queries done by this database
- * @return int
+ * Returns the number of queries done by this database.
+ * @return int Number of queries.
*/
public function perf_get_queries() {
return $this->writes + $this->reads;
* Abstract recordset.
*
* @package core
+ * @category dml
* @subpackage dml
* @copyright 2008 Petr Skoda (http://skodak.org)
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
* databases like postgres need this, because they don't lack any temp functionality.
*
* @package core
+ * @category dml
* @subpackage dml
* @copyright 2009 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
class moodle_temptables {
- protected $mdb; // circular reference, to be able to use DB facilities here if needed
- protected $prefix; // prefix to be used for all the DB objects
- protected $temptables; // simple array of moodle, not prefixed 'tablename' => DB, final (prefixed) 'tablename'
+ /** @var circular reference, to be able to use DB facilities here if needed */
+ protected $mdb;
+ /** @var prefix to be used for all the DB objects */
+ protected $prefix;
+ /** @var simple array of moodle, not prefixed 'tablename' => DB, final (prefixed) 'tablename' */
+ protected $temptables;
/**
* Creates new moodle_temptables instance
- * @param object moodle_database instance
+ * @param moodle_database $mdb An instance of moodle_database.
*/
public function __construct($mdb) {
$this->mdb = $mdb;
* Delegated database transaction support.
*
* @package core
+ * @category dml
* @subpackage dml
* @copyright 2009 Petr Skoda (http://skodak.org)
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
/**
* Delegated transaction class.
+ *
+ * @package core
+ * @category dml
+ * @subpackage dml
+ * @copyright 2009 Petr Skoda (http://skodak.org)
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class moodle_transaction {
+ /** @var array The debug_backtrace() returned array.*/
private $start_backtrace;
+ /**@var moodle_database The moodle_database instance.*/
private $database = null;
/**
* Mark transaction as disposed, no more
* commits and rollbacks allowed.
* To be used only from moodle_database class
- * @return unknown_type
+ * @return null
*/
public function dispose() {
return $this->database = null;
* Native mssql class representing moodle database interface.
*
* @package core
- * @subpackage dml
+ * @subpackage dml_driver
* @copyright 2009 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
/**
* Native mssql class representing moodle database interface.
+ *
+ * @package core
+ * @subpackage dml_driver
+ * @copyright 2009 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class mssql_native_moodle_database extends moodle_database {
/**
* Connect to db
* Must be called before other methods.
- * @param string $dbhost
- * @param string $dbuser
- * @param string $dbpass
- * @param string $dbname
+ * @param string $dbhost The database host.
+ * @param string $dbuser The database username.
+ * @param string $dbpass The database username's password.
+ * @param string $dbname The name of the database being connected to.
* @param mixed $prefix string means moodle db prefix, false used for external databases where prefix not used
* @param array $dboptions driver specific options
* @return bool true
/**
* Returns database server info array
- * @return array
+ * @return array Array containing 'description' and 'version' info
*/
public function get_server_info() {
static $info;
/**
* Returns supported query parameter types
- * @return int bitmask
+ * @return int bitmask of accepted SQL_PARAMS_*
*/
protected function allowed_param_types() {
return SQL_PARAMS_QM; // Not really, but emulated, see emulate_bound_params()
/**
* Return tables in database WITHOUT current prefix
+ * @param bool $usecache if true, returns list of cached tables.
* @return array of table names in lowercase and without prefix
*/
public function get_tables($usecache=true) {
}
/**
- * Return table indexes - everything lowercased
- * @return array of arrays
+ * Return table indexes - everything lowercased.
+ * @param string $table The table we want to get indexes from.
+ * @return array An associative array of indexes containing 'unique' flag and 'columns' being indexed
*/
public function get_indexes($table) {
$indexes = array();
}
/**
- * Normalise values based in RDBMS dependencies (booleans, LOBs...)
+ * Normalise values based on varying RDBMS's dependencies (booleans, LOBs...)
*
* @param database_column_info $column column metadata corresponding with the value we are going to normalise
* @param mixed $value value we are going to normalise
* Do NOT use in code, to be used by database_manager only!
* @param string $sql query
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function change_database_structure($sql) {
$this->reset_caches();
* @param string $sql query
* @param array $params query parameters
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function execute($sql, array $params=null) {
* code where it's possible there might be large datasets being returned. For known
* small datasets use get_records_sql - it leads to simpler code.
*
- * The return type is as for @see function get_recordset.
+ * The return type is like:
+ * @see function get_recordset.
*
* @param string $sql the SQL select query to execute.
* @param array $params array of sql parameters
* @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
* @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
* @return moodle_recordset instance
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_recordset_sql($sql, array $params=null, $limitfrom=0, $limitnum=0) {
$limitfrom = (int)$limitfrom;
/**
* Get a number of records as an array of objects using a SQL statement.
*
- * Return value as for @see function get_records.
+ * Return value is like:
+ * @see function get_records.
*
* @param string $sql the SQL select query to execute. The first column of this SELECT statement
* must be a unique value (usually the 'id' field), as it will be used as the key of the
* @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
* @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
* @return array of objects, or empty array if no records were found
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_records_sql($sql, array $params=null, $limitfrom=0, $limitnum=0) {
* @param string $sql The SQL query
* @param array $params array of sql parameters
* @return array of values
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_fieldset_sql($sql, array $params=null) {
* @param bool $bulk true means repeated inserts expected
* @param bool $customsequence true if 'id' included in $params, disables $returnid
* @return bool|int true or new id
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function insert_record_raw($table, $params, $returnid=true, $bulk=false, $customsequence=false) {
if (!is_array($params)) {
* @param object $data A data object with values for one or more fields in the record
* @param bool $returnid Should the id of the newly created record entry be returned? If this option is not requested then true/false is returned.
* @return bool|int true or new id
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function insert_record($table, $dataobject, $returnid=true, $bulk=false) {
$dataobject = (array)$dataobject;
* @param string $table name of database table to be inserted into
* @param object $dataobject A data object with values for one or more fields in the record
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function import_record($table, $dataobject) {
$dataobject = (array)$dataobject;
* @param mixed $params data record as object or array
* @param bool true means repeated updates expected
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function update_record_raw($table, $params, $bulk=false) {
$params = (array)$params;
* @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 true means repeated updates expected
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function update_record($table, $dataobject, $bulk=false) {
$dataobject = (array)$dataobject;
* @param string $select A fragment of SQL to be used in a where clause in the SQL call.
* @param array $params array of sql parameters
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function set_field_select($table, $newfield, $newvalue, $select, array $params=null) {
* @param string $select A fragment of SQL to be used in a where clause in the SQL call (used to define the selection criteria).
* @param array $params array of sql parameters
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function delete_records_select($table, $select, array $params=null) {
* MSSQL specific recordset.
*
* @package core
- * @subpackage dml
+ * @subpackage dml_driver
* @copyright 2009 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
* temp table names included in the get_tables() method of the DB.
*
* @package core
- * @subpackage dml
+ * @subpackage dml_driver
* @copyright 2009 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
* Native mysqli class representing moodle database interface.
*
* @package core
- * @subpackage dml
+ * @subpackage dml_driver
* @copyright 2008 Petr Skoda (http://skodak.org)
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
/**
* Native mysqli class representing moodle database interface.
+ *
+ * @package core
+ * @subpackage dml_driver
+ * @copyright 2008 Petr Skoda (http://skodak.org)
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class mysqli_native_moodle_database extends moodle_database {
* @param string $dbpass
* @param string $dbname
* @return bool success
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function create_database($dbhost, $dbuser, $dbpass, $dbname, array $dboptions=null) {
$driverstatus = $this->driver_installed();
/**
* Connect to db
* Must be called before other methods.
- * @param string $dbhost
- * @param string $dbuser
- * @param string $dbpass
- * @param string $dbname
+ * @param string $dbhost The database host.
+ * @param string $dbuser The database username.
+ * @param string $dbpass The database username's password.
+ * @param string $dbname The name of the database being connected to.e
* @param mixed $prefix string means moodle db prefix, false used for external databases where prefix not used
* @param array $dboptions driver specific options
* @return bool success
/**
* Returns database server info array
- * @return array
+ * @return array Array containing 'description' and 'version' info
*/
public function get_server_info() {
return array('description'=>$this->mysqli->server_info, 'version'=>$this->mysqli->server_info);
/**
* Returns supported query parameter types
- * @return int bitmask
+ * @return int bitmask of accepted SQL_PARAMS_*
*/
protected function allowed_param_types() {
return SQL_PARAMS_QM;
/**
* Return tables in database WITHOUT current prefix
+ * @param bool $usecache if true, returns list of cached tables.
* @return array of table names in lowercase and without prefix
*/
public function get_tables($usecache=true) {
}
/**
- * Return table indexes - everything lowercased
- * @return array of arrays
+ * Return table indexes - everything lowercased.
+ * @param string $table The table we want to get indexes from.
+ * @return array An associative array of indexes containing 'unique' flag and 'columns' being indexed
*/
public function get_indexes($table) {
$indexes = array();
* Do NOT use in code, to be used by database_manager only!
* @param string $sql query
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function change_database_structure($sql) {
$this->reset_caches();
* @param string $sql query
* @param array $params query parameters
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function execute($sql, array $params=null) {
list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
* code where it's possible there might be large datasets being returned. For known
* small datasets use get_records_sql - it leads to simpler code.
*
- * The return type is as for @see function get_recordset.
+ * The return type is like:
+ * @see function get_recordset.
*
* @param string $sql the SQL select query to execute.
* @param array $params array of sql parameters
* @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
* @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
* @return moodle_recordset instance
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_recordset_sql($sql, array $params=null, $limitfrom=0, $limitnum=0) {
$limitfrom = (int)$limitfrom;
/**
* Get a number of records as an array of objects using a SQL statement.
*
- * Return value as for @see function get_records.
+ * Return value is like:
+ * @see function get_records.
*
* @param string $sql the SQL select query to execute. The first column of this SELECT statement
* must be a unique value (usually the 'id' field), as it will be used as the key of the
* @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
* @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
* @return array of objects, or empty array if no records were found
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_records_sql($sql, array $params=null, $limitfrom=0, $limitnum=0) {
$limitfrom = (int)$limitfrom;
* @param string $sql The SQL query
* @param array $params array of sql parameters
* @return array of values
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_fieldset_sql($sql, array $params=null) {
list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
* @param bool $bulk true means repeated inserts expected
* @param bool $customsequence true if 'id' included in $params, disables $returnid
* @return bool|int true or new id
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function insert_record_raw($table, $params, $returnid=true, $bulk=false, $customsequence=false) {
if (!is_array($params)) {
* @param object $data A data object with values for one or more fields in the record
* @param bool $returnid Should the id of the newly created record entry be returned? If this option is not requested then true/false is returned.
* @return bool|int true or new id
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function insert_record($table, $dataobject, $returnid=true, $bulk=false) {
$dataobject = (array)$dataobject;
* @param string $table name of database table to be inserted into
* @param object $dataobject A data object with values for one or more fields in the record
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function import_record($table, $dataobject) {
$dataobject = (array)$dataobject;
* @param mixed $params data record as object or array
* @param bool true means repeated updates expected
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function update_record_raw($table, $params, $bulk=false) {
$params = (array)$params;
* @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 true means repeated updates expected
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function update_record($table, $dataobject, $bulk=false) {
$dataobject = (array)$dataobject;
* @param string $select A fragment of SQL to be used in a where clause in the SQL call.
* @param array $params array of sql parameters
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function set_field_select($table, $newfield, $newvalue, $select, array $params=null) {
if ($select) {
* @param string $select A fragment of SQL to be used in a where clause in the SQL call (used to define the selection criteria).
* @param array $params array of sql parameters
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function delete_records_select($table, $select, array $params=null) {
if ($select) {
* Mysqli specific recordset.
*
* @package core
- * @subpackage dml
+ * @subpackage dml_driver
* @copyright 2008 Petr Skoda (http://skodak.org)
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
/**
* Mysqli specific moodle recordset class
+ *
+ * @package core
+ * @subpackage dml_driver
+ * @copyright 2008 Petr Skoda (http://skodak.org)
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class mysqli_native_moodle_recordset extends moodle_recordset {
* temp table names included in the get_tables() method of the DB.
*
* @package core
- * @subpackage dml
+ * @subpackage dml_driver
* @copyright 2009 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
* Native oci class representing moodle database interface.
*
* @package core
- * @subpackage dml
+ * @subpackage dml_driver
* @copyright 2008 Petr Skoda (http://skodak.org)
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
*
* One complete reference for PHP + OCI:
* http://www.oracle.com/technology/tech/php/underground-php-oracle-manual.html
+ *
+ * @package core
+ * @subpackage dml_driver
+ * @copyright 2008 Petr Skoda (http://skodak.org)
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class oci_native_moodle_database extends moodle_database {
protected $oci = null;
- private $last_stmt_error = null; // To store stmt errors and enable get_last_error() to detect them
- private $commit_status = null; // default value initialised in connect method, we need the driver to be present
+ /** @var To store stmt errors and enable get_last_error() to detect them.*/
+ private $last_stmt_error = null;
+ /** @var Default value initialised in connect method, we need the driver to be present.*/
+ private $commit_status = null;
- private $last_error_reporting; // To handle oci driver default verbosity
- private $unique_session_id; // To store unique_session_id. Needed for temp tables unique naming
-
- private $dblocks_supported = null; // To cache locks support along the connection life
- private $bitwise_supported = null; // To cache bitwise operations support along the connection life
+ /** @var To handle oci driver default verbosity.*/
+ private $last_error_reporting;
+ /** @var To store unique_session_id. Needed for temp tables unique naming.*/
+ private $unique_session_id;
+ /** @var To cache locks support along the connection life.*/
+ private $dblocks_supported = null;
+ /** @var To cache bitwise operations support along the connection life.*/
+ private $bitwise_supported = null;
/**
* Detects if all needed PHP stuff installed.
/**
* Connect to db
* Must be called before other methods.
- * @param string $dbhost
- * @param string $dbuser
- * @param string $dbpass
- * @param string $dbname
+ * @param string $dbhost The database host.
+ * @param string $dbuser The database username.
+ * @param string $dbpass The database username's password.
+ * @param string $dbname The name of the database being connected to.
* @param mixed $prefix string means moodle db prefix, false used for external databases where prefix not used
* @param array $dboptions driver specific options
* @return bool true
/**
* Returns database server info array
- * @return array
+ * @return array Array containing 'description' and 'version' info
*/
public function get_server_info() {
static $info = null; // TODO: move to real object property
/**
* Returns supported query parameter types
- * @return int bitmask
+ * @return int bitmask of accepted SQL_PARAMS_*
*/
protected function allowed_param_types() {
return SQL_PARAMS_NAMED;
/**
* Return tables in database WITHOUT current prefix
+ * @param bool $usecache if true, returns list of cached tables.
* @return array of table names in lowercase and without prefix
*/
public function get_tables($usecache=true) {
}
/**
- * Return table indexes - everything lowercased
- * @return array of arrays
+ * Return table indexes - everything lowercased.
+ * @param string $table The table we want to get indexes from.
+ * @return array An associative array of indexes containing 'unique' flag and 'columns' being indexed
*/
public function get_indexes($table) {
$indexes = array();
* Do NOT use in code, to be used by database_manager only!
* @param string $sql query
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function change_database_structure($sql) {
$this->reset_caches();
* @param string $sql query
* @param array $params query parameters
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function execute($sql, array $params=null) {
list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
* IGNORE_MULTIPLE means return first, ignore multiple records found(not recommended);
* MUST_EXIST means throw exception if no record or multiple records found
* @return mixed a fieldset object containing the first matching record, false or exception if error not found depending on mode
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_record_sql($sql, array $params=null, $strictness=IGNORE_MISSING) {
$strictness = (int)$strictness;
* code where it's possible there might be large datasets being returned. For known
* small datasets use get_records_sql - it leads to simpler code.
*
- * The return type is as for @see function get_recordset.
+ * The return type is like:
+ * @see function get_recordset.
*
* @param string $sql the SQL select query to execute.
* @param array $params array of sql parameters
* @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
* @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
* @return moodle_recordset instance
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_recordset_sql($sql, array $params=null, $limitfrom=0, $limitnum=0) {
/**
* Get a number of records as an array of objects using a SQL statement.
*
- * Return value as for @see function get_records.
+ * Return value is like:
+ * @see function get_records.
*
* @param string $sql the SQL select query to execute. The first column of this SELECT statement
* must be a unique value (usually the 'id' field), as it will be used as the key of the
* @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
* @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
* @return array of objects, or empty array if no records were found
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_records_sql($sql, array $params=null, $limitfrom=0, $limitnum=0) {
* @param string $sql The SQL query
* @param array $params array of sql parameters
* @return array of values
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_fieldset_sql($sql, array $params=null) {
list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
* @param bool $bulk true means repeated inserts expected
* @param bool $customsequence true if 'id' included in $params, disables $returnid
* @return bool|int true or new id
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function insert_record_raw($table, $params, $returnid=true, $bulk=false, $customsequence=false) {
if (!is_array($params)) {
* @param object $data A data object with values for one or more fields in the record
* @param bool $returnid Should the id of the newly created record entry be returned? If this option is not requested then true/false is returned.
* @return bool|int true or new id
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function insert_record($table, $dataobject, $returnid=true, $bulk=false) {
$dataobject = (array)$dataobject;
* @param string $table name of database table to be inserted into
* @param object $dataobject A data object with values for one or more fields in the record
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function import_record($table, $dataobject) {
$dataobject = (array)$dataobject;
* @param mixed $params data record as object or array
* @param bool true means repeated updates expected
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function update_record_raw($table, $params, $bulk=false) {
$params = (array)$params;
* @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 true means repeated updates expected
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function update_record($table, $dataobject, $bulk=false) {
$dataobject = (array)$dataobject;
* @param string $select A fragment of SQL to be used in a where clause in the SQL call.
* @param array $params array of sql parameters
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function set_field_select($table, $newfield, $newvalue, $select, array $params=null) {
* @param string $select A fragment of SQL to be used in a where clause in the SQL call (used to define the selection criteria).
* @param array $params array of sql parameters
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function delete_records_select($table, $select, array $params=null) {
}
}
+ /**
+ * Returns the empty string char used by every supported DB. To be used when
+ * we are searching for that values in our queries. Only Oracle uses this
+ * for now (will be out, once we migrate to proper NULLs if that days arrives)
+ * @return string A string with single whitespace.
+ */
public function sql_empty() {
return ' ';
}
/**
* @package core
- * @subpackage dml
+ * @subpackage dml_driver
* @copyright 2009 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
* @version 20091010 (plz, keep this updated for easier reference)
* Oracle specific recordset.
*
* @package core
- * @subpackage dml
+ * @subpackage dml_driver
* @copyright 2008 Petr Skoda (http://skodak.org)
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
* method of the DB.
*
* @package core
- * @subpackage dml
+ * @subpackage dml_driver
* @copyright 2009 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
* Experimental pdo database class
*
* @package core
- * @subpackage dml
+ * @subpackage dml_driver
* @copyright 2008 Andrei Bautu
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
/**
* Experimental pdo database class
+ *
+ * @package core
+ * @subpackage dml_driver
+ * @copyright 2008 Andrei Bautu
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
abstract class pdo_moodle_database extends moodle_database {
/**
* Connect to db
* Must be called before other methods.
- * @param string $dbhost
- * @param string $dbuser
- * @param string $dbpass
- * @param string $dbname
+ * @param string $dbhost The database host.
+ * @param string $dbuser The database username.
+ * @param string $dbpass The database username's password.
+ * @param string $dbname The name of the database being connected to.
* @param mixed $prefix string means moodle db prefix, false used for external databases where prefix not used
* @param array $dboptions driver specific options
* @return bool success
/**
* Returns database server info array
- * @return array
+ * @return array Array containing 'description' and 'version' info
*/
public function get_server_info() {
$result = array();
/**
* Returns supported query parameter types
- * @return int bitmask
+ * @return int bitmask of accepted SQL_PARAMS_*
*/
protected function allowed_param_types() {
return SQL_PARAMS_QM | SQL_PARAMS_NAMED;
* code where it's possible there might be large datasets being returned. For known
* small datasets use get_records_sql - it leads to simpler code.
*
- * The return type is as for @see function get_recordset.
+ * The return type is like:
+ * @see function get_recordset.
*
* @param string $sql the SQL select query to execute.
* @param array $params array of sql parameters
/**
* Get a number of records as an array of objects.
*
- * Return value as for @see function get_records.
+ * Return value is like:
+ * @see function get_records.
*
* @param string $sql the SQL select query to execute. The first column of this SELECT statement
* must be a unique value (usually the 'id' field), as it will be used as the key of the
* Experimental pdo recordset
*
* @package core
- * @subpackage dml
+ * @subpackage dml_driver
* @copyright 2008 Andrei Bautu
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
/**
* Experimental pdo recordset
+ *
+ * @package core
+ * @subpackage dml_driver
+ * @copyright 2008 Andrei Bautu
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class pdo_moodle_recordset extends moodle_recordset {
* Native pgsql class representing moodle database interface.
*
* @package core
- * @subpackage dml
+ * @subpackage dml_driver
* @copyright 2008 Petr Skoda (http://skodak.org)
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
/**
* Native pgsql class representing moodle database interface.
+ *
+ * @package core
+ * @subpackage dml_driver
+ * @copyright 2008 Petr Skoda (http://skodak.org)
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class pgsql_native_moodle_database extends moodle_database {
/**
* Connect to db
* Must be called before other methods.
- * @param string $dbhost
- * @param string $dbuser
- * @param string $dbpass
- * @param string $dbname
+ * @param string $dbhost The database host.
+ * @param string $dbuser The database username.
+ * @param string $dbpass The database username's password.
+ * @param string $dbname The name of the database being connected to.
* @param mixed $prefix string means moodle db prefix, false used for external databases where prefix not used
* @param array $dboptions driver specific options
* @return bool true
/**
* Returns database server info array
- * @return array
+ * @return array Array containing 'description' and 'version' info
*/
public function get_server_info() {
static $info;
/**
* Returns supported query parameter types
- * @return int bitmask
+ * @return int bitmask of accepted SQL_PARAMS_*
*/
protected function allowed_param_types() {
return SQL_PARAMS_DOLLAR;
}
/**
- * Return tables in database WITHOUT current prefix
+ * Return tables in database WITHOUT current prefix.
+ * @param bool $usecache if true, returns list of cached tables.
* @return array of table names in lowercase and without prefix
*/
public function get_tables($usecache=true) {
}
/**
- * Return table indexes - everything lowercased
+ * Return table indexes - everything lowercased.
+ * @param string $table The table we want to get indexes from.
* @return array of arrays
*/
public function get_indexes($table) {
* Do NOT use in code, to be used by database_manager only!
* @param string $sql query
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function change_database_structure($sql) {
$this->reset_caches();
* @param string $sql query
* @param array $params query parameters
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function execute($sql, array $params=null) {
list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
* code where it's possible there might be large datasets being returned. For known
* small datasets use get_records_sql - it leads to simpler code.
*
- * The return type is as for @see function get_recordset.
+ * The return type is like:
+ * @see function get_recordset.
*
* @param string $sql the SQL select query to execute.
* @param array $params array of sql parameters
* @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
* @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
* @return moodle_recordset instance
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_recordset_sql($sql, array $params=null, $limitfrom=0, $limitnum=0) {
$limitfrom = (int)$limitfrom;
/**
* Get a number of records as an array of objects using a SQL statement.
*
- * Return value as for @see function get_records.
+ * Return value is like:
+ * @see function get_records.
*
* @param string $sql the SQL select query to execute. The first column of this SELECT statement
* must be a unique value (usually the 'id' field), as it will be used as the key of the
* @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
* @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
* @return array of objects, or empty array if no records were found
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_records_sql($sql, array $params=null, $limitfrom=0, $limitnum=0) {
$limitfrom = (int)$limitfrom;
* @param string $sql The SQL query
* @param array $params array of sql parameters
* @return array of values
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_fieldset_sql($sql, array $params=null) {
list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
* @param bool $bulk true means repeated inserts expected
* @param bool $customsequence true if 'id' included in $params, disables $returnid
* @return bool|int true or new id
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function insert_record_raw($table, $params, $returnid=true, $bulk=false, $customsequence=false) {
if (!is_array($params)) {
* @param object $data A data object with values for one or more fields in the record
* @param bool $returnid Should the id of the newly created record entry be returned? If this option is not requested then true/false is returned.
* @return bool|int true or new id
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function insert_record($table, $dataobject, $returnid=true, $bulk=false) {
$dataobject = (array)$dataobject;
* @param string $table name of database table to be inserted into
* @param object $dataobject A data object with values for one or more fields in the record
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function import_record($table, $dataobject) {
$dataobject = (array)$dataobject;
* @param mixed $params data record as object or array
* @param bool true means repeated updates expected
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function update_record_raw($table, $params, $bulk=false) {
$params = (array)$params;
* @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 true means repeated updates expected
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function update_record($table, $dataobject, $bulk=false) {
$dataobject = (array)$dataobject;
* @param string $select A fragment of SQL to be used in a where clause in the SQL call.
* @param array $params array of sql parameters
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function set_field_select($table, $newfield, $newvalue, $select, array $params=null) {
* @param string $select A fragment of SQL to be used in a where clause in the SQL call (used to define the selection criteria).
* @param array $params array of sql parameters
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function delete_records_select($table, $select, array $params=null) {
if ($select) {
* Native postgresql recordset.
*
* @package core
- * @subpackage dml
+ * @subpackage dml_driver
* @copyright 2008 Petr Skoda (http://skodak.org)
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
/**
* pgsql specific moodle recordset class
+ *
+ * @package core
+ * @subpackage dml_driver
+ * @copyright 2008 Petr Skoda (http://skodak.org)
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class pgsql_native_moodle_recordset extends moodle_recordset {
protected $result;
- protected $current; // current row as array
+ /** @var current row as array.*/
+ protected $current;
protected $bytea_oid;
protected $blobs = array();
* temp table names included in the get_tables() method of the DB.
*
* @package core
- * @subpackage dml
+ * @subpackage dml_driver
* @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
* Experimental pdo database class.
*
* @package core
- * @subpackage dml
+ * @subpackage dml_driver
* @copyright 2008 Andrei Bautu
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
/**
* Experimental pdo database class
+ *
+ * @package core
+ * @subpackage dml_driver
+ * @copyright 2008 Andrei Bautu
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class sqlite3_pdo_moodle_database extends pdo_moodle_database {
protected $database_file_extension = '.sq3.php';
}
/**
- * Return tables in database WITHOUT current prefix
+ * Return tables in database WITHOUT current prefix.
+ * @param bool $usecache if true, returns list of cached tables.
* @return array of table names in lowercase and without prefix
*/
public function get_tables($usecache=true) {
/**
* Return table indexes - everything lowercased
+ * @param string $table The table we want to get indexes from.
* @return array of arrays
*/
public function get_indexes($table) {
* Native sqlsrv class representing moodle database interface.
*
* @package core
- * @subpackage dml
+ * @subpackage dml_driver
* @copyright 2009 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v2 or later
*/
/**
* Native sqlsrv class representing moodle database interface.
+ *
+ * @package core
+ * @subpackage dml_driver
+ * @copyright 2009 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v2 or later
*/
class sqlsrv_native_moodle_database extends moodle_database {
/**
* Connect to db
- * Must be called before other methods.
- * @param string $dbhost
- * @param string $dbuser
- * @param string $dbpass
- * @param string $dbname
- * @param mixed $prefix string means moodle db prefix, false used for external databases where prefix not used
+ * Must be called before most other methods. (you can call methods that return connection configuration parameters)
+ * @param string $dbhost The database host.
+ * @param string $dbuser The database username.
+ * @param string $dbpass The database username's password.
+ * @param string $dbname The name of the database being connected to.
+ * @param mixed $prefix string|bool The moodle db table name's prefix. false is used for external databases where prefix not used
* @param array $dboptions driver specific options
* @return bool true
* @throws dml_connection_exception if error
/**
* Called before each db query.
* @param string $sql
- * @param array array of parameters
+ * @param array $params array of parameters
* @param int $type type of query
* @param mixed $extrainfo driver specific extra information
* @return void
/**
* Returns database server info array
- * @return array
+ * @return array Array containing 'description', 'version' and 'database' (current db) info
*/
public function get_server_info() {
static $info;
}
/**
- * Return tables in database WITHOUT current prefix
+ * Return tables in database WITHOUT current prefix.
+ * @param bool $usecache if true, returns list of cached tables.
* @return array of table names in lowercase and without prefix
*/
public function get_tables($usecache = true) {
}
/**
- * Return table indexes - everything lowercased
+ * Return table indexes - everything lowercased.
+ * @param string $table The table we want to get indexes from.
* @return array of arrays
*/
public function get_indexes($table) {
* Do NOT use in code, to be used by database_manager only!
* @param string $sql query
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function change_database_structure($sql) {
$this->reset_caches();
* @param string $sql query
* @param array $params query parameters
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function execute($sql, array $params = null) {
if (strpos($sql, ';') !== false) {
* code where it's possible there might be large datasets being returned. For known
* small datasets use get_records_sql - it leads to simpler code.
*
- * The return type is as for @see function get_recordset.
+ * The return type is like:
+ * @see function get_recordset.
*
* @param string $sql the SQL select query to execute.
* @param array $params array of sql parameters
* @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
* @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
* @return moodle_recordset instance
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_recordset_sql($sql, array $params = null, $limitfrom = 0, $limitnum = 0) {
$limitfrom = (int)$limitfrom;
/**
* Get a number of records as an array of objects using a SQL statement.
*
- * Return value as for @see function get_records.
+ * Return value is like:
+ * @see function get_records.
*
* @param string $sql the SQL select query to execute. The first column of this SELECT statement
* must be a unique value (usually the 'id' field), as it will be used as the key of the
* @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
* @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
* @return array of objects, or empty array if no records were found
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_records_sql($sql, array $params = null, $limitfrom = 0, $limitnum = 0) {
* @param string $sql The SQL query
* @param array $params array of sql parameters
* @return array of values
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function get_fieldset_sql($sql, array $params = null) {
* @param bool $bulk true means repeated inserts expected
* @param bool $customsequence true if 'id' included in $params, disables $returnid
* @return bool|int true or new id
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function insert_record_raw($table, $params, $returnid=true, $bulk=false, $customsequence=false) {
if (!is_array($params)) {
* @param object $data A data object with values for one or more fields in the record
* @param bool $returnid Should the id of the newly created record entry be returned? If this option is not requested then true/false is returned.
* @return bool|int true or new id
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function insert_record($table, $dataobject, $returnid = true, $bulk = false) {
$dataobject = (array)$dataobject;
* @param string $table name of database table to be inserted into
* @param object $dataobject A data object with values for one or more fields in the record
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function import_record($table, $dataobject) {
if (!is_object($dataobject)) {
* @param mixed $params data record as object or array
* @param bool true means repeated updates expected
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function update_record_raw($table, $params, $bulk = false) {
$params = (array)$params;
* @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 true means repeated updates expected
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function update_record($table, $dataobject, $bulk = false) {
$dataobject = (array)$dataobject;
* @param string $select A fragment of SQL to be used in a where clause in the SQL call.
* @param array $params array of sql parameters
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function set_field_select($table, $newfield, $newvalue, $select, array $params = null) {
if ($select) {
* @param string $select A fragment of SQL to be used in a where clause in the SQL call (used to define the selection criteria).
* @param array $params array of sql parameters
* @return bool true
- * @throws dml_exception if error
+ * @throws dml_exception A DML specific exception is thrown for any errors.
*/
public function delete_records_select($table, $select, array $params = null) {
if ($select) {
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
/**
- * sqlsrv specific recorset.
+ * sqlsrv specific recordset.
*
* @package core
- * @subpackage dml
+ * @subpackage dml_driver
* @copyright 2009 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v2 or later
*/
* temp table names included in the get_tables() method of the DB.
*
* @package core
- * @subpackage dml
+ * @subpackage dml_driver
* @copyright 2009 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v2 or later
*/
require_once($CFG->libdir.'/dml/mssql_native_moodle_temptables.php');
/***
-* This class is not specific to the SQL Server Native Driver but rather
-* to the family of Microsoft SQL Servers
-*/
+ * This class is not specific to the SQL Server Native Driver but rather
+ * to the family of Microsoft SQL Servers.
+ *
+ * @package core
+ * @subpackage dml_driver
+ * @copyright 2009 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v2 or later
+ */
class sqlsrv_native_moodle_temptables extends mssql_native_moodle_temptables {}
* (feel free to modify, improve and document such page, thanks!)
*
* @package core
+ * @category dml
* @subpackage dml
* @copyright 2008 Petr Skoda (http://skodak.org)
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
/**
* DML exception class, use instead of error() in dml code.
+ *
+ * @package core
+ * @category dml
+ * @subpackage dml
+ * @copyright 2008 Petr Skoda (http://skodak.org)
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class dml_exception extends moodle_exception {
/**
- * @param string $errorcode
- * @param string $a
- * @param string $debuginfo
+ * @param string $errorcode The name of the string from error.php to print.
+ * @param string $a Extra words and phrases that might be required in the error string.
+ * @param string $debuginfo Optional debugging information.
*/
function __construct($errorcode, $a=NULL, $debuginfo=null) {
parent::__construct($errorcode, '', '', $a, $debuginfo);
/**
* DML db connection exception - triggered if database not accessible.
+ *
+ * @package core
+ * @category dml
+ * @subpackage dml
+ * @copyright 2008 Petr Skoda (http://skodak.org)
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class dml_connection_exception extends dml_exception {
/**
* Constructor
- * @param string $error
+ * @param string $error Optional debugging information.
*/
function __construct($error) {
$errorinfo = $error;
/**
* DML db session wait exception - triggered when session lock request times out.
+ *
+ * @package core
+ * @category dml
+ * @subpackage dml
+ * @copyright 2008 Petr Skoda (http://skodak.org)
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class dml_sessionwait_exception extends dml_exception {
/**
/**
* DML read exception - triggered by some SQL syntax errors, etc.
+ *
+ * @package core
+ * @category dml
+ * @subpackage dml
+ * @copyright 2008 Petr Skoda (http://skodak.org)
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class dml_read_exception extends dml_exception {
- /** @var string */
+ /** @var string The name of the string from error.php to print.*/
public $error;
- /** @var string */
+ /** @var string The SQL that ran just before this read error.*/
public $sql;
- /** @var array */
+ /** @var array The SQL's related parameters.*/
public $params;
/**
* Constructor
- * @param string $error
- * @param string $sql
- * @param array $params
+ * @param string $error The name of the string from error.php to print.
+ * @param string $sql The SQL that ran just before this read error.
+ * @param array $params The SQL's related parameters.(optional)
*/
function __construct($error, $sql=null, array $params=null) {
$this->error = $error;
/**
* Caused by multiple records found in get_record() call.
+ *
+ * @package core
+ * @category dml
+ * @subpackage dml
+ * @copyright 2008 Petr Skoda (http://skodak.org)
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class dml_multiple_records_exception extends dml_exception {
- /** @var string */
+ /** @var string The SQL that ran just before this read error.*/
public $sql;
- /** @var array */
+ /** @var array The SQL's related parameters.*/
public $params;
/**
* Constructor
- * @param string $table table name if known, '' if unknown
- * @param string $sql
- * @param array $params
+ * @param string $sql The SQL that ran just before this read error.
+ * @param array $params The SQL's related parameters.(optional)
*/
function __construct($sql='', array $params=null) {
$errorinfo = $sql."\n[".var_export($params, true).']';
/**
* Caused by missing record that is required for normal operation.
+ *
+ * @package core
+ * @category dml
+ * @subpackage dml
+ * @copyright 2008 Petr Skoda (http://skodak.org)
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class dml_missing_record_exception extends dml_exception {
- /** @var string */
+ /** @var string A table's name.*/
public $table;
- /** @var string */
+ /** @var string An SQL query.*/
public $sql;
- /** @var array */
+ /** @var array The SQL's parameters.*/
public $params;
/**
* Constructor
- * @param string $table table name if known, '' if unknown
- * @param string $sql
- * @param array $params
+ * @param string $tablename The table name if known, '' if unknown.
+ * @param string $sql Optional SQL query.
+ * @param array $params Optional SQL query's parameters.
*/
function __construct($tablename, $sql='', array $params=null) {
if (empty($tablename)) {
/**
* DML write exception - triggered by some SQL syntax errors, etc.
+ *
+ * @package core
+ * @category dml
+ * @subpackage dml
+ * @copyright 2008 Petr Skoda (http://skodak.org)
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class dml_write_exception extends dml_exception {
- /** @var string */
+ /** @var string The name of the string from error.php to print.*/
public $error;
- /** @var string */
+ /** @var string The SQL that ran just before this write error.*/
public $sql;
- /** @var array */
+ /** @var array The SQL's related parameters.*/
public $params;
/**
* Constructor
- * @param string $error
- * @param string $sql
- * @param array $params
+ * @param string $error The name of the string from error.php to print.
+ * @param string $sql The SQL that ran just before this write error.
+ * @param array $params The SQL's related parameters.(optional)
*/
function __construct($error, $sql=null, array $params=null) {
$this->error = $error;
}
/**
- * DML transaction exception - triggered by problems related to DB transactions
+ * DML transaction exception - triggered by problems related to DB transactions.
+ *
+ * @todo MDL-20625 Use the info from $transaction for debugging purposes.
+ *
+ * @package core
+ * @category dml
+ * @subpackage dml
+ * @copyright 2008 Petr Skoda (http://skodak.org)
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class dml_transaction_exception extends dml_exception {
- /** @var moodle_transaction */
+ /** @var moodle_transaction An instance of a transaction.*/
public $transaction;
/**
* Constructor
- * @param array $start_backtrace
+ * @param array $debuginfo Optional debugging information.
+ * @param moodle_transaction $transaction The instance of the transaction.(Optional)
*/
function __construct($debuginfo=null, $transaction=null) {
$this->transaction = $transaction; // TODO: MDL-20625 use the info from $transaction for debugging purposes
/**
* Sets up global $DB moodle_database instance
*
- * @global object
- * @global object
- * @return void
+ * @global stdClass $CFG The global configuration instance.
+ * @see config.php
+ * @see config-dist.php
+ * @global stdClass $DB The global moodle_database instance.
+ * @return void|bool Returns true when finished setting up $DB. Returns void when $DB has already been set.
*/
function setup_DB() {
global $CFG, $DB;
* {@link http://docs.moodle.org/dev/Time_API#Timezone}
* @param bool $fixday If true (default) then the leading zero from %d is removed.
* If false then the leading zero is maintained.
+ * @param bool $fixhour If true (default) then the leading zero from %I is removed.
* @return string the formatted date/time.
*/
-function userdate($date, $format = '', $timezone = 99, $fixday = true) {
+function userdate($date, $format = '', $timezone = 99, $fixday = true, $fixhour = true) {
global $CFG;
} else if ($fixday) {
$formatnoday = str_replace('%d', 'DD', $format);
$fixday = ($formatnoday != $format);
+ $format = $formatnoday;
+ }
+
+ // Note: This logic about fixing 12-hour time to remove unnecessary leading
+ // zero is required because on Windows, PHP strftime function does not
+ // support the correct 'hour without leading zero' parameter (%l).
+ if (!empty($CFG->nofixhour)) {
+ // Config.php can force %I not to be fixed.
+ $fixhour = false;
+ } else if ($fixhour) {
+ $formatnohour = str_replace('%I', 'HH', $format);
+ $fixhour = ($formatnohour != $format);
+ $format = $formatnohour;
}
//add daylight saving offset for string timezones only, as we can't get dst for
$timezone = get_user_timezone_offset($timezone);
if (abs($timezone) > 13) { /// Server time
+ $datestring = strftime($format, $date);
if ($fixday) {
- $datestring = strftime($formatnoday, $date);
$daystring = ltrim(str_replace(array(' 0', ' '), '', strftime(' %d', $date)));
$datestring = str_replace('DD', $daystring, $datestring);
- } else {
- $datestring = strftime($format, $date);
+ }
+ if ($fixhour) {
+ $hourstring = ltrim(str_replace(array(' 0', ' '), '', strftime(' %I', $date)));
+ $datestring = str_replace('HH', $hourstring, $datestring);
}
} else {
$date += (int)($timezone * 3600);
+ $datestring = gmstrftime($format, $date);
if ($fixday) {
- $datestring = gmstrftime($formatnoday, $date);
$daystring = ltrim(str_replace(array(' 0', ' '), '', gmstrftime(' %d', $date)));
$datestring = str_replace('DD', $daystring, $datestring);
- } else {
- $datestring = gmstrftime($format, $date);
+ }
+ if ($fixhour) {
+ $hourstring = ltrim(str_replace(array(' 0', ' '), '', gmstrftime(' %I', $date)));
+ $datestring = str_replace('HH', $hourstring, $datestring);
}
}
}
}
- // When using the %l (12-hour time with no leading zero), it adds unwanted spaces
- $datestring = trim(str_replace(' ', ' ', $datestring));
return $datestring;
}
<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
* of this class in the $PAGE global variable. This class is a central repository
* of information about the page we are building up to send back to the user.
*
- * @package core
- * @subpackage lib
+ * @package core
+ * @category page
* @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
* $PAGE->blocks, etc.
*
* @copyright 2009 Tim Hunt
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
* @since Moodle 2.0
+ * @package core
+ * @category page
+ *
+ * The following properties are alphabetical. Please keep it that way so that its
+ * easy to maintain.
*
* @property-read string $activityname The type of activity we are in, for example 'forum' or 'quiz'.
* Will be null if this page is not within a module.
- * @property-read object $activityrecord The row from the activities own database table (for example
+ * @property-read stdClass $activityrecord The row from the activities own database table (for example
* the forum or quiz table) that this page belongs to. Will be null
* if this page is not within a module.
* @property-read array $alternativeversions Mime type => object with ->url and ->title.
* @property-read blocks_manager $blocks The blocks manager object for this page.
- * @property-read string $bodyclasses Returns a string to use within the class attribute on the body tag.
+ * @property-read string $bodyclasses A string to use within the class attribute on the body tag.
+ * @property-read string $bodyid A string to use as the id of the body tag.
* @property-read string $button The HTML to go where the Turn editing on button normally goes.
* @property-read bool $cacheable Defaults to true. Set to false to stop the page being cached at all.
* @property-read array $categories An array of all the categories the page course belongs to,
* starting with the immediately containing category, and working out to
* the top-level category. This may be the empty array if we are in the
* front page course.
- * @property-read mixed $category The category that the page course belongs to. If there isn't one returns null.
- * @property-read object $cm The course_module that this page belongs to. Will be null
+ * @property-read mixed $category The category that the page course belongs to.
+ * @property-read cm_info $cm The course_module that this page belongs to. Will be null
* if this page is not within a module. This is a full cm object, as loaded
* by get_coursemodule_from_id or get_coursemodule_from_instance,
* so the extra modname and name fields are present.
- * @property-read object $context The main context to which this page belongs.
- * @property-read object $course The current course that we are inside - a row from the
+ * @property-read context $context The main context to which this page belongs.
+ * @property-read stdClass $course The current course that we are inside - a row from the
* course table. (Also available as $COURSE global.) If we are not inside
* an actual course, this will be the site course.
* @property-read string $devicetypeinuse The name of the device type in use
* @property-read string $docspath The path to the Moodle docs for this page.
* @property-read string $focuscontrol The id of the HTML element to be focused when the page has loaded.
- * @property-read bool $headerprinted
+ * @property-read bool $headerprinted True if the page header has already been printed.
* @property-read string $heading The main heading that should be displayed at the top of the <body>.
* @property-read string $headingmenu The menu (or actions) to display in the heading
- * @property-read array $layout_options Returns arrays with options for layout file.
- * @property-read navbar $navbar Returns the navbar object used to display the navbar
- * @property-read global_navigation $navigation Returns the global navigation structure
+ * @property-read array $layout_options An arrays with options for the layout file.
+ * @property-read array $legacythemeinuse True if the legacy browser theme is in use.
+ * @property-read navbar $navbar The navbar object used to display the navbar
+ * @property-read global_navigation $navigation The navigation structure for this page.
* @property-read xml_container_stack $opencontainers Tracks XHTML tags on this page that have been opened but not closed.
* mainly for internal use by the rendering code.
* @property-read string $pagelayout The general type of page this is. For example 'normal', 'popup', 'home'.
* Allows the theme to display things differently, if it wishes to.
- * @property-read string $pagetype Returns the page type string, should be used as the id for the body tag in the theme.
+ * @property-read string $pagetype The page type string, should be used as the id for the body tag in the theme.
* @property-read int $periodicrefreshdelay The periodic refresh delay to use with meta refresh
* @property-read page_requirements_manager $requires Tracks the JavaScript, CSS files, etc. required by this page.
- * @property-read settings_navigation $settingsnav
+ * @property-read settings_navigation $settingsnav The settings navigation
* @property-read int $state One of the STATE_... constants
* @property-read string $subpage The subpage identifier, if any.
- * @property-read theme_config $theme Returns the initialised theme for this page.
+ * @property-read theme_config $theme The theme for this page.
* @property-read string $title The title that should go in the <head> section of the HTML of this page.
* @property-read moodle_url $url The moodle url object for this page.
*/
class moodle_page {
- /**#@+ Tracks the where we are in the generation of the page. */
+
+ /** The state of the page before it has printed the header **/
const STATE_BEFORE_HEADER = 0;
+
+ /** The state the page is in temporarily while the header is being printed **/
const STATE_PRINTING_HEADER = 1;
+
+ /** The state the page is in while content is presumably being printed **/
const STATE_IN_BODY = 2;
- const STATE_DONE = 3;
- /**#@-*/
-/// Field declarations =========================================================
+ /**
+ * The state the page is when the footer has been printed and its function is
+ * complete.
+ */
+ const STATE_DONE = 3;
+ /**
+ * @var int The current state of the page. The state a page is within
+ * determines what actions are possible for it.
+ */
protected $_state = self::STATE_BEFORE_HEADER;
+ /**
+ * @var stdClass The course currently associated with this page.
+ * If not has been provided the front page course is used.
+ */
protected $_course = null;
/**
- * If this page belongs to a module, this is the cm_info module description object.
- * @var cm_info
+ * @var cm_info If this page belongs to a module, this is the cm_info module
+ * description object.
*/
protected $_cm = null;
/**
- * If $_cm is not null, then this will hold the corresponding row from the
- * modname table. For example, if $_cm->modname is 'quiz', this will be a
- * row from the quiz table.
+ * @var stdClass If $_cm is not null, then this will hold the corresponding
+ * row from the modname table. For example, if $_cm->modname is 'quiz', this
+ * will be a row from the quiz table.
*/
protected $_module = null;
/**
- * The context that this page belongs to.
+ * @var context The context that this page belongs to.
*/
protected $_context = null;
/**
- * This holds any categories that $_course belongs to, starting with the
+ * @var array This holds any categories that $_course belongs to, starting with the
* particular category it belongs to, and working out through any parent
* categories to the top level. These are loaded progressively, if needed.
* There are three states. $_categories = null initially when nothing is
*/
protected $_categories = null;
+ /**
+ * @var array An array of CSS classes that should be added to the body tag in HTML.
+ */
protected $_bodyclasses = array();
+ /**
+ * @var string The title for the page. Used within the title tag in the HTML head.
+ */
protected $_title = '';
+ /**
+ * @var string The string to use as the heading of the page. Shown near the top of the
+ * page within most themes.
+ */
protected $_heading = '';
+ /**
+ * @var string The pagetype is used to describe the page and defaults to a representation
+ * of the physical path to the page e.g. my-index, mod-quiz-attempt
+ */
protected $_pagetype = null;
+ /**
+ * @var string The pagelayout to use when displaying this page. The
+ * pagelayout needs to have been defined by the theme in use, or one of its
+ * parents. By default base is used however standard is the more common layout.
+ * Note that this gets automatically set by core during operations like
+ * require_login.
+ */
protected $_pagelayout = 'base';
/**
- * List of theme layout options, these are ignored by core.
+ * @var array List of theme layout options, these are ignored by core.
* To be used in individual theme layout files only.
- * @var array
*/
protected $_layout_options = array();
+ /**
+ * @var string An optional arbitrary parameter that can be set on pages where the context
+ * and pagetype is not enough to identify the page.
+ */
protected $_subpage = '';
+ /**
+ * @var string Set a different path to use for the 'Moodle docs for this page' link.
+ * By default, it uses the path of the file for instance mod/quiz/attempt.
+ */
protected $_docspath = null;
- /** @var string|null A legacy class that will be added to the body tag */
+ /**
+ * @var string A legacy class that will be added to the body tag
+ */
protected $_legacyclass = null;
+ /**
+ * @var moodle_url The URL for this page. This is mandatory and must be set
+ * before output is started.
+ */
protected $_url = null;
+ /**
+ * @var array An array of links to alternative versions of this page.
+ * Primarily used for RSS versions of the current page.
+ */
protected $_alternateversions = array();
+ /**
+ * @var block_manager The blocks manager for this page. It is reponsible for
+ * the blocks and there content on this page.
+ */
protected $_blocks = null;
+ /**
+ * @var page_requirements_manager Page requirements manager. It is reponsible
+ * for all JavaScript and CSS resources required by this page.
+ */
protected $_requires = null;
+ /**
+ * @var string The capability required by the user in order to edit blocks
+ * and block settings on this page.
+ */
protected $_blockseditingcap = 'moodle/site:manageblocks';
+ /**
+ * @var bool An internal flag to record when block actions have been processed.
+ * Remember block actions occur on the current URL and it is important that
+ * even they are never executed more than once.
+ */
protected $_block_actions_done = false;
+ /**
+ * @var array An array of any other capabilities the current user must have
+ * in order to editing the page and/or its content (not just blocks).
+ */
protected $_othereditingcaps = array();
+ /**
+ * @var bool Sets whether this page should be cached by the browser or not.
+ * If it is set to true (default) the page is served with caching headers.
+ */
protected $_cacheable = true;
+ /**
+ * @var string Can be set to the ID of an element on the page, if done that
+ * element receives focus when the page loads.
+ */
protected $_focuscontrol = '';
+ /**
+ * @var string HTML to go where the turn on editing button is located. This
+ * is nearly a legacy item and not used very often any more.
+ */
protected $_button = '';
+ /**
+ * @var theme_config The theme to use with this page. This has to be properly
+ * initialised via {@link moodle_page::initialise_theme_and_output()} which
+ * happens magically before any operation that requires it.
+ */
protected $_theme = null;
- /** @var global_navigation Contains the global navigation structure*/
+
+ /**
+ * @var global_navigation Contains the global navigation structure.
+ */
protected $_navigation = null;
- /** @var null|settings_navigation Contains the settings navigation structure*/
+
+ /**
+ * @var settings_navigation Contains the settings navigation structure.
+ */
protected $_settingsnav = null;
- /** @var null|navbar Contains the navbar structure*/
+
+ /**
+ * @var navbar Contains the navbar structure.
+ */
protected $_navbar = null;
- /** @var string */
+
+ /**
+ * @var string The menu (or actions) to display in the heading.
+ */
protected $_headingmenu = null;
/**
- * Then the theme is initialised, we save the stack trace, for use in error messages.
- * @var array stack trace.
+ * @var array stack trace. Then the theme is initialised, we save the stack
+ * trace, for use in error messages.
*/
protected $_wherethemewasinitialised = null;
- /** @var xhtml_container_stack tracks XHTML tags on this page that have been opened but not closed. */
+ /**
+ * @var xhtml_container_stack Tracks XHTML tags on this page that have been
+ * opened but not closed.
+ */
protected $_opencontainers;
/**
- * Sets the page to refresh after a given delay (in seconds) using meta refresh
- * in {@link standard_head_html()} in outputlib.php
+ * @var int Sets the page to refresh after a given delay (in seconds) using
+ * meta refresh in {@link standard_head_html()} in outputlib.php
* If set to null(default) the page is not refreshed
- * @var int|null
*/
protected $_periodicrefreshdelay = null;
/**
- * This is simply to improve backwards compatibility. If old code relies on
- * a page class that implements print_header, or complex logic in
- * user_allowed_editing then we stash an instance of that other class here,
+ * @var stdClass This is simply to improve backwards compatibility. If old
+ * code relies on a page class that implements print_header, or complex logic
+ * in user_allowed_editing then we stash an instance of that other class here,
* and delegate to it in certain situations.
*/
protected $_legacypageobject = null;
/**
- * Associative array of browser shortnames (as used by check_browser_version)
+ * @var array Associative array of browser shortnames (as used by check_browser_version)
* and their minimum required versions
- * @var array
*/
protected $_legacybrowsers = array('MSIE' => 6.0);
/**
- * Is set to the name of the device type in use.
+ * @var string Is set to the name of the device type in use.
* This will we worked out when it is first used.
- *
- * @var string
*/
protected $_devicetypeinuse = null;
+ /**
+ * @var bool Used to determine if HTTPS should be required for login.
+ */
protected $_https_login_required = false;
+ /**
+ * @var bool Determines if popup notifications allowed on this page.
+ * Code such as the quiz module disables popup notifications in situations
+ * such as upgrading or completing a quiz.
+ */
protected $_popup_notification_allowed = true;
-/// Magic getter methods =============================================================
-/// Due to the __get magic below, you normally do not call these as $PAGE->magic_get_x
-/// methods, but instead use the $PAGE->x syntax.
+ // Magic getter methods =============================================================
+ // Due to the __get magic below, you normally do not call these as $PAGE->magic_get_x
+ // methods, but instead use the $PAGE->x syntax.
/**
- * Please do not call this method directly, use the ->state syntax. {@link __get()}.
- * @return integer one of the STATE_... constants. You should not normally need
+ * Please do not call this method directly, use the ->state syntax. {@link moodle_page::__get()}.
+ * @return integer one of the STATE_XXX constants. You should not normally need
* to use this in your code. It is intended for internal use by this class
* and its friends like print_header, to check that everything is working as
* expected. Also accessible as $PAGE->state.
}
/**
- * Please do not call this method directly, use the ->headerprinted syntax. {@link __get()}.
- * @return boolean has the header already been printed?
+ * Please do not call this method directly, use the ->headerprinted syntax. {@link moodle_page::__get()}.
+ * @return bool has the header already been printed?
*/
protected function magic_get_headerprinted() {
return $this->_state >= self::STATE_IN_BODY;
}
/**
- * Please do not call this method directly, use the ->course syntax. {@link __get()}.
- *
- * @global object
- * @return object the current course that we are inside - a row from the
+ * Please do not call this method directly, use the ->course syntax. {@link moodle_page::__get()}.
+ * @return stdClass the current course that we are inside - a row from the
* course table. (Also available as $COURSE global.) If we are not inside
* an actual course, this will be the site course.
*/
}
/**
- * Please do not call this method directly, use the ->cm syntax. {@link __get()}.
- * @return object the course_module that this page belongs to. Will be null
+ * Please do not call this method directly, use the ->cm syntax. {@link moodle_page::__get()}.
+ * @return cm_info the course_module that this page belongs to. Will be null
* if this page is not within a module. This is a full cm object, as loaded
* by get_coursemodule_from_id or get_coursemodule_from_instance,
* so the extra modname and name fields are present.
- * @return cm_info
*/
protected function magic_get_cm() {
return $this->_cm;
}
/**
- * Please do not call this method directly, use the ->activityrecord syntax. {@link __get()}.
- * @return object the row from the activities own database table (for example
+ * Please do not call this method directly, use the ->activityrecord syntax. {@link moodle_page::__get()}.
+ * @return stdClass the row from the activities own database table (for example
* the forum or quiz table) that this page belongs to. Will be null
* if this page is not within a module.
*/
}
/**
- * Please do not call this method directly, use the ->activityname syntax. {@link __get()}.
- * @return string|null the The type of activity we are in, for example 'forum' or 'quiz'.
+ * Please do not call this method directly, use the ->activityname syntax. {@link moodle_page::__get()}.
+ * @return string the The type of activity we are in, for example 'forum' or 'quiz'.
* Will be null if this page is not within a module.
*/
protected function magic_get_activityname() {
}
/**
- * Please do not call this method directly, use the ->category syntax. {@link __get()}.
- * @return mixed the category that the page course belongs to. If there isn't one
+ * Please do not call this method directly, use the ->category syntax. {@link moodle_page::__get()}.
+ * @return stdClass the category that the page course belongs to. If there isn't one
* (that is, if this is the front page course) returns null.
*/
protected function magic_get_category() {
}
/**
- * Please do not call this method directly, use the ->categories syntax. {@link __get()}.
+ * Please do not call this method directly, use the ->categories syntax. {@link moodle_page::__get()}.
* @return array an array of all the categories the page course belongs to,
* starting with the immediately containing category, and working out to
* the top-level category. This may be the empty array if we are in the
}
/**
- * Please do not call this method directly, use the ->context syntax. {@link __get()}.
- * @return object the main context to which this page belongs.
+ * Please do not call this method directly, use the ->context syntax. {@link moodle_page::__get()}.
+ * @return context the main context to which this page belongs.
*/
protected function magic_get_context() {
if (is_null($this->_context)) {
}
/**
- * Please do not call this method directly, use the ->pagetype syntax. {@link __get()}.
+ * Please do not call this method directly, use the ->pagetype syntax. {@link moodle_page::__get()}.
* @return string e.g. 'my-index' or 'mod-quiz-attempt'.
*/
protected function magic_get_pagetype() {
}
/**
- * Please do not call this method directly, use the ->pagetype syntax. {@link __get()}.
+ * Please do not call this method directly, use the ->pagetype syntax. {@link moodle_page::__get()}.
* @return string The id to use on the body tag, uses {@link magic_get_pagetype()}.
*/
protected function magic_get_bodyid() {
}
/**
- * Please do not call this method directly, use the ->pagelayout syntax. {@link __get()}.
+ * Please do not call this method directly, use the ->pagelayout syntax. {@link moodle_page::__get()}.
* @return string the general type of page this is. For example 'standard', 'popup', 'home'.
* Allows the theme to display things differently, if it wishes to.
*/
}
/**
- * Please do not call this method directly, use the ->layout_tions syntax. {@link __get()}.
+ * Please do not call this method directly, use the ->layout_tions syntax. {@link moodle_page::__get()}.
* @return array returns arrys with options for layout file
*/
protected function magic_get_layout_options() {
}
/**
- * Please do not call this method directly, use the ->subpage syntax. {@link __get()}.
- * @return string|null The subpage identifier, if any.
+ * Please do not call this method directly, use the ->subpage syntax. {@link moodle_page::__get()}.
+ * @return string The subpage identifier, if any.
*/
protected function magic_get_subpage() {
return $this->_subpage;
}
/**
- * Please do not call this method directly, use the ->bodyclasses syntax. {@link __get()}.
+ * Please do not call this method directly, use the ->bodyclasses syntax. {@link moodle_page::__get()}.
* @return string the class names to put on the body element in the HTML.
*/
protected function magic_get_bodyclasses() {
}
/**
- * Please do not call this method directly, use the ->title syntax. {@link __get()}.
+ * Please do not call this method directly, use the ->title syntax. {@link moodle_page::__get()}.
* @return string the title that should go in the <head> section of the HTML of this page.
*/
protected function magic_get_title() {
}
/**
- * Please do not call this method directly, use the ->heading syntax. {@link __get()}.
+ * Please do not call this method directly, use the ->heading syntax. {@link moodle_page::__get()}.
* @return string the main heading that should be displayed at the top of the <body>.
*/
protected function magic_get_heading() {
}
/**
- * Please do not call this method directly, use the ->heading syntax. {@link __get()}.
+ * Please do not call this method directly, use the ->heading syntax. {@link moodle_page::__get()}.
* @return string The menu (or actions) to display in the heading
*/
protected function magic_get_headingmenu() {
}
/**
- * Please do not call this method directly, use the ->docspath syntax. {@link __get()}.
+ * Please do not call this method directly, use the ->docspath syntax. {@link moodle_page::__get()}.
* @return string the path to the Moodle docs for this page.
*/
protected function magic_get_docspath() {
}
/**
- * Please do not call this method directly, use the ->url syntax. {@link __get()}.
+ * Please do not call this method directly, use the ->url syntax. {@link moodle_page::__get()}.
* @return moodle_url the clean URL required to load the current page. (You
* should normally use this in preference to $ME or $FULLME.)
*/
}
/**
- * Please do not call this method directly, use the ->blocks syntax. {@link __get()}.
+ * Please do not call this method directly, use the ->blocks syntax. {@link moodle_page::__get()}.
* @return blocks_manager the blocks manager object for this page.
*/
protected function magic_get_blocks() {
}
/**
- * Please do not call this method directly, use the ->requires syntax. {@link __get()}.
+ * Please do not call this method directly, use the ->requires syntax. {@link moodle_page::__get()}.
* @return page_requirements_manager tracks the JavaScript, CSS files, etc. required by this page.
*/
protected function magic_get_requires() {
}
/**
- * Please do not call this method directly, use the ->cacheable syntax. {@link __get()}.
- * @return boolean can this page be cached by the user's browser.
+ * Please do not call this method directly, use the ->cacheable syntax. {@link moodle_page::__get()}.
+ * @return bool can this page be cached by the user's browser.
*/
protected function magic_get_cacheable() {
return $this->_cacheable;
}
/**
- * Please do not call this method directly, use the ->focuscontrol syntax. {@link __get()}.
+ * Please do not call this method directly, use the ->focuscontrol syntax. {@link moodle_page::__get()}.
* @return string the id of the HTML element to be focused when the page has loaded.
*/
protected function magic_get_focuscontrol() {
}
/**
- * Please do not call this method directly, use the ->button syntax. {@link __get()}.
+ * Please do not call this method directly, use the ->button syntax. {@link moodle_page::__get()}.
* @return string the HTML to go where the Turn editing on button normally goes.
*/
protected function magic_get_button() {
}
/**
- * Please do not call this method directly, use the ->theme syntax. {@link __get()}.
+ * Please do not call this method directly, use the ->theme syntax. {@link moodle_page::__get()}.
* @return theme_config the initialised theme for this page.
*/
protected function magic_get_theme() {
}
/**
- * Please do not call this method directly, use the ->devicetypeinuse syntax. {@link __get()}.
- *
+ * Please do not call this method directly, use the ->devicetypeinuse syntax. {@link moodle_page::__get()}.
* @return string The device type being used.
*/
protected function magic_get_devicetypeinuse() {
}
/**
- * Please do not call this method directly, use the ->legacythemeinuse syntax. {@link __get()}.
+ * Please do not call this method directly, use the ->legacythemeinuse syntax. {@link moodle_page::__get()}.
* @deprecated since 2.1
* @return bool
*/
/**
* Please do not call this method directly use the ->periodicrefreshdelay syntax
- * {@link __get()}
+ * {@link moodle_page::__get()}
* @return int The periodic refresh delay to use with meta refresh
*/
protected function magic_get_periodicrefreshdelay() {
}
/**
- * Please do not call this method directly use the ->opencontainers syntax. {@link __get()}
+ * Please do not call this method directly use the ->opencontainers syntax. {@link moodle_page::__get()}
* @return xhtml_container_stack tracks XHTML tags on this page that have been opened but not closed.
* mainly for internal use by the rendering code.
*/
* it to the corresponding $PAGE->magic_get_course() method if there is one, and
* throwing an exception if not.
*
- * @param $name string property name
+ * @param string $name property name
* @return mixed
*/
public function __get($name) {
}
/**
- * PHP overloading magic which prevents the $PAGE->context = $context; syntax
+ * PHP overloading magic to catch obvious coding errors.
+ *
+ * This method has been created to catch obvious coding errors where the
+ * developer has tried to set a page property using $PAGE->key = $value.
+ * In the moodle_page class all properties must be set using the appropriate
+ * $PAGE->set_something($value) method.
*
- * @param $name string property name
- * @param $name mixed value
- * @return void, throws exception if field not defined in page class
+ * @param string $name property name
+ * @param mixed $value Value
+ * @return void Throws exception if field not defined in page class
*/
public function __set($name, $value) {
if (method_exists($this, 'set_' . $name)) {
}
}
-/// Other information getting methods ==========================================
+ // Other information getting methods ==========================================
/**
* Returns instance of page renderer
+ *
* @param string $component name such as 'core', 'mod_forum' or 'qtype_multichoice'.
* @param string $subtype optional subtype such as 'news' resulting to 'mod_forum_news'
* @param string $target one of rendering target constants
/**
* Checks to see if there are any items on the navbar object
+ *
* @return bool true if there are, false if not
*/
public function has_navbar() {
}
/**
- * @return boolean should the current user see this page in editing mode.
+ * Should the current user see this page in editing mode.
* That is, are they allowed to edit this page, and are they currently in
* editing mode.
+ * @return bool
*/
public function user_is_editing() {
global $USER;
}
/**
- * @return boolean does the user have permission to edit blocks on this page.
+ * Does the user have permission to edit blocks on this page.
+ * @return bool
*/
public function user_can_edit_blocks() {
return has_capability($this->_blockseditingcap, $this->_context);
}
/**
- * @return boolean does the user have permission to see this page in editing mode.
+ * Does the user have permission to see this page in editing mode.
+ * @return bool
*/
public function user_allowed_editing() {
if ($this->_legacypageobject) {
}
/**
- * @return string a description of this page. Normally displayed in the footer in
+ * Get a description of this page. Normally displayed in the footer in
* developer debug mode.
+ * @return string
*/
public function debug_summary() {
$summary = '';
return $summary;
}
-/// Setter methods =============================================================
+ // Setter methods =============================================================
/**
* Set the state. The state must be one of that STATE_... constants, and
* the state is only allowed to advance one step at a time.
- * @param integer $state the new state.
+ *
+ * @param integer $state The new state.
*/
public function set_state($state) {
if ($state != $this->_state + 1 || $state > self::STATE_DONE) {
*
* Sets $PAGE->context to the course context, if it is not already set.
*
- * @param object the course to set as the global course.
+ * @param stdClass $course the course to set as the global course.
*/
public function set_course($course) {
global $COURSE, $PAGE;
/**
* Set the main context to which this page belongs.
- * @param object $context a context object, normally obtained with get_context_instance.
+ *
+ * @param context $context a context object, normally obtained with get_context_instance.
*/
public function set_context($context) {
if ($context === null) {
}
/**
- * @param $module a row from the main database table for the module that this
- * page belongs to. For example, if ->cm is a forum, then you can pass the
- * corresponding row from the forum table here if you have it (saves a database
- * query sometimes).
+ * Sets the activity record. This could be a row from the main table for a
+ * module. For instance if the current module (cm) is a forum this should be a row
+ * from the forum table.
+ *
+ * @param stdClass $module A row from the main database table for the module that this
+ * page belongs to.
+ * @return void
*/
public function set_activity_record($module) {
if (is_null($this->_cm)) {
}
/**
- * @param string $pagetype e.g. 'my-index' or 'mod-quiz-attempt'. Normally
- * you do not need to set this manually, it is automatically created from the
- * script name. However, on some pages this is overridden. For example, the
- * page type for course/view.php includes the course format, for example
- * 'course-view-weeks'. This gets used as the id attribute on <body> and
- * also for determining which blocks are displayed.
+ * Sets the pagetype to use for this page.
+ *
+ * Normally you do not need to set this manually, it is automatically created
+ * from the script name. However, on some pages this is overridden.
+ * For example the page type for course/view.php includes the course format,
+ * for example 'course-view-weeks'. This gets used as the id attribute on
+ * <body> and also for determining which blocks are displayed.
+ *
+ * @param string $pagetype e.g. 'my-index' or 'mod-quiz-attempt'.
*/
public function set_pagetype($pagetype) {
$this->_pagetype = $pagetype;
}
/**
- * @param string $pagelayout the page layout this is. For example 'popup', 'home'.
+ * Sets the layout to use for this page.
+ *
+ * The page layout determines how the page will be displayed, things such as
+ * block regions, content areas, etc are controlled by the layout.
+ * The theme in use for the page will determine that the layout contains.
+ *
* This properly defaults to 'base', so you only need to call this function if
* you want something different. The exact range of supported layouts is specified
* in the standard theme.
+ *
+ * For an idea of the common page layouts see
+ * {@link http://docs.moodle.org/dev/Themes_2.0#The_different_layouts_as_of_August_17th.2C_2010}
+ * But please keep in mind that it may be (and normally is) out of date.
+ * The only place to find an accurate up-to-date list of the page layouts
+ * available for your version of Moodle is {@link theme/base/config.php}
+ *
+ * @param string $pagelayout the page layout this is. For example 'popup', 'home'.
*/
public function set_pagelayout($pagelayout) {
/**
/**
* If context->id and pagetype are not enough to uniquely identify this page,
* then you can set a subpage id as well. For example, the tags page sets
+ *
* @param string $subpage an arbitrary identifier that, along with context->id
* and pagetype, uniquely identifies this page.
*/
}
/**
+ * Adds a CSS class to the body tag of the page.
+ *
* @param string $class add this class name ot the class attribute on the body tag.
*/
public function add_body_class($class) {
}
/**
+ * Adds an array of body classes to the body tag of this page.
+ *
* @param array $classes this utility method calls add_body_class for each array element.
*/
public function add_body_classes($classes) {
}
/**
+ * Sets the title for the page.
+ * This is normally used within the title tag in the head of the page.
+ *
* @param string $title the title that should go in the <head> section of the HTML of this page.
*/
public function set_title($title) {
}
/**
+ * Sets the heading to use for the page.
+ * This is normally used as the main heading at the top of the content.
+ *
* @param string $heading the main heading that should be displayed at the top of the <body>.
*/
public function set_heading($heading) {
}
/**
+ * Sets some HTML to use next to the heading {@link moodle_page::set_heading()}
+ *
* @param string $menu The menu/content to show in the heading
*/
public function set_headingmenu($menu) {
}
/**
- * Set the course category this page belongs to manually. This automatically
- * sets $PAGE->course to be the site course. You cannot use this method if
- * you have already set $PAGE->course - in that case, the category must be
- * the one that the course belongs to. This also automatically sets the
- * page context to the category context.
+ * Set the course category this page belongs to manually.
+ *
+ * This automatically sets $PAGE->course to be the site course. You cannot
+ * use this method if you have already set $PAGE->course - in that case,
+ * the category must be the one that the course belongs to. This also
+ * automatically sets the page context to the category context.
+ *
* @param integer $categoryid The id of the category to set.
*/
public function set_category_by_id($categoryid) {
/**
* Set a different path to use for the 'Moodle docs for this page' link.
+ *
* By default, it uses the pagetype, which is normally the same as the
* script name. So, for example, for mod/quiz/attempt.php, pagetype is
* mod-quiz-attempt, and so docspath is mod/quiz/attempt.
+ *
* @param string $path the path to use at the end of the moodle docs URL.
*/
public function set_docs_path($path) {
/**
* You should call this method from every page to set the cleaned-up URL
- * that should be used to return to this page. Used, for example, by the
- * blocks editing UI to know where to return the user after an action.
+ * that should be used to return to this page.
+ *
+ * Used, for example, by the blocks editing UI to know where to return the
+ * user after an action.
* For example, course/view.php does:
* $id = optional_param('id', 0, PARAM_INT);
* $PAGE->set_url('/course/view.php', array('id' => $id));
+ *
* @param moodle_url|string $url URL relative to $CFG->wwwroot or {@link moodle_url} instance
* @param array $params parameters to add to the URL
*/
* If such other version exist, call this method, and a link to the alternate
* version will be included in the <head> of the page.
*
- * @param $title The title to give the alternate version.
- * @param $url The URL of the alternate version.
- * @param $mimetype The mime-type of the alternate version.
+ * @param string $title The title to give the alternate version.
+ * @param string|moodle_url $url The URL of the alternate version.
+ * @param string $mimetype The mime-type of the alternate version.
*/
public function add_alternate_version($title, $url, $mimetype) {
if ($this->_state > self::STATE_BEFORE_HEADER) {
}
/**
- * Set the capability that allows users to edit blocks on this page. Normally
- * the default of 'moodle/site:manageblocks' is used, but a few pages like
- * the My Moodle page need to use a different capability like 'moodle/my:manageblocks'.
+ * Set the capability that allows users to edit blocks on this page.
+ *
+ * Normally the default of 'moodle/site:manageblocks' is used, but a few
+ * pages like the My Moodle page need to use a different capability
+ * like 'moodle/my:manageblocks'.
+ *
* @param string $capability a capability.
*/
public function set_blocks_editing_capability($capability) {
* Some pages let you turn editing on for reasons other than editing blocks.
* If that is the case, you can pass other capabilities that let the user
* edit this page here.
+ *
* @param string|array $capability either a capability, or an array of capabilities.
*/
public function set_other_editing_capability($capability) {
}
/**
- * @return boolean $cacheable can this page be cached by the user's browser.
+ * Sets whether the browser should cache this page or not.
+ *
+ * @return bool $cacheable can this page be cached by the user's browser.
*/
public function set_cacheable($cacheable) {
$this->_cacheable = $cacheable;
* a coding exception will be thrown.
*
* @param int $delay Sets the delay before refreshing the page, if set to null
- * refresh is cancelled
+ * refresh is cancelled
*/
public function set_periodic_refresh_delay($delay=null) {
if ($this->_state > self::STATE_BEFORE_HEADER) {
/**
* Force this page to use a particular theme.
*
- * Please use this cautiously. It is only intended to be used by the themes selector admin page.
+ * Please use this cautiously.
+ * It is only intended to be used by the themes selector admin page.
*
- * @param $themename the name of the theme to use.
+ * @param string $themename the name of the theme to use.
*/
public function force_theme($themename) {
$this->ensure_theme_not_set();
}
}
-/// Initialisation methods =====================================================
-/// These set various things up in a default way.
+ // Initialisation methods =====================================================
+ // These set various things up in a default way.
/**
* This method is called when the page first moves out of the STATE_BEFORE_HEADER
* Make sure the right theme for this page is loaded. Tell our
* blocks_manager about the theme block regions, and then, if
* we are $PAGE, set up the global $OUTPUT.
+ *
+ * @return void
*/
public function initialise_theme_and_output() {
global $OUTPUT, $PAGE, $SITE;
/**
* Sets ->pagetype from the script name. For example, if the script that was
* run is mod/quiz/view.php, ->pagetype will be set to 'mod-quiz-view'.
+ *
* @param string $script the path to the script that should be used to
* initialise ->pagetype. If not passed the $SCRIPT global will be used.
* If legacy code has set $CFG->pagepath that will be used instead, and a
}
}
+ /**
+ * Initialises the CSS classes that will be added to body tag of the page.
+ *
+ * The function is responsible for adding all of the critical CSS classes
+ * that describe the current page, and its state.
+ * This includes classes that describe the following for example:
+ * - Current language
+ * - Language direction
+ * - YUI CSS initialisation
+ * - Pagelayout
+ * These are commonly used in CSS to target specific types of pages.
+ */
protected function initialise_standard_body_classes() {
global $CFG, $USER;
}
}
+ /**
+ * Loads the activity record for the current CM object associated with this
+ * page.
+ *
+ * This will load {@link moodle_page::$_module} with a row from the related
+ * module table in the database.
+ * For instance if {@link moodle_page::$_cm} is a forum then a row from the
+ * forum table will be loaded.
+ */
protected function load_activity_record() {
global $DB;
if (is_null($this->_cm)) {
$this->_module = $DB->get_record($this->_cm->modname, array('id' => $this->_cm->instance));
}
+ /**
+ * This function ensures that the category of the current course has been
+ * loaded, and if not, the function loads it now.
+ *
+ * @return void
+ * @throws coding_exception
+ */
protected function ensure_category_loaded() {
if (is_array($this->_categories)) {
return; // Already done.
}
}
+ /**
+ * Loads the requested category into the pages categories array.
+ *
+ * @param ing $categoryid
+ * @throws moodle_exception
+ */
protected function load_category($categoryid) {
global $DB;
$category = $DB->get_record('course_categories', array('id' => $categoryid));
}
}
+ /**
+ * Ensures that the category the current course is within, as well as all of
+ * its parent categories, have been loaded.
+ *
+ * @return void
+ */
protected function ensure_categories_loaded() {
global $DB;
$this->ensure_category_loaded();
}
}
+ /**
+ * Ensure the theme has not been loaded yet. If it has an exception is thrown.
+ * @source
+ *
+ * @throws coding_exception
+ */
protected function ensure_theme_not_set() {
if (!is_null($this->_theme)) {
throw new coding_exception('The theme has already been set up for this page ready for output. ' .
}
}
+ /**
+ * Converts the provided URL into a CSS class that be used within the page.
+ * This is primarily used to add the wwwroot to the body tag as a CSS class.
+ *
+ * @param string $url
+ * @return string
+ */
protected function url_to_class_name($url) {
$bits = parse_url($url);
$class = str_replace('.', '-', $bits['host']);
return $class;
}
+ /**
+ * Combines all of the required editing caps for the page and returns them
+ * as an array.
+ *
+ * @return array
+ */
protected function all_editing_caps() {
$caps = $this->_othereditingcaps;
$caps[] = $this->_blockseditingcap;
return $caps;
}
-/// Deprecated fields and methods for backwards compatibility ==================
+ // Deprecated fields and methods for backwards compatibility ==================
/**
+ * Returns the page type.
+ *
* @deprecated since Moodle 2.0 - use $PAGE->pagetype instead.
* @return string page type.
*/
}
/**
+ * Returns the page type.
+ *
* @deprecated since Moodle 2.0 - use $PAGE->pagetype instead.
* @return string this is what page_id_and_class used to return via the $getclass parameter.
*/
- function get_format_name() {
+ public function get_format_name() {
return $this->get_pagetype();
}
/**
+ * Returns the course associated with this page.
+ *
* @deprecated since Moodle 2.0 - use $PAGE->course instead.
- * @return object course.
+ * @return stdClass course.
*/
public function get_courserecord() {
debugging('Call to deprecated method moodle_page::get_courserecord. Please use $PAGE->course instead.');
}
/**
+ * Returns the legacy page class.
+ *
* @deprecated since Moodle 2.0
* @return string this is what page_id_and_class used to return via the $getclass parameter.
*/
}
/**
+ * Returns an array of block regions on this page.
+ *
* @deprecated since Moodle 2.0 - use $PAGE->blocks->get_regions() instead
- * @return string the places on this page where blocks can go.
+ * @return array the places on this page where blocks can go.
*/
function blocks_get_positions() {
debugging('Call to deprecated method moodle_page::blocks_get_positions. Use $PAGE->blocks->get_regions() instead.');
}
/**
+ * Returns the default block region.
+ *
* @deprecated since Moodle 2.0 - use $PAGE->blocks->get_default_region() instead
* @return string the default place for blocks on this page.
*/
}
/**
+ * Returns the default block to use of the page.
+ * This function no longer does anything. DO NOT USE.
+ *
* @deprecated since Moodle 2.0 - no longer used.
*/
function blocks_get_default() {
}
/**
+ * Moves a block.
+ * This function no longer does anything. DO NOT USE.
+ *
* @deprecated since Moodle 2.0 - no longer used.
*/
function blocks_move_position(&$instance, $move) {
}
/**
+ * Returns the URL parameters for the current page.
+ *
* @deprecated since Moodle 2.0 - use $this->url->params() instead.
* @return array URL parameters for this page.
*/
}
/**
+ * Returns the URL path of the current page.
+ *
* @deprecated since Moodle 2.0 - use $this->url->params() instead.
* @return string URL for this page without parameters.
*/
}
/**
+ * Returns the full URL for this page.
+ *
* @deprecated since Moodle 2.0 - use $this->url->out() instead.
* @return string full URL for this page.
*/
}
/**
+ * Returns the legacy page object.
+ *
* @deprecated since Moodle 2.0 - just a backwards compatibility hook.
+ * @return moodle_page
*/
function set_legacy_page_object($pageobject) {
return $this->_legacypageobject = $pageobject;
}
/**
+ * Prints a header... DO NOT USE!
+ *
* @deprecated since Moodle 2.0 - page objects should no longer be doing print_header.
- * @param $_,...
+ * @param mixed $_ ...
*/
function print_header($_) {
if (is_null($this->_legacypageobject)) {
}
/**
+ * Returns the ID for this page. DO NOT USE!
+ *
* @deprecated since Moodle 2.0
* @return the 'page id'. This concept no longer exists.
*/
}
/**
+ * Returns the ID for this page. DO NOT USE!
+ *
* @deprecated since Moodle 2.0
* @return the 'page id'. This concept no longer exists.
*/
}
/**
+ * Returns the module record for this page.
+ *
* @deprecated since Moodle 2.0 - user $PAGE->cm instead.
* @return $this->cm;
*/
return $this->cm;
}
+ /**
+ * Returns true if the page URL has beem set.
+ *
+ * @return bool
+ */
public function has_set_url() {
return ($this->_url!==null);
}
+ /**
+ * Gets set when the block actions for the page have been processed.
+ *
+ * @param bool $setting
+ */
public function set_block_actions_done($setting = true) {
$this->_block_actions_done = $setting;
}
/**
* Are popup notifications allowed on this page?
* Popup notifications may be disallowed in situations such as while upgrading or completing a quiz
- * @return boolean true if popup notifications may be displayed
+ *
+ * @return bool true if popup notifications may be displayed
*/
public function get_popup_notification_allowed() {
return $this->_popup_notification_allowed;
/**
* Allow or disallow popup notifications on this page. Popups are allowed by default.
- * @param boolean true if notifications are allowed. False if not allowed. They are allowed by default.
- * @return null
+ *
+ * @param bool $allowed true if notifications are allowed. False if not allowed. They are allowed by default.
*/
public function set_popup_notification_allowed($allowed) {
$this->_popup_notification_allowed = $allowed;
}
/**
+ * Not needed any more. DO NOT USE!
+ *
* @deprecated since Moodle 2.0
- * Not needed any more.
- * @param $path the folder path
+ * @param string $path the folder path
* @return array an array of page types.
*/
function page_import_types($path) {
}
/**
- * @deprecated since Moodle 2.0
* Do not use this any more. The global $PAGE is automatically created for you.
* If you need custom behaviour, you should just set properties of that object.
+ *
+ * @deprecated since Moodle 2.0
* @param integer $instance legacy page instance id.
- * @return the global $PAGE object.
+ * @return moodle_page The global $PAGE object.
*/
function page_create_instance($instance) {
global $PAGE;
}
/**
- * @deprecated since Moodle 2.0
* Do not use this any more. The global $PAGE is automatically created for you.
* If you need custom behaviour, you should just set properties of that object.
+ *
+ * @deprecated since Moodle 2.0
+ * @return moodle_page The global $PAGE object.
*/
function page_create_object($type, $id = NULL) {
global $CFG, $PAGE, $SITE, $ME;
}
/**
- * @deprecated since Moodle 2.0
* You should not be writing page subclasses any more. Just set properties on the
* global $PAGE object to control its behaviour.
+ *
+ * @deprecated since Moodle 2.0
+ * @return mixed Null if there is not a valid page mapping, or the mapping if
+ * it has been set.
*/
function page_map_class($type, $classname = NULL) {
global $CFG;
}
/**
- * @deprecated since Moodle 2.0
* Parent class from which all Moodle page classes derive
*
- * @package core
- * @subpackage lib
+ * @deprecated since Moodle 2.0
+ * @package core
+ * @category page
* @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class page_base extends moodle_page {
/**
- * The numeric identifier of the page being described.
- * @var int $id
+ * @var int The numeric identifier of the page being described.
*/
- var $id = NULL;
-
-/// Class Functions
+ public $id = null;
- // HTML OUTPUT SECTION
-
- // SELF-REPORTING SECTION
-
- // Simple stuff, do not override this.
- function get_id() {
+ /**
+ * Returns the page id
+ * @deprecated since Moodle 2.0
+ * @return int Returns the id of the page.
+ */
+ public function get_id() {
return $this->id;
}
- // Initialize the data members of the parent class
- function init_quick($data) {
+ /**
+ * Initialize the data members of the parent class
+ * @param scalar $data
+ */
+ public function init_quick($data) {
$this->id = $data->pageid;
}
- function init_full() {
- }
+ /**
+ * DOES NOTHING... DO NOT USE.
+ * @deprecated since Moodle 2.0
+ */
+ public function init_full() {}
}
/**
- * @deprecated since Moodle 2.0
* Class that models the behavior of a moodle course.
* Although this does nothing, this class declaration should be left for now
* since there may be legacy class doing class page_... extends page_course
*
- * @package core
- * @subpackage lib
+ * @deprecated since Moodle 2.0
+ * @package core
+ * @category page
* @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
-class page_course extends page_base {
-}
+class page_course extends page_base {}
/**
- * @deprecated since Moodle 2.0
* Class that models the common parts of all activity modules
*
- * @package core
- * @subpackage lib
+ * @deprecated since Moodle 2.0
+ * @package core
+ * @category page
* @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class page_generic_activity extends page_base {
- // Although this function is deprecated, it should be left here because
- // people upgrading legacy code need to copy it. See
- // http://docs.moodle.org/dev/Migrating_your_code_to_the_2.0_rendering_API
+
+ /**
+ * Although this function is deprecated, it should be left here because
+ * people upgrading legacy code need to copy it. See
+ * http://docs.moodle.org/dev/Migrating_your_code_to_the_2.0_rendering_API
+ *
+ * @param string $title
+ * @param array $morenavlinks
+ * @param string $bodytags
+ * @param string $meta
+ */
function print_header($title, $morenavlinks = NULL, $bodytags = '', $meta = '') {
global $USER, $CFG, $PAGE, $OUTPUT;
}
if (is_null($enabled)) {
- $enabled = explode(',', $CFG->auth);
+ $enabled = array_flip(explode(',', $CFG->auth));
}
return isset($enabled[$this->name]);
static $enabled = null;
if (is_null($enabled)) {
- $enabled = explode(',', $CFG->enrol_plugins_enabled);
+ $enabled = array_flip(explode(',', $CFG->enrol_plugins_enabled));
}
return isset($enabled[$this->name]);
/**
* This file contains all the common stuff to be used in RSS System
*
- * @package core
- * @subpackage rss
+ * @package core_rss
+ * @category rss
* @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com}
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
defined('MOODLE_INTERNAL') || die();
- function rss_add_http_header($context, $componentname, $componentinstance, $title) {
+/**
+ * Build the URL for the RSS feed and add it as a header
+ *
+ * @param stdClass $context The context under which the URL should be created
+ * @param string $componentname The name of the component for which the RSS feed exists
+ * @param stdClass $componentinstance The instance of the component
+ * @param string $title Name for the link to be added to the page header
+ */
+function rss_add_http_header($context, $componentname, $componentinstance, $title) {
global $PAGE, $USER;
$componentid = null;
}
/**
- * This function returns the icon (from theme) with the link to rss/file.php
+ * Print the link for the RSS feed with the correct RSS icon
*
- * @global object
- * @global object
+ * @param stdClass $contextid The id of the context under which the URL should be created
+ * @param int $userid The source of the RSS feed (site/course/group/user)
+ * @param string $componentname The name of the component for which the feed exists
+ * @param string $id The name by which to call the RSS File
+ * @param string $tooltiptext The tooltip to be displayed with the link
+ * @return string HTML output for the RSS link
*/
function rss_get_link($contextid, $userid, $componentname, $id, $tooltiptext='') {
global $OUTPUT;
/**
* This function returns the URL for the RSS XML file.
*
- * @global object
- * @param int contextid the course id
- * @param int userid the current user id
- * @param string modulename the name of the current module. For example "forum"
+ * @param int $contextid the course id
+ * @param int $userid the current user id
+ * @param string $componentname the name of the current component. For example "forum"
* @param string $additionalargs For modules, module instance id
+ * @return string the url of the RSS feed
*/
function rss_get_url($contextid, $userid, $componentname, $additionalargs) {
global $CFG;
}
/**
- * This function prints the icon (from theme) with the link to rss/file.php
+ * Print the link for the RSS feed with the correct RSS icon (Theme based)
+ *
+ * @param stdClass $contextid The id of the context under which the URL should be created
+ * @param int $userid The source of the RSS feed (site/course/group/user)
+ * @param string $componentname The name of the component for which the feed exists
+ * @param string $id The name by which to call the RSS File
+ * @param string $tooltiptext The tooltip to be displayed with the link
*/
function rss_print_link($contextid, $userid, $componentname, $id, $tooltiptext='') {
print rss_get_link($contextid, $userid, $componentname, $id, $tooltiptext);
/**
* Given an object, deletes all RSS files associated with it.
- * Relies on a naming convention. See rss_get_filename()
*
- * @param string $componentname the name of the module ie 'forum'. Used to construct the cache path.
- * @param object $instance An object with an id member variable ie $forum, $glossary.
- * @return void
+ * @param string $componentname the name of the module ie 'forum'. Used to construct the cache path.
+ * @param stdClass $instance An object with an id member variable ie $forum, $glossary.
*/
function rss_delete_file($componentname, $instance) {
global $CFG;
/**
* Are RSS feeds enabled for the supplied module instance?
- * @param object $instance An instance of an activity module ie $forum, $glossary.
- * @param boolean $hasrsstype Should there be a rsstype member variable?
- * @param boolean $hasrssarticles Should there be a rssarticles member variable?
+ *
+ * @param string $modname The name of the module to be checked
+ * @param stdClass $instance An instance of an activity module ie $forum, $glossary.
+ * @param bool $hasrsstype Should there be a rsstype member variable?
+ * @param bool $hasrssarticles Should there be a rssarticles member variable?
+ * @return bool whether or not RSS is enabled for the module
*/
function rss_enabled_for_mod($modname, $instance=null, $hasrsstype=true, $hasrssarticles=true) {
if ($hasrsstype) {
/**
* This function saves to file the rss feed specified in the parameters
*
- * @global object
- * @param string $componentname the module name ie forum. Used to create a cache directory.
- * @param string $filename the name of the file to be created ie "1234"
- * @param string $contents the data to be written to the file
+ * @param string $componentname the module name ie forum. Used to create a cache directory.
+ * @param string $filename the name of the file to be created ie "rss.xml"
+ * @param string $contents the data to be written to the file
+ * @param bool $expandfilename whether or not the fullname of the RSS file should be used
+ * @return bool whether the save was successful or not
*/
function rss_save_file($componentname, $filename, $contents, $expandfilename=true) {
global $CFG;
return $status;
}
-
+/**
+ * Retrieve the location and file name of a cached RSS feed
+ *
+ * @param string $componentname the name of the component the RSS feed is being created for
+ * @param string $filename the name of the RSS FEED
+ * @return string The full name and path of the RSS file
+ */
function rss_get_file_full_name($componentname, $filename) {
global $CFG;
return "$CFG->cachedir/rss/$componentname/$filename.xml";
}
+/**
+ * Construct the file name of the RSS File
+ *
+ * @param stdClass $instance the instance of the source of the RSS feed
+ * @param string $sql the SQL used to produce the RSS feed
+ * @return string the name of the RSS file
+ */
function rss_get_file_name($instance, $sql) {
return $instance->id.'_'.md5($sql);
}
/**
* This function return all the common headers for every rss feed in the site
*
- * @global object
- * @global object
+ * @param string $title the title for the RSS Feed
+ * @param string $link the link for the origin of the RSS feed
+ * @param string $description the description of the contents of the RSS feed
+ * @return bool|string the standard header for the RSS feed
*/
function rss_standard_header($title = NULL, $link = NULL, $description = NULL) {
global $CFG, $USER, $OUTPUT;
}
}
-//This function returns the rss XML code for every item passed in the array
-//item->title: The title of the item
-//item->author: The author of the item. Optional !!
-//item->pubdate: The pubdate of the item
-//item->link: The link url of the item
-//item->description: The content of the item
+
+/**
+ * Generates the rss XML code for every item passed in the array
+ *
+ * item->title: The title of the item
+ * item->author: The author of the item. Optional !!
+ * item->pubdate: The pubdate of the item
+ * item->link: The link url of the item
+ * item->description: The content of the item
+ *
+ * @param array $items an array of item objects
+ * @return bool|string the rss XML code for every item passed in the array
+ */
function rss_add_items($items) {
global $CFG;
/**
* This function return all the common footers for every rss feed in the site
+ *
+ * @param string $title Not used at all
+ * @param string $link Not used at all
+ * @param string $description Not used at all
+ * @todo MDL-31050 Fix/Remove this function
+ * @return string
*/
function rss_standard_footer($title = NULL, $link = NULL, $description = NULL) {
$status = true;
return $result;
}
+
/**
- * This function return an error xml file (string)
- * to be sent when a rss is required (file.php)
- * and something goes wrong
+ * This function return an error xml file (string) to be sent when a rss is required (file.php) and something goes wrong
+ *
+ * @param string $errortype Type of error to send, default is rsserror
+ * @return stdClass returns a XML Feed with an error message in it
*/
function rss_geterrorxmlfile($errortype = 'rsserror') {
global $CFG;
return $return;
}
+/**
+ * Get the ID of the user from a given RSS Token
+ *
+ * @param string $token the RSS token you would like to use to find the user id
+ * @return int The user id
+ */
function rss_get_userid_from_token($token) {
global $DB;
$record = $DB->get_record('user_private_key', array('script'=>'rss','value' => $token), 'userid', IGNORE_MISSING);
return null;
}
+/**
+ * Get the RSS Token from a given user id
+ *
+ * @param int $userid The user id
+ * @return string the RSS token for the user
+ */
function rss_get_token($userid) {
return get_user_key('rss', $userid);
}
+/**
+ * Removes the token for the given user from the DB
+ * @param int $userid The user id for the token you wish to delete
+ */
function rss_delete_token($userid) {
delete_user_key('rss', $userid);
}
-// ===== This function are used to write XML tags =========
-// [stronk7]: They are similar to the glossary export and backup generation
-// but I've replicated them here because they have some minor
-// diferences. Someday all they should go to a common place.
-
/**
* Return the xml start tag
+ *
+ * @param string $tag the xml tag name
+ * @param int $level the indentation level
+ * @param bool $endline whether or not to start new tags on a new line
+ * @param array $attributes the attributes of the xml tag
+ * @return string the xml start tag
*/
function rss_start_tag($tag,$level=0,$endline=false,$attributes=null) {
if ($endline) {
/**
* Return the xml end tag
+ * @param string $tag the xml tag name
+ * @param int $level the indentation level
+ * @param bool $endline whether or not to start new tags on a new line
+ * @return string the xml end tag
*/
function rss_end_tag($tag,$level=0,$endline=true) {
if ($endline) {
}
/**
- * Return the start tag, the contents and the end tag
+ * Return the while xml element, including content
+ *
+ * @param string $tag the xml tag name
+ * @param int $level the indentation level
+ * @param bool $endline whether or not to start new tags on a new line
+ * @param string $content the text to go inside the tag
+ * @param array $attributes the attributes of the xml tag
+ * @return string the whole xml element
*/
function rss_full_tag($tag,$level=0,$endline=true,$content,$attributes=null) {
$st = rss_start_tag($tag,$level,$endline,$attributes);
/**
* Adds RSS Media Enclosures for "podcasting" by including attachments that
* are specified in the item->attachments field.
- * Note also that iTunes does some things very badly - one thing it does is
- * refuse to download ANY of your files if you're using "file.php?file=blah"
- * and can't use the more elegant "file.php/blah" slasharguments setting. It
- * stops after ".php" and assumes the files are not media files, despite what
- * is specified in the "type" attribute. Dodgy coding all round!
- *
- * Authors
- * - Hannes Gassert <hannes@mediagonal.ch>
- * - Dan Stowell
*
- * @global object
- * @param $item object representing an RSS item
- * @return string RSS enclosure tags
+ * @param stdClass $item representing an RSS item
+ * @return string RSS enclosure tags
*/
function rss_add_enclosures($item){
global $CFG;
'time' => '1309514400',
'usertimezone' => 'America/Moncton',
'timezone' => '99', //dst offset and timezone offset.
- 'expectedoutput' => 'Friday, 1 July 2011, 07:00 AM'
+ 'expectedoutput' => 'Friday, 1 July 2011, 7:00 AM'
),
array(
'time' => '1309514400',
'usertimezone' => 'America/Moncton',
'timezone' => 'America/Moncton', //dst offset and timezone offset.
- 'expectedoutput' => 'Friday, 1 July 2011, 07:00 AM'
+ 'expectedoutput' => 'Friday, 1 July 2011, 7:00 AM'
),
array(
'time' => '1293876000 ',
'time' => '1293876000 ',
'usertimezone' => 'America/Moncton',
'timezone' => '99', //no dst offset in jan, so just timezone offset.
- 'expectedoutput' => 'Saturday, 1 January 2011, 06:00 AM'
+ 'expectedoutput' => 'Saturday, 1 January 2011, 6:00 AM'
),
array(
'time' => '1293876000 ',
'usertimezone' => 'America/Moncton',
'timezone' => 'America/Moncton', //no dst offset in jan
- 'expectedoutput' => 'Saturday, 1 January 2011, 06:00 AM'
+ 'expectedoutput' => 'Saturday, 1 January 2011, 6:00 AM'
),
array(
'time' => '1293876000 ',
'time' => '1293876000 ',
'usertimezone' => '-2',
'timezone' => '99', //take user timezone
- 'expectedoutput' => 'Saturday, 1 January 2011, 08:00 AM'
+ 'expectedoutput' => 'Saturday, 1 January 2011, 8:00 AM'
),
array(
'time' => '1293876000 ',
'time' => '1293876000 ',
'usertimezone' => '-10',
'timezone' => '-2', //take this timezone
- 'expectedoutput' => 'Saturday, 1 January 2011, 08:00 AM'
+ 'expectedoutput' => 'Saturday, 1 January 2011, 8:00 AM'
),
array(
'time' => '1293876000 ',
'usertimezone' => '-10',
'timezone' => 'random/time', //this should show server time
- 'expectedoutput' => 'Saturday, 1 January 2011, 06:00 PM'
+ 'expectedoutput' => 'Saturday, 1 January 2011, 6:00 PM'
),
array(
'time' => '1293876000 ',
'usertimezone' => '14', //server time zone
'timezone' => '99', //this should show user time
- 'expectedoutput' => 'Saturday, 1 January 2011, 06:00 PM'
+ 'expectedoutput' => 'Saturday, 1 January 2011, 6:00 PM'
),
);
$PAGE->navigation->extend_for_user($USER);
$PAGE->set_pagelayout('course');
+// Disable message notification popups while the user is viewing their messages
+$PAGE->set_popup_notification_allowed(false);
+
$context = get_context_instance(CONTEXT_SYSTEM);
$user1 = null;
} else {
if (isloggedin()) {
if ($submission = $this->get_submission($USER->id)) {
- if ($submission->timemodified) {
+ // If the submission has been completed
+ if ($this->is_submitted_with_required_data($submission)) {
if ($submission->timemodified <= $this->assignment->timedue || empty($this->assignment->timedue)) {
$submitted = '<span class="early">'.userdate($submission->timemodified).'</span>';
} else {
return $DB->get_record('assignment_submissions', array('assignment'=>$this->assignment->id, 'userid'=>$userid));
}
+ /**
+ * Check the given submission is complete. Preliminary rows are often created in the assignment_submissions
+ * table before a submission actually takes place. This function checks to see if the given submission has actually
+ * been submitted.
+ *
+ * @param stdClass $submission The submission we want to check for completion
+ * @return bool Indicates if the submission was found to be complete
+ */
+ public function is_submitted_with_required_data($submission) {
+ return $submission->timemodified;
+ }
+
/**
* Instantiates a new submission object for a given user
*
send_temp_file($zipfile, $filename); //send file and delete after sending.
}
}
+
+ /**
+ * Check the given submission is complete. Preliminary rows are often created in the assignment_submissions
+ * table before a submission actually takes place. This function checks to see if the given submission has actually
+ * been submitted.
+ *
+ * @param stdClass $submission The submission we want to check for completion
+ * @return bool Indicates if the submission was found to be complete
+ */
+ public function is_submitted_with_required_data($submission) {
+ return ($submission->timemodified AND $submission->data2);
+ }
}
class mod_assignment_upload_notes_form extends moodleform {
send_temp_file($zipfile, $filename); //send file and delete after sending.
}
}
+
+ /**
+ * Check the given submission is complete. Preliminary rows are often created in the assignment_submissions
+ * table before a submission actually takes place. This function checks to see if the given submission has actually
+ * been submitted.
+ *
+ * @param stdClass $submission The submission we want to check for completion
+ * @return bool Indicates if the submission was found to be complete
+ */
+ public function is_submitted_with_required_data($submission) {
+ return ($submission->timemodified AND $submission->numfiles > 0);
+ }
}
class mod_assignment_uploadsingle_response_form extends moodleform {
<?php
- // This file adds support to rss feeds generation
- // This function is the main entry point to database module
- // rss feeds generation.
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * This file contains all the common stuff to be used for RSS in the Database Module
+ *
+ * @package mod_data
+ * @category rss
+ * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com}
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Generates the Database modules RSS Feed
+ *
+ * @param strClass $context the context the feed should be created under
+ * @param array $args array of arguments to be used in the creation of the RSS Feed
+ * @return NULL|string NULL if there is nothing to return, or the file path of the cached file if there is
+ */
function data_rss_get_feed($context, $args) {
global $CFG, $DB;
if (!$records = $DB->get_records_sql($sql, array(), 0, $data->rssarticles)) {
return null;
}
-
+
$firstrecord = array_shift($records); // Get the first and put it back
array_unshift($records, $firstrecord);
return $cachedfilepath;
}
-
+/**
+ * Creates and returns a SQL query for the items that would be included in the RSS Feed
+ *
+ * @param stdClass $data database instance object
+ * @param int $time epoch timestamp to compare time-modified to, 0 for all or a proper value
+ * @return string SQL query string to get the items for the databse RSS Feed
+ */
function data_rss_get_sql($data, $time=0) {
//do we only want new posts?
if ($time) {
* If there is new stuff in since $time this returns true
* Otherwise it returns false.
*
- * @param object $data the data activity object
- * @param int $time timestamp
- * @return bool
+ * @param stdClass $data the data activity object
+ * @param int $time timestamp
+ * @return bool true if there is new stuff for the RSS Feed
*/
function data_rss_newstuff($data, $time) {
global $DB;
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
/**
-* This file adds support to rss feeds generation
-*
-* @package mod-forum
-* @copyright 2001 Eloy Lafuente (stronk7) http://contiento.com
-* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
-*/
+ * This file adds support to rss feeds generation
+ *
+ * @package mod_forum
+ * @category rss
+ * @copyright 2001 Eloy Lafuente (stronk7) http://contiento.com
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
/**
* Returns the path to the cached rss feed contents. Creates/updates the cache if necessary.
- * @global object $CFG
- * @global object $DB
- * @param object $context the context
- * @param int $forumid the ID of the forum
- * @param array $args the arguments received in the url
+ * @param stdClass $context the context
+ * @param array $args the arguments received in the url
* @return string the full path to the cached RSS feed directory. Null if there is a problem.
*/
function forum_rss_get_feed($context, $args) {
/**
* Given a forum object, deletes all cached RSS files associated with it.
*
- * @param object $forum
- * @return void
+ * @param stdClass $forum
*/
function forum_rss_delete_file($forum) {
rss_delete_file('mod_forum', $forum);
* If there is new stuff in the forum since $time this returns true
* Otherwise it returns false.
*
- * @param object $forum the forum object
- * @param object $cm
- * @param int $time timestamp
- * @return bool
+ * @param stdClass $forum the forum object
+ * @param stdClass $cm Course Module object
+ * @param int $time check for items since this epoch timestamp
+ * @return bool True for new items
*/
function forum_rss_newstuff($forum, $cm, $time) {
global $DB;
return ($recs && !empty($recs));
}
+/**
+ * Determines which type of SQL query is required, one for posts or one for discussions, and returns the appropriate query
+ *
+ * @param stdClass $forum the forum object
+ * @param stdClass $cm Course Module object
+ * @param int $time check for items since this epoch timestamp
+ * @return string the SQL query to be used to get the Discussion/Post details from the forum table of the database
+ */
function forum_rss_get_sql($forum, $cm, $time=0) {
$sql = null;
return $sql;
}
+/**
+ * Generates the SQL query used to get the Discussion details from the forum table of the database
+ *
+ * @param stdClass $forum the forum object
+ * @param stdClass $cm Course Module object
+ * @param int $newsince check for items since this epoch timestamp
+ * @return string the SQL query to be used to get the Discussion details from the forum table of the database
+ */
function forum_rss_feed_discussions_sql($forum, $cm, $newsince=0) {
global $CFG, $DB, $USER;
return $sql;
}
+/**
+ * Generates the SQL query used to get the Post details from the forum table of the database
+ *
+ * @param stdClass $forum the forum object
+ * @param stdClass $cm Course Module object
+ * @param int $newsince check for items since this epoch timestamp
+ * @return string the SQL query to be used to get the Post details from the forum table of the database
+ */
function forum_rss_feed_posts_sql($forum, $cm, $newsince=0) {
$modcontext = get_context_instance(CONTEXT_MODULE, $cm->id);
return $sql;
}
+/**
+ * Retrieve the correct SQL snippet for group-only forums
+ *
+ * @param stdClass $cm Course Module object
+ * @param int $groupmode the mode in which the forum's groups are operating
+ * @param bool $currentgroup true if the user is from the a group enabled on the forum
+ * @param stdClass $modcontext The context instance of the forum module
+ * @return string SQL Query for group details of the forum
+ */
function forum_rss_get_group_sql($cm, $groupmode, $currentgroup, $modcontext=null) {
$groupselect = '';
return $groupselect;
}
-
-
-
/**
* This function return the XML rss contents about the forum
* It returns false if something is wrong
*
- * @param object $forum
- * @param bool
+ * @param stdClass $forum the forum object
+ * @param string $sql The SQL used to retrieve the contents from the database
+ * @return bool|string false if the contents is empty, otherwise the contents of the feed is returned
+ *
+ * @Todo MDL-31129 implement post attachment handling
*/
function forum_rss_feed_contents($forum, $sql) {
global $CFG, $DB;
$formatoptions->trusted = $rec->posttrust;
$item->description = format_text($rec->postmessage,$rec->postformat,$formatoptions,$forum->course);
- //TODO: implement post attachment handling
+ //TODO: MDL-31129 implement post attachment handling
/*if (!$isdiscussion) {
$post_file_area_name = str_replace('//', '/', "$forum->course/$CFG->moddata/forum/$forum->id/$rec->postid");
$post_files = get_directory_list("$CFG->dataroot/$post_file_area_name");
<?xml version="1.0" encoding="UTF-8" ?>
-<XMLDB PATH="mod/glossary/db" VERSION="20101115" COMMENT="XMLDB file for Moodle mod/glossary"
+<XMLDB PATH="mod/glossary/db" VERSION="20120104" COMMENT="XMLDB file for Moodle mod/glossary"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<FIELD NAME="allowcomments" TYPE="int" LENGTH="2" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="showall" NEXT="allowprintview"/>
<FIELD NAME="allowprintview" TYPE="int" LENGTH="2" NOTNULL="true" UNSIGNED="true" DEFAULT="1" SEQUENCE="false" PREVIOUS="allowcomments" NEXT="usedynalink"/>
<FIELD NAME="usedynalink" TYPE="int" LENGTH="2" NOTNULL="true" UNSIGNED="true" DEFAULT="1" SEQUENCE="false" PREVIOUS="allowprintview" NEXT="defaultapproval"/>
- <FIELD NAME="defaultapproval" TYPE="int" LENGTH="2" NOTNULL="true" UNSIGNED="true" DEFAULT="1" SEQUENCE="false" PREVIOUS="usedynalink" NEXT="globalglossary"/>
- <FIELD NAME="globalglossary" TYPE="int" LENGTH="2" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="defaultapproval" NEXT="entbypage"/>
+ <FIELD NAME="defaultapproval" TYPE="int" LENGTH="2" NOTNULL="true" UNSIGNED="true" DEFAULT="1" SEQUENCE="false" PREVIOUS="usedynalink" NEXT="approvaldisplayformat"/>
+ <FIELD NAME="approvaldisplayformat" TYPE="char" LENGTH="50" NOTNULL="true" DEFAULT="default" SEQUENCE="false" COMMENT="Display Format when approving entries" PREVIOUS="defaultapproval" NEXT="globalglossary"/>
+ <FIELD NAME="globalglossary" TYPE="int" LENGTH="2" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="approvaldisplayformat" NEXT="entbypage"/>
<FIELD NAME="entbypage" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="10" SEQUENCE="false" PREVIOUS="globalglossary" NEXT="editalways"/>
<FIELD NAME="editalways" TYPE="int" LENGTH="2" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="entbypage" NEXT="rsstype"/>
<FIELD NAME="rsstype" TYPE="int" LENGTH="2" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="editalways" NEXT="rssarticles"/>
</KEYS>
</TABLE>
</TABLES>
-</XMLDB>
\ No newline at end of file
+</XMLDB>
// Moodle v2.2.0 release upgrade line
// Put any upgrade step following this
+ if ($oldversion < 2012010400) {
+
+ // Define field approvaldisplayformat to be added to glossary
+ $table = new xmldb_table('glossary');
+ $field = new xmldb_field('approvaldisplayformat', XMLDB_TYPE_CHAR, '50', null, XMLDB_NOTNULL, null, 'default', 'defaultapproval');
+
+ // Conditionally launch add field approvaldisplayformat
+ if (!$dbman->field_exists($table, $field)) {
+ $dbman->add_field($table, $field);
+ }
+
+ // Set the default approvaldisplayformat for existing entries to be
+ // the existing displayformat so as not to change existing
+ // functionality
+ $sql = "UPDATE {glossary}
+ SET approvaldisplayformat = 'default'";
+ $DB->execute($sql);
+
+ // glossary savepoint reached
+ upgrade_mod_savepoint(true, 2012010400, 'glossary');
+ }
+
return true;
}
$anchortagcontents = glossary_print_entry_concept($entry, true);
- $link = "/mod/glossary/showentry.php?courseid={$course->id}&eid={$entry->id}&displayformat=dictionary";
- $action = new popup_action('click', $link.'&popup=1', 'entry',array('title'=>'entry','width'=>600,'height'=>450));
-
- $anchor = $OUTPUT->action_link($link, $anchortagcontents, $action);
+ $link = new moodle_url('/mod/glossary/showentry.php', array('courseid' => $course->id,
+ 'eid' => $entry->id, 'displayformat' => 'dictionary'));
+ $anchor = html_writer::link($link, $anchortagcontents);
echo "<div class=\"concept\">$anchor</div> ";
echo '</td><td align="right" class="entrylowersection">';
$string['andmorenewentries'] = 'and {$a} more new entries.';
$string['answer'] = 'Answer';
$string['approve'] = 'Approve';
+$string['approvaldisplayformat'] = 'Approval display format';
+$string['approvaldisplayformat_help'] = 'When approving glossary items you may wish to use a different display format';
$string['areyousuredelete'] = 'Are you sure you want to delete this entry?';
$string['areyousuredeletecomment'] = 'Are you sure you want to delete this comment?';
$string['areyousureexport'] = 'Are you sure you want to export this entry to';
* Entry list - Concepts are listed as links
* FAQ - The words QUESTION and ANSWER are appended to the concept and definition respectively';
$string['displayformatcontinuous'] = 'Continuous without author';
+$string['displayformatdefault'] = 'Default to same as display format';
$string['displayformatdictionary'] = 'Simple, dictionary style';
$string['displayformatencyclopedia'] = 'Encyclopedia';
$string['displayformatentrylist'] = 'Entry list';
$mform->setDefault('displayformat', 'dictionary');
$mform->addHelpButton('displayformat', 'displayformat', 'glossary');
+ $displayformats['default'] = get_string('displayformatdefault', 'glossary');
+ $displayformats = array_merge($displayformats, $formats);
+ $mform->addElement('select', 'approvaldisplayformat', get_string('approvaldisplayformat', 'glossary'), $displayformats);
+ $mform->setDefault('approvaldisplayformat', 'default');
+ $mform->addHelpButton('approvaldisplayformat', 'approvaldisplayformat', 'glossary');
+
$mform->addElement('selectyesno', 'showspecial', get_string('showspecial', 'glossary'));
$mform->setDefault('showspecial', 1);
$mform->addHelpButton('showspecial', 'showspecial', 'glossary');
