Skip to content
Browse files

MDL-31251 documentation : improved core ddl API phpdocs. (used moodle…

…check plugin)
  • Loading branch information...
1 parent 216f6d8 commit 83a4ee1ea031fc4953bf63c0cba4fb9b75586795 @nebgor nebgor committed Jan 27, 2012
View
191 lib/ddl/database_manager.php
@@ -1,5 +1,4 @@
<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
@@ -17,10 +16,10 @@
/**
- * Database manager instance is responsible for all database structure
- * modifications.
+ * Database manager instance is responsible for all database structure modifications.
*
* @package core
+ * @category ddl
* @subpackage ddl
* @copyright 1999 onwards Martin Dougiamas http://dougiamas.com
* 2001-3001 Eloy Lafuente (stronk7) http://contiento.com
@@ -31,18 +30,29 @@
defined('MOODLE_INTERNAL') || die();
/**
- * Database manager instance is responsible for all database structure
- * modifications. It is using db specific generators to find out
- * the correct SQL syntax to do that.
+ * Database manager instance is responsible for all database structure modifications.
+ *
+ * It is using db specific generators to find out the correct SQL syntax to do that.
+ *
+ * @package core
+ * @category ddl
+ * @subpackage ddl
+ * @copyright 1999 onwards Martin Dougiamas http://dougiamas.com
+ * 2001-3001 Eloy Lafuente (stronk7) http://contiento.com
+ * 2008 Petr Skoda http://skodak.org
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class database_manager {
+ /** @var moodle_database A moodle_database driver speific instance.*/
protected $mdb;
- public $generator; // public because XMLDB editor needs to access it
+ /** @var sql_generator A driver specific SQL generator instance. Public because XMLDB editor needs to access it.*/
+ public $generator;
/**
- * Creates new database manager
- * @param object moodle_database instance
+ * Creates a new database manager instance.
+ * @param moodle_database $mdb A moodle_database driver specific instance.
+ * @param sql_generator $generator A driver specific SQL generator instance.
*/
public function __construct($mdb, $generator) {
global $CFG;
@@ -52,7 +62,7 @@ public function __construct($mdb, $generator) {
}
/**
- * Release all resources
+ * Releases all resources
*/
public function dispose() {
if ($this->generator) {
@@ -65,10 +75,8 @@ public function dispose() {
/**
* This function will execute an array of SQL commands.
*
- * @exception ddl_exception if error found
- *
- * @param array $sqlarr array of sql statements to execute
- * @return void
+ * @param array $sqlarr Array of sql statements to execute.
+ * @throws ddl_exception This exception is thrown if any error is found.
*/
protected function execute_sql_arr(array $sqlarr) {
foreach ($sqlarr as $sql) {
@@ -77,12 +85,10 @@ protected function execute_sql_arr(array $sqlarr) {
}
/**
- * Execute a given sql command string
- *
- * @exception ddl_exception if error found
+ * Execute a given sql command string.
*
- * @param string $command The sql string you wish to be executed.
- * @return void
+ * @param string $sql The sql string you wish to be executed.
+ * @throws ddl_exception This exception is thrown if any error is found.
*/
protected function execute_sql($sql) {
if (!$this->mdb->change_database_structure($sql)) {
@@ -92,10 +98,10 @@ protected function execute_sql($sql) {
}
/**
- * Given one xmldb_table, check if it exists in DB (true/false)
+ * Given one xmldb_table, check if it exists in DB (true/false).
*
- * @param mixed the table to be searched (string name or xmldb_table instance)
- * @return boolean true/false
+ * @param mixed $table The table to be searched (string name or xmldb_table instance).
+ * @return bool true/false True is a table exists, false otherwise.
*/
public function table_exists($table) {
if (!is_string($table) and !($table instanceof xmldb_table)) {
@@ -106,8 +112,8 @@ public function table_exists($table) {
/**
* Reset a sequence to the id field of a table.
- * @param string $table name of table
- * @return success
+ * @param string $table Name of table.
+ * @throws ddl_exception|ddl_table_missing_exception Exception thrown upon reset errors.
*/
public function reset_sequence($table) {
if (!is_string($table) and !($table instanceof xmldb_table)) {
@@ -127,11 +133,12 @@ public function reset_sequence($table) {
}
/**
- * Given one xmldb_field, check if it exists in DB (true/false)
+ * Given one xmldb_field, check if it exists in DB (true/false).
*
- * @param mixed the table to be searched (string name or xmldb_table instance)
- * @param mixed the field to be searched for (string name or xmldb_field instance)
- * @return boolean true/false
+ * @param mixed $table The table to be searched (string name or xmldb_table instance).
+ * @param mixed $field The field to be searched for (string name or xmldb_field instance).
+ * @return boolean true is exists false otherwise.
+ * @throws ddl_table_missing_exception
*/
public function field_exists($table, $field) {
/// Calculate the name of the table
@@ -165,9 +172,10 @@ public function field_exists($table, $field) {
* Given one xmldb_index, the function returns the name of the index in DB
* of false if it doesn't exist
*
- * @param object $xmldb_table table to be searched
- * @param object $xmldb_index the index to be searched
- * @return string index name of false
+ * @param xmldb_table $xmldb_table table to be searched
+ * @param xmldb_index $xmldb_index the index to be searched
+ * @return string|bool Index name or false if no indexes are found.
+ * @throws ddl_table_missing_exception Thrown when table is not found.
*/
public function find_index_name(xmldb_table $xmldb_table, xmldb_index $xmldb_index) {
/// Calculate the name of the table
@@ -200,11 +208,11 @@ public function find_index_name(xmldb_table $xmldb_table, xmldb_index $xmldb_ind
}
/**
- * Given one xmldb_index, check if it exists in DB (true/false)
+ * Given one xmldb_index, check if it exists in DB (true/false).
*
- * @param object $xmldb_table the table to be searched
- * @param object $xmldb_index the index to be searched for
- * @return boolean true/false
+ * @param xmldb_table $xmldb_table The table to be searched.
+ * @param xmldb_index $xmldb_index The index to be searched for.
+ * @return boolean true id index exists, false otherwise.
*/
public function index_exists(xmldb_table $xmldb_table, xmldb_index $xmldb_index) {
if (!$this->table_exists($xmldb_table)) {
@@ -219,11 +227,11 @@ public function index_exists(xmldb_table $xmldb_table, xmldb_index $xmldb_index)
* to 1 "enum-like" constraint. So, if more than one is returned, only the first one will be
* retrieved by this function.
*
- * TODO: Moodle 2.1 - Drop find_check_constraint_name()
+ * @todo MDL-31147 Moodle 2.1 - Drop find_check_constraint_name()
*
- * @param xmldb_table the table to be searched
- * @param xmldb_field the field to be searched
- * @return string check constraint name or false
+ * @param xmldb_table $xmldb_table The table to be searched.
+ * @param xmldb_field $xmldb_field The field to be searched.
+ * @return string|bool check constraint name or false
*/
public function find_check_constraint_name(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -256,8 +264,8 @@ public function find_check_constraint_name(xmldb_table $xmldb_table, xmldb_field
*
* TODO: Moodle 2.1 - Drop check_constraint_exists()
*
- * @param xmldb_table the table
- * @param xmldb_field the field to be searched for any existing constraint
+ * @param xmldb_table $xmldb_table The table.
+ * @param xmldb_field $xmldb_field The field to be searched for any existing constraint.
* @return boolean true/false
*/
public function check_constraint_exists(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -271,9 +279,9 @@ public function check_constraint_exists(xmldb_table $xmldb_table, xmldb_field $x
* Given one xmldb_key, the function returns the name of the key in DB (if exists)
* of false if it doesn't exist
*
- * @param xmldb_table the table to be searched
- * @param xmldb_key the key to be searched
- * @return string key name of false
+ * @param xmldb_table $xmldb_table The table to be searched.
+ * @param xmldb_key $xmldb_key The key to be searched.
+ * @return string key name if found
*/
public function find_key_name(xmldb_table $xmldb_table, xmldb_key $xmldb_key) {
@@ -316,7 +324,7 @@ public function find_key_name(xmldb_table $xmldb_table, xmldb_key $xmldb_key) {
/**
* This function will delete all tables found in XMLDB file from db
*
- * @param $file full path to the XML file to be used
+ * @param string $file Full path to the XML file to be used.
* @return void
*/
public function delete_tables_from_xmldb_file($file) {
@@ -354,7 +362,7 @@ public function delete_tables_from_xmldb_file($file) {
* and all the associated objects (keys, indexes, constraints, sequences, triggers)
* will be dropped too.
*
- * @param xmldb_table table object (just the name is mandatory)
+ * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
* @return void
*/
public function drop_table(xmldb_table $xmldb_table) {
@@ -399,7 +407,7 @@ private function load_xmldb_file($file) {
/**
* This function will load one entire XMLDB file and call install_from_xmldb_structure.
*
- * @param $file full path to the XML file to be used
+ * @param string $file full path to the XML file to be used
* @return void
*/
public function install_from_xmldb_file($file) {
@@ -411,8 +419,8 @@ public function install_from_xmldb_file($file) {
/**
* This function will load one entire XMLDB file and call install_from_xmldb_structure.
*
- * @param $file full path to the XML file to be used
- * @param $tablename the name of the table.
+ * @param string $file full path to the XML file to be used
+ * @param string $tablename the name of the table.
* @param bool $cachestructures boolean to decide if loaded xmldb structures can be safely cached
* useful for testunits loading the enormous main xml file hundred of times (100x)
*/
@@ -445,7 +453,7 @@ public function install_one_table_from_xmldb_file($file, $tablename, $cachestruc
* This function will generate all the needed SQL statements, specific for each
* RDBMS type and, finally, it will execute all those statements against the DB.
*
- * @param object $structure xmldb_structure object
+ * @param stdClass $xmldb_structure xmldb_structure object.
* @return void
*/
public function install_from_xmldb_structure($xmldb_structure) {
@@ -460,7 +468,7 @@ public function install_from_xmldb_structure($xmldb_structure) {
* This function will create the table passed as argument with all its
* fields/keys/indexes/sequences, everything based in the XMLDB object
*
- * @param xmldb_table table object (full specs are required)
+ * @param xmldb_table $xmldb_table Table object (full specs are required).
* @return void
*/
public function create_table(xmldb_table $xmldb_table) {
@@ -482,7 +490,7 @@ public function create_table(xmldb_table $xmldb_table) {
* If table already exists ddl_exception will be thrown, please make sure
* the table name does not collide with existing normal table!
*
- * @param xmldb_table table object (full specs are required)
+ * @param xmldb_table $xmldb_table Table object (full specs are required).
* @return void
*/
public function create_temp_table(xmldb_table $xmldb_table) {
@@ -505,7 +513,7 @@ public function create_temp_table(xmldb_table $xmldb_table) {
*
* It is recommended to drop temp table when not used anymore.
*
- * @param xmldb_table table object
+ * @param xmldb_table $xmldb_table Table object.
* @return void
*/
public function drop_temp_table(xmldb_table $xmldb_table) {
@@ -526,8 +534,8 @@ public function drop_temp_table(xmldb_table $xmldb_table) {
* This function will rename the table passed as argument
* Before renaming the index, the function will check it exists
*
- * @param xmldb_table table object (just the name is mandatory)
- * @param string new name of the index
+ * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+ * @param string $newname New name of the index.
* @return void
*/
public function rename_table(xmldb_table $xmldb_table, $newname) {
@@ -563,8 +571,8 @@ public function rename_table(xmldb_table $xmldb_table, $newname) {
/**
* This function will add the field to the table passed as arguments
*
- * @param xmldb_table table object (just the name is mandatory)
- * @param xmldb_field field object (full specs are required)
+ * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+ * @param xmldb_field $xmldb_field Index object (full specs are required).
* @return void
*/
public function add_field(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -589,8 +597,8 @@ public function add_field(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
/**
* This function will drop the field from the table passed as arguments
*
- * @param xmldb_table table object (just the name is mandatory)
- * @param xmldb_field field object (just the name is mandatory)
+ * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+ * @param xmldb_field $xmldb_field Index object (full specs are required).
* @return void
*/
public function drop_field(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -614,8 +622,8 @@ public function drop_field(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
/**
* This function will change the type of the field in the table passed as arguments
*
- * @param xmldb_table table object (just the name is mandatory)
- * @param xmldb_field field object (full specs are required)
+ * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+ * @param xmldb_field $xmldb_field Index object (full specs are required).
* @return void
*/
public function change_field_type(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -639,8 +647,8 @@ public function change_field_type(xmldb_table $xmldb_table, xmldb_field $xmldb_f
/**
* This function will change the precision of the field in the table passed as arguments
*
- * @param xmldb_table table object (just the name is mandatory)
- * @param xmldb_field field object (full specs are required)
+ * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+ * @param xmldb_field $xmldb_field Index object (full specs are required).
* @return void
*/
public function change_field_precision(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -651,8 +659,8 @@ public function change_field_precision(xmldb_table $xmldb_table, xmldb_field $xm
/**
* This function will change the unsigned/signed of the field in the table passed as arguments
*
- * @param xmldb_table table object (just the name is mandatory)
- * @param xmldb_field field object (full specs are required)
+ * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+ * @param xmldb_field $xmldb_field Index object (full specs are required).
* @return void
*/
public function change_field_unsigned(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -663,8 +671,8 @@ public function change_field_unsigned(xmldb_table $xmldb_table, xmldb_field $xml
/**
* This function will change the nullability of the field in the table passed as arguments
*
- * @param xmldb_table table object (just the name is mandatory)
- * @param xmldb_field field object (full specs are required)
+ * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+ * @param xmldb_field $xmldb_field Index object (full specs are required).
* @return void
*/
public function change_field_notnull(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -676,8 +684,8 @@ public function change_field_notnull(xmldb_table $xmldb_table, xmldb_field $xmld
* This function will change the default of the field in the table passed as arguments
* One null value in the default field means delete the default
*
- * @param xmldb_table table object (just the name is mandatory)
- * @param xmldb_field field object (full specs are required)
+ * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+ * @param xmldb_field $xmldb_field Index object (full specs are required).
* @return void
*/
public function change_field_default(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -703,8 +711,8 @@ public function change_field_default(xmldb_table $xmldb_table, xmldb_field $xmld
*
* TODO: Moodle 2.1 - Drop drop_enum_from_field()
*
- * @param xmldb_table table object (just the name is mandatory)
- * @param xmldb_field field object (full specs are required)
+ * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+ * @param xmldb_field $xmldb_field Index object (full specs are required).
* @return void
*/
public function drop_enum_from_field(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -733,9 +741,9 @@ public function drop_enum_from_field(xmldb_table $xmldb_table, xmldb_field $xmld
* This function will rename the field in the table passed as arguments
* Before renaming the field, the function will check it exists
*
- * @param xmldb_table table object (just the name is mandatory)
- * @param xmldb_field index object (full specs are required)
- * @param string new name of the field
+ * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+ * @param xmldb_field $xmldb_field Index object (full specs are required).
+ * @param string $newname New name of the field.
* @return void
*/
public function rename_field(xmldb_table $xmldb_table, xmldb_field $xmldb_field, $newname) {
@@ -776,7 +784,12 @@ public function rename_field(xmldb_table $xmldb_table, xmldb_field $xmldb_field,
/**
* This function will check, for the given table and field, if there there is any dependency
* preventing the field to be modified. It's used by all the public methods that perform any
- * DDL change on fields, throwing one ddl_dependency_exception if dependencies are found
+ * DDL change on fields, throwing one ddl_dependency_exception if dependencies are found.
+ *
+ * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+ * @param xmldb_field $xmldb_field Index object (full specs are required).
+ * @return void
+ * @throws ddl_dependency_exception|ddl_field_missing_exception|ddl_table_missing_exception if dependency not met.
*/
private function check_field_dependencies(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -805,8 +818,8 @@ private function check_field_dependencies(xmldb_table $xmldb_table, xmldb_field
/**
* This function will create the key in the table passed as arguments
*
- * @param xmldb_table table object (just the name is mandatory)
- * @param xmldb_key index object (full specs are required)
+ * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+ * @param xmldb_key $xmldb_key Index object (full specs are required).
* @return void
*/
public function add_key(xmldb_table $xmldb_table, xmldb_key $xmldb_key) {
@@ -825,8 +838,8 @@ public function add_key(xmldb_table $xmldb_table, xmldb_key $xmldb_key) {
/**
* This function will drop the key in the table passed as arguments
*
- * @param xmldb_table table object (just the name is mandatory)
- * @param xmldb_key key object (full specs are required)
+ * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+ * @param xmldb_key $xmldb_key Key object (full specs are required).
* @return void
*/
public function drop_key(xmldb_table $xmldb_table, xmldb_key $xmldb_key) {
@@ -845,9 +858,9 @@ public function drop_key(xmldb_table $xmldb_table, xmldb_key $xmldb_key) {
* This function will rename the key in the table passed as arguments
* Experimental. Shouldn't be used at all in normal installation/upgrade!
*
- * @param xmldb_table table object (just the name is mandatory)
- * @param xmldb_key key object (full specs are required)
- * @param string new name of the key
+ * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+ * @param xmldb_key $xmldb_key key object (full specs are required).
+ * @param string $newname New name of the key.
* @return void
*/
public function rename_key(xmldb_table $xmldb_table, xmldb_key $xmldb_key, $newname) {
@@ -869,8 +882,8 @@ public function rename_key(xmldb_table $xmldb_table, xmldb_key $xmldb_key, $newn
* This function will create the index in the table passed as arguments
* Before creating the index, the function will check it doesn't exists
*
- * @param xmldb_table table object (just the name is mandatory)
- * @param xmldb_index index object (full specs are required)
+ * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+ * @param xmldb_index $xmldb_intex Index object (full specs are required).
* @return void
*/
public function add_index($xmldb_table, $xmldb_intex) {
@@ -896,8 +909,8 @@ public function add_index($xmldb_table, $xmldb_intex) {
* This function will drop the index in the table passed as arguments
* Before dropping the index, the function will check it exists
*
- * @param xmldb_table table object (just the name is mandatory)
- * @param xmldb_index index object (full specs are required)
+ * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+ * @param xmldb_index $xmldb_intex Index object (full specs are required).
* @return void
*/
public function drop_index($xmldb_table, $xmldb_intex) {
@@ -924,9 +937,9 @@ public function drop_index($xmldb_table, $xmldb_intex) {
* Before renaming the index, the function will check it exists
* Experimental. Shouldn't be used at all!
*
- * @param xmldb_table table object (just the name is mandatory)
- * @param xmldb_index index object (full specs are required)
- * @param string new name of the index
+ * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+ * @param xmldb_index $xmldb_intex Index object (full specs are required).
+ * @param string $newname New name of the index.
* @return void
*/
public function rename_index($xmldb_table, $xmldb_intex, $newname) {
View
2 lib/ddl/mssql_sql_generator.php
@@ -20,7 +20,7 @@
* MSSQL specific SQL code generator.
*
* @package core
- * @subpackage ddl
+ * @subpackage ddl_generator
* @copyright 1999 onwards Martin Dougiamas http://dougiamas.com
* 2001-3001 Eloy Lafuente (stronk7) http://contiento.com
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
View
2 lib/ddl/mysql_sql_generator.php
@@ -20,7 +20,7 @@
* Mysql specific SQL code generator.
*
* @package core
- * @subpackage ddl
+ * @subpackage ddl_generator
* @copyright 1999 onwards Martin Dougiamas http://dougiamas.com
* 2001-3001 Eloy Lafuente (stronk7) http://contiento.com
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
View
2 lib/ddl/oracle_sql_generator.php
@@ -20,7 +20,7 @@
* Oracle specific SQL code generator.
*
* @package core
- * @subpackage ddl
+ * @subpackage ddl_generator
* @copyright 1999 onwards Martin Dougiamas http://dougiamas.com
* 2001-3001 Eloy Lafuente (stronk7) http://contiento.com
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
View
2 lib/ddl/postgres_sql_generator.php
@@ -20,7 +20,7 @@
* PostgreSQL specific SQL code generator.
*
* @package core
- * @subpackage ddl
+ * @subpackage ddl_generator
* @copyright 1999 onwards Martin Dougiamas http://dougiamas.com
* 2001-3001 Eloy Lafuente (stronk7) http://contiento.com
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
View
449 lib/ddl/sql_generator.php
@@ -1,5 +1,4 @@
<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
@@ -17,13 +16,13 @@
/**
- * This class represent the base generator class where all the
- * needed functions to generate proper SQL are defined.
+ * This class represent the base generator class where all the needed functions to generate proper SQL are defined.
*
* The rest of classes will inherit, by default, the same logic.
* Functions will be overridden as needed to generate correct SQL.
*
* @package core
+ * @category ddl
* @subpackage ddl
* @copyright 1999 onwards Martin Dougiamas http://dougiamas.com
* 2001-3001 Eloy Lafuente (stronk7) http://contiento.com
@@ -34,6 +33,13 @@
/**
* Abstract sql generator class, base for all db specific implementations.
+ *
+ * @package core
+ * @category ddl
+ * @subpackage ddl
+ * @copyright 1999 onwards Martin Dougiamas http://dougiamas.com
+ * 2001-3001 Eloy Lafuente (stronk7) http://contiento.com
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
abstract class sql_generator {
@@ -42,96 +48,146 @@
/// that, by default, inherit this configuration.
/// To change any of them, do it in extended classes instead.
- public $quote_string = '"'; // String used to quote names
+ /** @var string Used to quote names. */
+ public $quote_string = '"';
- public $statement_end = ';'; // String to be automatically added at the end of each statement
+ /** @var string To be automatically added at the end of each statement. */
+ public $statement_end = ';';
- public $quote_all = false; // To decide if we want to quote all the names or only the reserved ones
+ /** @var bool To decide if we want to quote all the names or only the reserved ones. */
+ public $quote_all = false;
- public $integer_to_number = false; // To create all the integers as NUMBER(x) (also called DECIMAL, NUMERIC...)
- public $float_to_number = false; // To create all the floats as NUMBER(x) (also called DECIMAL, NUMERIC...)
+ /** @var bool To create all the integers as NUMBER(x) (also called DECIMAL, NUMERIC...). */
+ public $integer_to_number = false;
+ /** @var bool To create all the floats as NUMBER(x) (also called DECIMAL, NUMERIC...). */
+ public $float_to_number = false;
- public $number_type = 'NUMERIC'; // Proper type for NUMBER(x) in this DB
+ /** @var string Proper type for NUMBER(x) in this DB. */
+ public $number_type = 'NUMERIC';
- public $unsigned_allowed = true; // To define in the generator must handle unsigned information
- public $default_for_char = null; // To define the default to set for NOT NULLs CHARs without default (null=do nothing)
+ /** @var bool To define in the generator must handle unsigned information.*/
+ public $unsigned_allowed = true;
+ /** @var string To define the default to set for NOT NULLs CHARs without default (null=do nothing).*/
+ public $default_for_char = null;
- public $drop_default_value_required = false; //To specify if the generator must use some DEFAULT clause to drop defaults
- public $drop_default_value = ''; //The DEFAULT clause required to drop defaults
+ /** @var bool To specify if the generator must use some DEFAULT clause to drop defaults.*/
+ public $drop_default_value_required = false;
+ /** @var string The DEFAULT clause required to drop defaults.*/
+ public $drop_default_value = '';
- public $default_after_null = true; //To decide if the default clause of each field must go after the null clause
+ /** @var bool To decide if the default clause of each field must go after the null clause.*/
+ public $default_after_null = true;
- public $specify_nulls = false; //To force the generator if NULL clauses must be specified. It shouldn't be necessary
- //but some mssql drivers require them or everything is created as NOT NULL :-(
-
- public $primary_key_name = null; //To force primary key names to one string (null=no force)
+ /**
+ * @var bool To force the generator if NULL clauses must be specified. It shouldn't be necessary.
+ * note: some mssql drivers require them or everything is created as NOT NULL :-(
+ */
+ public $specify_nulls = false;
- public $primary_keys = true; // Does the generator build primary keys
- public $unique_keys = false; // Does the generator build unique keys
- public $foreign_keys = false; // Does the generator build foreign keys
+ /** @var string To force primary key names to one string (null=no force).*/
+ public $primary_key_name = null;
- public $drop_primary_key = 'ALTER TABLE TABLENAME DROP CONSTRAINT KEYNAME'; // Template to drop PKs
- // with automatic replace for TABLENAME and KEYNAME
+ /** @var bool True if the generator builds primary keys.*/
+ public $primary_keys = true;
+ /** @var bool True if the generator builds unique keys.*/
+ public $unique_keys = false;
+ /** @var bool True if the generator builds foreign keys.*/
+ public $foreign_keys = false;
- public $drop_unique_key = 'ALTER TABLE TABLENAME DROP CONSTRAINT KEYNAME'; // Template to drop UKs
- // with automatic replace for TABLENAME and KEYNAME
+ /**
+ * @var string Template to drop PKs.
+ * 'TABLENAME' and 'KEYNAME' will be replaced from this template.
+ */
+ public $drop_primary_key = 'ALTER TABLE TABLENAME DROP CONSTRAINT KEYNAME';
- public $drop_foreign_key = 'ALTER TABLE TABLENAME DROP CONSTRAINT KEYNAME'; // Template to drop FKs
- // with automatic replace for TABLENAME and KEYNAME
+ /**
+ * @var string Template to drop UKs.
+ * 'TABLENAME' and 'KEYNAME' will be replaced from this template.
+ */
+ public $drop_unique_key = 'ALTER TABLE TABLENAME DROP CONSTRAINT KEYNAME';
- public $sequence_extra_code = true; //Does the generator need to add extra code to generate the sequence fields
- public $sequence_name = 'auto_increment'; //Particular name for inline sequences in this generator
- public $sequence_name_small = false; //Different name for small (4byte) sequences or false if same
- public $sequence_only = false; //To avoid to output the rest of the field specs, leaving only the name and the sequence_name publiciable
+ /** @var string Template to drop FKs.
+ * 'TABLENAME' and 'KEYNAME' will be replaced from this template.
+ */
+ public $drop_foreign_key = 'ALTER TABLE TABLENAME DROP CONSTRAINT KEYNAME';
+
+ /** @var bool True if the generator needs to add extra code to generate the sequence fields.*/
+ public $sequence_extra_code = true;
+ /** @var string The particular name for inline sequences in this generator.*/
+ public $sequence_name = 'auto_increment';
+ /** @var string|bool Different name for small (4byte) sequences or false if same.*/
+ public $sequence_name_small = false;
+ /**
+ * @var bool To avoid outputting the rest of the field specs, leaving only the name and the sequence_name returned.
+ * @see getFieldSQL()
+ */
+ public $sequence_only = false;
- public $add_table_comments = true; // Does the generator need to add code for table comments
+ /** @var bool True if the generator needs to add code for table comments.*/
+ public $add_table_comments = true;
- public $add_after_clause = false; // Does the generator need to add the after clause for fields
+ /** @var bool True if the generator needs to add the after clause for fields.*/
+ public $add_after_clause = false;
- public $prefix_on_names = true; //Does the generator need to prepend the prefix to all the key/index/sequence/trigger/check names
+ /**
+ * @var bool True if the generator needs to prepend the prefix to all the key/index/sequence/trigger/check names.
+ * @see $prefix
+ */
+ public $prefix_on_names = true;
- public $names_max_length = 30; //Max length for key/index/sequence/trigger/check names (keep 30 for all!)
+ /** @var int Maximum length for key/index/sequence/trigger/check names (keep 30 for all!).*/
+ public $names_max_length = 30;
- public $concat_character = '||'; //Characters to be used as concatenation operator. If not defined
- //MySQL CONCAT function will be used
+ /** @var string Characters to be used as concatenation operator.
+ * If not defined, MySQL CONCAT function will be used.
+ */
+ public $concat_character = '||';
- public $rename_table_sql = 'ALTER TABLE OLDNAME RENAME TO NEWNAME'; //SQL sentence to rename one table, both
- //OLDNAME and NEWNAME are dynamically replaced
+ /** @var string SQL sentence to rename one table, both 'OLDNAME' and 'NEWNAME' keywords are dynamically replaced.*/
+ public $rename_table_sql = 'ALTER TABLE OLDNAME RENAME TO NEWNAME';
- public $drop_table_sql = 'DROP TABLE TABLENAME'; //SQL sentence to drop one table
- //TABLENAME is dynamically replaced
+ /** @var string SQL sentence to drop one table where the 'TABLENAME' keyword is dynamically replaced.*/
+ public $drop_table_sql = 'DROP TABLE TABLENAME';
- public $alter_column_sql = 'ALTER TABLE TABLENAME ALTER COLUMN COLUMNSPECS'; //The SQL template to alter columns
+ /** @var string The SQL template to alter columns where the 'TABLENAME' and 'COLUMNSPECS' keywords are dynamically replaced.*/
+ public $alter_column_sql = 'ALTER TABLE TABLENAME ALTER COLUMN COLUMNSPECS';
- public $alter_column_skip_default = false; //The generator will skip the default clause on alter columns
+ /** @var bool The generator will skip the default clause on alter columns.*/
+ public $alter_column_skip_default = false;
- public $alter_column_skip_type = false; //The generator will skip the type clause on alter columns
+ /** @var bool The generator will skip the type clause on alter columns.*/
+ public $alter_column_skip_type = false;
- public $alter_column_skip_notnull = false; //The generator will skip the null/notnull clause on alter columns
+ /** @var bool The generator will skip the null/notnull clause on alter columns.*/
+ public $alter_column_skip_notnull = false;
+ /** @var string SQL sentence to rename one column where 'TABLENAME', 'OLDFIELDNAME' and 'NEWFIELDNAME' keywords are dynamically replaced.*/
public $rename_column_sql = 'ALTER TABLE TABLENAME RENAME COLUMN OLDFIELDNAME TO NEWFIELDNAME';
- ///TABLENAME, OLDFIELDNAME and NEWFIELDNAME are dyanmically replaced
- public $drop_index_sql = 'DROP INDEX INDEXNAME'; //SQL sentence to drop one index
- //TABLENAME, INDEXNAME are dynamically replaced
+ /** @var string SQL sentence to drop one index where 'TABLENAME', 'INDEXNAME' keywords are dynamically replaced.*/
+ public $drop_index_sql = 'DROP INDEX INDEXNAME';
- public $rename_index_sql = 'ALTER INDEX OLDINDEXNAME RENAME TO NEWINDEXNAME'; //SQL sentence to rename one index
- //TABLENAME, OLDINDEXNAME, NEWINDEXNAME are dynamically replaced
+ /** @var string SQL sentence to rename one index where 'TABLENAME', 'OLDINDEXNAME' and 'NEWINDEXNAME' are dynamically replaced.*/
+ public $rename_index_sql = 'ALTER INDEX OLDINDEXNAME RENAME TO NEWINDEXNAME';
- public $rename_key_sql = 'ALTER TABLE TABLENAME CONSTRAINT OLDKEYNAME RENAME TO NEWKEYNAME'; //SQL sentence to rename one key
- //TABLENAME, OLDKEYNAME, NEWKEYNAME are dynamically replaced
+ /** @var string SQL sentence to rename one key 'TABLENAME', 'OLDKEYNAME' and 'NEWKEYNAME' are dynamically replaced.*/
+ public $rename_key_sql = 'ALTER TABLE TABLENAME CONSTRAINT OLDKEYNAME RENAME TO NEWKEYNAME';
- public $prefix; // Prefix to be used for all the DB objects
+ /** @var string The prefix to be used for all the DB objects.*/
+ public $prefix;
- public $reserved_words; // List of reserved words (in order to quote them properly)
+ /** @var string List of reserved words (in order to quote them properly).*/
+ public $reserved_words;
+ /** @var moodle_database The moodle_database instance.*/
public $mdb;
-
- protected $temptables; // Control existing temptables
+ /** @var Control existing temptables.*/
+ protected $temptables;
/**
- * Creates new sql_generator
- * @param object moodle_database instance
+ * Creates a new sql_generator.
+ * @param moodle_database $mdb The moodle_database object instance.
+ * @param moodle_temptables $temptables The optional moodle_temptables instance, null by default.
*/
public function __construct($mdb, $temptables = null) {
$this->prefix = $mdb->get_prefix();
@@ -141,14 +197,18 @@ public function __construct($mdb, $temptables = null) {
}
/**
- * Release all resources
+ * Releases all resources.
*/
public function dispose() {
$this->mdb = null;
}
/**
- * Given one string (or one array), ends it with statement_end
+ * Given one string (or one array), ends it with $statement_end .
+ *
+ * @see $statement_end
+ *
+ * @param array|string $input SQL statement(s).
*/
public function getEndedStatements($input) {
@@ -164,9 +224,9 @@ public function getEndedStatements($input) {
}
/**
- * Given one xmldb_table, check if it exists in DB (true/false)
+ * Given one xmldb_table, checks if it exists in DB (true/false).
*
- * @param mixed the table to be searched (string name or xmldb_table instance)
+ * @param mixed $table The table to be searched (string name or xmldb_table instance).
* @return boolean true/false
*/
public function table_exists($table) {
@@ -185,7 +245,11 @@ public function table_exists($table) {
}
/**
- * This function will return the SQL code needed to create db tables and statements
+ * This function will return the SQL code needed to create db tables and statements.
+ *
+ * @param xmldb_structure $xmldb_structure An xmldb_structure instance.
+ *
+ * @see xmldb_structure
*/
public function getCreateStructureSQL($xmldb_structure) {
$results = array();
@@ -200,11 +264,14 @@ public function getCreateStructureSQL($xmldb_structure) {
}
/**
- * Given one xmldb_table, returns it's correct name, depending of all the parametrization
+ * Given one xmldb_table, this returns it's correct name, depending of all the parameterization.
+ * eg: This appends $prefix to the table name.
+ *
+ * @see $prefix
*
- * @param xmldb_table table whose name we want
- * @param boolean to specify if the name must be quoted (if reserved word, only!)
- * @return string the correct name of the table
+ * @param xmldb_table $xmldb_table The table whose name we want.
+ * @param boolean $quoted To specify if the name must be quoted (if reserved word, only!).
+ * @return string The correct name of the table.
*/
public function getTableName(xmldb_table $xmldb_table, $quoted=true) {
/// Get the name
@@ -220,7 +287,11 @@ public function getTableName(xmldb_table $xmldb_table, $quoted=true) {
/**
* Given one correct xmldb_table, returns the SQL statements
- * to create it (inside one array)
+ * to create it (inside one array).
+ *
+ * @param xmldb_table $xmldb_table An xmldb_table instance.
+ * @return array An array of SQL statements, starting with the table creation SQL followed
+ * by any of its comments, indexes and sequence creation SQL statements.
*/
public function getCreateTableSQL($xmldb_table) {
@@ -345,7 +416,12 @@ public function getCreateTableSQL($xmldb_table) {
/**
* Given one correct xmldb_index, returns the SQL statements
- * needed to create it (in array)
+ * needed to create it (in array).
+ *
+ * @param xmldb_table $xmldb_table The xmldb_table instance to create the index on.
+ * @param xmldb_index $xmldb_index The xmldb_index to create.
+ * @return array An array of SQL statements to create the index.
+ * @throws coding_exception Thrown if the xmldb_index does not validate with the xmldb_table.
*/
public function getCreateIndexSQL($xmldb_table, $xmldb_index) {
if ($error = $xmldb_index->validateDefinition($xmldb_table)) {
@@ -368,7 +444,17 @@ public function getCreateIndexSQL($xmldb_table, $xmldb_index) {
}
/**
- * Given one correct xmldb_field, returns the complete SQL line to create it
+ * Given one correct xmldb_field, returns the complete SQL line to create it.
+ *
+ * @param xmldb_table $xmldb_table The table related to $xmldb_field.
+ * @param xmldb_field $xmldb_field The instance of xmldb_field to create the SQL from.
+ * @param string $skip_type_clause The type clause on alter columns, NULL by default.
+ * @param string $skip_default_clause The default clause on alter columns, NULL by default.
+ * @param string $skip_notnull_clause The null/notnull clause on alter columns, NULL by default.
+ * @param string $specify_nulls_clause To force a specific null clause, NULL by default.
+ * @param bool $specify_field_name Flag to specify fieldname in return.
+ * @return string The field generating SQL statement.
+ * @throws coding_exception Thrown when xmldb_field doesn't validate with the xmldb_table.
*/
public function getFieldSQL($xmldb_table, $xmldb_field, $skip_type_clause = NULL, $skip_default_clause = NULL, $skip_notnull_clause = NULL, $specify_nulls_clause = NULL, $specify_field_name = true) {
if ($error = $xmldb_field->validateDefinition($xmldb_table)) {
@@ -453,7 +539,11 @@ public function getFieldSQL($xmldb_table, $xmldb_field, $skip_type_clause = NULL
}
/**
- * Given one correct xmldb_key, returns its specs
+ * Given one correct xmldb_key, returns its specs.
+ *
+ * @param xmldb_table $xmldb_table The table related to $xmldb_key.
+ * @param xmldb_key $xmldb_key The xmldb_key's specifications requested.
+ * @return string SQL statement about the xmldb_key.
*/
public function getKeySQL($xmldb_table, $xmldb_key) {
@@ -492,6 +582,9 @@ public function getKeySQL($xmldb_table, $xmldb_key) {
/**
* Give one xmldb_field, returns the correct "default value" for the current configuration
+ *
+ * @param xmldb_field $xmldb_field The field.
+ * @return The default value of the field.
*/
public function getDefaultValue($xmldb_field) {
@@ -529,7 +622,10 @@ public function getDefaultValue($xmldb_field) {
}
/**
- * Given one xmldb_field, returns the correct "default clause" for the current configuration
+ * Given one xmldb_field, returns the correct "default clause" for the current configuration.
+ *
+ * @param xmldb_field $xmldb_field The xmldb_field.
+ * @return The SQL clause for generating the default value as in $xmldb_field.
*/
public function getDefaultClause($xmldb_field) {
@@ -544,7 +640,11 @@ public function getDefaultClause($xmldb_field) {
/**
* Given one correct xmldb_table and the new name, returns the SQL statements
- * to rename it (inside one array)
+ * to rename it (inside one array).
+ *
+ * @param xmldb_table $xmldb_table The table to rename.
+ * @param string $newname The new name to rename the table to.
+ * @return array SQL statement(s) to rename the table.
*/
public function getRenameTableSQL($xmldb_table, $newname) {
@@ -566,7 +666,10 @@ public function getRenameTableSQL($xmldb_table, $newname) {
/**
* Given one correct xmldb_table and the new name, returns the SQL statements
- * to drop it (inside one array)
+ * to drop it (inside one array).
+ *
+ * @param xmldb_table $xmldb_table The table to drop.
+ * @return array SQL statement(s) for dropping the specified table.
*/
public function getDropTableSQL($xmldb_table) {
@@ -584,7 +687,14 @@ public function getDropTableSQL($xmldb_table) {
}
/**
- * Given one xmldb_table and one xmldb_field, return the SQL statements needed to add the field to the table
+ * Given one xmldb_table and one xmldb_field, return the SQL statements needed to add the field to the table.
+ *
+ * @param xmldb_table $xmldb_table The table related to $xmldb_field.
+ * @param xmldb_field $xmldb_field The instance of xmldb_field to create the SQL from.
+ * @param string $skip_type_clause The type clause on alter columns, NULL by default.
+ * @param string $skip_default_clause The default clause on alter columns, NULL by default.
+ * @param string $skip_notnull_clause The null/notnull clause on alter columns, NULL by default.
+ * @return array The SQL statement for adding a field to the table.
*/
public function getAddFieldSQL($xmldb_table, $xmldb_field, $skip_type_clause = NULL, $skip_default_clause = NULL, $skip_notnull_clause = NULL) {
@@ -612,7 +722,11 @@ public function getAddFieldSQL($xmldb_table, $xmldb_field, $skip_type_clause = N
}
/**
- * Given one xmldb_table and one xmldb_field, return the SQL statements needed to drop the field from the table
+ * Given one xmldb_table and one xmldb_field, return the SQL statements needed to drop the field from the table.
+ *
+ * @param xmldb_table $xmldb_table The table related to $xmldb_field.
+ * @param xmldb_field $xmldb_field The instance of xmldb_field to create the SQL from.
+ * @return array The SQL statement for dropping a field from the table.
*/
public function getDropFieldSQL($xmldb_table, $xmldb_field) {
@@ -629,7 +743,14 @@ public function getDropFieldSQL($xmldb_table, $xmldb_field) {
}
/**
- * Given one xmldb_table and one xmldb_field, return the SQL statements needed to alter the field in the table
+ * Given one xmldb_table and one xmldb_field, return the SQL statements needed to alter the field in the table.
+ *
+ * @param xmldb_table $xmldb_table The table related to $xmldb_field.
+ * @param xmldb_field $xmldb_field The instance of xmldb_field to create the SQL from.
+ * @param string $skip_type_clause The type clause on alter columns, NULL by default.
+ * @param string $skip_default_clause The default clause on alter columns, NULL by default.
+ * @param string $skip_notnull_clause The null/notnull clause on alter columns, NULL by default.
+ * @return string The field altering SQL statement.
*/
public function getAlterFieldSQL($xmldb_table, $xmldb_field, $skip_type_clause = NULL, $skip_default_clause = NULL, $skip_notnull_clause = NULL) {
@@ -663,7 +784,11 @@ public function getAlterFieldSQL($xmldb_table, $xmldb_field, $skip_type_clause =
}
/**
- * Given one xmldb_table and one xmldb_field, return the SQL statements needed to modify the default of the field in the table
+ * Given one xmldb_table and one xmldb_field, return the SQL statements needed to modify the default of the field in the table.
+ *
+ * @param xmldb_table $xmldb_table The table related to $xmldb_field.
+ * @param xmldb_field $xmldb_field The instance of xmldb_field to get the modified default value from.
+ * @return array The SQL statement for modifying the default value.
*/
public function getModifyDefaultSQL($xmldb_table, $xmldb_field) {
@@ -685,7 +810,12 @@ public function getModifyDefaultSQL($xmldb_table, $xmldb_field) {
/**
* Given one correct xmldb_field and the new name, returns the SQL statements
- * to rename it (inside one array)
+ * to rename it (inside one array).
+ *
+ * @param xmldb_table $xmldb_table The table related to $xmldb_field.
+ * @param xmldb_field $xmldb_field The instance of xmldb_field to get the renamed field from.
+ * @param string $newname The new name to rename the field to.
+ * @return array The SQL statements for renaming the field.
*/
public function getRenameFieldSQL($xmldb_table, $xmldb_field, $newname) {
@@ -717,7 +847,11 @@ public function getRenameFieldSQL($xmldb_table, $xmldb_field, $newname) {
/**
* Given one xmldb_table and one xmldb_key, return the SQL statements needed to add the key to the table
- * note that undelying indexes will be added as parametrised by $xxxx_keys and $xxxx_index parameters
+ * note that undelying indexes will be added as parametrised by $xxxx_keys and $xxxx_index parameters.
+ *
+ * @param xmldb_table $xmldb_table The table related to $xmldb_key.
+ * @param xmldb_key $xmldb_key The xmldb_key to add.
+ * @return array SQL statement to add the xmldb_key.
*/
public function getAddKeySQL($xmldb_table, $xmldb_key) {
@@ -757,7 +891,11 @@ public function getAddKeySQL($xmldb_table, $xmldb_key) {
}
/**
- * Given one xmldb_table and one xmldb_index, return the SQL statements needed to drop the index from the table
+ * Given one xmldb_table and one xmldb_index, return the SQL statements needed to drop the index from the table.
+ *
+ * @param xmldb_table $xmldb_table The table related to $xmldb_key.
+ * @param xmldb_key $xmldb_key The xmldb_key to drop.
+ * @return array SQL statement to drop the xmldb_key.
*/
public function getDropKeySQL($xmldb_table, $xmldb_key) {
@@ -826,8 +964,12 @@ public function getDropKeySQL($xmldb_table, $xmldb_key) {
/**
* Given one xmldb_table and one xmldb_key, return the SQL statements needed to rename the key in the table
* Experimental! Shouldn't be used at all!
+ *
+ * @param xmldb_table $xmldb_table The table related to $xmldb_key.
+ * @param xmldb_key $xmldb_key The xmldb_key to rename.
+ * @param string $newname The xmldb_key's new name.
+ * @return array SQL statement to rename the xmldb_key.
*/
-
public function getRenameKeySQL($xmldb_table, $xmldb_key, $newname) {
$results = array();
@@ -861,7 +1003,11 @@ public function getRenameKeySQL($xmldb_table, $xmldb_key, $newname) {
}
/**
- * Given one xmldb_table and one xmldb_index, return the SQL statements needed to add the index to the table
+ * Given one xmldb_table and one xmldb_index, return the SQL statements needed to add the index to the table.
+ *
+ * @param xmldb_table $xmldb_table The xmldb_table instance to add the index on.
+ * @param xmldb_index $xmldb_index The xmldb_index to add.
+ * @return array An array of SQL statements to add the index.
*/
public function getAddIndexSQL($xmldb_table, $xmldb_index) {
@@ -870,7 +1016,11 @@ public function getAddIndexSQL($xmldb_table, $xmldb_index) {
}
/**
- * Given one xmldb_table and one xmldb_index, return the SQL statements needed to drop the index from the table
+ * Given one xmldb_table and one xmldb_index, return the SQL statements needed to drop the index from the table.
+ *
+ * @param xmldb_table $xmldb_table The xmldb_table instance to drop the index on.
+ * @param xmldb_index $xmldb_index The xmldb_index to drop.
+ * @return array An array of SQL statements to drop the index.
*/
public function getDropIndexSQL($xmldb_table, $xmldb_index) {
@@ -891,6 +1041,11 @@ public function getDropIndexSQL($xmldb_table, $xmldb_index) {
/**
* Given one xmldb_table and one xmldb_index, return the SQL statements needed to rename the index in the table
* Experimental! Shouldn't be used at all!
+ *
+ * @param xmldb_table $xmldb_table The xmldb_table instance to rename the index on.
+ * @param xmldb_index $xmldb_index The xmldb_index to rename.
+ * @param string $newname The xmldb_index's new name.
+ * @return array An array of SQL statements to rename the index.
*/
function getRenameIndexSQL($xmldb_table, $xmldb_index, $newname) {
/// Some DB doesn't support index renaming (MySQL) so this can be empty
@@ -914,6 +1069,11 @@ function getRenameIndexSQL($xmldb_table, $xmldb_index, $newname) {
*
* IMPORTANT: This function must be used to CALCULATE NAMES of objects TO BE CREATED,
* NEVER TO GUESS NAMES of EXISTING objects!!!
+ *
+ * @param string $tablename The table name.
+ * @param string $fields A list of comma separated fields.
+ * @param string $suffix A suffix for the object name.
+ * @return string Object's name.
*/
public function getNameForObject($tablename, $fields, $suffix='') {
@@ -985,6 +1145,9 @@ public function getNameForObject($tablename, $fields, $suffix='') {
/**
* Given any string (or one array), enclose it by the proper quotes
* if it's a reserved word
+ *
+ * @param string|array $input String to quote.
+ * @return Quoted string.
*/
public function getEncQuoted($input) {
@@ -1005,7 +1168,10 @@ public function getEncQuoted($input) {
}
/**
- * Given one XMLDB Statement, build the needed SQL insert sentences to execute it
+ * Given one XMLDB Statement, build the needed SQL insert sentences to execute it.
+ *
+ * @param string $statement SQL statement.
+ * @return array Array of sentences in the SQL statement.
*/
function getExecuteInsertSQL($statement) {
@@ -1057,9 +1223,14 @@ function getExecuteInsertSQL($statement) {
}
/**
- * Given one array of elements, build de proper CONCAT expression, based
+ * Given one array of elements, build the proper CONCAT expression, based
* in the $concat_character setting. If such setting is empty, then
- * MySQL's CONCAT function will be used instead
+ * MySQL's CONCAT function will be used instead.
+ *
+ * @param array $elements An array of elements to concatenate.
+ * @return mixed Returns the result of moodle_database::sql_concat() or false.
+ * @uses moodle_database::sql_concat()
+ * @uses call_user_func_array()
*/
public function getConcatSQL($elements) {
@@ -1078,18 +1249,27 @@ public function getConcatSQL($elements) {
/**
* Returns the name (string) of the sequence used in the table for the autonumeric pk
- * Only some DB have this implemented
+ * Only some DB have this implemented.
+ *
+ * @param xmldb_table $xmldb_table The xmldb_table instance.
+ * @return bool Returns the sequence from the DB or false.
*/
public function getSequenceFromDB($xmldb_table) {
return false;
}
/**
- * Given one object name and it's type (pk, uk, fk, ck, ix, uix, seq, trg)
- * return if such name is currently in use (true) or no (false)
+ * Given one object name and it's type (pk, uk, fk, ck, ix, uix, seq, trg).
+ *
* (MySQL requires the whole xmldb_table object to be specified, so we add it always)
- * (invoked from getNameForObject()
- * Only some DB have this implemented
+ *
+ * This is invoked from getNameForObject().
+ * Only some DB have this implemented.
+ *
+ * @param string $object_name The object's name to check for.
+ * @param string $type The object's type (pk, uk, fk, ck, ix, uix, seq, trg).
+ * @param string $table_name The table's name to check in
+ * @return bool If such name is currently in use (true) or no (false)
*/
public function isNameInUse($object_name, $type, $table_name) {
return false; //For generators not implementing introspection,
@@ -1101,57 +1281,87 @@ public function isNameInUse($object_name, $type, $table_name) {
/**
* Reset a sequence to the id field of a table.
- * @param string $table name of table
+ *
+ * @param string $tablename name of table.
* @return success
*/
public abstract function getResetSequenceSQL($tablename);
/**
* Given one correct xmldb_table, returns the SQL statements
- * to create temporary table (inside one array)
+ * to create temporary table (inside one array).
+ *
+ * @param xmldb_table $xmldb_table The xmldb_table object instance.
+ * @return array SQL statements.
*/
abstract public function getCreateTempTableSQL($xmldb_table);
/**
- * Given one correct xmldb_table and the new name, returns the SQL statements
- * to drop it (inside one array)
+ * Given one correct xmldb_table and the new name, returns the SQL statements.
+ * to drop it (inside one array).
+ *
+ * @param xmldb_table $xmldb_table The xmldb_table object instance.
+ * @return array SQL statements.
*/
abstract public function getDropTempTableSQL($xmldb_table);
/**
- * Given one XMLDB Type, length and decimals, returns the DB proper SQL type
+ * Given one XMLDB Type, length and decimals, returns the DB proper SQL type.
+ *
+ * @param int $xmldb_type The xmldb_type defined constant. XMLDB_TYPE_INTEGER and other XMLDB_TYPE_* constants.
+ * @param int $xmldb_length The length of that data type.
+ * @param int $xmldb_decimals The decimal places of precision of the data type.
+ * @return string The DB defined data type.
*/
public abstract function getTypeSQL($xmldb_type, $xmldb_length=null, $xmldb_decimals=null);
/**
- * Returns the code (array of statements) needed to execute extra statements on field rename
+ * Returns the code (array of statements) needed to execute extra statements on field rename.
+ *
+ * @param xmldb_table $xmldb_table The xmldb_table object instance.
+ * @param xmldb_field $xmldb_field The xmldb_field object instance.
+ * @return array Array of extra SQL statements to run with a field being renamed.
*/
public function getRenameFieldExtraSQL($xmldb_table, $xmldb_field) {
return array();
}
/**
* Returns the code (array of statements) needed
- * to create one sequence for the xmldb_table and xmldb_field passes
+ * to create one sequence for the xmldb_table and xmldb_field passed in.
+ *
+ * @param xmldb_table $xmldb_table The xmldb_table object instance.
+ * @param xmldb_field $xmldb_field The xmldb_field object instance.
+ * @return array Array of SQL statements to create the sequence.
*/
public function getCreateSequenceSQL($xmldb_table, $xmldb_field) {
return array();
}
/**
- * Returns the code (array of statements) needed to add one comment to the table
+ * Returns the code (array of statements) needed to add one comment to the table.
+ *
+ * @param xmldb_table $xmldb_table The xmldb_table object instance.
+ * @return array Array of SQL statements to add one comment to the table.
*/
public abstract function getCommentSQL($xmldb_table);
/**
- * Returns the code (array of statements) needed to execute extra statements on table rename
+ * Returns the code (array of statements) needed to execute extra statements on table rename.
+ *
+ * @param xmldb_table $xmldb_table The xmldb_table object instance.
+ * @param string $newname The new name for the table.
+ * @return array Array of extra SQL statements to rename a table.
*/
public function getRenameTableExtraSQL($xmldb_table, $newname) {
return array();
}
/**
* Returns the code (array of statements) needed to execute extra statements on table drop
+ *
+ * @param xmldb_table $xmldb_table The xmldb_table object instance.
+ * @return array Array of extra SQL statements to drop a table.
*/
public function getDropTableExtraSQL($xmldb_table) {
return array();
@@ -1161,15 +1371,25 @@ public function getDropTableExtraSQL($xmldb_table) {
* Given one xmldb_table and one xmldb_field, return the SQL statements needed to drop its enum
* (usually invoked from getModifyEnumSQL()
*
- * TODO: Moodle 2.1 - Drop getDropEnumSQL()
+ * Note that this method may be dropped in future.
+ *
+ * @param xmldb_table $xmldb_table The xmldb_table object instance.
+ * @param xmldb_field $xmldb_field The xmldb_field object instance.
+ *
+ * @todo MDL-31147 Moodle 2.1 - Drop getDropEnumSQL()
*/
public abstract function getDropEnumSQL($xmldb_table, $xmldb_field);
/**
* Given one xmldb_table and one xmldb_field, return the SQL statements needed to drop its default
* (usually invoked from getModifyDefaultSQL()
*
- * TODO: Moodle 2.1 - Drop getDropDefaultSQL()
+ * Note that this method may be dropped in future.
+ *
+ * @param xmldb_table $xmldb_table The xmldb_table object instance.
+ * @param xmldb_field $xmldb_field The xmldb_field object instance.
+ *
+ * @todo MDL-31147 Moodle 2.1 - Drop getDropDefaultSQL()
*/
public abstract function getDropDefaultSQL($xmldb_table, $xmldb_field);
@@ -1178,27 +1398,37 @@ public function getDropTableExtraSQL($xmldb_table) {
* constrainst found for that table (or field). Must exist for each DB supported.
* (usually invoked from find_check_constraint_name)
*
- * TODO: Moodle 2.1 - Drop getCheckConstraintsFromDB
+ * Note that this method may be dropped in future.
+ *
+ * @param xmldb_table $xmldb_table The xmldb_table object instance.
+ * @param xmldb_field $xmldb_field The xmldb_field object instance.
+ *
+ * @todo MDL-31147 Moodle 2.1 - Drop getCheckConstraintsFromDB
*/
public abstract function getCheckConstraintsFromDB($xmldb_table, $xmldb_field=null);
/**
* Given one xmldb_table and one xmldb_field, return the SQL statements needed to add its default
* (usually invoked from getModifyDefaultSQL()
+ *
+ * @param xmldb_table $xmldb_table The xmldb_table object instance.
+ * @param xmldb_field $xmldb_field The xmldb_field object instance.
+ * @return array Array of SQL statements to create a field's default.
*/
public abstract function getCreateDefaultSQL($xmldb_table, $xmldb_field);
/**
* Returns an array of reserved words (lowercase) for this DB
- * You MUST provide the real list for each DB inside every XMLDB class
- * @return array of reserved words
+ * You MUST provide the real list for each DB inside every XMLDB class.
+ * @return array An array of database specific reserved words.
+ * @throws coding_exception Thrown if not implemented for the specific DB.
*/
public static function getReservedWords() {
throw new coding_exception('getReservedWords() method needs to be overridden in each subclass of sql_generator');
}
/**
- * Returns all reserved works in supported databases.
+ * Returns all reserved words in supported databases.
* Reserved words should be lowercase.
* @return array ('word'=>array(databases))
*/
@@ -1219,6 +1449,11 @@ public static function getAllReservedWords() {
return $reserved_words;
}
+ /**
+ * Adds slashes to string.
+ * @param string $s
+ * @return string The escaped string.
+ */
public function addslashes($s) {
// do not use php addslashes() because it depends on PHP quote settings!
$s = str_replace('\\','\\\\',$s);
View
2 lib/ddl/sqlite_sql_generator.php
@@ -20,7 +20,7 @@
* Experimental SQLite specific SQL code generator.
*
* @package core
- * @subpackage ddl
+ * @subpackage ddl_generator
* @copyright 2008 Andrei Bautu
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

0 comments on commit 83a4ee1

Please sign in to comment.
Something went wrong with that request. Please try again.